@double-codeing/flow2spec 3.0.9 → 3.0.12

package/docs/README-/345/221/275/344/273/244/350/257/264/346/230/216.md

@@ -6,64 +6,84 @@
 
 **作用**：根据用户说明或扫描代码，生成项目架构说明初稿。无固定格式要求，描述清楚系统结构、模块关系、关键决策即可。
 
+**工作原理**：以「inventory 驱动扫描」为核心——先由主 agent 产出模块清单（inventory）与扫描契约（读哪些入口、关注哪些维度），再按 inventory 执行只读代码扫描，最后将扫描结果聚合为人可读的架构初稿落盘 `stock-docs/`。整个流程不改代码，仅做「代码→文档」的单向提取。
+
 **使用场景**：
+
 - 新项目需要架构文档
 - 存量项目需要补充架构说明
 - 系统重构后更新架构描述
 
 **关联关系**：
+
 - **前置**：无
 - **后续**：`f2s-doc-final`（规范化终稿）或直接用于 `f2s-ctx-build`
 - **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内扫描代码并生成
 - `subAgent: true`：默认走 **B 模式**（主产出 inventory + 扫描契约 → 子 agent 并行只读扫表 → 主合并落盘）；满足以下任一条件时升级为 **C 模式**（多轮纠偏）：多 workspace / monorepo、源路径 > 20 条、首轮子表有矛盾或空洞、多源叙述冲突严重
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 产出 inventory（入口 + 核心模块名）与扫描契约，汇总子 agent 交付，落盘 stock-docs 初稿 |
+
+
+| 角色              | 职责                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------ |
+| 主 agent         | 产出 inventory（入口 + 核心模块名）与扫描契约，汇总子 agent 交付，落盘 stock-docs 初稿                                |
 | 子 agent（B/C 模式） | 按主手写 inventory 并行只读扫描，按统一 YAML schema 交付（`source / scope / cross_refs / pending`），不得自行裁剪范围 |
 
+
 ---
 
 ### `f2s-doc-final`
 
 **作用**：将 PDF 技术方案或初稿文档转为《终稿模版》规范格式，统一文档结构，便于后续进入知识库。
 
+**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-ctx-build` 的标准输入物，确保知识库入口的结构一致性。
+
 **使用场景**：
+
 - PDF 技术方案需要转为 Markdown
 - 初稿需要规范化以便沉淀
 - 外部文档需要纳入 Flow2Spec 管理
 
 **关联关系**：
+
 - **前置**：PDF 文档或初稿文档
 - **后续**：`f2s-ctx-build`（终稿入库）
 - **输出**：`.Knowledge/stock-docs/<文档>_终稿.md`
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成全流程
 - `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做套模版与排版草稿；子不追问用户、不补写流程说明、不宣称终稿合规；主 agent 识别格式缺口并定稿验收
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 识别格式缺口、对照模版与澄清文档验收定稿 |
+
+
+| 角色      | 职责                    |
+| ------- | --------------------- |
+| 主 agent | 识别格式缺口、对照模版与澄清文档验收定稿  |
 | 子 agent | 套模版与排版草稿，不追问用户、不写流程说明 |
 
+
 ---
 
 ### `f2s-ctx-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`
@@ -74,44 +94,57 @@
   - `.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           | 单点落盘 manifest-routing.json 和 index.md，整体验收 |
+| 子 agent（topics）   | 仅写 topics/ 目录下的主题文件，不触碰 manifest 和 index   |
 | 子 agent（matchers） | 仅写 matchers/ 目录下的分片文件，不触碰 manifest 和 index |
 
+
 ---
 
 ### `f2s-doc-add`
 
 **作用**：将已落地能力（多文件聚合）解析进知识库。适用于代码已实现但缺少文档，或已有多个文档需要统一入库的场景。
 
+**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-ctx-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         | 产出 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 内验证
 
@@ -121,17 +154,22 @@
 
 **作用**：按 stock-docs 文档删除对应的知识主题与索引映射。仅删除知识库中的引用关系，不删除源文档本身。
 
+**工作原理**：`f2s-ctx-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 恒由主落盘
 
@@ -141,28 +179,36 @@
 
 **作用**：将 PDF 技术方案转为 Markdown 格式，保存到 `req-docs/`，可补全流程说明。
 
+**工作原理**：面向「按方案实现代码」的前置环节——将 PDF 中的接口定义、数据模型、时序流程等结构化内容提取为 Markdown 格式并落盘 `req-docs/`。与 `f2s-doc-final` 的区别在于目标路径和用途：`doc-pdf` 输出到 `req-docs/` 供 `implement-tech-design` 规则消费驱动编码，`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。
+
 **使用场景**：
+
 - 收到 PDF 格式技术方案需要实现
 - 历史 PDF 文档需要纳入管理
 - 跨团队交付物为 PDF 时需要转换
 
 **关联关系**：
+
 - **前置**：PDF 文档
 - **输出**：`.Knowledge/req-docs/<方案>.md`
 - **下一步**：
   - 1. 如果是需求实现：提供转换后的方案路径并说明"按技术方案实现"，由 `implement-tech-design` 规则驱动编码
-  - 2. 如果是转存知识库：走转换终稿流程 `f2s-doc-final` → `f2s-ctx-build`
+  - 1. 如果是转存知识库：走转换终稿流程 `f2s-doc-final` → `f2s-ctx-build`
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成全流程
 - `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做 PDF→MD 首稿落盘 req-docs；子不追问用户、不补写流程说明章节；主 agent 接手追问与流程说明补写
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 追问用户补充流程说明、完成 req-docs 落盘验收 |
+
+
+| 角色      | 职责                              |
+| ------- | ------------------------------- |
+| 主 agent | 追问用户补充流程说明、完成 req-docs 落盘验收     |
 | 子 agent | 仅做 PDF→MD 首稿并落盘 req-docs，不向用户追问 |
 
+
 ---
 
 ## 2) 需求与方案
@@ -171,12 +217,16 @@
 
 **作用**：针对 PRD/需求文档进行反问澄清，通过多轮问答明确需求边界、非目标、关键流程，直至需求足够清晰可供技术方案编写。
 
+**工作原理**：采用「结构化追问」策略——将需求文档按「角色/场景/流程/边界/异常/非目标」六维拆解，逐维检查是否存在模糊表述、未定义概念或矛盾点，对每个缺口生成针对性追问。多轮对话直到所有维度无歧义后，输出需求澄清记录作为 `f2s-req-backend` 的输入。本质是将非结构化 PRD 转为可落地的结构化需求约束。
+
 **使用场景**：
+
 - 收到 PRD 后首步骤，确保理解正确
 - 需求边界模糊、缺少验收标准时
 - 跨团队协作需求，需明确接口契约
 
 **关联关系**：
+
 - **前置**：无（可直接触发）
 - **后续**：`f2s-req-backend`（澄清后生成技术方案）
 - **输出**：需求澄清记录（可选保存至 `.Knowledge/req-docs/`）
@@ -189,26 +239,35 @@
 
 **作用**：基于已澄清的需求和项目知识库，生成后端技术方案文档，包含接口设计、数据模型、流程说明、错误码等。
 
+**工作原理**：以「知识库约束 + 模版驱动」为核心——先从 `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 | 抽取项目约定摘要、分配写作任务、对照模版做定稿验收并写入 req-docs                                   |
 | 子 agent | 只读多源（topics / stock-docs / 澄清 req-docs / 模版），按模版写 req-docs 初稿；不自行扩展读取范围 |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 子 agent 落盘的接口/模型/流程文档 → 主 agent 校验跨章节一致性（接口签名与数据模型对齐、流程与异常处理覆盖）
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -218,27 +277,35 @@
 
 **作用**：从技术方案或需求描述出发，**始终创建任务清单**，然后按清单实现代码。不依赖 `changeTracking` 配置，代表用户明确需要可追溯的任务管理。
 
+**工作原理**：执行「解析→规划→确认→实现→归档」五阶段闭环。① 解析技术方案文档提取实现要点；② 按模块/功能粒度拆分为可执行任务清单并写入 `.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     | 输出草稿、用户确认、写 `todo.json`、汇总实现摘要       |
+| 子 agent（解析） | 只读文档，输出解析结果摘要，不落盘                    |
 | 子 agent（实现） | 按模块实现代码，不触碰 `.task/` 和 `.Knowledge/` |
 
+
 ---
 
 ## 3) Git 提交
@@ -247,17 +314,22 @@
 
 **作用**：代码写完后执行 Git 提交。自动检查变更文件、比对知识库覆盖情况，未入库的能力会提示用户处理，确认提交信息后执行 commit。
 
+**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。提交信息强制 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) 取消
@@ -266,6 +338,7 @@
 6. 输出 commit hash；若选 B 则附带未补录能力提醒
 
 **约束**：
+
 - 禁止 `git add -A` / `git add .`，只 add 已确认的变更文件
 - 禁止 `--no-verify`，hook 失败须修复后重试
 - 禁止自动 push
@@ -281,7 +354,10 @@
 
 **作用**：根据用户指出的实现或规则错误修正代码，并**默认自动同步**知识库相关文档与索引。
 
+**工作原理**：执行「定位→修复→同步」三步——先根据用户描述在知识库路由（manifest→topic→stock-docs）中定位相关上下文与代码位置，确认问题根因；修复代码后，自动检查 `topics/stock-docs/matchers` 中与该能力相关的描述是否因修复而需要更新，若有则原位修订（现行真值覆盖，不追加历史否定句）。「修代码必同步文档」是核心原则，避免知识库与实现漂移。
+
 **使用场景**：
+
 - 代码实现与技术方案不符
 - 规则理解有误需要修正
 - Bug 修复后需要同步文档
@@ -289,22 +365,28 @@
 **变更追踪**：若 `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        | 定位问题根因、制定修复方案、落盘文风合规内容、校验知识库一致性                      |
+| 子 agent（代码）    | 负责指定模块的代码 bug 修复，输出变更并报告影响范围                         |
 | 子 agent（文档，可选） | 仅输出 before/after diff 片段，不整文件重写，不触碰 manifest 和 index |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 子 agent 落盘的代码变更 → 主 agent 校验修复正确性与知识库一致性
 - 主 agent 落盘的知识库同步 → 子 agent 复核 topic/manifest 一致性（须 `subAgent: true` 且已拆出子任务，否则主 agent 内自验）
 - 复核方与落盘方必须为不同 agent 实例
@@ -315,29 +397,38 @@
 
 **作用**：新增能力时补全实现与知识库；若能力已实现，则仅同步知识库。
 
+**工作原理**：执行「判断→实现→入库」三阶段——先判断用户描述的能力在代码中处于「未实现/部分实现/已实现」哪种状态；未实现或部分实现时先补齐代码；最后走知识库同步：写 `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        | 确定能力边界与实现范围、落盘文风合规内容、最终校验知识库一致性                      |
+| 子 agent（代码）    | 负责代码实现（接口、逻辑、数据层），输出实现清单                             |
 | 子 agent（文档，可选） | 仅输出 before/after diff 片段，不整文件重写，不触碰 manifest 和 index |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 文档子 agent 落盘的 topic → 主 agent 校验与实现代码的能力描述一致性
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -348,28 +439,35 @@
 **作用**：将会话中的已实现能力沉淀回知识库。可显式给出能力或零输入推断。
 
 **使用场景**：
+
 - 会话中已完成实现，需要补录知识库
 - 从代码反向沉淀知识
 - 定期知识库整理
 
 **关联关系**：
+
 - **前置**：无（可直接触发，或零输入推断）
 - **后续**：无
 - **特点**：先输出知识库更新大纲，用户确认后才写入
 - **与 `f2s-ctx-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     | 输出大纲并确认、单点落盘 manifest 和 index、最终验收                      |
+| 子 agent（汇总） | 只读会话历史、推断能力点、生成结构化更新大纲片段                                |
 | 子 agent（同步） | 按大纲写 topic/matcher，落盘前加载近邻主题摘要对齐风格，不触碰 manifest 和 index |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 同步子 agent 落盘的 topic/matcher → 主 agent 校验跨 topic 路由完整性与 `includeAny` 关键词覆盖
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -379,57 +477,74 @@
 
 **作用**：解决 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 | 按策略落盘合并结果、处理实现侧冲突决策、验收              |
 | 子 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-*` 包技能）
+  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 形式），不写状态文件、不写删除执行记录 |
+| 子 agent | 负责指定主题的搬运与草案片段生成（patch 形式），不写状态文件、不写删除执行记录    |
+
 
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 子 agent 迁移落盘的主题 → 主 agent 校验迁移完整性（旧路径是否全量覆盖、主题边界是否重叠）
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -439,28 +554,37 @@
 
 **作用**：知识库模板升级。对齐 manifest-routing + matchers 分片。
 
+**工作原理**：通过「版本分流 + init 代跑」实现升级——先检测当前知识库属于 V1（旧结构，需先 migrate）还是 V2+（已有 `.Knowledge`），V1 走 migrate 后再 init，V2+ 直接代跑 `flow2spec init` 进行包级结构增量对齐（补齐新模板、升级 manifest schema、对齐 matchers 分片格式）。升级后重读 SKILL.md 判断是否需要重跑某些步骤。与单独 `init` 的区别：`kb-upgrade` 包含版本判断和重跑逻辑，`init` 仅做一次性结构补齐。
+
 **使用场景**：
+
 - flow2spec 包版本升级后，升级项目知识库模板
 - 旧项目升级到最新结构
 
 **关联关系**：
+
 - **前置**：`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 命令，不落盘知识库内容 |
+| 子 agent | 仅代跑 `flow2spec init` 等 shell 命令，不落盘知识库内容                                      |
+
 
 **交叉验证**：本技能不绑定交叉校验，落盘侧自验。
 
@@ -470,23 +594,37 @@
 
 以下不是技能命令，而是通过触发词激活的规则，用于辅助指导 Agent 的行为。
 
+### `f2s-karpathy-guidelines`
+
+**触发词**：`alwaysApply`（始终生效，无需显式触发）
+
+**作用**：Flow2Spec 内置的 Karpathy 式编码行为准则，约束 Agent 的编码决策质量。
+
+**工作原理**：从 Andrej Karpathy 对 LLM 写代码常见失误的观察中提炼四条行为约束，作为 `alwaysApply` 规则在所有 `f2s-*` 技能执行时隐式生效：① 先想清楚再写代码（假设要说清楚，不确定就问）；② 简单优先（用最少代码解决问题）；③ 手术式修改（只动该动的，风格对齐现有代码）；④ 目标驱动执行（先定义可验证的成功标准再循环迭代）。当这些准则与 `f2s-*` 强制步骤冲突时，以 `f2s-*` 为准。
+
+---
+
 ### `f2s-task`
 
 **触发词**：changeTracking、变更追踪、任务追踪、续作、继续上次任务
 
-**作用**：变更追踪规则（`alwaysApply`）。当对应技能的 `changeTracking.*` 为 `true` 时，在技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。
+**作用**：变更追踪规则（`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.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.*`
+**规则位置**：`配置根/rules/f2s-task.`*
 
 ---
 
@@ -496,14 +634,19 @@
 
 **作用**：区分知识沉淀目录与需求实现目录的边界。
 
+**工作原理**：通过「用途隔离」避免文档混放——`stock-docs/` 存放已沉淀的存量知识（架构、终稿），由 `ctx-build` 消费入库，禁止直接用于编码；`req-docs/` 存放面向实现的需求与技术方案，由 `implement-tech-design` 规则消费驱动编码。两目录的写入者和消费者完全隔离，防止「存量描述被当编码依据」或「实现方案被当能力沉淀」的混淆。
+
 **目录分工**：
 
-| 目录 | 用途 | 写入时机 |
-|------|------|----------|
-| `stock-docs/` | 存量沉淀（架构、终稿） | `f2s-doc-arch`、`f2s-doc-final`、`f2s-ctx-build` |
-| `req-docs/` | 需求与技术方案（驱动实现） | `f2s-req-backend`、`f2s-doc-pdf`、手动放置 |
+
+| 目录            | 用途            | 写入时机                                           |
+| ------------- | ------------- | ---------------------------------------------- |
+| `stock-docs/` | 存量沉淀（架构、终稿）   | `f2s-doc-arch`、`f2s-doc-final`、`f2s-ctx-build` |
+| `req-docs/`   | 需求与技术方案（驱动实现） | `f2s-req-backend`、`f2s-doc-pdf`、手动放置           |
+
 
 **使用场景**：
+
 - 不确定文档应该放哪里
 - 需要明确 stock-docs 与 req-docs 的分工
 
@@ -515,13 +658,17 @@
 
 **作用**：根据 `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-backend` 或手动放置）
 - **规则位置**：
   - Cursor：`.cursor/rules/f2s-implement-tech-design.mdc`
@@ -529,6 +676,7 @@
   - Codex：`.codex/AGENTS.md` + `.codex/topics/f2s-implement-tech-design.md`
 
 **执行流程**（规则强制）：
+
 1. 输入标准化
 2. 理解方案与上下文
 3. **输出实现任务列表**（必做，不可跳过）
@@ -546,21 +694,25 @@
 
 ### 多端如何「看到」配置（与下文字段表配合）
 
-`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[Flow2Spec使用说明 § 一、`f2s-*` 与 `flow2spec.config.json`](./Flow2Spec使用说明.md)。
+`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[Flow2Spec使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./Flow2Spec使用说明.md)`。
 
 ### `subAgent` 字段
 
-| 取值 | 行为 |
-|------|------|
-| `false`（默认） | 所有 `f2s-*` 技能在主 agent 内完成 |
-| `true` | 部分技能可按正文约定使用子 agent（大规模并行处理场景） |
+
+| 取值          | 行为                             |
+| ----------- | ------------------------------ |
+| `false`（默认） | 所有 `f2s-*` 技能在主 agent 内完成      |
+| `true`      | 部分技能可按正文约定使用子 agent（大规模并行处理场景） |
+
 
 ### `switchAgentVerification` 字段
 
-| 取值 | 行为 |
-|------|------|
-| `false`（默认） | 落盘侧自验：谁落盘谁验 |
-| `true` | 技能正文明确写出该步骤时，启用交叉校验：子 agent 落盘 → 主 agent 验；主 agent 落盘 → 子 agent 验（须 `subAgent: true` 且已拆出子任务） |
+
+| 取值          | 行为                                                                                            |
+| ----------- | --------------------------------------------------------------------------------------------- |
+| `false`（默认） | 落盘侧自验：谁落盘谁验                                                                                   |
+| `true`      | 技能正文明确写出该步骤时，启用交叉校验：子 agent 落盘 → 主 agent 验；主 agent 落盘 → 子 agent 验（须 `subAgent: true` 且已拆出子任务） |
+
 
 ### `changeTracking` 字段
 
@@ -576,11 +728,13 @@
 }
 ```
 
-| 子项 | 对应技能 | 效果 |
-|------|---------|------|
-| `feat` | `f2s-kb-feat` | 执行前创建任务清单，完成后归档，支持跨会话续作 |
-| `fix` | `f2s-kb-fix` | 同上 |
-| `implement` | `f2s-implement-tech-design` | 同上 |
+
+| 子项          | 对应技能                        | 效果                      |
+| ----------- | --------------------------- | ----------------------- |
+| `feat`      | `f2s-kb-feat`               | 执行前创建任务清单，完成后归档，支持跨会话续作 |
+| `fix`       | `f2s-kb-fix`                | 同上                      |
+| `implement` | `f2s-implement-tech-design` | 同上                      |
+
 
 > `f2s-req-plan` 不受此配置约束，始终创建任务清单。旧版布尔值（`"changeTracking": true/false`）向下兼容，自动展开为三项全开/全关。
 
@@ -597,7 +751,9 @@
 ---
 
 相关文档：
+
 - [Flow2Spec使用说明](./Flow2Spec使用说明.md)
 - [README-目录与路径约定](./README-目录与路径约定.md)
 - [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+