@double-codeing/flow2spec 2.2.2 → 3.0.7

package/templates/skills/f2s-doc-add/SKILL.md

@@ -1,142 +1,105 @@
 ---
 name: f2s-doc-add
-description: 工作中把已落地能力解析进上下文（与 f2s-doc-arch 分工不同）：多文件路径→适度深度解析→stock-docs 初稿→终稿→f2s-ctx-build 产出 Rules、Skills、docs-index；触发：f2s-doc-add、已有能力进知识库、多文件生成上下文
+description: 工作中把已落地能力解析进知识库（多文件聚合）：初稿→终稿→topics/index/manifest；触发：f2s-doc-add、已有能力进知识库、多文件生成上下文
 ---
 
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径；**路径默认相对「配置根的父目录」**（即业务仓库根），除非用户给出绝对路径。
+> 执行口径：本技能只维护 `.Knowledge`，不改配置根 `rules/skills`。
 
-# f2s-doc-add：多文件聚合 → 初稿 → 终稿 → Rules / Skills / 索引
+## 编排（主 / 子 agent）
 
-## 使用时机（何时才用本技能）
+- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。
+- 默认不拆子：主会话全流程完成；低于阈值时拆子收益低于 context 切换成本。
+- 拆子阈值（仅当 `subAgent=true` 且任一满足）：① 输入路径 ≥ 5；② 单源文件 > ~3000 行；③ 多路径总量 > ~10000 行。
+- **拆子策略（仅在达到拆子阈值且 `subAgent=true` 时启用）**：
+  - **B 模式（默认，单轮并行）**：主先产出「inventory（待解析源文档路径清单 + 核心能力名，主手写，禁止子 agent 自行增删）」+「扫描契约（每个源读哪些章节 / 行号范围、禁扫目录、统一产出字段与表头）」→ 子 agent 并行只读按表填写 → 主一轮合并 + 去重 → 写 `.Knowledge/stock-docs/<方案名>_初稿.md` → 主做用户确认与验收。适合源边界较清晰、中等规模、希望尽快出一版。
+  - **C 模式（大仓 / 高风险，多轮纠偏）**：在 B 之前或替代 B 首轮 —— 主先做 inventory → 子并行交表 → 主专做一轮**对表**（标重合 / 矛盾 / 缺依赖 / 跨源边界）→ 必要时对矛盾点补派小任务或主自读关键点 → 最后主写 / 改定稿。适合多 workspace / monorepo、目录极深、源路径 > 20 条、首轮子表矛盾或空洞明显、多源叙述重合或矛盾严重的场景。
+  - **切换判据**（任一成立即切到 C）：多 workspace / monorepo；目录极深或源路径 > 20 条；首轮子表矛盾 / 空洞明显；多源叙述重合 / 矛盾严重。
+- **子交付硬约束**：子 agent 不得自行裁剪源路径范围，必须按主手写 inventory 执行；交付按「子交付 YAML schema」（字段：`source` / `scope` / `capabilities` / `cross_refs` / `pending`），禁止散文式回传；子不得写 `manifest-routing.json` / `.Knowledge/index.md`；子不得单独宣布「已进知识库」。
+- 主必控：重合判定、终稿定稿、`f2s-ctx-build` 调度、整体验收。
+- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘。
+- 落盘侧自验。
 
-本技能面向**日常开发/维护中**这一场景：**某条能力或功能已经在代码里做好**（或已有对应说明分散在多个文件），你希望把它**系统化解析并写入 AI 可用的上下文**（`stock-docs` 终稿 + Rules + Skills + `docs-index`），便于后续对话与协作**照着知识库走**。
+# f2s-doc-add：多文件聚合 -> 初稿 -> 终稿 -> 知识路由同步
 
-- **典型**：补文档、做模块交接、把「已实现但只在代码里」的约定沉淀成可加载规则与技能。
-- **非典型（勿用本技能当首选）**：从零画整体架构蓝图、只要一份架构初稿——请用 **f2s-doc-arch** 及后续 **f2s-doc-final** / **f2s-ctx-build** 按步执行。
+## 使用时机
 
----
-
-## 与 f2s-doc-arch 的分工（必读）
-
-| 技能 | 典型入口 | 产出侧重 |
-|------|----------|----------|
-| **f2s-doc-arch** | **一段说明**、**单个文档路径**，或确认后的**无参扫描** | **项目/模块架构说明初稿**（默认 `架构说明_初稿.md` 等），不写终稿、不直接跑 ctx-build |
-| **f2s-doc-add**（本技能） | **工作中**为**已做好的能力**列出 **≥1 个相关文件路径**（实现、配置、说明等），多路径聚合 | 把该能力**解析进上下文**：**`stock-docs` 初稿** → **终稿** → **f2s-ctx-build** 生成 **Rules / Skills / docs-index** |
-
-**不要混用**：仅要「架构说明初稿」、入口是文字或单文档时，用 **f2s-doc-arch**，**不要**用本技能代替。仅当用户明确要为**已存在实现的一批文件**做「进知识库 / 进上下文」的整条链时，用本技能。
+- 某能力已在代码中落地，但信息分散在多个文件，需沉淀为可检索知识。
+- 与 `f2s-doc-arch` 区分：`doc-arch` 产出架构初稿；`doc-add` 产出“已落地能力”知识沉淀链路。
 
----
-
-本技能在流程上衔接 **f2s-doc-final** 与 **f2s-ctx-build** 的约定（**不包含** f2s-doc-arch 的架构专述步骤）：用户一次性提供**多个**本地文件路径，Agent **适度深度**阅读后先写 **`stock-docs` 初稿**，再在同一轮（或用户确认后的连续执行中）将初稿规范为 **终稿**，最后按 **`配置根/skills/f2s-ctx-build/SKILL.md`** 生成 **Rules、Skills、`docs-index.md`**（并按需更新 **`main.mdc`**）。
-
-**与 f2s-doc-final / f2s-ctx-build 的关系**：终稿形态、链接、`sourceDoc` 等**以 `f2s-doc-final`、`f2s-ctx-build` 原文为准**；本文件只规定**多源入参、读源策略、与 f2s-doc-arch 的边界**。
-
----
-
-## 入参
+## 输入
 
 | 参数 | 必填 | 说明 |
-|------|------|------|
-| **文件路径列表** | **是** | 一个或多个路径：空格/换行分隔，或对话中 `@` 多文件。支持 `.md`、`.txt`、常见源码与配置（`.js`、`.ts`、`.json`、`.yaml` 等）。路径相对**配置根的父目录**，或绝对路径。 |
-| **方案名**（可选） | 否 | 用于 `<方案名>_初稿.md`、`<方案名>_终稿.md` 及后续 **Rule/Skill 主题命名**；不传则从路径共性、目录名、`package.json` 的 `name` 等推断，并做**合法文件名**（去非法字符、避免空名）。 |
-| **初稿输出路径**（可选） | 否 | 默认 **`配置根/stock-docs/<方案名>_初稿.md`**。 |
-| **终稿输出路径**（可选） | 否 | 默认 **`配置根/stock-docs/<方案名>_终稿.md`**。 |
+| --- | --- | --- |
+| 文件路径列表 | 是 | 一个或多个路径（空格/换行/`@`）；支持源码、配置、文档 |
+| 方案名 | 否 | 用于生成 `<方案名>_初稿.md`、`<方案名>_终稿.md` |
+| 初稿/终稿路径 | 否 | 默认放 `.Knowledge/stock-docs/` |
 
-若用户**未给出任何可读路径**，**中止**并请其至少提供一条路径。
+无有效路径时中止并要求用户补充。
 
----
+## 步骤 0：重合判定（重要）
 
-## 与现有知识库重合时的处理（重要）
+执行前先对照：
 
-执行前与读源后，应用 **`配置根/docs-index.md`**、**`配置根/rules/`**、**`配置根/skills/`** 及 **`配置根/stock-docs/`** 做一次**对照**（必要时结合对话里已加载的 Rules/Skills 摘要）：
+- `.Knowledge/index.md`
+- `.Knowledge/topics/*.md`
+- `.Knowledge/stock-docs/*.md`
 
-| 情况 | 做法 |
-|------|------|
-| 用户给出的路径**本身就在** `stock-docs/`、`rules/`、`skills/` 内，且与当前任务**同一主题**（同一方案、同一模块说明） | **优先在原文件上直接修改**：合并重复段落、补全缺口、统一术语与链接，使单份文档或单条 Rule/Skill **自洽、合理**；**不要**仅为走流程再新建一套并行的 `_初稿.md` / `_终稿.md`，除非用户明确要求「另存新文件」。 |
-| 知识库里**已有**描述同一能力的终稿 / Rule / Skill，而用户给的是**外围代码或其它 MD** | 以**既有知识库文件为锚点**：把新读到的信息**吸收进**对应终稿或专题 Rule/Skill（更新正文与 `generatedAt`），并同步 **`docs-index.md`** 中该行的「简要说明」等；避免 **docs-index** 出现多行指向实质重复的主题。 |
-| **无重合**或确认为**全新主题** | 按默认路径新建 **`<方案名>_初稿.md`** → **`_终稿.md`**，再执行步骤 4 **新建或追加** Rule/Skill 与索引行（仍遵守 **f2s-ctx-build** 的「同一终稿只占一行」）。 |
+若已有同主题沉淀，优先原位更新，避免重复主题和重复索引行。
 
-**原则**：知识库里**已经写过**的说明，以**修订原文件**为主，保证上下文**不重复、不打架**；新建文件仅在有明确增量主题或用户指定新方案名时使用。
+## 步骤 1：适度深度解析
 
----
-
-## 步骤 0：准备
-
-1. 确保 **`配置根/stock-docs/`** 存在（不存在则创建）。
-2. 解析路径列表：去重、展开用户 `@` 的文件；**不存在的路径**在初稿「来源与缺口」中列出，**不中断**（除非全部无效则中止）。
-3. **对照**上文「与现有知识库重合时的处理」：决定本轮产出是**更新既有路径**还是**新建** `<方案名>_初稿.md` / `_终稿.md`，并在回复中**一句话说明**本次选择理由。
-
----
-
-## 步骤 1：适度深度解析（读源策略）
-
-对每个文件**依次**读取（可用工具分批，避免单次过大）：
-
-| 情况 | 策略 |
-|------|------|
-| 文本/Markdown/常规源码，体量 **≤ 约 500 行** | 尽量**通读**全文。 |
-| **更大** 或响应体过长 | **适度深度**：优先读 **文件头/尾**、**导出/类/接口定义**、**配置块**、**README 式章节标题**；代码可结合目录与符号性段落归纳，**禁止**假装已读未读部分。 |
-| **二进制**或无法解码 | 跳过并在初稿注明「无法解析」。 |
-| **多文件** | 归纳：**模块边界**、**重复出现的概念**、**依赖/调用关系**、与 **`配置根`** 约定相关的目录（若有）。 |
-
-解析目标：足够支撑一份**结构清楚、有主有次**的初稿，而非逐字抄录。
-
----
+- 小文件通读；
+- 大文件优先结构与关键片段（导出、接口、配置、流程）；
+- 不确定内容显式标注“待确认”，禁止编造。
+- 若任一拆子阈值满足（输入路径 ≥ 5 / 单源 > ~3000 行 / 多路径总量 > ~10000 行）且 `subAgent=true`，按 B 模式（默认）或 C 模式（达成切换判据时）拆子并行只读扫描；否则主全流程。**启用拆子时，子 agent 必须按主手写 inventory 与扫描契约执行，不得自行增删源路径。**
 
 ## 步骤 2：生成初稿
 
-1. 若已判定在**既有文件**上修订：可将「初稿」阶段体现为**该文件内的增补段落**或**同路径覆盖**（合并读源结论），不必机械新建 `_初稿.md`。否则写入 **默认** **`配置根/stock-docs/<方案名>_初稿.md`**（或用户指定的初稿路径）。
-2. 初稿**无固定版式**，建议包含：
-   - **概述**（这批文件共同说明什么）；
-   - **来源清单**（路径 + 每文件一句话作用 + 是否部分阅读）；
-   - **分文件/分模块归纳**（适度深度解析的结论）；
-   - **交叉关系**（配置、入口、数据流等）；
-   - **待确认项**（读源时未覆盖或推断处）。
-3. 文末可加一句：**「本初稿由 f2s-doc-add 根据用户所列文件聚合生成。」**
+- 默认输出：`.Knowledge/stock-docs/<方案名>_初稿.md`
+- 初稿建议结构：
+  - 概述
+  - 来源清单（含不可读文件）
+  - 分模块归纳
+  - 交叉关系
+  - 待确认项
 
----
-
-## 步骤 3：基于初稿生成终稿（对齐 f2s-doc-final）
+## 步骤 3：生成终稿
 
-1. **读取** **`配置根/template/终稿模版.md`**（若存在）作为章节提示；**不强制逐条套用**，以初稿事实与逻辑为主。
-2. 将初稿**提炼、归纳**为终稿风格 Markdown（参见 **`配置根/skills/f2s-doc-final/SKILL.md`** 流程一）：
-   - **一级标题** = 方案名（可与 `<方案名>` 一致或略润色）；
-   - **至少**包含二级标题：**核心概念**、**业务规则**、**关键流程**；
-   - 按需补充：状态与流转、接口/API、配置与错误、实现位置与对接方式等。
-3. 写入 **默认** **`配置根/stock-docs/<方案名>_终稿.md`**（或用户指定的终稿路径）；若本轮锚定**已有终稿路径**，则在**该文件上**按终稿结构整理保存，并保证 **`sourceDoc` 仍指向该路径**（步骤 4 中 Rule/Skill 链接与 frontmatter 与之一致）。
+- 参考 `.Knowledge/template/终稿模版.md`
+- 输出：`.Knowledge/stock-docs/<方案名>_终稿.md`
+- 若用户要求“先审初稿”，则停在初稿并等待确认
 
-若用户要求「先审初稿再出终稿」，可在初稿保存后**暂停**并等待确认；用户确认后从**同一份初稿**继续执行步骤 3～4。
+## 步骤 4：同步知识路由
 
----
+基于终稿调用 `f2s-ctx-build` 口径，更新：
 
-## 步骤 4：基于终稿生成 Rules、Skills 与索引（对齐 f2s-ctx-build）
+- `.Knowledge/topics/`
+- `.Knowledge/index.md`
+- 路由清单（必要时）
 
-以 **步骤 3 产出或修订后的终稿**（单一 `stock-docs` 下的 `.md` 文件）为 **`sourceDoc` 锚定文档**，执行 **`配置根/skills/f2s-ctx-build/SKILL.md`** 中的要求，包括但不限于：
+## 输出摘要（必须）
 
-- **拆解与分工**：篇幅长、多块独立内容时，拆成多条专题 Rule / 多个 Skill + 总览；否则可单 Rule + 单 Skill。
-- **文档路径与链接约定**（**必守**）：Rule 正文链向源文档用 **`../stock-docs/<终稿文件名>.md`**；Skill 用 **`../../stock-docs/<终稿文件名>.md`**；`docs-index.md` 中该文档格用 **`stock-docs/<终稿文件名>.md`** 作为 href；每条 Rule/Skill 的 frontmatter **`sourceDoc`** 为 **`配置根/stock-docs/<终稿文件名>.md`**，并带 **`generatedAt`**（东八区 ISO 8601）。
-- **`main.mdc`**：按 f2s-ctx-build「3.0」判断是否更新模块一览/公共能力入口。
-- **`docs-index.md`**：同一终稿路径**只占一行**；若已存在则**更新**该行的 Rules、Skills、简要说明。
+1. 初稿/终稿路径
+2. 更新的 topic/index/路由清单 路径
+3. 未完成项与原因（如路径无效、信息不足）
 
-**禁止**将 **`req-docs/`** 下的文件作为本技能链最终 `sourceDoc` 指向；终稿必须在 **`stock-docs/`**。
+## 复杂场景示例
 
----
+用户输入 6 个文件（代码、配置、旧文档混合），其中 2 个路径不可读。
 
-## 输出与自检
+- 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
+- 若发现已有 `.Knowledge/stock-docs/支付能力_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
+- 用户要求“先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。
 
-完成后向用户说明：
+## 约束
 
-1. **初稿**（若单独落盘）、**终稿**的磁盘路径，或写明「本轮仅在既有 `xxx.md` / 某 Rule / 某 Skill 上修订」；
-2. **新建或更新**的 Rule、Skill 路径及 **`docs-index`** 是否已更新；
-3. 提醒：若 **`main.mdc`** 已改，需扫一眼渐进式读取约定是否仍连贯。
-
-**自检**：对照 **`f2s-ctx-build`** 技能末尾「完成后自检（路径必查）」五项，核对链接与 `sourceDoc`。
-
----
+- 终稿 `sourceDoc` 仅指向 `.Knowledge/stock-docs/*`
+- 不改配置根 `rules/skills`
+- 同主题优先更新，不平行新建重复知识
+- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束），子 agent 不得触碰
 
-## 约束与注意
+## 完成后自检
 
-- **与知识库重合时**：已述内容见上文「与现有知识库重合时的处理」；**禁止**在已有同主题终稿/Rules/Skills 时仍机械新建平行文件导致重复索引。
-- **适度深度**是硬性要求：大文件不得虚构未读段落细节；不确定处写入待确认或终稿「（待补充）」。
-- **版权与敏感**：用户给出的路径可能含密钥或内网信息；写入 `stock-docs` 前**脱敏**或删去秘钥，并在初稿/终稿注明「已脱敏」若已处理。
-- 本技能**不替代**单独执行 **f2s-doc-pdf**（PDF 须先转 MD 再作为路径列表之一传入）。
+1. 初稿/终稿路径是否落在 `.Knowledge/stock-docs/`。
+2. 同主题是否避免重复新建。
+3. topic/index/manifest 是否与终稿语义一致。

package/templates/skills/f2s-doc-arch/SKILL.md

@@ -2,13 +2,23 @@
 name: f2s-doc-arch
 description: 根据用户说明或文档（或扫描代码）生成项目架构说明初稿，无固定格式，描述清楚即可；触发：项目架构说明、f2s-doc-arch、架构初稿
 ---
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+> 执行口径：本技能产物默认写入 `.Knowledge/stock-docs/`，后续由知识库技能链（如 `f2s-doc-final`、`f2s-ctx-build`）同步到 `.Knowledge/topics/index/manifest`。
+
+## 编排（主 / 子 agent）
+
+- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
+- 当 `subAgent=true` 时，从以下两种子策略择一：
+  - **B 模式（默认，单轮并行）**：主先产出「inventory（入口 + 核心模块名，主手写）」+「扫描契约（可读路径 / 禁扫目录 / 统一产出字段）」→ 子 agent 并行只读扫表 → 主一轮合并去重 → 写 `stock-docs` 初稿 → 用户确认与验收在主 agent 内完成。
+  - **C 模式（多轮纠偏）**：切换判据为以下任一 —— 多 workspace / monorepo、目录极深或源路径 > 20 条、首轮子表矛盾或空洞明显、多源叙述重合 / 矛盾严重。
+- **子交付硬约束**：子 agent 不得自行裁剪目录范围，必须按主手写 inventory 执行；子交付按「子交付 YAML schema」（字段：`source` / `scope` / `cross_refs` / `pending`），禁止散文式回传。
+- **写权硬约束**：`.Knowledge/index.md` / `manifest-routing.json` 恒由主 agent 落盘，子 agent 不得触碰。
+- 落盘侧自验；本 SKILL 不绑定交叉校验。
 
 # 生成项目架构说明（初稿）
 
 本技能用于**帮助用户生成项目架构的文档说明**，产出形态类似**初稿**：无固定格式规范，以**描述清楚**为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。
 
-**与 f2s-doc-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-ctx-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进上下文（初稿→终稿→Rules/Skills/索引），应使用 **`配置根/skills/f2s-doc-add/SKILL.md`**，**勿用本技能冒充该流程**。
+**与 f2s-doc-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-ctx-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进知识库（初稿→终稿→topics/index/manifest），应使用 **`f2s-doc-add`**，**勿用本技能冒充该流程**。
 
 ---
 
@@ -16,8 +26,8 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 
 | 参数           | 说明                                                                                                                                                              |
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `配置根/stock-docs/xxx.md`、**`配置根/req-docs/README.md`**、`README.md`）。不传则进入「无输入」流程。 |
-| **第二个参数** | 可选。输出文件路径；若不传，默认写入 `配置根/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。                          |
+| **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `.Knowledge/stock-docs/xxx.md`、`.Knowledge/req-docs/README.md`、`README.md`）。不传则进入「无输入」流程。 |
+| **第二个参数** | 可选。输出文件路径；若不传，默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。 |
 
 **注意**：不传任何说明或文档时，将使用 **AI 扫描项目代码与目录** 生成架构说明初稿，**不保证质量**。执行时**必须先提示用户**：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才继续。
 
@@ -34,11 +44,12 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
    - 根据用户说明中的**代码路径、模块名、入口**等线索，结合配置根的父目录下的实际目录结构、关键文件（如 package.json、入口文件、配置文件）进行**归纳与补全**。
    - 若用户说明较宽泛（如只说了「一个后台系统」），**主动引导**用户补充：主要代码路径、模块/包划分、入口与启动方式、与外部系统的边界等，便于生成更贴合的架构说明。
 3. **生成初稿**
+   - 若启用拆子（B 模式），子 agent 必须按主手写 inventory 执行扫描，交付遵循子交付 YAML schema。
    - 产出一份**项目架构说明**：可包含但不限于：项目定位、技术栈、目录/模块划分、关键路径与入口、配置与部署要点、与文档产物阶段的对应说明（若适用）。
    - **无固定格式**：采用清晰的标题与段落即可，不强制套用《终稿模版》。
 4. **输出**
-   - 默认写入 `**配置根/stock-docs/架构说明_初稿.md**`；若用户传入第二参数则写入该路径。
-   - 若 `配置根/stock-docs/` 不存在则先创建。
+   - 默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`；若用户传入第二参数则写入该路径。
+   - 若目录不存在则先创建。
 
 ### 2. 若用户未提供任何说明或文档
 
@@ -50,21 +61,21 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
    - 基于配置根的父目录：列出主要目录与代表性文件（可结合 package.json、常见入口与配置文件名），归纳出「目录结构、疑似模块、入口与配置」等。
    - 生成一份**架构说明初稿**，并在文中注明「本初稿由扫描项目结构生成，建议结合业务说明与代码细节进一步补充」。
 3. **输出**
-   - 同上，默认 `配置根/stock-docs/架构说明_初稿.md`，或用户指定的第二参数。
+   - 同上，默认 `.Knowledge/stock-docs/架构说明_初稿.md`，或用户指定的第二参数。
 
 ---
 
 ## 引导与迭代
 
 - 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。
-- 生成初稿后，可提示用户：可根据需要修改 `配置根/stock-docs/xxx架构说明_初稿.md`，若需转为《终稿模版》规范格式，可再按 **f2s-doc-final** 技能、以 `配置根/stock-docs/xxx架构说明_初稿.md` 为入参得到终稿（`_终稿.md`），再按 **f2s-ctx-build** 技能生成 Rules、Skills。
+- 生成初稿后，可提示用户：可根据需要修改 `.Knowledge/stock-docs/xxx架构说明_初稿.md`，若需转为《终稿模版》规范格式，可再按 **f2s-doc-final** 技能，以该路径为入参得到终稿，再按 **f2s-ctx-build** 同步知识路由主题与索引。
 
 ---
 
 ## 路径与输出约定
 
 - 所有路径均相对于**配置根的父目录**。
-- **默认输出**：`配置根/stock-docs/架构说明_初稿.md`；项目名取自 `package.json` 的 `name`（去掉 scope 与非法字符）或当前目录名。
+- **默认输出**：`.Knowledge/stock-docs/架构说明_初稿.md`；项目名取自 `package.json` 的 `name`（去掉 scope 与非法字符）或当前目录名。
 - 若用户传入第二参数为输出路径，则优先使用该路径；若目录不存在则先创建。
 
 ---

package/templates/skills/f2s-doc-final/SKILL.md

@@ -1,17 +1,25 @@
 ---
 name: f2s-doc-final
-description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-ctx-build 生成 Rules、Skills、索引；触发：f2s-doc-final、转成概述模板、终稿模版
+description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-ctx-build 同步 topics/index/manifest；触发：f2s-doc-final、转成概述模板、终稿模版
 ---
 
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+> 执行口径：初稿/终稿统一写入 `.Knowledge/stock-docs/`；模板优先读取 `.Knowledge/template/终稿模版.md`。
+
+## 编排（主 / 子 agent）
+
+- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
+- **默认不拆子**：MD / PDF → 终稿模版的连贯性最好，由主会话一气呵成完成理解、套模版与定稿。
+- **可选拆子**（仅当 `subAgent=true` 且大体量 / 多文件，阈值：PDF **> 50 页** 或 **> ~5MB 文本**）：子 agent 做「套模版、排版与结构搬运」**草稿**；主 agent 对照终稿模版、识别缺口并向用户追问、与用户对齐并**定稿 / 验收**；**子 agent 不得单独宣称终稿已合规**。
+- 不为「格式转换可独立」默认拆子：终稿合规依赖模版语义 + 业务表述，主侧验收成本通常仍在。
+- 校验：落盘侧 agent 自验，本 SKILL 不绑定交叉校验。
 
 # 将 PDF 或 MD 转换为《终稿模版》规范格式（spec → context）
 
 用户会在本技能后附带**至少一个参数**：**第一个参数**为本地 **PDF 文件路径**或 **Markdown 文件路径**（必填）；**第二个参数**（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 **f2s-ctx-build** 技能消费的终稿风格 Markdown 文档。
 
-**终稿模版仅作提示**：若存在项目内 **`配置根/template/终稿模版.md`**（或 Flow2Spec 包内的 `templates/template/终稿模版.md`），可读取作为**结构参考与写作提示**，**不强制套用**；输出以原文内容与逻辑为主，按需采纳模版中的章节建议。若项目内无该文件，则按本技能下方「内嵌模板结构」作为可选参考。
+**终稿模版仅作提示**：若存在 `.Knowledge/template/终稿模版.md`（来源 `templates/knowledge/template/终稿模版.md`），可读取作为结构参考；不强制套用。
 
-## 内嵌模板结构（当项目内无「配置根」下 `template/终稿模版.md` 时使用）
+## 内嵌模板结构（当项目内无 `.Knowledge/template/终稿模版.md` 时使用）
 
 规范要求：
 
@@ -28,15 +36,15 @@ description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续
 ## 流程一：用户传入的是 Markdown（.md）
 
 1. **读取**用户传入的 `.md` 文件内容。
-2. **参考格式**（不强制）：若存在 `配置根/template/终稿模版.md` 或包内 `templates/template/终稿模版.md`，可读取作为结构提示；否则可参考下方内嵌模板结构。**不强制套用**，以原文信息完整、逻辑清晰为主。
+2. **参考格式**（不强制）：若存在 `.Knowledge/template/终稿模版.md`，可读取作为结构提示；否则可参考下方内嵌模板结构。
 3. **分析与转换**：
   - 理解原文主题与结构，提炼「方案名」「核心概念」「业务规则」「关键流程」及与原文相关的其他章节（如状态与流转、接口、配置/表设计/错误码、实现位置等）。
   - 将内容重组为结构清晰的终稿风格 Markdown：一级标题为方案名；建议至少包含 核心概念、业务规则、关键流程 三个二级标题，其余按原文有无与需要增删；表格/列表格式可参考模版，不必完全一致。
   - 若原文缺少某节，可标「（待补充）」或根据原文推断补全；若原文结构已清晰，可保留原文章节命名。
 4. **输出**：
-  - 默认写入 `**配置根/stock-docs/<方案名>_终稿.md**`（方案名由一级标题或文件名推断，做合法文件名处理；**最终产物带 `_终稿` 标识**）。
+  - 默认写入 `.Knowledge/stock-docs/<方案名>_终稿.md`（最终产物带 `_终稿` 标识）。
   - 若用户希望指定输出路径，可在命令后附带第二个参数作为输出路径；否则用默认。
-5. **回复**：告知用户已生成 `配置根/stock-docs/<方案名>_终稿.md`，并提示可按 **f2s-ctx-build** 技能、以 `配置根/stock-docs/<方案名>_终稿.md` 为入参生成 Rules、Skills。
+5. **回复**：告知用户已生成 `.Knowledge/stock-docs/<方案名>_终稿.md`，并提示可按 `f2s-ctx-build` 继续同步 `.Knowledge/topics`、`.Knowledge/index.md`（必要时 `manifest`）。
 
 ---
 
@@ -46,34 +54,34 @@ description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续
 
 ### 步骤 A：首次执行（传入 PDF 路径）
 
-1. **尝试读取 PDF**：按用户传入路径读取 PDF（可为绝对路径，或相对**配置根的父目录**；如 `配置根/stock-docs/xxx.pdf`）。
+1. **尝试读取 PDF**：按用户传入路径读取 PDF（可为绝对路径，或相对项目根；如 `.Knowledge/stock-docs/xxx.pdf`）。
   - 若当前环境可解析 PDF 文本：提取正文，转为 Markdown 初稿（保留标题层级、列表、段落，表格若可识别则保留）。
-  - 若无法直接读取 PDF（如仅能拿到二进制）：回复用户「当前无法直接解析 PDF，请任选其一：① 将 PDF 内容复制粘贴到项目内 `配置根/stock-docs/xxx.md`，再执行本技能并传入该路径；② 使用本地工具将 PDF 转为 .md 后，把 .md 路径传入本技能。」
+  - 若无法直接读取 PDF（如仅能拿到二进制）：回复用户可将 PDF 内容转存为 `.Knowledge/stock-docs/xxx.md` 后再执行。
 2. **生成初稿**：
-  - 将提取出的内容保存为 `**配置根/stock-docs/<方案名>_初稿.md**`（方案名可从 PDF 文件名或首标题推断）。
+  - 将提取出的内容保存为 `.Knowledge/stock-docs/<方案名>_初稿.md`（方案名可从 PDF 文件名或首标题推断）。
   - 在回复中**展示初稿的全文或主要结构**，并明确说明：
-    - 「初稿已保存为 `配置根/stock-docs/<方案名>_初稿.md`，请检查并修改。」
-    - 「确认无误后，请执行：`**f2s-doc-final 技能 配置根/stock-docs/<方案名>_初稿.md**`，将自动转换为《终稿模版》规范格式。」
+    - 「初稿已保存为 `.Knowledge/stock-docs/<方案名>_初稿.md`，请检查并修改。」
+    - 「确认无误后，请执行：`f2s-doc-final .Knowledge/stock-docs/<方案名>_初稿.md`。」
 3. **本轮不进行模板格式转换**，仅完成 PDF → 初稿 MD。
 
 ### 步骤 B：用户确认后再次执行（传入初稿 .md 路径）
 
-当用户**再次执行本技能并传入初稿的 .md 路径**（如 `配置根/stock-docs/技术方案设计_初稿.md`）时：
+当用户**再次执行本技能并传入初稿的 .md 路径**（如 `.Knowledge/stock-docs/技术方案设计_初稿.md`）时：
 
 - 按 **「流程一：用户传入的是 Markdown」** 的步骤 2～5 执行：读取格式规范 → 分析与转换 → 输出为模板格式。
-- **输出建议**：生成 `**配置根/stock-docs/<方案名>_终稿.md**`（与初稿同方案名，最终产物带 `_终稿` 标识），作为最终规范版；初稿文件可保留供对比，或在回复中提示用户可自行删除 `_初稿.md`。
-- **回复**：告知已生成规范版 `配置根/stock-docs/<方案名>_终稿.md`，并提示可按 **f2s-ctx-build** 技能、以该路径为入参生成 Rules、Skills。
+- **输出建议**：生成 `.Knowledge/stock-docs/<方案名>_终稿.md`。
+- **回复**：告知已生成规范版，并提示可按 `f2s-ctx-build` 继续同步 `.Knowledge/topics` 与索引。
 
 ---
 
 ## 路径与输出约定
 
-- 所有路径均相对于**配置根的父目录**；初稿/终稿等统一放在 **配置根** 下的 **`stock-docs/`** 目录内（存量上下文源，供 **f2s-ctx-build** 技能使用）。
-- **输入**：用户传入的**第一个参数**为文件路径（必填），如 `配置根/stock-docs/方案.pdf` 或 `配置根/stock-docs/方案_初稿.md`；**第二个参数**（可选）为输出路径，若提供则覆盖默认输出位置。
+- 所有路径均相对于项目根；初稿/终稿统一放在 `.Knowledge/stock-docs/`。
+- **输入**：第一个参数为文件路径（必填），如 `.Knowledge/stock-docs/方案.pdf` 或 `.Knowledge/stock-docs/方案_初稿.md`；第二个参数可选。
 - **输出**：
-  - PDF 首次：`配置根/stock-docs/<方案名>_初稿.md`
-  - MD 或初稿 MD（最终产物）：`配置根/stock-docs/<方案名>_终稿.md`（若用户传入第二参数为输出路径，则用该路径）。
-- 若 `配置根/stock-docs/` 目录不存在，先创建再写入。
+  - PDF 首次：`.Knowledge/stock-docs/<方案名>_初稿.md`
+  - MD 或初稿 MD：`.Knowledge/stock-docs/<方案名>_终稿.md`
+- 若 `.Knowledge/stock-docs/` 目录不存在，先创建再写入。
 
 ---
 
@@ -81,5 +89,5 @@ description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续
 
 - 转换时**不要照抄原文**，要按模板**提炼、归纳、补全**，使核心概念、业务规则、关键流程清晰可查。
 - 建议（不强制）保留 **核心概念、业务规则、关键流程** 三个二级标题；其余章节按原文与需求增删，终稿模版仅作提示，不强制套用。
-- 完成后用一句话总结：已生成 xxx（初稿路径或终稿路径 `配置根/stock-docs/<方案名>_终稿.md`），并说明下一步建议（确认后再次执行本技能，或按 **f2s-ctx-build** 技能以终稿路径为入参）。
+- 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 `f2s-ctx-build` 同步知识路由主题与索引。
 

package/templates/skills/f2s-doc-pdf/SKILL.md

@@ -3,17 +3,24 @@ name: f2s-doc-pdf
 description: 将 PDF 技术方案转为 Markdown 并保存到 req-docs，可补全流程说明；触发：PDF转MD、按方案实现前的 PDF
 ---
 
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+> 执行口径：技术方案文档统一落在 `.Knowledge/req-docs/`；规则能力仍由配置根 `rules/skills` 加载。
+
+## 编排（主 / 子 agent）
+
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本文不复述。
+- **默认不拆子**：追问-落盘必须在主 agent 内完成（子 agent 无法向用户追问）。
+- **可选拆子**：仅当 `subAgent=true` 且 PDF 规模超阈值（**> 50 页 或 > ~5MB 文本**）时启用；子 agent 仅负责 PDF→MD 首稿并落盘 `.Knowledge/req-docs/<名>.md`，**不向用户追问、不写「流程说明」章节**；主 agent 接手后续追问与流程图补写。
+- 校验默认由落盘侧 agent 自验；本 SKILL 不绑定交叉校验。
 
 # 将 PDF 技术方案文档转为 Markdown（并补全流程说明）
 
-用户会在本技能后附带**一个参数**：**PDF 技术方案文档的本地路径**（如 `~/Downloads/技术方案.pdf`，或已落在 **配置根** 下的 **`req-docs/某草稿.pdf`**）。请按以下步骤执行，将 PDF 技术方案文档转为 Markdown 并保存到**配置根 `req-docs/`** 下，必要时引导用户补全流程说明。
+用户会在本技能后附带**一个参数**：**PDF 技术方案文档的本地路径**（如 `~/Downloads/技术方案.pdf`，或 `.Knowledge/req-docs/某草稿.pdf`）。请按以下步骤执行，将 PDF 转为 Markdown 并保存到 `.Knowledge/req-docs/`，必要时引导用户补全流程说明。
 
 ## 步骤 1：读取 PDF 并转为 Markdown
 
-1. **读取**用户传入的 PDF 文件，提取其中的**文字内容**（表格、章节、列表、代码块等尽量保留结构），整理为 Markdown 格式。
-2. **保存到配置根下** `req-docs/`，推荐路径：`**配置根/req-docs/<方案名>.md**`（如 `.cursor/req-docs/xxx.md`；技术方案用于「按方案实现代码」；**`stock-docs/`** 用于生成 Rules/Skills 的源文档，不用于实现）。文件名为原 PDF 文件名去掉 `.pdf` 后加 `.md`。
-3. 若配置根下尚无 **`req-docs/`**，可先创建再写入（`flow2spec init` 会预建该目录）。
+1. 若启用拆子（PDF > 50 页 或 > ~5MB），子 agent 仅负责 PDF→MD 首稿并落盘 `req-docs/<名>.md`，不追问、不写流程说明；主 agent 接手后续步骤。**读取**用户传入的 PDF 文件，提取其中的**文字内容**（表格、章节、列表、代码块等尽量保留结构），整理为 Markdown 格式。
+2. **保存到** `.Knowledge/req-docs/`，推荐路径：`.Knowledge/req-docs/<方案名>.md`。文件名为原 PDF 文件名去掉 `.pdf` 后加 `.md`。
+3. 若目录不存在，先创建再写入。
 4. 保存后告知用户：「已将该 PDF 转为 Markdown 并保存为 `xxx.md`。」
 
 ---
@@ -22,11 +29,11 @@ description: 将 PDF 技术方案转为 Markdown 并保存到 req-docs，可补
 
 PDF 内嵌的**流程图**无法被直接解析为步骤与分支，若需按图实现代码，需用户配合提供。
 
-1. 向用户说明：「文档中可能包含流程图，我无法从 PDF 中解析图中的步骤与分支。若您后续会根据技术方案实现代码（见 配置根/rules/implement-tech-design.mdc），建议补全流程说明：
+1. 向用户说明：「文档中可能包含流程图，我无法从 PDF 中解析图中的步骤与分支。若您后续会根据技术方案实现代码（见 `implement-tech-design` 规则），建议补全流程说明：
   - **方式一**：将相关流程图以**图片形式**发到本次对话中，我将解析后以文字形式写入上述 MD；  
   - **方式二**：直接以**文字描述**每个接口/流程的步骤（如：1. 是否登录 2. 查某表 3. 判断某字段 → 返回结果），我将原样写入上述 MD。  
    若文档无流程图或暂不提供，可回复「跳过」，我将结束本技能。」
-2. **若用户回复「跳过」或明确表示无需流程说明**：告知用户「在对话中提供上述 MD 路径，并说明要按该技术方案实现代码，我将按 **配置根/rules/implement-tech-design.mdc** 执行。」并结束。
+2. **若用户回复「跳过」或明确表示无需流程说明**：告知用户「在对话中提供上述 MD 路径并说明按技术方案实现代码，我将按 `implement-tech-design` 规则执行。」并结束。
 3. **若用户提供流程图（图片或文字）**：进入步骤 3。
 
 ---
@@ -52,12 +59,12 @@ PDF 内嵌的**流程图**无法被直接解析为步骤与分支，若需按图
 …
 ```
 
-1. 保存后告知用户：「流程说明已写入 `xxx.md`。接下来请在对话中提供该 MD 路径并说明要按技术方案实现代码，我将按 **配置根/rules/implement-tech-design.mdc** 执行。」
+1. 保存后告知用户：「流程说明已写入 `xxx.md`。接下来请在对话中提供该 MD 路径并说明要按技术方案实现代码，我将按 `implement-tech-design` 规则执行。」
 
 ---
 
 ## 约束与小结
 
-- **路径**：用户传入的 PDF 路径可为绝对路径或相对于配置根的父目录的路径。输出 MD 建议保存在 **`配置根/req-docs/<方案名>.md`**（如 `.cursor/req-docs/...`；**`req-docs/`** 在配置根下，放需要实现成代码的技术方案；**`stock-docs/`** 放生成 Rules/Skills 的存量源文档）。
-- **本技能仅负责**：PDF → Markdown 转换 + 可选流程说明补全；不执行代码实现。完成后可提示用户：在对话中提供生成的 MD 路径并说明按技术方案实现，AI 将按 **implement-tech-design.mdc** 执行。
+- **路径**：用户传入的 PDF 路径可为绝对路径或相对项目根。输出 MD 建议保存在 `.Knowledge/req-docs/<方案名>.md`（`req-docs` 放实现文档，`stock-docs` 放知识沉淀源文档）。
+- **本技能仅负责**：PDF → Markdown 转换 + 可选流程说明补全；不执行代码实现。完成后可提示用户：在对话中提供生成的 MD 路径并说明按技术方案实现，AI 将按 **f2s-implement-tech-design.mdc** 执行。