工作流与技能说明

命令速查表

上表是聊天里触发的 /f2s-* 技能。仓库还带 shell CLI：flow2spec kb status / check / plan / apply / build 用于协作合库，见 § 7；flow2spec doctor 用于只读项目体检，见 § 8。

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 条、首轮子表有矛盾或空洞、多源叙述冲突严重

职责划分：

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 识别格式缺口并定稿验收

职责划分：

f2s-kb-build

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

工作原理：以终稿文档为输入，执行「文档→路由」的三步映射：① 从终稿中提取能力主题与关键词；② 生成 topics/<topic>.md（路由摘要，含执行边界与下一步指针）和 matchers/<id>.json（机读匹配词 includeAny/includeAll/excludeAny/excludeAll）；③ 在 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 不跨边界落盘

职责划分：

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 行

职责划分：

交叉验证（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 接手追问与流程说明补写

职责划分：

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 做契约定稿与验收

职责划分：

交叉验证（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 写

职责划分：

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 恒由主落盘

职责划分：

交叉验证（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 恒由主落盘

职责划分：

交叉验证（switchAgentVerification: true 时）：

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

f2s-kb-distill

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

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

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

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

业务源码定义：路径不在 .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 恒由主落盘

职责划分：

交叉验证（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 按策略落盘、处理实现侧决策、完成验收

职责划分：

f2s-kb-upgrade

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

工作原理：先用 flow2spec version / flow2spec update --check 分开判断 Core 与 Template，再检测当前知识库属于 V1（旧结构）还是 V2+（已有 .Knowledge）。Core-only 更新只刷新 Core 与 Hook；Template 更新才代跑 init，并按 projectRev / pkgRev 选择快速路径或完整流程。V1 不再内置迁移支持。

使用场景：

• Template Version 升级后，对齐项目知识库模板
• 旧项目升级到最新结构
• 项目使用 locale 模板语言时，默认沿用 flow2spec.config.json.locale；未配置则按 zh-CN 补齐
• Hook 检测到 templateUpdateAvailable=true 后，在 Agent 对话中执行本技能；Core-only 更新不进入本技能
• Cursor 通过 .cursor/hooks.json 在 sessionStart 自动检测到知识库版本落后后，会提示执行本技能
• Codex 通过 .codex/hooks.json 在 SessionStart 自动检测到知识库版本落后后，会提示执行本技能（首次或变更后需在 Codex /hooks 中信任）

关联关系：

• 前置：已存在的 .Knowledge/（V1 旧结构不再支持自动迁移）
• 包含：内部会调用 flow2spec init 进行结构对齐
• 注意：单独的 flow2spec init 不是升级命令

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

• V1：不再内置迁移支持；技能停止并告知用户处理方式（历史版本包一次性迁移 / 手动迁入 .Knowledge）
• 现行库（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 融合、校验摘要输出

职责划分：

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

5) 规则说明

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

f2s-task

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

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

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

生效范围：

跨会话续作：新会话开始时若存在 .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，演讲口径见 Flow2Spec 演讲稿 Slide 13b）。完整路径与表格只维护一处：使用说明 § 一、f2s-* 与 flow2spec.config.json。

subAgent 字段

switchAgentVerification 字段

changeTracking 字段

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

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

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

完整原则与设计意图见 体系与原理 § 4. Agent 执行模型。

7) flow2spec kb CLI（协作合库）

上面 6) 之前的 /f2s-* 都是聊天里触发的技能。flow2spec kb * 不同——是 shell 里跑的 CLI，只做一件事：把技能写到 .task/<id>/active/<task>/kb-delta.json 里的变更请求，安全地合入共享的 .Knowledge/。设计动机与两条隔离线的关系见 体系与原理 § 6。

五个子命令

--json 所有子命令都支持，给脚本/hook 消费。kb status 与 kb check 通过 exit code 表明健康度（0 ok，1 有 issue），可以直接接进 CI。

kb-delta.json 结构

技能产出这份文件，形状约定：

{
  "taskId": "add-payment-rule",
  "developerId": "alice",
  "baseRevisions": { "topic-a": 3 },
  "changes": [
    { "targetTopic": "topic-a", "type": "appendBody", "content": "..." },
    { "targetTopic": "topic-c", "type": "createTopic", "content": "...", "frontmatter": { "title": "Topic C" } }
  ]
}

baseRevisions 是本次改动读取时磁盘上的 revision，apply 时若盘上已经变了（别人先 apply 过），plan 会报出该 topic 冲突且拒绝落盘。四种 type：

• appendBody / replaceBody：正文级，content 不能为空字符串，parse 阶段就拒
• updateFrontmatter：改 frontmatter 键值，revision 由 apply 自动 +1
• createTopic：新增 targetTopic，路径由 topic id 推导；已存在则冲突，可选携带 taskRule + matcher 同步接入路由

与 f2s-kb-* 技能的关系

技能产出 delta、CLI 负责合库，两侧不重叠：

• f2s-kb-feat / f2s-kb-fix / f2s-kb-distill / f2s-kb-sync 形成 kb-delta，不绕开预检直接改 .Knowledge/topics/*.md
• 触发 f2s-git-commit 后，Agent 会自动检查当前任务线并在可唯一定位、可合并时执行 plan → apply → build → check；手动 CLI 主要用于独立排查、维护和 CI
• kb plan 报 revision 冲突（队友先 apply 了同一 topic）通常靠 git pull 拉最新 topic → 重读 revision → 重写 delta 里该 topic 的 change；f2s-kb-merge 是给 Git 层面的 <<<<<<< 冲突标记用的，不是 revision 层
• f2s-kb-build 技能仍然存在，语义与 CLI kb build 对齐（从 stock-docs 反向重生成 topics/index/manifest）

日常操作模板见 使用说明 § 多人协作。

完整概念、同 topic 冲突示例与管理者视角见 团队协作。

8) flow2spec doctor（项目体检）

flow2spec doctor 在排查“为什么 Flow2Spec 没有按预期工作”时，一次检查本机运行环境和当前项目状态。命令只读、不联网，也不会自动修改配置或知识库。

flow2spec doctor
flow2spec doctor --json

检查范围：

• Node.js 版本是否满足包的 engines.node
• flow2spec.config.json、根 AGENTS.md 与 .Knowledge/manifest-routing.json 是否存在且可用
• 已存在的 .codex、.claude、.cursor 配置根是否包含必要入口和 hooks
• 实际解析出的 developerId、来源与 TASK_ROOT；无法识别身份而回退到 .task/ 时给出警告
• 根 .gitignore 是否忽略 .task/
• 知识图、topic revision 和 routing 元数据是否通过严格校验

文本输出用 [PASS]、[WARN]、[FAIL] 标记每项，并在异常项后给出修复建议。--json 输出稳定的 ok / package / cwd / summary / checks 结构，便于 CI 或脚本消费。

退出码规则：仅有警告时返回 0；任何错误返回 1。--fix 等未知参数会直接失败。需要修复旧 topic 缺少 revision 时，根据提示运行：

flow2spec kb build --fix-topics
flow2spec kb check --strict

9) 快速参考

典型工作场景与完整链路见 使用说明 § 三、典型工作场景。

目录完整说明见 目录与路径约定。

相关文档：

• Flow2Spec 基础介绍
• 使用说明
• 目录与路径约定
• 体系与原理
• 使用案例-模拟对话
• 项目里程碑