@double-codeing/flow2spec 2.2.3 → 3.0.8

package/templates/skills/f2s-kb-migrate/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: f2s-kb-migrate
+description: 旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移
+---
+
+> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含：
+> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`
+> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs`
+>
+> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。
+>
+> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。
+
+## 编排（主 / 子 agent）
+
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
+- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。
+- **主必控**：
+  - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）；
+  - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加；
+  - **删除清单确认**与闭环收尾必主完成。
+- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。
+- 默认落盘侧自验；本 SKILL 不绑定交叉校验。
+
+# f2s-kb-migrate（旧版知识库 -> 新版知识库）
+
+## 与 `f2s-kb-upgrade` 为何并存
+
+| 技能 | 解决的问题 |
+| --- | --- |
+| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 |
+| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 |
+
+- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。
+- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。
+
+**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步** `templates/skills/` 中的内容。
+
+## 本命令做什么（对外口径）
+
+把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。
+
+必须覆盖的对象：
+
+1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。
+2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。
+3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。
+4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。
+
+对“索引未覆盖”的对象：
+
+- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。
+- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。
+
+迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）：
+
+- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。
+- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。
+- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。
+- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。
+
+**用户确认的含义（重要）**：
+
+- **不是**询问「要不要做清理」；清理是流程的一部分。
+- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能：
+  - 回复「**确认清单**」按当前清单执行删除；或
+  - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。
+- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。
+
+## 适用场景
+
+- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。
+- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。
+- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。
+
+## 输入
+
+- 可选输入：
+  - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`）
+  - 旧版 `index-doc.md`（或 `docs-index.md`）路径
+  - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`）
+  - 旧版需求文档目录（如 `req-docs/`、`docs/req/`）
+  - 迁移范围（全部主题 / 指定主题）
+- 不提供时，先在仓库中定位上述文件并向用户确认。
+
+## 断点续迁状态文件（必须启用）
+
+- 状态文件路径：`.Knowledge/.migrate-state.json`
+- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。
+- 初始化时机：用户确认“开始迁移”后立即创建。
+- 结束时机：
+  - 全部迁移完成且用户确认结束：删除状态文件。
+  - 用户主动“停止”：保留状态文件，等待下次恢复。
+- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。
+
+建议字段（最小集）：
+
+```json
+{
+  "version": "1",
+  "status": "running",
+  "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup",
+  "topicQueue": [],
+  "topicDone": [],
+  "bizRuleQueue": [],
+  "bizRuleDone": [],
+  "bizSkillQueue": [],
+  "bizSkillDone": [],
+  "stockQueue": [],
+  "stockDone": [],
+  "reqQueue": [],
+  "reqDone": [],
+  "pendingManual": [],
+  "failed": [],
+  "notes": [],
+  "updatedAt": "ISO-8601"
+}
+```
+
+更新规则（必须执行）：
+
+1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。
+2. 收到“重试 <topic|file>”时，先回滚该项状态，再执行重试。
+3. 收到“继续”时，优先读取状态文件，从未完成队列继续。
+4. 收到“停止”时，写入 `status=paused` 并结束本轮。
+5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。
+
+## 强制流程（分阶段执行）
+
+### 步骤 1：读取旧版映射
+
+1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。
+2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。
+3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）：
+   - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名）
+   - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)`
+4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。
+5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。
+6. 生成待迁移清单并展示给用户确认：
+   - 主题清单（去重、排序）
+   - 业务规则文件清单（`bizRuleQueue`）
+   - 业务技能目录清单（`bizSkillQueue`）
+   - `stock-docs` 文件清单
+   - `req-docs` 文件清单
+7. 文档分类口径（必须明确）：
+   - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs`
+   - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs`
+   - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移
+8. 计算“索引外候选”（`orphans`）：
+   - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件
+   - `bizSkillQueue` 中未被索引映射覆盖的目录
+   - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。
+9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。
+
+### 步骤 2：逐主题迁移（结构层核心）
+
+对每个主题按以下顺序执行：
+
+1. 汇总该主题旧资料：
+   - 相关 `rules/*.md(c)`（业务规则）
+   - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件）
+   - 索引映射中的**业务文档**路径
+   - **不得**包含 `skills/f2s-*` 下任何文件
+2. 生成或更新 `.Knowledge/topics/<topic>.md`：
+   - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。
+   - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。
+3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。
+4. 按需更新路由清单：
+   - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`fallbackTopic`
+   - `.Knowledge/matchers/<matcherId>.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致）
+5. 输出本主题迁移摘要并**暂停**，提示用户：
+   - 回复“继续”迁移下一个主题
+   - 或回复“停止”终止本轮
+   - 或回复“重试 <topic>”重做当前主题
+
+> 未收到“继续”前，不得迁移下一个主题。
+> 每完成一个主题，必须先更新状态文件再进入等待。
+
+### 步骤 3：迁移 `stock-docs`（文档层）
+
+当步骤 2 全部完成后，执行：
+
+1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/<relative-path>`，不做平铺。
+2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。
+3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。
+4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。
+
+> 未收到“继续”前，不得迁移下一个文件。
+> 每完成一个文件，必须先更新状态文件再进入等待。
+
+### 步骤 4：迁移 `req-docs`（文档层）
+
+当 `stock-docs` 阶段完成后，执行：
+
+1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/<relative-path>`，不做平铺。
+2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。
+3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。
+4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。
+
+> 未收到“继续”前，不得迁移下一个文件。
+> 每完成一个文件，必须先更新状态文件再进入等待。
+
+### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认）
+
+当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。
+
+#### 5.0 迁移报告（必选：写入项目 Markdown）
+
+1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。
+2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）：
+   - **「迁移对照表」**：
+     - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/<dir>`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/<topic>.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。
+     - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。
+     - **`req-docs`**：同上。
+   - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。
+3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。
+4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。
+5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。
+
+> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。
+
+#### 5.1 总摘要（对话内，可与报告摘要一致）
+
+- 已迁移主题列表
+- 新增/更新的 `.Knowledge` 文件
+- 已迁移 `stock-docs` 文件
+- 已迁移 `req-docs` 文件
+- 未迁移或失败项
+
+#### 5.2 必选清理阶段（删除清单确认，不得跳过）
+
+1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含：
+   - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则）
+   - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`）
+   - 旧版 **`docs-index.md` / `index-doc.md`**
+   - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。
+2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。
+3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。
+4. 收尾完成后处理状态文件：
+   - 本轮完整完成：删除 `.Knowledge/.migrate-state.json`
+   - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因
+
+## 输出摘要格式（建议）
+
+```markdown
+## 主题迁移完成：<topic>
+
+### 来源
+- rules: <旧路径...>
+- 业务文档: <索引映射中的文档路径...>
+- 映射: <docs-index / index-doc 行或文档名>
+
+### 已写入
+- .Knowledge/topics/<topic>.md
+- .Knowledge/index.md（更新 <x> 行）
+- .Knowledge/manifest-routing.json（更新字段：...）
+- .Knowledge/matchers/<id>.json（更新 `includeAny` 等：...）
+
+### 下一步
+- 回复“继续”迁移下一个主题
+- 回复“停止”结束迁移
+```
+
+```markdown
+## 文档迁移完成：<stock-docs|req-docs>/<file>
+
+### 来源
+- source: <旧路径...>
+
+### 已写入
+- .Knowledge/<stock-docs|req-docs>/<relative-path>
+
+### 下一步
+- 回复“继续”迁移下一个文件
+- 回复“停止”结束迁移
+```
+
+## 约束
+
+- 必须逐主题确认，不可批量跳过确认直接全量迁移。
+- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。
+- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。
+- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。**
+- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。
+- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。
+- 未完成文档迁移前，禁止删除旧文档目录。
+- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。
+- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。
+- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。
+- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。
+- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。
+
+## 迁移报告模板（落盘 `migration-report.md` 时建议结构）
+
+以下骨架可直接复制后填空；路径均为相对项目根。
+
+```markdown
+# 知识库迁移报告
+
+- **生成时间（ISO-8601）**：<...>
+- **配置根（如 `.cursor/`）**：<...>
+
+## 迁移对照表
+
+### 主题（旧来源 → 新路径）
+
+| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 |
+| --- | --- | --- |
+| <id> | <...> | `.Knowledge/topics/<id>.md` |
+
+### stock-docs（源 → 目标）
+
+| 源路径 | 目标路径 | 备注 |
+| --- | --- | --- |
+| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 |
+
+### req-docs（源 → 目标）
+
+| 源路径 | 目标路径 | 备注 |
+| --- | --- | --- |
+| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 |
+
+## 拟删除路径清单（默认全选；与对话内清单一致）
+
+- [ ] `<路径>`（`rules/` 下逐文件）
+- [ ] `<路径>`（业务 `skills/<dir>`，不含 `f2s-*`）
+- [ ] `.cursor/docs-index.md`（或实际路径）
+- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录
+
+## 用户排除项（如有）
+
+- （无则写「无」）
+
+## 失败或未迁移项（如有）
+
+- （无则写「无」）
+
+## 删除执行记录
+
+（仅在执行物理删除后追加：时间、已删列表、未删及原因）
+```
+
+## 完成后自检
+
+1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。
+2. `manifest.topics[].path` 是否都存在。
+3. `index` 是否可定位到每个已迁移主题。
+4. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。
+5. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。
+6. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。
+7. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。
+8. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。
+9. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。
+10. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。
+11. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。
+12. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。

package/templates/skills/f2s-kb-sync/SKILL.md

@@ -1,88 +1,109 @@
 ---
 name: f2s-kb-sync
-description: 可将「Agent 已实现的能力」写清传入，也可零输入；零输入时由 Agent 根据当前上下文推断用户与项目关心的能力，先输出知识库更新大纲、确认后写入 Rules/Skills/索引以注入上下文；触发：f2s-kb-sync、全局同步、知识库同步、已实现能力
+description: 可显式给出能力或零输入推断；先输出知识库更新大纲，确认后写入 topics/index/manifest；触发：f2s-kb-sync、全局同步、知识库同步、已实现能力
 ---
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
 
-# f2s-kb-sync（知识库同步 · 先大纲后写入）
+> 执行口径：本技能只维护 `.Knowledge`，默认不改配置根 `rules/skills`。
 
-在用户要执行 **f2s-kb-sync** 时：把**用户本次描述**、**当前 Agent / 会话角色相关描述**、**与项目相关的功能与约定**、以及**要注入上下文的「能力」集合**（见下文「输入」）整理为对**知识库**的更新方案；**必须先输出「更新大纲」并征得用户明确确认**，再写入 **`rules/`**、**`skills/`**（在既有结构上**增补或修订**，不无故整目录删除模板技能）、**`docs-index.md`**、**`main.mdc`** 等，使这些能力在后续对话中可被 **Rule / Skill / 索引** 加载，即**注入到 Agent 可用上下文**。可选在 **`stock-docs/`** 增加简短摘录类 MD 作为索源（若需要且大纲已列明）。
+## 编排（主 / 子 agent）
 
-**知识库**在本技能中指：供 AI 持续使用的**项目侧上下文产物**——主要是 **`rules/*.mdc`**、**`skills/*/SKILL.md`**（项目自增的 skill 或既有 skill 的正文补丁）、**`docs-index.md`**、**`rules/main.mdc`**，以及为索源服务的 **`stock-docs/*.md`**（按需）。
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。
+- 步骤 1（素材汇总）：`subAgent=true` 时可拆子并行，仅只读汇总，不得落盘。
+- 步骤 2（大纲 + 用户确认）：必主 agent 完成，确认权不可下放子 agent。
+- 步骤 3（落盘）：`subAgent=true` 时可按已确认大纲拆子逐项落盘；硬约束：子落盘前必须前置加载近邻 2–3 个主题的开头摘要，做叙事风格对齐。
+- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 单点落盘，禁止下放。
+- 校验：默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。
 
----
+# f2s-kb-sync（先大纲后写入）
 
-## 输入（均可选；能力来源二选一或组合）
+## 输入（可选）
 
-### 1）用户指定「Agent 已实现的能力」（可选）
+1. 用户显式给出“已实现能力列表”
+2. 零输入：由 Agent 基于当前上下文推断
+3. 辅助材料：`@` 文件、需求文档、架构说明等
 
-- 用户可在消息中**明确列出**当前 Agent（或本会话）**已经具备 / 已经实现**的能力：例如条目列表、模块名、命令或技能名、可回答的问题类型、已接好的 MCP/工具等。
-- 若用户写了这部分：将其视为**高优先级事实**，写入大纲中的 **「用户指定的能力清单」**，与下文推断结果**对齐、合并、去重**；冲突时以**用户本次明确文字**为准。
+## 强制流程（不可颠倒）
 
-### 2）零输入或仅少量补充（可选）
+### 步骤 1：收集素材（只读）
 
-- 用户**可以不输入任何内容**（或只 `@` 个别文件、只说一句「同步一下」等）。
-- 此时 **Agent 必须自行判断**：在当前上下文（**本轮对话**、**用户已打开或引用的文件**、**工作区与项目结构**、**已有 `docs-index` / `main` / rules / skills**）下，**用户与项目最关心、最常被依赖的能力**是哪些。
-- 推断要求：
-  - 给出**简短依据**（例如：来自哪几条用户原话、哪个目录、哪份文档标题），写进大纲的 **「Agent 推断：关心的能力」** 小节，便于用户核对。
-  - **宁缺毋滥**：只纳入与后续协作强相关、可写成可维护规则/技能条目的能力；忌泛泛「会写代码」类空话。
-  - 若上下文极薄、无法合理推断：在大纲中如实写「推断受限」，并列出**为完成同步请用户补充的最少信息**（一两问即可），仍**先出大纲再请确认**，不要无确认写库。
+- 汇总用户目标、范围、优先级
+- 汇总已实现能力（用户指定 + Agent 推断）
+- 对照现有知识库：
+  - `.Knowledge/topics/`
+  - `.Knowledge/index.md`
+  - `.Knowledge/manifest-routing.json`
+  - `.Knowledge/matchers/*.json`（与路由中 `matcherPath` 对应的分片）
+  - `.Knowledge/stock-docs/`
 
-### 3）其它常见输入（仍可选）
+### 步骤 2：输出《更新大纲》（必须）
 
-- **用户自然语言**：本次想同步什么、强调哪些模块或约定、对 Agent 的期望等。
-- **路径/附件**：如 **`配置根/req-docs/xxx.md`**、**`配置根/stock-docs/xxx.md`**、README、架构说明等；用户也可用 `@` 引用文件。
+大纲至少包含：
 
----
+1. 同步目标
+2. 能力清单（用户指定 / Agent 推断 / 合并结果）
+3. 信息来源
+4. 拟改文件清单（精确到路径）
+5. 不改动范围
+6. 等待用户确认提示
 
-## 执行步骤（顺序不可颠倒）
+> 未确认前禁止落盘修改。
 
-### 步骤 1：收集素材（只读与归纳，不写知识库）
+### 步骤 3：确认后写入
 
-1. **能力集合**（本步核心）  
-   - 若用户**已指定**「Agent 已实现的能力」：逐条收录，并标为 **「用户指定」**。  
-   - 若用户**未指定**或指定不全：**由 Agent 根据当前上下文推断**「用户与项目关心的能力」，标为 **「Agent 推断」**，每条附**一句依据**（对话原句 / 路径 / 文件角色）。  
-   - 合并为本次要注入知识库的 **「目标能力列表」**（去重；用户指定与推断冲突时以用户指定为准）。
-2. **用户侧**：整理用户消息中的目标、范围、术语、约束、验收或优先级；若用户声明了「当前 Agent 身份/模式/回答风格」等，单独摘录为「Agent 描述」小节素材。
-3. **项目侧**（在合理范围内浏览/检索，避免全仓无目的扫描）：例如 **`README`**、**`package.json`**、顶层目录、与对话相关的源码路径；读取 **`配置根/docs-index.md`**、**`配置根/rules/main.mdc`**（若存在）以了解现有知识库结构，避免重复或冲突。
-4. **功能与约定**：围绕 **「目标能力列表」**，归纳**业务能力、模块边界、接口/MQ/配置习惯**等（只写从文档与代码中可支撑的结论；不确定处在大纲标「待确认」，不写进最终落库正文，除非用户在大纲确认中一并认可）。
+> 硬约束：若启用拆子，子 agent 落盘前必须读取近邻 2–3 个主题的开头摘要，确保叙事风格一致；`manifest-routing.json` 与 `.Knowledge/index.md` 由主 agent 单点落盘，子 agent 无写权。
 
-### 步骤 2：输出「更新大纲」（必须；此步结束前禁止写任何知识库文件）
+按大纲逐项更新：
 
-向用户输出一份清晰的 **Markdown《知识库更新大纲》**，建议包含：
+- `.Knowledge/topics/*.md`
+- `.Knowledge/index.md`（同步主题路由表的“关联文档（摘要）”列）
+- 路由清单（按需）
+- `.Knowledge/stock-docs/*.md`（按需补充索源文档）
 
-1. **同步目标**：一两句话说明本次更新解决什么问题（含：要把哪些**能力**注入可加载上下文）。
-2. **能力清单**（必填小节）：  
-   - **用户指定的能力**（若无则写「无」）；  
-   - **Agent 推断：用户与项目关心的能力**（若无则写「无」或「推断受限」+ 需补充的问题）；  
-   - **合并后的目标能力列表**（最终将以知识库条目支撑的能力）。
-3. **信息来源**：列出已依据的用户原话要点、Agent 描述要点、项目文件/路径（不必贴全文）。
-4. **拟变更清单**（逐项、可到路径级）：
-   - **rules**：拟新建或修改的 `.mdc` 路径 + 每处「改什么 / 为什么」。
-   - **skills**：拟新建子目录与 `SKILL.md` 或拟修改的现有 `SKILL.md` + 每处「改什么 / 为什么」。
-   - **docs-index / main**：是否增删行、是否更新模块一览等。
-   - **stock-docs**（可选）：是否新增摘录类 MD、文件名建议、是否后续再走 **f2s-ctx-build**（若需从终稿生成大套 Rules/Skills，应在大纲中单独列为可选阶段）。
-5. **不做的事**：明确写出本次**不会**改动的范围（如业务源码、依赖版本、未在大纲中的文件），避免用户误解。
-6. **确认提示**：用单独一段请求用户回复，例如：「请回复 **确认** 按大纲执行」「或回复修改意见（指出要删/要改的条目）」。
+### 步骤 4：收尾摘要
 
-**禁止**：在用户确认前创建、覆盖或删除 **`配置根/rules/`**、**`配置根/skills/`** 下任何文件，以及 **`docs-index.md`**、**`main.mdc`**（本步骤仅输出大纲）。
+- 列出已修改路径与目的
+- 列出未执行项与原因
 
-### 步骤 3：用户确认后再写入（注入上下文）
+## 输出摘要格式（建议）
 
-- 仅当用户**明确确认**大纲（或确认经用户要求修订后的新版大纲）后，再按大纲**逐项**实施写入。
-- **注入的含义**：通过新增/更新 **`rules/`**、**`skills/`**、**`docs-index.md`**、**`main.mdc`**（及按需 **`stock-docs/`**），使 **「目标能力列表」** 在后续会话中以 **globs / description / 索引** 等形式被 Cursor（或当前工具）加载，而不是只在当轮对话记忆里存在。
-- 写入 **`rules/`**、**`skills/`** 时遵守项目既有风格与 frontmatter；若涉及从 **`stock-docs/`** 链出或写 **sourceDoc**，遵守 **`f2s-ctx-build`** 技能中的「文档路径与链接约定」（参见 `配置根/skills/f2s-ctx-build/SKILL.md`）。
-- 若大纲列有「先 **f2s-doc-final** / **f2s-ctx-build**」等后续技能：在本技能完成**已确认**的写入后，再引导用户按需触发对应技能，**不要**在本技能内跳过确认擅自执行长链路。
+```markdown
+## 知识库同步结果
 
-### 步骤 4：收尾摘要
+### 已确认能力范围
+- <能力1>
+- <能力2>
 
-- 列出已写入/修改的文件路径与一句话说明。
-- 若有大纲中未执行项（如用户缩小范围），说明原因。
+### 已修改文件
+- .Knowledge/topics/<topic>.md：<修改说明>
+- .Knowledge/index.md：<修改说明>
+- .Knowledge/manifest-routing.json：<修改说明或“未改动”>
+- .Knowledge/matchers/<id>.json：<修改说明或“未改动”>
+- .Knowledge/stock-docs/<doc>.md：<修改说明或“未改动”>
 
----
+### 未执行项
+- <项>：<原因>
+```
+
+## 复杂场景示例
+
+用户仅说“/f2s-kb-sync 同步一下”，未给能力清单。
+
+- 步骤 1 先做最小推断（例如支付、订单两个高频能力），并给出推断依据。
+- 步骤 2 必须输出大纲并等待“确认”；未确认前禁止写入任何 `.Knowledge` 文件。
+- 用户确认后只执行大纲内条目；若用户中途缩小范围，未执行项写入收尾摘要。
+
+## 约束
+
+- 先大纲，后写入
+- 小步增补，避免整文件重写
+- 同主题优先原位更新
+- `index.md` 每个主题需包含 `stock-docs/req-docs` 的摘要级**可点击 Markdown 链接**（格式：`[标题](相对路径)`，1-3 条，允许写“无”）
+- 不改配置根 `rules/skills`
 
-## 约束与注意
+## 完成后自检
 
-- **先大纲、后写入**：无确认则无写库；用户仅说「继续」而未确认大纲时，须再次展示大纲要点并请其明确确认。
-- **克制修改**：优先**小步增补**；避免一次性重写 `main.mdc` 或整表 `docs-index`；与 Flow2Spec 模板自带的 **`skills/`** 工作流文件冲突时，优先**新增**项目专用 rule/skill 文件，而非覆盖模板包名同名文件——除非大纲已写明且用户确认。
-- **与 f2s-kb-fix / f2s-kb-feat 区分**：本技能侧重「会话与项目现状 → 知识库对齐」；针对**已指明的规则违反**用 **f2s-kb-fix**；针对**新增能力**用 **f2s-kb-feat**。
+1. 是否存在未确认即写入（必须为否）。
+2. topic 文件与 index 行是否一一对应，且“关联文档（摘要）”已同步更新。
+3. manifest 中 `topics` / `taskToTopicRules` / `topicDependencies` 是否仍引用有效路径。
+4. 是否误改配置根 `rules/skills`（必须为否）。
+5. 步骤 2 大纲 + 用户确认未下放子 agent；步骤 3 子落盘前已加载近邻 2–3 主题摘要；manifest / index 由主单点落盘。