# 工作流与技能说明

[English](./en/commands-reference.md)

## 命令速查表

| 命令 | 用途 | 分类 |
|---|---|---|
| `/f2s-doc-arch` | 扫描项目，生成架构说明初稿 | 文档沉淀 |
| `/f2s-doc-final` | PDF / 初稿转《终稿模版》规范格式 | 文档沉淀 |
| `/f2s-kb-build` | 终稿文档同步到知识库路由（生成 topics / matchers / manifest） | 文档沉淀 |
| `/f2s-kb-add <路径>` | 已落地能力多文件聚合入知识库 | 文档沉淀 |
| `/f2s-kb-rm` | 删除某 stock-docs 文档对应的知识主题与索引映射 | 文档沉淀 |
| `/f2s-doc-pdf` | PDF 技术方案转 Markdown，保存到 req-docs | 文档沉淀 |
| `/f2s-req-clarify` | 需求澄清，多轮问答明确需求边界 | 需求与方案 |
| `/f2s-req-tech` | 基于澄清结果生成技术方案文档 | 需求与方案 |
| `/f2s-req-plan` | 按技术方案拆任务清单，支持并行实现 （不依赖 `changeTracking.*` 配置） | 需求与方案 |
| `/f2s-git-commit` | 提交代码，默认检查知识库覆盖；说“快捷提交”时跳过覆盖检查 | 提交 |
| `/f2s-kb-feat` | 新增能力，补全实现 + 同步知识库 | 知识库维护 |
| `/f2s-kb-fix` | 修复 BUG + 自动同步知识库 | 知识库维护 |
| `/f2s-kb-distill` | 从问答过程中提取可复用知识事实并自动入库 | 知识库维护 |
| `/f2s-kb-sync` | 将会话中已实现能力沉淀回知识库 | 知识库维护 |
| `/f2s-kb-merge` | 解决 Git 合并后的知识库冲突 | 知识库维护 |
| `/f2s-kb-migrate` | 旧版知识库一次性迁移到 `.Knowledge/` | 知识库维护 |
| `/f2s-kb-upgrade` | 知识库模板升级，对齐 manifest + matchers 分片 | 知识库维护 |

---

## 1) 文档沉淀（stock-docs 链路）

### `f2s-doc-arch`

**作用**：根据用户说明或扫描代码，生成项目架构说明初稿。无固定格式要求，描述清楚系统结构、模块关系、关键决策即可。

**工作原理**：以「inventory 驱动扫描」为核心——先由主 agent 产出模块清单（inventory）与扫描契约（读哪些入口、关注哪些维度），再按 inventory 执行只读代码扫描，最后将扫描结果聚合为人可读的架构初稿落盘 `stock-docs/`。整个流程不改代码，仅做「代码→文档」的单向提取。

**使用场景**：

- 新项目需要架构文档
- 存量项目需要补充架构说明
- 系统重构后更新架构描述

**关联关系**：

- **前置**：无
- **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-kb-build`（**须终稿入参**；初稿不可直驱 build）
- **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内扫描代码并生成
- `subAgent: true`：默认走 **B 模式**（主产出 inventory + 扫描契约 → 子 agent 并行只读扫表 → 主合并落盘）；满足以下任一条件时升级为 **C 模式**（多轮纠偏）：多 workspace / monorepo、源路径 > 20 条、首轮子表有矛盾或空洞、多源叙述冲突严重

**职责划分**：


| 角色              | 职责                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------ |
| 主 agent         | 产出 inventory（入口 + 核心模块名）与扫描契约，汇总子 agent 交付，落盘 stock-docs 初稿                                |
| 子 agent（B/C 模式） | 按主手写 inventory 并行只读扫描，按统一 YAML schema 交付（`source / scope / cross_refs / pending`），不得自行裁剪范围 |


---

### `f2s-doc-final`

**作用**：将 PDF 技术方案或初稿文档转为《终稿模版》规范格式，统一文档结构，便于后续进入知识库。

**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-kb-build` 的标准输入物，确保知识库入口的结构一致性。

**使用场景**：

- PDF 技术方案需要转为 Markdown
- 初稿需要规范化以便沉淀
- 外部文档需要纳入 Flow2Spec 管理

**关联关系**：

- **前置**：PDF 文档或初稿文档
- **后续**：`f2s-kb-build`（终稿入库）
- **输出**：`.Knowledge/stock-docs/<文档>_终稿.md`

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成全流程
- `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做套模版与排版草稿；子不追问用户、不补写流程说明、不宣称终稿合规；主 agent 识别格式缺口并定稿验收

**职责划分**：


| 角色      | 职责                    |
| ------- | --------------------- |
| 主 agent | 识别格式缺口、对照模版与澄清文档验收定稿  |
| 子 agent | 套模版与排版草稿，不追问用户、不写流程说明 |


---

### `f2s-kb-build`

**作用**：将 `stock-docs/` 中的沉淀文档（架构、终稿）同步到知识库路由系统，生成/更新主题文件、索引、manifest-routing、matchers。

**工作原理**：以终稿文档为输入，执行「文档→路由」的三步映射：① 从终稿中提取能力主题与关键词；② 生成 `topics/<topic>.md`（路由摘要，含执行边界与下一步指针）和 `matchers/<id>.json`（机读匹配词 `includeAny`）；③ 在 `manifest-routing.json` 注册 task→topic 映射规则，并更新 `index.md` 人读导航。完成后，任务路由引擎即可通过关键词命中该主题。

**使用场景**：

- 终稿文档完成后，需要让知识库"知道"这些文档
- 新增业务领域，需要建立路由映射
- 文档内容更新后，同步更新知识库索引

**关联关系**：

- **前置**：`f2s-doc-arch`、`f2s-doc-final` 或直接编写的终稿
- **后续**：无（入库完成后可直接使用）
- **输入**：`.Knowledge/stock-docs/*.md`
- **输出**：
  - `.Knowledge/topics/<topic>.md`
  - `.Knowledge/index.md`
  - `.Knowledge/manifest-routing.json`
  - `.Knowledge/matchers/*.json`

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内顺序处理各文档
- `subAgent: true`：改动超过阈值（新增/修改主题 > 2 个 OR 新增 matcher > 1 个 OR 涉及跨主题批量引用调整）时拆子；子A 只写 topics/、子B 只写 matchers/；主 agent 单点编辑 manifest-routing.json 和 index.md，子 agent 不跨边界落盘

**职责划分**：


| 角色                | 职责                                         |
| ----------------- | ------------------------------------------ |
| 主 agent           | 单点落盘 manifest-routing.json 和 index.md，整体验收 |
| 子 agent（topics）   | 仅写 topics/ 目录下的主题文件，不触碰 manifest 和 index   |
| 子 agent（matchers） | 仅写 matchers/ 目录下的分片文件，不触碰 manifest 和 index |


---

### `f2s-kb-add`

**作用**：将已落地能力（多文件聚合）解析进知识库。适用于代码已实现但缺少文档，或已有多个文档需要统一入库的场景。

**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-kb-build` 的区别在于输入：`ctx-build` 从已有的单份终稿驱动，`doc-add` 从多个散落源聚合后再走同一管线。本质是补齐「有实现无文档」的缺口。

**使用场景**：

- 存量代码需要补录知识库
- 多份相关文档需要聚合入库
- 第三方文档批量导入

**关联关系**：

- **前置**：无（可直接触发）
- **后续**：无（入库完成即结束）
- **流程**：初稿 → 终稿 → topics/index/manifest

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内顺序处理
- `subAgent: true`：满足以下任一阈值时启用，默认走 **B 模式**（主产出 inventory → 子并行只读按 schema 填表 → 主合并落盘）；多 workspace / monorepo、首轮子表矛盾或空洞、多源叙述冲突严重时升级 **C 模式**（多轮纠偏）
  - 阈值：输入路径 ≥ 5 条 OR 单源 > 3000 行 OR 多路径总量 > 10000 行

**职责划分**：


| 角色              | 职责                                                                                                                                |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 主 agent         | 产出 inventory 与扫描契约，汇总子表，落盘 topics/index/manifest                                                                                  |
| 子 agent（B/C 模式） | 按主手写 inventory 执行只读扫描，按 schema 交表（`source / scope / capabilities / cross_refs / pending`）；不得自行裁剪范围、不写 manifest 和 index、不宣布"已进知识库" |


**交叉验证（`switchAgentVerification: true` 时）**：

- 子 agent 落盘的 topic 文件 → 主 agent 校验路由映射完整性与关键词覆盖
- 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

---

### `f2s-kb-rm`

**作用**：按 stock-docs 文档删除对应的知识主题与索引映射。仅删除知识库中的引用关系，不删除源文档本身。

**工作原理**：`f2s-kb-build` 的逆操作——给定一份 `stock-docs` 文档路径，定位其在 `manifest-routing.json` 中的 task→topic 规则、对应的 `matchers/<id>.json` 分片、`topics/<topic>.md` 文件以及 `index.md` 中的行项，逐一清除引用。若删除后某 topic 无任何 task 引用，则移除该 topic 文件。源文档本身保留不动，用户可自行决定是否物理删除。

**使用场景**：

- 文档已废弃，需要从知识路由中移除
- 误入库的文档需要撤销路由映射
- 文档合并后清理旧映射

**关联关系**：

- **前置**：已入库的 stock-docs 文档
- **后续**：无
- **注意**：只删路由映射，不删源文档

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内全流程执行（单点删除拆子收益低）
- `subAgent: true`：仅当**批量删除 ≥ 5 个主题**时才拆子执行删除与清引用；主 agent 必控范围确认与 fallbackTopic 重指；manifest-routing.json 与 index.md 恒由主落盘

---

### `f2s-doc-pdf`

**作用**：将 PDF 技术方案转为 Markdown 格式，保存到 `req-docs/`，可补全流程说明。

**工作原理**：将 PDF 中的接口定义、数据模型、时序流程等提取为 Markdown 并落盘 `req-docs/`，便于后续编辑或与 `f2s-req-clarify` / `f2s-req-tech` 衔接。与 `f2s-doc-final` 的区别：`doc-pdf` 输出到 `req-docs/`（实现侧文档目录），`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。**不推荐**把「PDF 转 MD」当作跳过澄清与技术方案的直驱编码路径。

**使用场景**：

- 跨团队交付物为 PDF，需转为可编辑的 Markdown
- 历史 PDF 技术方案需纳入 `req-docs/` 管理
- 为后续 `f2s-req-clarify` / `f2s-req-tech` 提供可读底稿

**关联关系**：

- **前置**：PDF 文档
- **输出**：`.Knowledge/req-docs/<方案>.md`
- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-tech` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-kb-build`

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成全流程
- `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做 PDF→MD 首稿落盘 req-docs；子不追问用户、不补写流程说明章节；主 agent 接手追问与流程说明补写

**职责划分**：


| 角色      | 职责                              |
| ------- | ------------------------------- |
| 主 agent | 追问用户补充流程说明、完成 req-docs 落盘验收     |
| 子 agent | 仅做 PDF→MD 首稿并落盘 req-docs，不向用户追问 |


---

## 2) 需求与方案

### `f2s-req-clarify`

**作用**：针对 PRD/需求文档进行反问澄清，通过多轮问答明确需求边界、非目标、关键流程，直至需求足够清晰可供技术方案编写。

**工作原理**：采用「结构化追问」策略——将需求文档按「角色/场景/流程/边界/异常/非目标」六维拆解，逐维检查是否存在模糊表述、未定义概念或矛盾点，对每个缺口生成针对性追问。多轮对话直到所有维度无歧义后，输出需求澄清记录作为 `f2s-req-tech` 的输入。本质是将非结构化 PRD 转为可落地的结构化需求约束。

**使用场景**：

- 收到 PRD 后首步骤，确保理解正确
- 需求边界模糊、缺少验收标准时
- 跨团队协作需求，需明确接口契约

**关联关系**：

- **前置**：无（可直接触发）
- **后续**：`f2s-req-tech`（澄清后生成技术方案）
- **输出**：需求澄清记录（可选保存至 `.Knowledge/req-docs/`）

**子 agent 调用**：无（澄清全程依赖连续对话与用户即时反馈，不拆子 agent）

---

### `f2s-req-tech`

**作用**：基于已澄清的需求和项目知识库，生成可实现的技术方案文档；具体内容按需求选择，可能是 API、页面/组件、脚本工具、数据处理、配置、消息事件或模块改造等。

**工作原理**：以「知识库约束 + 模版参考」为核心——先从 `topics/stock-docs` 中抽取当前项目的架构约定、契约风格、数据与模块边界等约束摘要，再按技术方案模版的可选积木取舍章节；不为套模板强行生成接口、数据库、错误码或消息队列章节。输出落盘 `req-docs/`，即为 `implement-tech-design` 的编码依据。

**使用场景**：

- `f2s-req-clarify` 完成后，基于澄清结果输出方案
- 已有明确需求文档，直接生成技术方案

**关联关系**：

- **前置**：`f2s-req-clarify`（推荐）或明确的需求文档
- **输出**：`.Knowledge/req-docs/<技术方案>.md`
- **下一步**：提供技术方案路径并说明"按技术方案实现"，由 `implement-tech-design` 规则驱动编码

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成方案编写
- `subAgent: true`：主 agent 必须先从 topics/stock-docs 抽取 < 80 行项目约定摘要（含架构约定、接口风格、数据模型规范等 6 类条款）作为子强制上下文，再拆子并行写 req-docs 初稿；主 agent 做契约定稿与验收

**职责划分**：


| 角色      | 职责                                                                      |
| ------- | ----------------------------------------------------------------------- |
| 主 agent | 抽取项目约定摘要、分配写作任务、对照模版做定稿验收并写入 req-docs                                   |
| 子 agent | 只读多源（topics / stock-docs / 澄清 req-docs / 模版），按模版写 req-docs 初稿；不自行扩展读取范围 |


**交叉验证（`switchAgentVerification: true` 时）**：

- 子 agent 落盘的方案初稿 → 主 agent 校验交付单元、数据结构、处理流程、异常处理与项目约定是否一致
- 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

---

### `f2s-req-plan`

**作用**：从技术方案或需求描述出发，**始终创建任务清单**，然后按清单实现代码。不依赖 `changeTracking` 配置，代表用户明确需要可追溯的任务管理。

> **关于任务清单**：任务清单不是 `/f2s-req-plan` 专属。`/f2s-kb-feat`、`/f2s-kb-fix` 和 `implement-tech-design` 在 `flow2spec.config.json` 中对应 `changeTracking.*` 字段为 `true` 时同样会自动创建任务清单。`/f2s-req-plan` 的区别是**不依赖任何配置、始终创建清单**，适合用户明确希望追踪进度的大型需求。

**工作原理**：执行「解析→规划→确认→实现→归档」五阶段闭环。① 解析技术方案文档提取实现要点；② 按模块/功能粒度拆分为可执行任务清单并写入 `.task/`；③ 展示草稿给用户确认后锁定清单；④ 按清单逐项实现代码，每完成一项立即打钩 `task.md`；⑤ 全部完成后归档。与 `implement-tech-design` 规则的区别：`req-plan` 始终带任务追踪且支持并行子 agent 实现，适合大型需求；后者是轻量规则驱动的单线程编码。

**使用场景**：

- 有技术方案文档，需要拆解为任务清单后再实现
- 需求描述较复杂，希望先确认清单再动手
- 希望跨会话追踪实现进度

**关联关系**：

- **前置**：技术方案文档路径（`.Knowledge/req-docs/*.md` 或 PDF）或需求/变更描述
- **输出**：`.task/active/<task-name>/task.md` + `context.md`；实现代码
- **后续**：可按需调用 `f2s-kb-sync` 补充知识库

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成解析、确认、实现全流程
- `subAgent: true`：步骤 1（解析文档）可拆子并行只读；步骤 2（草稿确认）必须主 agent；步骤 4（实现代码）可按模块拆子并行；`todo.json` 恒由主 agent 写

**职责划分**：


| 角色          | 职责                                   |
| ----------- | ------------------------------------ |
| 主 agent     | 输出草稿、用户确认、写 `todo.json`、汇总实现摘要       |
| 子 agent（解析） | 只读文档，输出解析结果摘要，不落盘                    |
| 子 agent（实现） | 按模块实现代码，不触碰 `.task/` 和 `.Knowledge/` |


---

## 3) Git 提交

### `f2s-git-commit`

**作用**：代码写完后执行 Git 提交。默认自动检查变更文件、比对知识库覆盖情况，未入库的能力会提示用户处理；用户明确说“快捷提交”时跳过知识库覆盖检查。提交前会展示提交信息首行，然后直接执行 commit。

**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。快捷提交模式只跳过这层覆盖门控，不跳过冲突检查、提交信息展示、精确 `git add`、git hooks。提交信息强制 emoji + Conventional Commits 格式，保证 git log 的机读一致性。

**使用场景**：

- 每次功能实现或 Bug 修复后提交代码
- 希望在提交时得到知识库覆盖情况的提醒
- 已明确不需要本次覆盖检查，只想快捷提交
- 需要 AI 帮助生成有意义的提交信息

**关联关系**：

- **前置**：代码已写完（`implement-tech-design`、`f2s-kb-fix`、`f2s-kb-feat` 等执行后）
- **后续**：无（commit 完成即结束，不自动 push）
- **可衔接**：若知识库未覆盖，可先运行 `f2s-kb-sync` 或 `f2s-kb-feat` 补录后继续提交

**执行流程**：

1. `git status --short` + `git diff HEAD` 区分 staged / unstaged / untracked 三类文件；发现 merge conflict 标记立即终止
2. 默认对比 `.Knowledge/topics/` 与 `stock-docs/`，判断本次变更能力是否已入库；`.Knowledge` 不存在时跳过并提示；用户说“快捷提交”时跳过本步
3. 未覆盖时提示用户选择：A) 先补录再提交 / B) 先提交稍后补录 / C) 取消
4. 基于 `git diff` 实际内容生成提交信息草稿，等待用户确认或修改
5. `git add <具体文件>` + `git commit`；hook 失败则提示修复，不跳过
6. 输出 commit hash；若选 B 则附带未补录能力提醒

**约束**：

- 禁止 `git add -A` / `git add .`，只 add 已确认的变更文件
- 禁止 `--no-verify`，hook 失败须修复后重试
- 禁止自动 push
- 提交前必须展示提交信息首行；不要求用户额外确认 commit

**子 agent 调用**：无（全程交互确认，主 agent 内完成）

---

## 4) 知识库维护

### `f2s-kb-fix`

**作用**：根据用户指出的实现或规则错误修正代码，并**默认自动同步**知识库相关文档与索引。

**工作原理**：执行「定位→修复→同步」三步——先根据用户描述在知识库路由（manifest→topic→stock-docs）中定位相关上下文与代码位置，确认问题根因；修复代码后，自动检查 `topics/stock-docs/matchers` 中与该能力相关的描述是否因修复而需要更新，若有则原位修订（现行真值覆盖，不追加历史否定句）。「修代码必同步文档」是核心原则，避免知识库与实现漂移。

**使用场景**：

- 代码实现与技术方案不符
- 规则理解有误需要修正
- Bug 修复后需要同步文档

**变更追踪**：若 `changeTracking.fix: true`，执行前自动检查 `.task/todo.json` 并创建任务清单，完成后自动归档；跨会话可通过关键词续作（见 `f2s-task` 规则）。

**关联关系**：

- **前置**：问题发现（代码实现错误或规则偏差）
- **后续**：无（修复并同步完成即结束）
- **特点**：无需用户额外要求"请同步知识库"，自动完成

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成修复和知识库同步
- `subAgent: true`：代码子包（bug 修复）可外包给子 agent；文档子包（rules/skills/topics 文风类）默认主 agent 直接写，如拆则子 agent 仅输出 before/after diff 片段，不整文件重写；manifest 和 index 恒由主落盘

**职责划分**：


| 角色             | 职责                                                   |
| -------------- | ---------------------------------------------------- |
| 主 agent        | 定位问题根因、制定修复方案、落盘文风合规内容、校验知识库一致性                      |
| 子 agent（代码）    | 负责指定模块的代码 bug 修复，输出变更并报告影响范围                         |
| 子 agent（文档，可选） | 仅输出 before/after diff 片段，不整文件重写，不触碰 manifest 和 index |


**交叉验证（`switchAgentVerification: true` 时）**：

- 子 agent 落盘的代码变更 → 主 agent 校验修复正确性与知识库一致性
- 主 agent 落盘的知识库同步 → 子 agent 复核 topic/manifest 一致性（须 `subAgent: true` 且已拆出子任务，否则主 agent 内自验）
- 复核方与落盘方必须为不同 agent 实例

---

### `f2s-kb-feat`

**作用**：新增能力时补全实现与知识库；若能力已实现，则仅同步知识库。

**工作原理**：执行「判断→实现→入库」三阶段——先判断用户描述的能力在代码中处于「未实现/部分实现/已实现」哪种状态；未实现或部分实现时先补齐代码；最后走知识库同步：写 `stock-docs` 能力说明、生成或更新 `topics` 主题摘要、在 `manifest-routing` 和 `matchers` 注册路由映射。与 `f2s-kb-fix` 的区别：`kb-feat` 面向「新增」，`kb-fix` 面向「修正已有」。

**使用场景**：

- 新功能开发
- 存量功能需要补录知识库

**变更追踪**：若 `changeTracking.feat: true`，执行前自动检查 `.task/todo.json` 并创建任务清单，完成后自动归档；跨会话可通过关键词续作（见 `f2s-task` 规则）。

**关联关系**：

- **前置**：无（可直接触发）
- **后续**：无（实现+同步完成即结束）
- **特点**：自动同步知识库，无需用户额外要求

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成
- `subAgent: true`：代码子包（新增实现）可外包给子 agent；文档子包（rules/skills/topics 文风类）默认主 agent 直接写，如拆则子 agent 仅输出 before/after diff 片段；manifest 和 index 恒由主落盘

**职责划分**：


| 角色             | 职责                                                   |
| -------------- | ---------------------------------------------------- |
| 主 agent        | 确定能力边界与实现范围、落盘文风合规内容、最终校验知识库一致性                      |
| 子 agent（代码）    | 负责代码实现（接口、逻辑、数据层），输出实现清单                             |
| 子 agent（文档，可选） | 仅输出 before/after diff 片段，不整文件重写，不触碰 manifest 和 index |


**交叉验证（`switchAgentVerification: true` 时）**：

- 文档子 agent 落盘的 topic → 主 agent 校验与实现代码的能力描述一致性
- 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

---

### `f2s-kb-distill`

**作用**：从问答过程中提取可复用知识事实，自动入库；根据下钻深度与命中主题判断是新增主题还是补充既有主题。

**工作原理**：在 Agent 通过源码回答用户问题后，自动分析本轮对话中出现的可复用知识事实（核心机制、状态流转、返回值契约、配置开关影响、失败回退策略、模块边界等），判断是否已被知识库覆盖：未覆盖则新建或扩充 topic；已覆盖但不够细则补充细节。与 `f2s-kb-sync` 的区别：`sync` 适合批量同步多个能力；`distill` 专注于单次问答驱动的增量知识提取。

**执行挡位（agent 自动判，无命令参数）**：

| 挡位 | 跳过 | 适用场景 |
| --- | --- | --- |
| **轻量挡** | 步骤 2.1（下钻量化打分）/ 2.4（既有 topic 描述程度评估）/ 3（决策矩阵）/ 4.1（读近邻 topic 风格对齐） | 上游已给明确入库结论 + 本轮知识够轻 + 用户没推翻上游 |
| **严格挡** | 不跳，跑完整 6 步 | 上述三条任一不成立 |

**判挡 4 维度**（**全满足**才走轻量挡，否则严格挡）：

| 维度 | 条件 |
| --- | --- |
| 上游 `f2s-kb-feedback-closing` case | **case 2 或 case 3**（case 1 / 无收口块 → 严格挡） |
| 本轮 Read 业务源码文件数 | **≤ 3 个** |
| 本轮回答引用函数 / 类名数 | **≤ 5 个** |
| 用户追问是否否定上游结论 | **否** |

**业务源码定义**：路径**不在** `.claude/` / `.cursor/` / `.codex/` / `.Knowledge/` / `.task/` 这 5 个目录下的 Read 才计数。

**为什么这样划分**：

- 「上游已给明确结论」→ 决策矩阵不用跑，照搬「本轮将入库」概要即可
- 「本轮知识够轻」→ 不会撞「描述程度差 ≥ 2 级」事故（轻量补充天然和既有 topic 同级）
- 「用户没推翻」→ 上游结论本身没被否定

**步骤 5 / 6 永不省**：无论哪一挡，**路由 / matcher / index 同步**和**落盘 + 自检**都跑完整版——这是入库正确性的硬约束。

**使用场景**：

- 问答下钻源码后，发现 topic 不覆盖或不够细
- 由 `f2s-kb-feedback-closing` 规则自动建议调用
- 用户主动将本次问答结论沉淀进知识库

**关联关系**：

- **前置**：一次含有源码下钻的问答（自动从对话历史提取上下文）
- **后续**：无（入库完成即结束）
- **特点**：不改 `rules/skills` 配置根，只维护 `.Knowledge/`

**子 agent 调用**：无（单轮聚焦任务，主 agent 内全流程完成）

---

### `f2s-kb-sync`

**作用**：将会话中的已实现能力沉淀回知识库。可显式给出能力或零输入推断。

**使用场景**：

- 会话中已完成实现，需要补录知识库
- 从代码反向沉淀知识
- 定期知识库整理

**关联关系**：

- **前置**：无（可直接触发，或零输入推断）
- **后续**：无
- **特点**：先输出知识库更新大纲，用户确认后才写入
- **与 `f2s-kb-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成推断和同步
- `subAgent: true`：分步骤拆子——**步骤 1**（汇总推断）可拆子并行只读会话历史；**步骤 2**（用户确认大纲）必须在主 agent 完成；**步骤 3**（落盘同步）可拆子写 topic/matcher，但子落盘前须读近邻 2–3 个主题摘要做风格对齐；manifest 和 index 恒由主落盘

**职责划分**：


| 角色          | 职责                                                      |
| ----------- | ------------------------------------------------------- |
| 主 agent     | 输出大纲并确认、单点落盘 manifest 和 index、最终验收                      |
| 子 agent（汇总） | 只读会话历史、推断能力点、生成结构化更新大纲片段                                |
| 子 agent（同步） | 按大纲写 topic/matcher，落盘前加载近邻主题摘要对齐风格，不触碰 manifest 和 index |


**交叉验证（`switchAgentVerification: true` 时）**：

- 同步子 agent 落盘的 topic/matcher → 主 agent 校验跨 topic 路由完整性与 `includeAny` 关键词覆盖
- 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

---

### `f2s-kb-merge`

**作用**：解决 Git 合并后的编辑器上下文冲突。可选传入冲突文件路径。

**工作原理**：按文件类别分层处理冲突——将冲突文件分为「可安全自动合并」（index、manifest、matchers 等结构化文件，取并集或最新版本）和「须用户确认」（实现代码、业务规则等语义文件）两类。对前者自动 resolve，对后者生成分类对照表（ours/theirs 摘要 + 建议）并罗列差异，等待用户逐项裁决。核心设计思想：知识库元数据可自动化，业务语义不可擅自裁定。

**使用场景**：

- Git merge/rebase 后出现上下文冲突
- 多人协作导致知识库文件冲突
- 分支合并后需要统一知识库状态

**关联关系**：

- **前置**：Git 合并产生的冲突
- **后续**：无（冲突解决即结束）
- **特点**：实现侧冲突仅罗列待用户确认

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内分析与解决冲突
- `subAgent: true`：可拆子做冲突扫描与分类对照表（`file / category / ours_summary / theirs_summary / recommendation` 五字段）；子不得自行合并文件；主 agent 按策略落盘、处理实现侧决策、完成验收

**职责划分**：


| 角色      | 职责                                  |
| ------- | ----------------------------------- |
| 主 agent | 按策略落盘合并结果、处理实现侧冲突决策、验收              |
| 子 agent | 仅做冲突扫描与分类，按五字段 schema 交付对照表，不自行合并文件 |


---

### `f2s-kb-migrate`

**作用**：将旧版知识库（`docs-index.md` + `rules/` 模式）按主题迁移到 `.Knowledge/` 结构。

**工作原理**：以旧版 `docs-index.md` 和 `rules/main.md(c)` 为「索引线索」，递归识别所有被引用的业务规则和技能文件，按主题粒度重新组织到 `.Knowledge/` 的 `topics/stock-docs/req-docs` 三层结构中。迁移完成后落盘 `migration-report.md`（对照表 + 拟删路径），待用户确认后清理旧文件。本质是一次性的结构重组，将分散的规则/文档归并为统一知识库。

**使用场景**：

- 旧项目升级到 Flow2Spec 新版
- 存量知识库需要结构化整理

**关联关系**：

- **前置**：旧版知识库（`docs-index.md`、`rules/`、`skills/`）
- **后续**：`f2s-kb-upgrade`（**流程 V1** 旧库须先 migrate 再 upgrade；**现行库 V2+**（含 npm v3.x）见 upgrade 技能步骤 0）
- **流程**：
  1. 以 `docs-index.md` + `rules/main.md(c)` 为主索引
  2. 全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-`* 包技能）
  3. 全量迁移 `stock-docs`/`req-docs`
  4. 落盘 `.Knowledge/migration-report.md`
  5. 用户确认后删除已迁旧的文件

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内逐主题迁移
- `subAgent: true`：子只做搬运 + migration-report 草案片段（以 patch 形式交付）；状态文件（migration-report.md、删除执行记录）由主 agent 唯一落盘；主 agent 主导删除清单确认与删除闭环

**职责划分**：


| 角色      | 职责                                            |
| ------- | --------------------------------------------- |
| 主 agent | 制定迁移规划、合并迁移结果、落盘 migration-report、主导删除确认与执行闭环 |
| 子 agent | 负责指定主题的搬运与草案片段生成（patch 形式），不写状态文件、不写删除执行记录    |


**交叉验证（`switchAgentVerification: true` 时）**：

- 子 agent 迁移落盘的主题 → 主 agent 校验迁移完整性（旧路径是否全量覆盖、主题边界是否重叠）
- 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

---

### `f2s-kb-upgrade`

**作用**：知识库模板升级。对齐 manifest-routing + matchers 分片。

**工作原理**：通过「版本分流 + init 代跑」实现升级——先检测当前知识库属于 V1（旧结构，需先 migrate）还是 V2+（已有 `.Knowledge`），V1 走 migrate 后再 init，V2+ 直接代跑 `flow2spec init` 进行包级结构增量对齐（补齐新模板、升级 manifest schema、对齐 matchers 分片格式）。升级后重读 SKILL.md 判断是否需要重跑某些步骤。与单独 `init` 的区别：`kb-upgrade` 包含版本判断和重跑逻辑，`init` 仅做一次性结构补齐。

**使用场景**：

- flow2spec 包版本升级后，升级项目知识库模板
- 旧项目升级到最新结构
- 项目使用 `locale` 模板语言时，默认沿用 `flow2spec.config.json.locale`；未配置则按 `zh-CN` 补齐
- CLI 在交互式 `flow2spec version` / `flow2spec init` 中发现 npm 有新版本后，会提示先 `flow2spec update`，再在 Agent 对话中执行本技能
- Cursor 通过 `.cursor/hooks.json` 在 `sessionStart` 自动检测到知识库版本落后后，会提示执行本技能
- Codex 通过 `.codex/hooks.json` 在 `SessionStart` 自动检测到知识库版本落后后，会提示执行本技能（首次或变更后需在 Codex `/hooks` 中信任）

**关联关系**：

- **前置**：`f2s-kb-migrate`（V1 流程）或已存在的 `.Knowledge/`
- **包含**：内部会调用 `flow2spec init` 进行结构对齐
- **注意**：单独的 `flow2spec init` **不是**升级命令

**流程差异**（技能内分流代号，**不等于** npm 包主版本号）：

- **V1**：先 `f2s-kb-migrate` 再代跑 `flow2spec init`
- **现行库（V2+）**：已稳定 `.Knowledge` + `manifest-routing` 时，代跑 `flow2spec init` 以对齐 manifest-routing + matchers 分片（**含 Flow2Spec npm v3.x 等**，详见 `skills/f2s-kb-upgrade/SKILL.md` 步骤 0）

**子 agent 调用**：

- `subAgent: false`（默认）：主 agent 内完成升级
- `subAgent: true`：子 agent 仅承接 shell 命令执行（代跑 `flow2spec init`），不承担知识库正文落盘；以下步骤主 agent 不可下放：版本分流（V1 / 现行库 V2+）、init 后重读 SKILL.md 并判断是否整技能重跑、步骤 3b index.md 融合、校验摘要输出

**职责划分**：


| 角色      | 职责                                                                            |
| ------- | ----------------------------------------------------------------------------- |
| 主 agent | 版本分流、init 后重读并判断重跑、步骤 3b index.md 融合、校验摘要；落盘 manifest-routing.json 和 index.md |
| 子 agent | 仅代跑 `flow2spec init` 等 shell 命令，不落盘知识库内容                                      |


**交叉验证**：本技能不绑定交叉校验，落盘侧自验。

---

## 5) 规则说明

以下不是技能命令，而是通过触发词激活的规则，用于辅助指导 Agent 的行为。


---
---

### `f2s-task`

**触发词**：changeTracking、变更追踪、任务追踪、续作、继续上次任务

**作用**：变更追踪规则（`alwaysApply`）。当对应技能的 `changeTracking.`* 为 `true` 时，在技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。

**工作原理**：基于「磁盘 checkpoint + 关键词匹配」实现跨会话状态持久化——每个活跃任务在 `.task/active/<name>/task.md` 中以 checkbox 记录进度（`[ ]`/`[x]`），`todo.json` 作为活跃任务索引。新会话开始时，规则自动将用户首条消息与各任务的 `keywords` 做模糊匹配：命中则加载 `task.md` 剩余步骤和 `linkedSkill` 对应的技能文件，恢复完整执行上下文。任务完成后移入 `completed/` 归档。核心设计：以文件系统而非对话记忆作为状态真值，对话中断不丢进度。

**生效范围**：


| 配置项                        | 对应技能                        |
| -------------------------- | --------------------------- |
| `changeTracking.feat`      | `f2s-kb-feat`               |
| `changeTracking.fix`       | `f2s-kb-fix`                |
| `changeTracking.implement` | `f2s-implement-tech-design` |


**跨会话续作**：新会话开始时若存在 `.task/todo.json`，自动将用户首条消息与各任务 `keywords` 匹配；命中则加载对应 `task.md` 及 `linkedSkill` 技能文件，展示剩余清单，提示是否继续；无命中则不打扰。

**规则位置**：`配置根/rules/f2s-task.`*

---


---
---

### `implement-tech-design`

**触发词**：按技术方案实现、implement-tech-design、根据方案实现

**作用**：根据 `req-docs/` 中的技术方案文档实现可运行代码。

**工作原理**：以「方案即合约」为核心约束——Agent 以 `req-docs/` 中的技术方案为唯一编码依据，按「理解方案→输出任务列表→提问确认→逐步实现→输出待完成列表」的强制六步流水线执行。任务列表和实现前提问是不可跳过的门禁，确保不会在理解偏差的情况下动手编码。与 `f2s-req-plan` 的区别：本规则是轻量单线程编码驱动，不强制创建 `.task/` 追踪（除非 `changeTracking.implement: true`）。

**变更追踪**：若 `changeTracking.implement: true`，在步骤 2.5 输出任务列表后同步写入 `.task/active/<task-name>/task.md`；步骤 5 收尾时归档任务。

**使用场景**：

- 技术方案已就绪，需要按方案编码
- 方案变更后需要同步更新代码

**关联关系**：

- **前置**：`.Knowledge/req-docs/<技术方案>.md`（通过 `f2s-req-tech` 或手动放置）
- **规则位置**：
  - Cursor：`.cursor/rules/f2s-implement-tech-design.mdc`
  - Claude：`.claude/rules/f2s-implement-tech-design.md`
  - Codex：`.codex/AGENTS.md` + `.codex/topics/f2s-implement-tech-design.md`

**执行流程**（规则强制）：

1. 输入标准化
2. 理解方案与上下文
3. **输出实现任务列表**（必做，不可跳过）
4. **实现前提问**（必做，不可跳过）
5. 按任务列表实现
6. **输出待完成列表与实现后提醒**（必做）

**子 agent 调用**：无（规则驱动编码，主 agent 内完成全流程）

---

## 6) 子 Agent 配置说明

通过项目根 `flow2spec.config.json` 控制。默认值：`subAgent=false`、`switchAgentVerification=false`、`changeTracking.feat=true`、`changeTracking.fix=false`、`changeTracking.implement=true`。

### 多端如何「看到」配置（与下文字段表配合）

`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude SessionStart 摘要 + PreToolUse 守门 / Codex SessionStart 摘要 + AGENTS 字段语义表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [设计说明 § 四、5.1](./设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./使用说明.md)`。

### `subAgent` 字段


| 取值          | 行为                             |
| ----------- | ------------------------------ |
| `false`（默认） | 所有 `f2s-*` 技能在主 agent 内完成      |
| `true`      | 部分技能可按正文约定使用子 agent（大规模并行处理场景） |


### `switchAgentVerification` 字段


| 取值          | 行为                                                                                            |
| ----------- | --------------------------------------------------------------------------------------------- |
| `false`（默认） | 落盘侧自验：谁落盘谁验                                                                                   |
| `true`      | 技能正文明确写出该步骤时，启用交叉校验：子 agent 落盘 → 主 agent 验；主 agent 落盘 → 子 agent 验（须 `subAgent: true` 且已拆出子任务） |


### `changeTracking` 字段

嵌套对象，各技能子项独立控制：

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


| 子项          | 对应技能                        | 效果                      |
| ----------- | --------------------------- | ----------------------- |
| `feat`      | `f2s-kb-feat`               | 执行前创建任务清单，完成后归档，支持跨会话续作 |
| `fix`       | `f2s-kb-fix`                | 同上                      |
| `implement` | `f2s-implement-tech-design` | 同上                      |


> `f2s-req-plan` 不受此配置约束，始终创建任务清单。旧版布尔值（`"changeTracking": true/false`）向下兼容，自动展开为三项全开/全关。

完整原则与设计意图见 [体系与原理 § 4. Agent 执行模型](./体系与原理.md)。

---

## 7) 快速参考

典型工作场景与完整链路见 [使用说明 § 三、典型工作场景](./使用说明.md)。

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

---

相关文档：

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