@double-codeing/flow2spec 2.2.2 → 3.0.7

package/templates/skills/f2s-git-commit/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: f2s-git-commit
+description: 代码写完后提交 Git：检查变更与知识库覆盖；生成带 emoji 首行的提交说明后**可直接 commit**（须在当条回复展示首行，不要求用户单独确认 commit）；**git pull 类拉取须用户先确认**。触发：f2s-git-commit、提交代码、git commit、帮我提交
+---
+
+> 执行口径：本技能代用户执行 git 操作；不使用 `git add -A` / `git add .`，不跳过 hooks（`--no-verify`），不自动 push。**`git pull` / `git fetch` 合并入本地前必须取得用户对「拉取」的明确确认**；`git commit` 不要求单独一轮「确认」交互（见步骤 3–4）。
+
+## 编排（主 / 子 agent）
+
+- `subAgent` / `switchAgentVerification` 语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`。
+- 本技能全程在主 agent 完成（**pull 的确认**不可下放子 agent；`git commit` 不要求单独一轮用户确认，见步骤 3–4）。
+
+# f2s-git-commit（提交代码）
+
+## 强制流程
+
+### 步骤 1：读取变更（只读）
+
+```bash
+git status --short
+git diff HEAD
+```
+
+- 从 `git status --short` 区分三类文件：
+  - **Staged**：已 `git add`，前缀为 `M `、`A `、`D `（首列非空）
+  - **Unstaged**：已追踪但未 add，前缀为 ` M`、` D`（次列非空）
+  - **Untracked**：`??` 前缀，新文件尚未追踪
+- 若三类均为空（nothing to commit），直接告知用户并结束。
+
+**冲突检查（必须，先于一切）**：
+
+扫描所有变更文件内容，若任意文件包含 `<<<<<<<`、`=======`、`>>>>>>>` 冲突标记，立即终止并提示：
+
+```
+❌ 检测到未解决的 merge conflict：
+  - <文件路径>
+
+请先解决冲突后再提交。
+```
+
+### 步骤 2：知识库覆盖检查（必须）
+
+**先判断 `.Knowledge/` 是否存在：**
+
+- 若 `.Knowledge/manifest-routing.json` 不存在：跳过本步骤，在步骤 5 收尾提示「项目尚未初始化 Flow2Spec 知识库，建议运行 flow2spec init」，继续步骤 3。
+
+**存在时执行覆盖检查：**
+
+1. 从 `git diff HEAD` 及 untracked 文件路径推断本次变更涉及的**功能模块**（如：支付、订单、用户认证等）。
+2. 读取 `.Knowledge/topics/` 目录列表与 `.Knowledge/stock-docs/` 目录列表。
+3. 对比步骤 1 推断出的功能模块，判断对应文档是否已在知识库中登记。
+4. 得出结论：**已覆盖 / 部分覆盖 / 未覆盖**。
+
+> 判断粗粒度即可：有对应 topic 或 stock-docs 文档即视为已覆盖；若知识库为空或找不到相关文档则视为未覆盖。
+
+**未覆盖或部分覆盖时（必须提示）：**
+
+```
+⚠️  本次变更涉及以下能力尚未入知识库：
+  - <能力描述>
+
+建议在提交前同步知识库，可选：
+  A) 现在运行 f2s-kb-sync 补录，完成后自动继续提交流程
+  B) 先提交，稍后手动补录（输入 B 确认）
+  C) 取消本次提交（输入 C）
+```
+
+- 选 **A**：提示用户运行 `f2s-kb-sync` 或 `f2s-kb-feat` 补录；用户补录完成后在**同一会话声明已补录**或**再次触发本技能**时，从步骤 1 或步骤 3 继续（**不要求**为「继续 commit」单独打字确认，与步骤 3–4 一致）。
+- 选 **B**：记录未覆盖能力描述，在步骤 5 收尾提示中输出。
+- 选 **C**：终止本技能。
+
+### 步骤 3：生成提交信息草稿（必须）
+
+读取 `git diff HEAD`（内容过长时取前 300 行），基于实际变更内容生成提交信息。
+
+#### 首行格式（必须）：类型图标 + Conventional Commits
+
+**首行**须同时满足：
+
+1. **以一个 emoji 开头**（与下表 `type` 对应，**禁止**用多个装饰 emoji 堆叠）。
+2. 紧跟 **一个 ASCII 空格**，再写 **小写 `type`**、英文冒号 `:`、**一个空格**、**中文或英文简述**。
+3. **可选 scope**：使用 Conventional 的 `type(scope):`，紧跟在 `type` 之后、冒号之前，例如 `🐛 fix(auth): 修复登录态丢失`。
+4. 首行总长度建议 **≤ 72 个字符**（含 emoji；过宽时优先缩短描述）。
+
+**推荐模板（单行）**：
+
+```text
+<emoji> <type>[(scope)]: <简述>
+```
+
+无 scope 时省略括号段，例如：`🚀 feat: 简述`。
+
+**`type` → 首字符 emoji（固定选用下表，便于检索与发布说明）**：
+
+| `type` | emoji | 典型场景 |
+|--------|--------|----------|
+| `feat` | 🚀 | 新功能、对用户可见的能力增量 |
+| `fix` | 🐛 | 缺陷修复、线上/测试问题 |
+| `docs` | 📚 | 仅文档、注释、README、知识库正文类 |
+| `style` | 💄 | 纯格式、缩进、分号等不改变行为的排版 |
+| `refactor` | ♻️ | 重构、改名、无行为变化的结构调整 |
+| `perf` | ⚡ | 性能优化 |
+| `test` | 🧪 | 测试用例、测试桩、快照 |
+| `build` | 🏗️ | 打包、依赖、编译脚本、artifact |
+| `ci` | 👷 | CI 配置、流水线、自动化脚本 |
+| `chore` | 🔧 | 杂项、工具脚本、非 build/ci 的维护性改动 |
+| `revert` | ↩️ | 回滚某次提交 |
+
+**示例**：
+
+```text
+🚀 feat: 支持xxx活动缓存预热
+🐛 fix(coupon): 领券窗口边界条件错误
+📚 docs: 补充公共模块 QConfig 说明
+♻️ refactor: 提取拼团校验为独立函数
+🔧 chore: 升级 ESLint 配置
+```
+
+**正文（可选）**：第二行起可为列表或段落，**不要求**每行再加 emoji；若需条目，用 `- ` 即可。
+
+**用户已给出首行时**：若已含上表之一且 emoji 与 `type` 一致，**尊重用户文案**；若仅有 `type:` 无 emoji，**须补全 emoji** 再进入步骤 4。
+
+**与 `git commit` 的确认策略（必须）**：
+
+- 在**同一条 assistant 回复**中：**先**展示拟提交说明的**首行**（及可选正文），**随后立即**执行步骤 4（`git add` 逐项 + `git commit`）。**不要求**用户再回复「确认」才允许 commit。
+- 若用户在该轮对话中**已先写明**提交说明且合规，可直接使用并进入步骤 4，仍须在执行前**复述首行**再 commit。
+- 用户若明确表示「改提交说明 / 换一个 type」：改稿后仍在本策略下**展示即提交**，不增加「请回复确认」门槛。
+
+### 步骤 4：执行提交（展示说明后立即执行）
+
+根据步骤 1 的三类文件分别处理：
+
+```bash
+# 1. Unstaged 文件：需先 add
+git add <unstaged 文件列表>
+
+# 2. Untracked 文件：需先 add
+git add <untracked 文件列表>
+
+# 3. Staged 文件：已 add，无需重复操作
+
+# 执行提交
+git commit -m "<步骤 3 定稿的完整提交信息>"
+```
+
+- 禁止使用 `git add -A` / `git add .`，仅 add 步骤 1 中明确列出的文件。
+- 若 pre-commit hook 失败：输出完整错误信息，提示用户修复后重新触发本技能，**不**使用 `--no-verify` 绕过。
+- 若 commit 成功：读取 commit hash（`git rev-parse --short HEAD`）并进入步骤 5。
+
+### 步骤 5：收尾提示
+
+```
+✅ commit <hash> 完成
+   <提交信息首行>
+
+[若步骤 2 选了 B]
+📌 提醒：以下能力仍未入知识库，建议在合并前补录：
+  - <能力描述>
+  可运行：f2s-kb-sync 或 f2s-kb-feat
+
+[若跳过了步骤 2（.Knowledge 不存在）]
+💡 项目尚未初始化 Flow2Spec 知识库，如需接入可运行：flow2spec init
+```
+
+## 约束
+
+- 禁止使用 `git add -A` / `git add .`，只 add 已确认的变更文件。
+- 禁止 `--no-verify`，hook 失败须修复后重试。
+- 禁止 `--amend` 已推送的 commit，除非用户明确要求。
+- 禁止自动 push，commit 完成后停止。
+- 知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）。
+- **`git pull` / `git pull --rebase` / 会改写当前分支工作区内容的 `git fetch` 后续合并操作**：**必须**先向用户说明目的与风险，**取得用户对「拉取」的明确确认**（如用户回复「确认 pull」）后再执行；**禁止**为 commit 而顺带静默 pull。
+- **`git commit`**：**不要求**用户单独回复「确认」；但**禁止完全不展示**拟提交首行就执行 commit（须在当条回复中可见首行后再执行）。
+- 提交信息**首行**须符合步骤 3 的 **emoji + type** 格式（用户已合规给出时可保留）。
+- 存在 merge conflict 标记时必须终止，不得继续。
+
+## 完成后自检
+
+1. 步骤 1 是否检查了 merge conflict（必须为是）。
+2. 是否区分了 staged / unstaged / untracked 三类文件（必须为是）。
+3. 是否用了 `git add -A` / `git add .`（必须为否）。
+4. 知识库检查是否执行或有明确跳过理由（必须为是）。
+5. 步骤 3 是否基于 `git diff` 实际内容生成提交信息（必须为是，而非仅 `--stat`）。
+6. 执行 commit 前是否在当条回复中**展示了拟提交首行**（必须为是）；**不得**要求用户单独「确认 commit」才执行（与策略一致）。
+7. 提交信息**首行**是否为 `<emoji> <type>[(scope)]: <简述>` 且 emoji 与 type 与上表一致（合并 revert 等例外须在展示中说明）。
+8. 若 pre-commit 失败，是否跳过了 hook（必须为否）。
+9. 若步骤 2 选 B，收尾提示是否包含未补录提醒。
+10. 若步骤 2 选 A，是否在用户补录或再次触发后继续流程（**不要求**为继续 commit 单独要确认）。
+11. 若本流程中曾需要 `git pull`：是否在执行前取得用户对 **pull** 的明确确认（必须为是）；未涉及 pull 则标 N/A。

package/templates/skills/f2s-karpathy-guidelines/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: f2s-karpathy-guidelines
+description: Flow2Spec 内置的 Karpathy 式编码纪律：澄清假设、极简实现、手术式修改、可验证目标。默认由同名 topic 规则 alwaysApply 随 init 落盘；显式调用本技能时重申四条。
+license: MIT
+---
+
+# f2s-karpathy-guidelines
+
+`flow2spec init` 将 npm 包内 **`templates/rules/f2s-karpathy-guidelines.mdc`** 去 frontmatter 后写入 **`./.codex/topics/f2s-karpathy-guidelines.md`**（相对仓库根，**`alwaysApply`** 语义以源 `.mdc` 的 frontmatter 为准）。
+
+**显式使用本技能时**：在回复中简要重申并遵守以下四条（与 **`./.codex/topics/f2s-karpathy-guidelines.md`** 全文一致；冲突时以 **f2s 流程条令** 为准）。
+
+1. **先想清楚再写代码**：假设说清；多解并列；说不清就停、先问。
+2. **简单优先**：最少代码解决问题；无臆测功能/抽象/配置。
+3. **手术式修改**：只动任务相关行；不顺带「优化」无关代码；只删自己改动产生的孤儿。
+4. **目标驱动**：先定义可验证成功标准（测试、检查项），再迭代到满足。
+
+cursor/claude: 完整条文以磁盘上 **`rules/f2s-karpathy-guidelines.mdc`**为准。
+
+或 Codex 侧 **`.codex/topics/f2s-karpathy-guidelines.md`**为准。

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

@@ -1,79 +1,101 @@
 ---
 name: f2s-kb-feat
-description: 新增能力时补全实现与文档；已实现则仅基于实现与规则补充文档；触发：f2s-kb-feat、新增能力
+description: 新增能力时补全实现与知识库；已实现则仅同步知识库；触发：f2s-kb-feat、新增能力
 ---
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
 
-# /新增能力（f2s-kb-feat）
+> 执行口径：`f2s-kb-feat` 默认同步 `.Knowledge`，无需用户额外提出"请同步知识库"。
 
-当用户需要新增一个能力（功能、模块或约定）时，补全实现与文档；若该能力已实现，则基于现有实现与项目规则补充、对齐文档，使能力可被复用、可被 AI 与后续开发遵循。
+## 编排（主 / 子 agent）
 
-**输入**：用户描述「要新增什么能力」。例如：
+- `subAgent` 与 `switchAgentVerification` 的语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本处不复述。
+- **代码子包**（新增 / 修改实现代码）：`subAgent=true` 时可外包给子 agent 执行。
+- **文档子包**（rules / skills / topics / stock-docs 文风类改动）：默认不拆，由主 agent 写，以保证「现行真值覆盖 / 篇幅上限 / 禁历史否定堆砌」等文风合规。
+- 若确需外包文档改动：子侧只输出「原位替换 diff」（before / after 小段），不得整文件重写；主合并落盘。
+- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘，子 agent 不得触碰。
+- 落盘侧自验。
 
-- 「新增一个 XX 能力，需要…」
-- 「加一个 Y 模块，用来…」
-- 「支持 Z 场景，需要…」
+# /新增能力（f2s-kb-feat）
 
-用户可附带**范围**（如目录、模块、路径）或设计文档路径。
+## 输入
 
-**步骤**
+- 用户描述新增能力、场景、边界、可选路径。
 
-1. **理解需求与现状**
-   - 明确要新增的**能力**（功能点、入口、约定等）。
-   - 判断是否已有**部分或全部实现**：搜索相关代码与文档。
-   - 若需求不清或与现有实现冲突，可先询问用户再继续。
+## 步骤
 
-2. **补全实现（若尚未实现或未完成）**
-   - 按项目既有目录与约定实现，遵循现有规则（rules）与技能（skills）；实现后与规则、技能保持一致。
+**步骤 0：变更追踪（仅当 `changeTracking.feat: true`）**
 
-3. **补充/对齐文档**
-   - **项目文档**：在约定的文档目录中新增或修订与能力相关的小节，写清能力说明与使用方式；若有主文档索引则引用。
-   - **规则（Rules）**：若该能力引入新的项目级或模块级约定，在 `配置根/rules/` 下新增或更新规则，写清适用范围（目录/globs）与必须/禁止项。
-   - **技能（Skills）**：若该能力需要被 AI 或后续开发频繁引用，在 `配置根/skills/` 下新增或更新 Skill，写清触发词、能力摘要与使用方式，便于检索与遵循。
+执行前读取 `flow2spec.config.json`，若 `changeTracking.feat: true`：
 
-4. **（若已实现）基于实现反推文档**
-   - 梳理现有代码与调用关系，归纳能力入口与行为；将结果写入文档、规则与 Skill，与现有风格一致。不修改已有实现，只补文档与规则。
+- 检查 `.task/todo.json` 是否存在活跃任务，将用户描述与 `keywords` 匹配。
+- 命中 → 加载对应 `task.md`，展示剩余清单，在已有任务中继续。
+- 无命中 → 创建新任务（见 `f2s-task` 规则），将步骤 1–4 写入 `task.md` 作为任务 checklist。
+- **执中必写盘**：每完成 `task.md` 中一步，**同一会话内**立即 `Edit` 将该步 `[ ]`→`[x]`；禁止把打钩积压到「收尾/归档」一步、禁止口头完成代替写盘（见 `f2s-task`「中断与会话结束」「归档门禁」）。
+- **用户代办**：凡须用户改库、配环境、点平台等项，**同会话内**追加写入 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`）；新建任务时若尚无代办，仍应创建该文件（可占位）。
 
-5. **输出摘要**
-   - **能力**：新增/补全了哪些能力点。
-   - **实现**：涉及的文件与改动（若未改动实现则说明「实现已存在，未改代码」）。
-   - **文档**：新增/修订了哪些文档路径与小节。
-   - **规则 / Skill**：新增或更新了哪条 rule、哪个 skill。
+1. 判断能力状态：未实现 / 部分实现 / 已实现。
+2. 补齐代码实现（已实现则跳过此步）。
+3. 同步知识库（默认执行）：
+   - `.Knowledge/stock-docs/`：能力说明与使用方式
+   - `.Knowledge/topics/`：新增/修订主题规则与流程
+   - `.Knowledge/index.md`：主题索引
+   - 路由清单：路由或依赖变化时最小更新
+4. 输出摘要（能力点、实现、知识库变更）。
 
-**输出格式示例**
+## 输出摘要格式（建议）
 
 ```markdown
-## 新增能力：<能力简述>
-
-### 能力说明
+## 新增能力：<能力名>
 
-- <要点 1>
-- <要点 2>
-- …
+### 能力范围
+- <能力点1>
+- <能力点2>
 
 ### 实现
+- <文件路径>：<改动说明>（若未改代码则写"已有实现"）
+
+### 知识库
+- .Knowledge/stock-docs/<文件>.md：<新增/修订说明>
+- .Knowledge/topics/<topic>.md：<新增/修订说明>
+- .Knowledge/index.md：<更新说明>
+- .Knowledge/manifest-routing.json：<是否更新与原因>
+- .Knowledge/matchers/<id>.json：<是否更新 includeAny 与原因>
+```
 
-- <路径>：<说明>（若未改代码：实现已存在，仅补充文档）
-- …
+## 复杂场景示例
 
-### 文档
+用户要求"新增失败重试队列能力"，且代码中已有半成品实现。
 
-- <文档路径>：新增/修订「…」小节
-- …
+- 先判断为"部分实现"，补齐缺口代码而非重做整模块。
+- 同步新增或修订 `topics/retry-queue.md`，并更新 `index` 入口说明。
+- 若该能力需任务路由命中（如"重试队列改造"），补充 `manifest.taskToTopicRules`。
 
-### 规则 / Skill
+## 约束
 
-- <规则路径>：新增/更新 — …
-- <Skill 路径>：新增/更新 — 触发词：…
-```
+- 与旧约定冲突时：**改写到当前真值**，不要另起「（不再与某 X 有关）」等历史否定句。
+- 与现有主题重合时优先原位更新。
+- 至少落一处知识库更新，避免"代码有了但不可检索"。
+- 不改配置根 `rules/skills`。
+- 文档子包默认不拆；必要外包子侧仅出 before/after diff 片段，主合并落盘；`manifest-routing.json` / `.Knowledge/index.md` 恒主落盘（写权硬约束）。
+
+## 知识库落盘文风（必须，防赘述）
 
-**约束**
+写 `stock-docs` / `topics` / `index` 时遵守：
 
-- 实现须符合项目既有规则与技能；有冲突时以项目规则为准，必要时在文档中注明。
-- 至少补充文档；能力为项目级或会复用时，建议同时更新规则与 Skill。
-- 已实现的能力：只补文档与规则，不改代码；实现与约定不符时可单独指出或走修正规则流程。
+1. **增量最小**：只追加或改写与**本次能力**直接相关的句段；禁止因「同步知识库」而全文重述背景、需求复述、与实现无关的教程式铺垫。
+2. **现行真值覆盖（禁止历史否定堆砌）**：约定从「与 A 有关」变为「与 B 有关」等时，应**删除或原位改写**与旧约定冲突的句子，正文只写**当前成立**的关系（例如直接写与 B 的边界与流程）。**禁止**在正确句后再叠「（不再与 A 有关）」「已与 A 脱钩」「原与 A 有关现已改」等括号、脚注或对照旧版的赘述。仅在用户明确要求写「迁移 / breaking 说明」时，可单开一小节简要列旧→新，且仍避免正文逐句否定旧版。
+3. **不重复叙事**：同一事实在 `stock-docs` 与 `topics` **不要各写一长篇**；择一处写清可执行约定，另一处用短段落 + 链接指向，或仅列要点与引用路径。
+4. **条文化优先**：`topics` 以规则、边界、步骤、错误与配置要点为主；能用列表/表格表达的不用长段落。
+5. **篇幅上限（软约束）**：单次同步中，对**同一文件**的新增正文合计不宜超过约 **80 行**（不含代码块行）；超出则拆分为新 topic、或先写「摘要 + 详见代码路径/另一文档」，禁止单文件堆叠重复说明。
+6. **`index.md`**：只改与本次主题相关的行/表项，禁止整表或整节复制粘贴式刷新。
+7. **禁止**：重复解释 Flow2Spec 目录分工、重复贴用户对话全文、与本次 diff 无关的「历史回顾」大段。
 
-**何时使用**
+## 完成后自检
 
-- 用户表达要「新增能力」「加功能/模块」或「支持某场景」时。
-- 能力已实现但文档不全，用户希望按实现与现有规则补全文档时。
+1. 能力描述与代码实现是否一致。
+2. 新增能力是否可通过 topic 被检索。
+3. `index` 与 `manifest` 是否同步更新。
+4. 知识库变更是否可再压缩：删掉与本次变更无关的套话后，规则与链接是否仍完整。
+5. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：若现行规则已写清，此类句应删或并入用户要求的迁移小节。
+6. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。
+7. 若 `changeTracking.feat: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才将 `.task/active/<task-name>/` 归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。
+8. 若 `changeTracking.feat: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。

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

@@ -1,67 +1,98 @@
 ---
 name: f2s-kb-fix
-description: 根据用户指出的实现规则错误，修正代码并同步更新文档与全局规则；触发：f2s-kb-fix、修正实现规则
+description: 根据用户指出的实现或规则错误修正代码，并默认同步知识库；触发：f2s-kb-fix、修正实现规则
 ---
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
 
-在代码实现后，若用户指出某处违反了项目规则或约定，则修正实现并同步更新相关文档与全局规则，使该约定被明确记录、后续实现与 AI 可遵循。
+> 执行口径：`f2s-kb-fix` 默认"修代码 + 同步 `.Knowledge`"，无需用户额外要求"请同步知识库"。
 
-**输入**：用户描述「哪里错了、应遵循什么规则」。例如：
-- 「某处违反了 XX 规则，请改掉并补充到规则里」
-- 「Y 模块下所有 Z 的写法错了，应该是…」
-- 「只改某目录 / 某类文件」
+## 编排（主 / 子 agent）
 
-用户可附带**范围**（如具体目录、文件或「全项目同类写法」）。
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本处不复述。
+- 代码子包（bug 修复类实现代码）：`subAgent=true` 时可外包给子 agent 执行。
+- 文档子包（rules / skills / topics / stock-docs 等文风类改动）：默认不拆，由主 agent 直接编写，以保证「现行真值覆盖 / 篇幅上限 / 禁历史否定堆砌」等文风合规。
+- 若确需外包文档改动：子侧**只输出「原位替换 diff」**（before / after 小段），**不得整文件重写**；由主 agent 合并落盘。
+- 写权硬约束：`manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘，子 agent 不得触碰。
+- 落盘侧自验。
 
-**步骤**
+# /修正能力（f2s-kb-fix）
 
-1. **解析用户指出的问题**
-   - 明确违反的**规则或约定**（正确写法 vs 当前错误写法）。
-   - 明确**范围**：具体文件、目录或「全项目同类写法」。
-   - 若范围不清，可询问用户后再继续。
+## 输入
 
-2. **修正代码**
-   - 在范围内按正确写法修改所有相关位置（编辑文件）。
-   - 若用户表达为「所有这类」或规则为全局性，可搜索代码库中同类错误写法并一并修正。
+- 用户描述违规点、正确写法、可选范围。
 
-3. **更新相关文档**
-   - 判断与该约定相关的文档（项目约定的文档目录，如 `配置根/stock-docs`、`req-docs` 等）。
-   - 在文档中新增或修订一小节，写清该约定，必要时注明对应 rule/skill。
+## 步骤
 
-4. **更新全局规则与 Skill**
-   - 若该约定为项目级或模块级：
-     - 在项目约定的规则目录（如 `配置根/rules/`）下新增或更新一条规则，写清「必须/禁止」及适用范围（**Cursor**：`globs` + **`.mdc`**；**Claude Code** 的 **`.claude/rules/`**：**`.md`** + **`paths:`**，勿写 **`.mdc`** / **`globs:`**）。
-     - 在项目约定的技能目录（如 `配置根/skills/`）下新增或更新一个 Skill，写清触发词与正确/错误示例，便于后续实现与 AI 按规则执行。
-   - 规则与 Skill 中可引用文档作为约定出处。
+**步骤 0：变更追踪（仅当 `changeTracking.fix: true`）**
 
-5. **输出摘要**
-   - **代码**：修改了哪些文件、改了什么。
-   - **文档**：更新了哪些路径、新增/修订了哪一节。
-   - **规则/Skill**：新增或更新了哪条 rule、哪个 skill。
+执行前读取 `flow2spec.config.json`，若 `changeTracking.fix: true`：
 
-**输出格式示例**
+- 检查 `.task/todo.json` 是否存在活跃任务，将用户描述与 `keywords` 匹配。
+- 命中 → 加载对应 `task.md`，展示剩余清单，在已有任务中继续。
+- 无命中 → 创建新任务（见 `f2s-task` 规则），将步骤 1–4 写入 `task.md` 作为任务 checklist。
+- **执中必写盘**：每完成 `task.md` 中一步，**同一会话内**立即 `Edit` 将该步 `[ ]`→`[x]`；禁止积压打钩或口头完成代替写盘（见 `f2s-task`「中断与会话结束」「归档门禁」）。
+- **用户代办**：凡须用户改库、配环境、回归验证等项，**同会话内**追加写入 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`）；新建任务时若无代办可写占位说明。
+
+1. 明确违规点与影响范围（不清先追问）。
+2. 修复代码实现。
+3. 同步知识库（默认执行）：
+   - `.Knowledge/stock-docs/`：修订约定说明
+   - `.Knowledge/topics/`：修订对应主题规则/流程
+   - `.Knowledge/index.md`：更新主题索引
+   - 路由清单：若路由受影响则最小更新
+4. 输出摘要（代码改动 + 知识库改动）。
+
+## 输出摘要格式（建议）
 
 ```markdown
-## 修正：<规则简述>
+## 修正结果：<约定简述>
 
 ### 代码
-- <路径>：<具体修改说明>
-- …
+- <文件路径>：<改动说明>
+
+### 知识库
+- .Knowledge/stock-docs/<文件>.md：<新增/修订说明>
+- .Knowledge/topics/<topic>.md：<新增/修订说明>
+- .Knowledge/index.md：<更新说明>
+- .Knowledge/manifest-routing.json：<是否更新与原因>
+- .Knowledge/matchers/<id>.json：<是否更新与原因>
+```
 
-### 文档
-- <文档路径>：新增/修订「…」小节
-- …
+## 复杂场景示例
 
-### 规则 / Skill
-- <规则路径>：新增/更新 — …
-- <Skill 路径>：新增/更新 — 触发词：…
-```
+用户指出"订单回调幂等实现错误"，但未给明确文件范围。
+
+- 先按最小可行范围修复已定位的回调处理链路，并在摘要中说明"可继续扩展全仓同类修复"。
+- 同步更新 `topics` 中幂等规则段落，避免后续再次生成错误实现。
+- 若该修复影响任务路由（例如新增"幂等修复"主题），再最小更新 `manifest`。
+
+## 约束
+
+- 与旧约定冲突时：**改写到当前真值**，不要叠写「（不再与某 X 有关）」等对照旧版的赘句。
+- 同主题优先原位更新。
+- 范围不明时按最小可行范围修复并说明。
+- 不改配置根 `rules/skills`。
+- 文档子包默认不拆；必要外包子侧仅出 before/after diff 片段，主合并落盘；`manifest-routing.json` / `.Knowledge/index.md` 恒主落盘（写权硬约束）。
+
+## 知识库落盘文风（必须，防赘述）
+
+写 `stock-docs` / `topics` / `index` 时遵守：
+
+1. **增量最小**：只改与**本次修复**直接相关的段落或列表项；禁止借机重述整份方案、整段历史背景或与修复无关的说明。
+2. **现行真值覆盖（禁止历史否定堆砌）**：修复后约定从「与 A 有关」变为「与 B 有关」等时，应**删除或原位改写**仍写着旧约定的句子，正文只保留**当前成立**的表述。**禁止**叠写「（不再与 A 有关）」「原错误地与 A 绑定」等对照旧版的括号或脚注；除非用户明确要求「迁移说明」，否则不写旧→新对照长文。
+3. **不重复叙事**：`stock-docs` 与 `topics` 不就同一修复各写长篇；一处写清「错因 / 正确约定 / 注意点」，另一处简短引用或链到该段。
+4. **条文化优先**：以「错误表现 → 根因 → 正确行为 / 边界」为序的短列表为主，避免散文式展开。
+5. **篇幅上限（软约束）**：单次同步中，对**同一文件**的新增或替换正文合计不宜超过约 **60 行**（不含代码块行）；超出则只保留与修复相关的最小说明，其余用「见提交/见某路径」代替。
+6. **`index.md`**：仅更新受影响的索引行或摘要列，禁止无关整表重写。
+7. **禁止**：重复粘贴用户报错全文（可摘一行标识 + 链接）、重复解释 Flow2Spec 用法。
 
-**约束**
-- 范围不明时：按最可能范围（如用户提到的模块或近期改动的文件）修正，并说明「若其他位置也有同类写法，可再说，我一起改」。
-- 至少更新「文档、规则、Skill」中的一类，使约定被书面化。
-- 一条约定优先对应一条规则 + 一个 Skill；若已有合适 rule/skill 文件，在其上增补即可。
+## 完成后自检
 
-**何时使用**
-- 实现完成后，用户指出「这里违反规则」「写错了」「应该按 XX 约定来」时。
-- 用户希望既改代码，又把规则沉淀到文档与 Cursor（rules/skills）以便以后统一遵循时。
+1. 代码修复是否覆盖用户点名范围。
+2. 主题文档是否与修复后的实现一致。
+3. `index` 是否指向正确主题。
+4. 若更新了 `manifest`，路由字段是否仍可解析。
+5. 知识库变更是否可再压缩：删套话后约定是否仍清晰。
+6. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：现行规则已写清则应删。
+7. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。
+8. 若 `changeTracking.fix: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。
+9. 若 `changeTracking.fix: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。

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

@@ -3,6 +3,14 @@ name: f2s-kb-merge
 description: 解决 Git 合并后编辑器上下文冲突；可选传入冲突文件；实现侧冲突仅罗列待用户确认；触发：合并上下文冲突、f2s-kb-merge
 ---
 
+## 编排（主 / 子 agent）
+
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。
+- **子 agent 职责**（仅当 `subAgent=true`）：只做**冲突扫描 + 按类别对照表**，每条包含五字段 —— `file` / `category`（文档索引 / 总览规则 / 模块规则 / 技能 / 说明文档 / 实现类 / 依赖元数据）/ `ours_summary` / `theirs_summary` / `recommendation`（并集 / 保留某侧 / 并入必须项 / 待用户选）。
+- **子 agent 不出成品合并稿**，避免主 agent 二次重写。
+- **主 agent 职责**：按策略落盘 + 实现类决策 + 验收。
+- 默认落盘侧自验，本技能不绑定交叉校验。
+
 # /合并上下文冲突（f2s-kb-merge）
 
 在 **rebase / merge** 后出现 `<<<<<<<` / `=======` / `>>>>>>>` 时，优先**自动合并「AI 与开发者上下文」相关文件**，保证索引、规则、技能与说明文档互相对齐；**涉及可执行实现、部署或依赖声明的冲突不擅自合并**，需**向用户展示双方差异并等待确认**后再改。
@@ -55,6 +63,7 @@ description: 解决 Git 合并后编辑器上下文冲突；可选传入冲突
 ## 执行步骤
 
 1. **确定范围**：若用户已指定冲突文件，仅以这些文件为范围；否则全工作区检索冲突标记（或结合 IDE 冲突列表）。再按**适用范围**分类。
+   - 若启用拆子，子 agent 按子交付对照表 schema（`file` / `category` / `ours_summary` / `theirs_summary` / `recommendation` 五字段）产出分类表；主 agent 接手后续落盘 / 决策 / 验收步骤。
 2. **上下文类**：按合并策略直接修改并保存。
 3. **实现类**：只输出对比摘要与建议，**不修改文件**直至用户确认。
 4. **输出摘要**（Markdown）：已解决文件 + 要点；待确认文件 + 两侧差异 + 建议。