# 使用说明

[English](./en/usage-guide.md)

## 一、init 做了什么

在业务仓库根执行：

```bash
flow2spec init [cursor|claude|codex ...]
# 使用英文模板：
flow2spec init [cursor|claude|codex ...] --locale en-US
# 需要强制重置 .Knowledge 到模板时：
flow2spec init [cursor|claude|codex ...] --reset-knowledge
```


| init 做                                      | init 不做                      |
| ------------------------------------------- | ---------------------------- |
| 补齐缺失的目录与模板文件                                | 撰写或更新业务文档内容                  |
| 落盘各 agent 配置根 `rules/` `skills/`            | 更新 `includeAny` 业务词条         |
| `manifest-routing` + `matchers/` 包级结构对齐     | 替代 `f2s-*` 技能对业务语义的书写        |
| `--reset-knowledge` 时强制覆盖 `.Knowledge` 模板文件 | （不加此参数时）覆盖已有 `.Knowledge` 内容 |


> **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-kb-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-kb-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。

### 模板语言

`flow2spec init` 默认使用 `zh-CN` 模板；可通过 `--locale en-US` 使用英文模板。`locale` 只决定 Flow2Spec 包模板（rules / skills / knowledge template / hooks / AGENTS）的自然语言，不翻译已有业务知识库内容。`f2s-kb-upgrade` 默认沿用项目 `flow2spec.config.json.locale`，字段不存在时按 `zh-CN` 补齐。

### `f2s-*` 与 `flow2spec.config.json`：多端多重提示（权威仍为磁盘 JSON）

执行任意 **`f2s-*` 技能**前，需要让 Agent 拿到 **`subAgent` / `switchAgentVerification` / `changeTracking`** 等实际值。Flow2Spec 在 **不同客户端** 用 **不同机制** 强化这一点；它们彼此**补充**，**不**互相替代，**权威始终**是项目根 **`flow2spec.config.json`**（须用 **Read** 与磁盘一致后再进技能正文）。


| 端               | `init` 落盘与行为                                                                          | 说明                                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cursor**      | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`）                                   | 配置读取走文本约束：技能正文前先 **Read(`flow2spec.config.json`)**；Cursor hook 仅用于版本更新检测，不自动读取配置。                                                                                                  |
| **Claude Code** | `.claude/hooks/f2s-config-session.js` + `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` | `SessionStart` 仅注入一次配置摘要；`PreToolUse` 仅在调用 **`f2s-*` Skill** 时做守门提示，提醒首步必须 **Read**。两者都不替代磁盘 Read。                                                                |
| **Codex**       | 根 `AGENTS.md` 顶部强制步骤 + `.codex/topics/f2s-config-check.md` + `{{FLOW2SPEC_PROJECT_CONFIG}}` 字段语义表 + `.codex/hooks/f2s-config-session.js` | `SessionStart` 注入一次配置摘要；配置读取仍以文本约束 + **Read** 为硬要求；表格只说明字段语义，不写当前值，配置真值以磁盘 **Read** 为准。Codex 无 Claude 的 `PreToolUse` 守门，`subAgent=true` 时需在技能正文前段显式判断是否拆子；即使不拆，也必须输出不拆原因。 |
| **知识库（可选）**     | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时                              | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。                                                                      |


字段语义与默认值规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。设计视角见 [设计说明 § 四、5.1](./设计说明.md)；口述见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)。

---

## 二、目录约定

核心区分：`stock-docs/` 放沉淀文档（驱动知识路由），`req-docs/` 放技术方案（驱动编码实现），两者不互换。

完整目录说明见 [目录与路径约定](./目录与路径约定.md)。

---

## 三、典型工作场景

### 变更追踪与跨会话续作（推荐）

在 `flow2spec.config.json` 按技能开启 `changeTracking`（各子项独立）：

```json
{
  "changeTracking": {
    "feat": true,
    "fix": true,
    "implement": true
  }
}
```

开启后，`f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` 执行时会在 `.task/active/` 自动创建任务清单，逐步勾选，完成后归档。下次会话描述相关内容时，`f2s-task` 规则会匹配并加载剩余步骤，无需重复交代上下文。

若你**关闭了** `changeTracking` 但仍临时需要 `.task/` 清单，可显式调用 `f2s-req-plan`（不读配置、始终建清单）——这是兜底用法，非常规主路径；详见 [命令说明 § f2s-req-plan](./命令说明.md)。

### 新需求开发

```
f2s-req-clarify 一句话需求或文档 → f2s-req-tech → 实现xx技术方案 （会严格按照implement-tech-design规则走）
实现完成后需新增能力→ f2s-kb-feat
实现完成后需修bug→ f2s-kb-fix
调试完成后-> f2s-kb-sync
最后->f2s-git-commit
```

需求已明确时可跳过 `f2s-req-clarify`，直接从 `f2s-req-tech` 开始。技术方案落入 `req-docs/` 后，由 `implement-tech-design` 规则驱动编码。

### 文档沉淀

```
新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-kb-build
PDF/初稿沉淀：     f2s-doc-final → f2s-kb-build
```

把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 `f2s-doc-final` 转为终稿再 `f2s-kb-build`；`f2s-doc-pdf` 仅把 PDF 转为 `req-docs/` 下的 Markdown 便于编辑，**不**作为「PDF 直驱编码」的推荐路径。

### 存量能力补录

```
f2s-kb-add      # 多文件聚合，从源码/文档提取
f2s-kb-sync      # 从当前会话推断已实现能力
```

代码已落地但知识库没有记录时使用。`f2s-kb-add` 适合批量导入，`f2s-kb-sync` 适合会话结束时的即时沉淀。

### 日常维护

```
f2s-kb-fix       # 修复实现或规则错误，自动同步知识库
f2s-kb-feat      # 新增能力，自动同步知识库
f2s-kb-sync      # 定期同步或补录
f2s-kb-merge     # Git 合并后解决上下文冲突
```

### 知识库跨版本升级

```
f2s-kb-migrate（流程 V1：旧库）→ f2s-kb-upgrade
f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，见技能步骤 0）
```

Flow2Spec CLI 在交互式执行 `flow2spec version` / `flow2spec init` 时会按缓存检查 npm 最新版本；若发现新版本，会提示先执行 `flow2spec update`，随后在 Agent 对话中执行 `f2s-kb-upgrade`，用于对齐项目知识库模板、manifest/matchers 与配置根产物。更新检查失败会静默跳过，不影响当前命令；`CI`、非 TTY 或设置 `FLOW2SPEC_SKIP_UPDATE_CHECK=1` 时不检查。

Codex 项目执行 `flow2spec init codex` 后会写入 `.codex/hooks.json`、`.codex/hooks/f2s-config-session.js` 与 `.codex/hooks/f2s-update-check.js`：前者在 Codex `SessionStart` 的 `startup|resume` 事件注入一次配置摘要，后者自动检查知识库版本；首次生成或 hook 内容变化后，需要在 Codex 中通过 `/hooks` 信任该项目 hook。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时仅跳过版本检查，不影响配置摘要注入。

Cursor 项目执行 `flow2spec init cursor` 后会写入 `.cursor/hooks.json` 与 `.cursor/hooks/f2s-update-check.js`，在 Cursor `sessionStart` 自动检查知识库版本；脚本通过 `additional_context` 把升级提示注入会话。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时跳过检查。

Claude 项目执行 `flow2spec init claude` 后会写入 `.claude/settings.json`、`.claude/hooks/f2s-config-session.js`、`.claude/hooks/f2s-config-inject.js` 与 `.claude/hooks/f2s-update-check.js`：`SessionStart` 注入配置摘要并检查知识库版本，`PreToolUse Skill` 仅在调用 `f2s-*` Skill 前做守门提示。版本检查脚本通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户），格式为："当前项目「<项目名>」知识库版本 v<当前版本>，低于最新包版本 v<最新版本>。可执行 f2s-kb-upgrade skill 对齐模板与路由。"若当天缓存仍标记需升级，新会话每次都会重新注入提示；升级成功后 `f2s-kb-upgrade` 会清理 `.Knowledge/update-check.json`，避免旧提示残留。

---

## 四、Agent 执行配置

通过项目根 `flow2spec.config.json` 控制，字段完整规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。**各端如何被提示读到配置、为何仍以 Read 为权威**见 **§ 一**（本 § 仅说明**何时**打开各开关）。

**何时开启 `subAgent: true`**：任务规模较大时（多模块并行实现、批量文档入库、大规模迁移）。开启后各技能按自身规模门槛决定是否实际拆分，未达门槛的仍在主 agent 内完成。

**何时开启 `switchAgentVerification: true`**：需要更高落盘一致性时（大规模迁移、重要方案实现）。代价是增加执行轮次；常规维护场景默认 `false` 足够。须搭配 `subAgent: true` 才能触发"主落子验"方向的交叉。

**何时开启 `changeTracking.*`**：希望每次技能执行自动留下可续作的任务清单时。各技能子项独立配置，互不影响：

```json
{
  "changeTracking": {
    "feat": true,
    "fix": false,
    "implement": true
  }
}
```

`changeTracking` 全关且仍要任务清单时，再考虑 `f2s-req-plan`（见 § 三「变更追踪」脚注）。

---

## 五、规则改造建议

- 项目特化「按技术方案实现」逻辑时，优先调整 **`f2s-implement-tech-design`**：Cursor `.cursor/rules/f2s-implement-tech-design.mdc`，Claude `.claude/rules/f2s-implement-tech-design.md`；Codex 以 `.codex/AGENTS.md` 与相关 `skills/` 为准
- 再次 `init` 默认仅补齐缺失模板并做包级结构对齐，**不**替代 `f2s-*` 对业务内容的维护；需用模板重置 `.Knowledge` 时加 `--reset-knowledge`

---

## 六、技能标识

技能以 `name` 与 `description` 匹配触发，文件位于 `配置根/skills/*/SKILL.md`。

---

## 七、相关文档

- [Flow2Spec 基础介绍](./Flow2Spec基础介绍.md)
- [命令说明](./命令说明.md)
- [目录与路径约定](./目录与路径约定.md)
- [体系与原理](./体系与原理.md)
- [使用案例-模拟对话](./使用案例-模拟对话.md)
- [项目里程碑](./项目里程碑.md)