@double-codeing/flow2spec 2.2.3 → 3.0.7

package/docs/Flow2Spec/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -1,123 +1,163 @@
 # Flow2Spec 使用说明
 
-使用手册：**init → 目录约定 → 推荐顺序 → 典型流程 → 技能标识 → 常见问题**。概览与快速开始见仓库 [README.md](../README.md)。
+## 一、init 做了什么
 
-**文档**：[README-命令说明](./README-命令说明.md) · [README-目录与路径约定](./README-目录与路径约定.md) · [README-体系与原理](./README-体系与原理.md) · [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+在业务仓库根执行：
 
-| 章节                                                                     | 内容                                                                                  |
-| ---------- | ----------------------- |
-| [一、init](#一init-做了什么)                                             | 写入目录与模板                                                                        |
-| [二、目录约定](#二文档目录约定)                                          | `stock-docs/` vs `req-docs/`；完整结构见 [目录与路径约定](./README-目录与路径约定.md) |
-| [三、推荐顺序](#三推荐执行顺序)                                          | 链到 [命令说明 · 按使用顺序查找](./README-命令说明.md#按使用顺序查找)                 |
-| [四、典型流程](#四典型流程)                                              | 架构 / 上下文 / 按方案实现 / 全局技能                                                 |
-| [五、改造 implement-tech-design](#五implement-tech-designmdc-可自行改造) | 按项目改「按方案实现」规则                                                            |
-| [六、技能标识](#六技能与工作流标识)                                      | `skills/<name>/SKILL.md` 速览                                                         |
-| [七、延伸](#七速查与相关文档)                                            | 速查与 FAQ                                                                            |
-| [使用案例（另文）](./Flow2Spec-使用案例-模拟对话.md)                     | 真实输入、命令解释、场景与速查                                                        |
+```bash
+flow2spec init [cursor|claude|codex ...]
+# 需要强制重置 .Knowledge 到模板时：
+flow2spec init [cursor|claude|codex ...] --reset-knowledge
+```
 
----
+| init 做 | init 不做 |
+|---------|----------|
+| 补齐缺失的目录与模板文件 | 撰写或更新业务文档内容 |
+| 落盘各 agent 配置根 `rules/` `skills/` | 更新 `includeAny` 业务词条 |
+| `manifest-routing` + `matchers/` 包级结构对齐 | 替代 `f2s-*` 技能对业务语义的书写 |
+| `--reset-knowledge` 时强制覆盖 `.Knowledge` 模板文件 | （不加此参数时）覆盖已有 `.Knowledge` 内容 |
 
-## 一、init 做了什么
+> **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-doc-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-ctx-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。
 
-在**配置根父目录**执行 **`flow2spec init [agent ...]`**（未全局安装可用 **`npx @double-codeing/flow2spec init`**）。`agent` 省略时默认 **`cursor`** → **`.cursor/`**；可多个：`cursor claude codex`，各写一套相同结构。详见 **`flow2spec --help`**。
+### `f2s-*` 与 `flow2spec.config.json`：多端多重提示（权威仍为磁盘 JSON）
 
-对每个所选配置根：**覆盖写入** `templates/` 中的 `rules/`、`skills/`、`template/`，并预建 **`stock-docs/`**、**`req-docs/`**。Cursor 下 Agent 按场景加载 **`skills/<标识>/SKILL.md`**。
+执行任意 **`f2s-*` 技能**前，需要让 Agent 拿到 **`subAgent` / `switchAgentVerification` / `changeTracking`** 等实际值。Flow2Spec 在 **不同客户端** 用 **不同机制** 强化这一点；它们彼此**补充**，**不**互相替代，**权威始终**是项目根 **`flow2spec.config.json`**（须用 **Read** 与磁盘一致后再进技能正文）。
 
-**规则文件与工具差异**：**Cursor** 的 `rules/` 使用 **`.mdc`**，frontmatter 用 **`globs:`**、**`alwaysApply:`**。**Claude Code** 仅加载 **`.claude/rules/`** 下 **`.md`**（官方文档「Organize rules with .claude/rules」）；`flow2spec init claude` 会把模板 **`.mdc`** 转为 **`.md`**，并将 **`globs:`** 改为 **`paths:`**、去掉 **`alwaysApply`**（无 `paths` 的规则与会话一并加载，等价于总览类 always 规则）。
+| 端 | `init` 落盘与行为 | 说明 |
+| --- | --- | --- |
+| **Cursor** | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`） | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。 |
+| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。 |
+| **Codex** | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表 | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
+| **知识库（可选）** | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时 | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。 |
+
+字段语义与默认值规则见 [README-命令说明 § 6) 子 Agent 配置说明](./README-命令说明.md)。设计视角见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)；口述见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)。
+
+---
 
-| 子目录          | 用途                                       |
-| --------------- | ------------------------------------------ |
-| **skills/**     | f2s-\* 工作流 + **stock-docs-vs-req-docs** |
-| **rules/**      | Cursor：**\*.mdc**（如 **implement-tech-design.mdc**）；Claude Code：**\*.md**（如 **implement-tech-design.md**） |
-| **template/**   | 终稿模版、后端技术模版                     |
-| **stock-docs/** | 生成 Rules/Skills 的**存量源文档**         |
-| **req-docs/**   | 需求澄清、技术方案、**按方案实现**用 MD    |
+## 二、目录约定
 
-**注意**：再次 init 会覆盖模板；本地对模板的长期修改请用分支或备份。
+核心区分：`stock-docs/` 放沉淀文档（驱动知识路由），`req-docs/` 放技术方案（驱动编码实现），两者不互换。
+
+完整目录说明见 [README-目录与路径约定](./README-目录与路径约定.md)。
 
 ---
 
-## 二、文档目录约定
+## 三、典型工作场景
 
-**配置根**：如 `.cursor/`、`.claude/`。
+### 需求规划并实现
 
-| 目录            | 用途                                                         |
-| --------------- | ------------------------------------------------------------ |
-| **stock-docs/** | 终稿、架构说明等 → **f2s-ctx-build** 入参                    |
-| **req-docs/**   | 技术方案等 → 对话提供路径 + **implement-tech-design** 写代码 |
+```
+f2s-req-plan
+```
 
-细则、链接写法、原稿/初稿/终稿：[README-目录与路径约定](./README-目录与路径约定.md)。
+输入技术方案文档路径或需求描述，先输出任务清单草稿并等待确认，确认后按清单实现代码。始终创建 `.task/` 任务清单，不需要配置 `changeTracking`。适合希望先看清全貌再动手、或需要跨会话追踪进度的场景。
 
----
+### 变更追踪与跨会话续作
 
-## 三、推荐执行顺序
+```
+# 自动模式：配置开启（各技能独立）
+flow2spec.config.json → changeTracking.feat / fix / implement: true
 
-**需求（可选）**：f2s-req-clarify → f2s-req-backend
+# 显式模式：调用 f2s-req-plan（规划 + 实现，不依赖配置）
+f2s-req-plan
+```
 
-**上下文（架构说明）**：**f2s-doc-arch** → **f2s-doc-final** → **f2s-ctx-build**  
-**上下文（已落地能力→知识库）**：**f2s-doc-add**——**工作中**要把**已经做好的能力**从多份源码/说明里**解析进上下文**时用；独立技能，**不要**与「仅要架构初稿」的 f2s-doc-arch 混用（见 `skills/f2s-doc-add/SKILL.md`「使用时机」与分工表）
+**自动模式**：开启后，`f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` 执行时自动在 `.task/active/` 创建任务清单，逐步勾选，完成后归档。下次会话描述相关内容，`f2s-task` 规则自动匹配并加载剩余清单，无需重新说明上下文。
 
-**实现**：可选 f2s-doc-pdf → **req-docs/** 下 MD + 说明「按方案实现」→ **implement-tech-design**
+**显式模式**：直接调用 `f2s-req-plan`，不管 `changeTracking` 配置，始终创建任务清单并按清单实现代码，适合希望先确认全貌再动手的场景。
 
-**知识库维护**：任意时机 **f2s-kb-fix** / **f2s-kb-feat**；**实现后**（或收尾）沉淀写库 → **f2s-kb-sync**；合并冲突 → **f2s-kb-merge**
+### 新需求开发
 
-完整表与入参/输出：[README-命令说明 · 按使用顺序查找](./README-命令说明.md#按使用顺序查找)。
+```
+f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
+```
 
----
+需求已明确时可跳过 `f2s-req-clarify`，直接从 `f2s-req-backend` 开始。技术方案落入 `req-docs/` 后，由 `implement-tech-design` 规则驱动编码。
 
-## 四、典型流程
+### 文档沉淀
 
-**架构初稿**：**f2s-doc-arch**（说明或文档路径；无参扫描需用户确认）→ 可选 **f2s-doc-final** → **f2s-ctx-build**。
+```
+新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-ctx-build
+PDF 文档沉淀：    f2s-doc-pdf  → f2s-doc-final → f2s-ctx-build
+```
 
-**已落地能力 → 上下文**：在日常开发中，某能力**已实现**且材料分散在多文件时，加载 **f2s-doc-add**，给出**多个相关路径**：适度深度解析 → **`stock-docs/<方案名>_初稿.md`** → 终稿 → **f2s-ctx-build** 等价产物。
+把架构说明或 PDF 技术方案纳入知识路由（生成 topics/matchers/manifest-routing）。
 
-**文档 → 上下文**：材料放 **stock-docs/**；PDF/杂乱 MD 用 **f2s-doc-final**（PDF 常先初稿再终稿）；终稿路径交给 **f2s-ctx-build**。会话沉淀、大纲确认写库：**f2s-kb-sync**。冲突标记：**f2s-kb-merge**（见 [命令说明 §3.3](./README-命令说明.md#33-f2s-kb-merge)）。
+### PDF 方案实现
 
-**技术方案 → 代码**：提供 **req-docs/xxx.md**（或 PDF，规则会先走 **f2s-doc-pdf**），说明按方案实现；行为见 **rules/implement-tech-design.mdc**。
+```
+f2s-doc-pdf → implement-tech-design
+```
 
-**全局**：**f2s-kb-feat** / **f2s-kb-fix**（任意时机）；**f2s-kb-sync**（典型在实现后，大纲确认后写库）。
+拿到 PDF 技术方案后直接转 Markdown 落入 `req-docs/`，再由 `implement-tech-design` 规则驱动编码。
 
----
+### 存量能力补录
+
+```
+f2s-doc-add      # 多文件聚合，从源码/文档提取
+f2s-kb-sync      # 从当前会话推断已实现能力
+```
 
-## 五、implement-tech-design.mdc 可自行改造
+代码已落地但知识库没有记录时使用。`f2s-doc-add` 适合批量导入，`f2s-kb-sync` 适合会话结束时的即时沉淀。
 
-路径：**`rules/implement-tech-design.mdc`**。可按项目改目录约定、步骤、**globs**（默认含 `**/req-docs/**/*.md`）。再次 **init** 会覆盖 `rules/` 等模板，定制请用分支或备份。
+### 日常维护
+
+```
+f2s-kb-fix       # 修复实现或规则错误，自动同步知识库
+f2s-kb-feat      # 新增能力，自动同步知识库
+f2s-kb-sync      # 定期同步或补录
+f2s-kb-merge     # Git 合并后解决上下文冲突
+```
+
+### 知识库跨版本升级
+
+```
+f2s-kb-migrate（流程 V1：旧库）→ f2s-kb-upgrade
+f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，见技能步骤 0）
+```
 
 ---
 
-## 六、技能与工作流标识
+## 四、Agent 执行配置
+
+通过项目根 `flow2spec.config.json` 控制，字段完整规则见 [README-命令说明 § 6) 子 Agent 配置说明](./README-命令说明.md)。**各端如何被提示读到配置、为何仍以 Read 为权威**见 **§ 一**（本 § 仅说明**何时**打开各开关）。
+
+**何时开启 `subAgent: true`**：任务规模较大时（多模块并行实现、批量文档入库、大规模迁移）。开启后各技能按自身规模门槛决定是否实际拆分，未达门槛的仍在主 agent 内完成。
+
+**何时开启 `switchAgentVerification: true`**：需要更高落盘一致性时（大规模迁移、重要方案实现）。代价是增加执行轮次；常规维护场景默认 `false` 足够。须搭配 `subAgent: true` 才能触发"主落子验"方向的交叉。
 
-工作流在 **`skills/<标识>/SKILL.md`**；Agent 依 **frontmatter** 的 `name`、`description` 匹配。
+**何时开启 `changeTracking.*`**：希望每次技能执行自动留下可续作的任务清单时。各技能子项独立配置，互不影响：
 
-| name                                                  | 用途                                                 |
-| ----------------------------------------------------- | ---------------------------------------------------- |
-| f2s-doc-arch                                          | **仅**架构说明类初稿（文字/单文档/扫描）；**不**内含终稿与 ctx-build |
-| f2s-doc-add                                           | **工作中**：**已做好的能力** + 多文件路径→解析进上下文（初稿→终稿→Rules/Skills/索引）；勿与 f2s-doc-arch 混用 |
-| f2s-doc-final                                         | PDF/MD → 终稿模版                                    |
-| f2s-ctx-build                                         | 终稿 → Rules / Skills / docs-index                   |
-| f2s-ctx-rm                                            | 按文档删上下文                                       |
-| f2s-doc-pdf                                           | PDF → req-docs MD                                    |
-| f2s-req-clarify / f2s-req-backend                     | 需求澄清 / 后端技术方案                              |
-| f2s-kb-fix / f2s-kb-feat / f2s-kb-sync / f2s-kb-merge | 任意：纠错、新能力；典型实现后：写库；冲突：合并     |
-| stock-docs-vs-req-docs                                | 两目录分工说明                                       |
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": false,
+    "implement": true
+  }
+}
+```
 
-入参与输出细节仍以各 **SKILL.md** 与 [README-命令说明](./README-命令说明.md) 为准。
+不想依赖配置、希望按需显式规划任务时，直接使用 `f2s-req-plan`。
 
 ---
 
-## 七、速查与相关文档
+## 五、规则改造建议
 
-**按阶段速查**：[README-命令说明 §6](./README-命令说明.md#6-快速参考按阶段)。
+- 项目特化「按技术方案实现」逻辑时，优先调整 **`f2s-implement-tech-design`**：Cursor `.cursor/rules/f2s-implement-tech-design.mdc`，Claude `.claude/rules/f2s-implement-tech-design.md`；Codex 以 `.codex/AGENTS.md` 与相关 `skills/` 为准
+- 再次 `init` 默认仅补齐缺失模板并做包级结构对齐，**不**替代 `f2s-*` 对业务内容的维护；需用模板重置 `.Knowledge` 时加 `--reset-knowledge`
 
-**常见问题**
+---
+
+## 六、技能标识
+
+技能以 `name` 与 `description` 匹配触发，文件位于 `配置根/skills/*/SKILL.md`。
+
+---
 
-- **按方案实现要改行为**：改 **implement-tech-design.mdc**（见上文第五节）。
-- **技能不触发**：确认已 init；对话里点名技能名或 `description` 里的词。
-- **顺序搞不清**：看 [README-命令说明](./README-命令说明.md) 开头总表。
+## 七、相关文档
 
-| 文档                                                            | 说明                                         |
-| - | -------------------------------------------- |
-| [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md) | 真实输入 + 命令解释 + Agent 示意，全文同版式 |
-| [README-命令说明](./README-命令说明.md)                         | 入参、输出、顺序、§6 速查                    |
-| [README-目录与路径约定](./README-目录与路径约定.md)             | 路径、链接、产物阶段                         |
-| [README-体系与原理](./README-体系与原理.md)                     | main、docs-index、拆解原则                   |
+- [README-命令说明](./README-命令说明.md)
+- [README-目录与路径约定](./README-目录与路径约定.md)
+- [README-体系与原理](./README-体系与原理.md)
+- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)

package/docs/README-/344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md

@@ -1,79 +1,120 @@
 # 体系与原理
 
-Flow2Spec 如何把**长文档**变成 **main + 专题 Rules + 专题 Skills + docs-index**，让 AI **按需加载**、控制上下文体积。**配置根**同前（默认 `.cursor/`）。
+Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开：
 
-**一句话**：**stock-docs** 里文档经 **f2s-ctx-build** 落成 **main（总览）**、**globs 规则**、**description 技能** 与 **docs-index（文档↔产物表）**；实现代码用 **req-docs** + **implement-tech-design**。
-
-**文档**：[Flow2Spec使用说明](./Flow2Spec使用说明.md) · [README-命令说明](./README-命令说明.md) · [README-目录与路径约定](./README-目录与路径约定.md) · [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- **知识层**：`.Knowledge`（文档与索引）
+- **执行层**：配置根 `rules/skills`（供各工具原生加载）
 
 ---
 
-## 1. 目标与价值
+## 1. 两层结构
 
-- **目标**：按路径 / 按问题加载片段，避免整篇长文塞进一轮对话。  
-- **手段**：Rule 写约束（+ globs）；Skill 写知识与步骤（+ description）；**main** 总览；**docs-index** 查某文档对应哪些产物。
+| 层 | 位置 | 作用 |
+| --- | --- | --- |
+| 知识层 | `.Knowledge/` | 保存业务文档、索引、路由 |
+| 执行层 | `.cursor/.claude/.codex` | 保存规则与技能入口 |
 
 ---
 
-## 2. 整体架构
+## 2. 渐进式读取
 
-在**配置根**里，和 Flow2Spec 日常闭环相关的主要是**三条线**（先建立整体印象，再下看表格）：
+统一建议顺序：
 
-| 线 | 目录 / 产物 | 在闭环里的角色 |
-|----|----------------|----------------|
-| **A. 文档源** | **`stock-docs/`** | 放终稿、初稿、架构长文等；是 **f2s-ctx-build** 的输入源 |
-| **B. 可加载知识库** | **`main.mdc`**、**`rules/`**、**`skills/`**、**`docs-index.md`** | Agent **按需**读：总览 → 索引 → 专题规则/技能 → 必要时回 **`stock-docs/`** 长文 |
-| **C. 按方案写代码** | **`req-docs/`** + **`implement-tech-design`** | 技术方案 MD 驱动改业务代码；**不**替代 A→B 那条「把长文拆进规则与技能」的链 |
+1. `.Knowledge/manifest-routing.json`
+2. `.Knowledge/matchers/<matcher>.json`（按需：由 `manifest-routing.taskToTopicRules[].matcherPath` 直链定位）
+3. `.Knowledge/index.md`
+4. 命中的 `stock-docs` / `req-docs` 文档
+5. 必要时下钻源码
 
-**阶段二：用终稿跑一次 f2s-ctx-build**——入参通常是 **`stock-docs/…_终稿.md`**（或 URL 等，见 [命令说明 §2.3](./README-命令说明.md#23-f2s-ctx-build)）。**同一次执行会一并写出 / 更新下面几类文件**；它们是**并列产物**，不是「先跑完 main 再跑 rules」的串行流水线。
+读取后执行 `match → expand → verify → act` 四步流水线：命中主候选后展开依赖主题、缺口检查，置信度足够时才执行；低置信度先澄清。
 
-| 产物 | 作用 |
-|------|------|
-| **main.mdc** | 唯一 **alwaysApply**；总地图、模块一览、公共入口（正文应约定先读 **docs-index** 再下钻） |
-| **专题 Rules**（`rules/*-context.mdc`） | 必须/禁止/约定；按 **globs** 命中文件时加载 |
-| **专题 Skills**（`skills/` 下各主题的 **SKILL.md**） | 概念、流程、示例；按 **description** 匹配问题 |
-| **docs-index.md** | 表格式：文档路径、Rules、Skills、摘要（**非** alwaysApply，须按需读） |
+同时由配置根入口（Flow2Spec 包规则：`f2s-flow2spec-unified-entry.mdc` / `f2s-flow2spec-unified-entry.md`；旧版业务仓库常见为 `main.md(c)`；以及 `AGENTS.md`）约束加载行为。  
+其中 Codex 不读取 `rules/` 目录，统一通过 `.codex/AGENTS.md` + `skills/` 承载执行约束。
 
 ---
 
-## 3. 设计原则：拆解与分工
+## 3. 关键链路
 
-- **拆解**：长文档或多块独立内容 → 多条 Rule、多个 Skill，单条更短、更聚焦。  
-- **分工**：Rule = 约束与范围；Skill = 知识与操作；main = 索引不写细节；docs-index = 文档级映射。
+- 文档沉淀链：`f2s-doc-arch` → `f2s-doc-final` → `f2s-ctx-build`
+- 实现链：`.Knowledge/req-docs/*.md` → `implement-tech-design` → 代码
+- 维护链：`f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge`
+- 需求规划链：`f2s-req-plan`（规划 + 实现，始终创建任务清单）
+- 变更追踪链：`changeTracking.*` 配置 → `f2s-task` 规则（自动）→ `.task/` 任务清单 → 跨会话续作
+- 包模板/路由形态与配置根对齐：`f2s-kb-upgrade`（**勿**将单独 `flow2spec init` 等同于「知识库升级」）；旧库结构迁入 `.Knowledge`：`f2s-kb-migrate`
 
 ---
 
-## 4. main.mdc 与 docs-index.md
+## 4. Agent 执行模型
 
-| | **main.mdc** | **docs-index.md** |
-|---|--------------|-------------------|
-| 路径 | `rules/main.mdc` | 配置根下与 stock-docs 同级 |
-| 角色 | 项目总览、模块与公共能力入口 | 按文档列 Rules / Skills |
-| 加载 | **唯一 alwaysApply** | 不自动进上下文；由 **main** 约定阅读顺序 |
+Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentVerification` 两个字段控制执行行为。
 
-**查模块/入口** → main；**查某文档生成了哪些 Rule/Skill** → docs-index。
+**Agent 如何读到上述真值**：多端提示 + **Read** 权威，见 [Flow2Spec使用说明 § 一（唯一详表）](./Flow2Spec使用说明.md)；设计归纳见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)。
 
----
+### 4.1 主/子 Agent 职责划分原则
+
+**`subAgent: false`（默认）**：全部 `f2s-*` 技能在主 agent 内顺序完成，无并行拆分。
+
+**`subAgent: true`**：达到技能正文约定的规模门槛时，允许拆分子 agent 并行处理。职责边界如下：
+
+| 角色 | 职责边界 |
+|------|----------|
+| 主 agent | 统筹规划、确定任务粒度与分配策略、汇总子 agent 输出、校验跨单元一致性、最终落盘 |
+| 子 agent | 处理指定单元（模块/文档/主题），按约定格式输出结果，不跨单元决策 |
+
+子 agent 的拆分边界由各 `f2s-*` 技能正文逐步约定（如模块数、文档数、代码行数等门槛），**当前尚未在模板层给出统一阶段表**，以技能正文为准。
+
+### 4.2 验证归属原则
+
+**默认（谁落盘谁验）**：落盘或变更后的验证在落盘侧 agent 内完成。子 agent 落盘则子 agent 自验，主 agent 落盘则主 agent 自验。
+
+**交叉验证（`switchAgentVerification: true`）**：由对方 agent 承担验证，适用于需要更高置信度的场景。启用条件必须**同时满足**：
+
+1. 配置 `switchAgentVerification: true`
+2. 当前执行的 `f2s-*` 技能正文**明确写出**该步骤依赖本项
+
+交叉验证规则：
+
+| 落盘方 | 验证方 | 前提条件 |
+|--------|--------|----------|
+| 子 agent 落盘 | 主 agent 验证 | 无额外条件 |
+| 主 agent 落盘 | 子 agent 验证 | 须 `subAgent: true` 且实际已拆出子任务；否则仍由主 agent 自验 |
+
+设计意图：交叉验证引入外部视角，降低落盘侧的自验盲区，但增加执行开销，因此设为显式 opt-in 而非默认行为。
+
+### 4.3 变更追踪（changeTracking）
 
-## 5. 版本管理与索源
+`changeTracking` 是独立于 `subAgent` / `switchAgentVerification` 的第三个维度，控制技能执行时是否自动创建可跨会话续作的任务清单。
 
-字段格式见 [README-目录与路径约定 §4](./README-目录与路径约定.md#4-版本管理sourcedoc-与-generatedat)。
+```json
+{
+  "changeTracking": {
+    "feat": false,
+    "fix": false,
+    "implement": false
+  }
+}
+```
 
-- **sourceDoc**：产物 → 源文档。  
-- **docs-index 行**：文档 → 产物列表。  
-- **更新**：改 **stock-docs** 源文后，对同路径再执行 **f2s-ctx-build**。
+- 各技能子项独立控制，互不影响
+- 开启后：技能执行前自动检查 `.task/todo.json`，创建或续接任务；完成后自动归档
+- 跨会话：新会话描述相关内容，`f2s-task` 规则（`alwaysApply`）关键词匹配命中后自动加载剩余清单和对应技能上下文
+- `f2s-req-plan` 不受此配置约束，始终创建任务清单
 
 ---
 
-## 6. 推荐顺序（概要）
+## 5. 设计收益
 
-上下文链 → **req-docs** 实现 → **f2s-kb-*** 维护；冲突 **f2s-kb-merge**。详表：[README-命令说明](./README-命令说明.md#按使用顺序查找)。
+1. 跨工具共享同一业务知识源
+2. 不破坏 Claude/Cursor/Codex 的规则加载习惯
+3. 通过 `manifest-routing` + `matcherPath` 分片（`matchers/*.json`）控制任务路由与依赖，减少误读与全量扫描
+4. 主/子 agent 职责边界清晰，主 agent 始终持有全局视图，子 agent 专注单元处理，汇总一致性由主 agent 保证
+5. 验证归属可配置：默认落盘侧自验保持低开销，交叉验证按需启用提升关键场景置信度
 
 ---
 
-## 7. 延伸阅读
+## 6. 相关文档
 
-- **路径与链接**：[README-目录与路径约定](./README-目录与路径约定.md)  
-- **命令与速查**：[README-命令说明](./README-命令说明.md)  
-- **操作手册**：[Flow2Spec使用说明](./Flow2Spec使用说明.md)  
-- **使用案例（对话版式）**：[Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
+- [README-命令说明](./README-命令说明.md)
+- [README-目录与路径约定](./README-目录与路径约定.md)
+- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)