@double-codeing/flow2spec 3.0.19 → 3.1.1

package/templates/rules/f2s-topic-authoring.mdc

@@ -0,0 +1,124 @@
+---
+description: Flow2Spec 主题创作准则：topic 命名 / 骨架 / topicMetadata / topicDependencies 判定 / rule 是否需建对应 topic / 写盘权属指针
+alwaysApply: false
+---
+
+# Flow2Spec 主题创作准则（Topic Authoring）
+
+本条为 **创作侧** 单一事实源；凡 `f2s-*` 技能在新增或修改 `.Knowledge/topics/<topic>.md`、调整 `manifest-routing.topicMetadata` / `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**必须先 Read 本条全文**，再按对应 SKILL 的步骤继续。与 `f2s-flow2spec-unified-entry`（消费侧）**并存**；硬冲突时以统一入口为准。
+
+## 适用范围
+
+满足下列任一即「触达本条」：
+
+- 新增或重写 `.Knowledge/topics/<topic>.md`；
+- 修改既有 topic 的标题 / 适用场景 / 关键流程边界；
+- 新增、删除或调整 `manifest-routing.topicMetadata`；
+- 在 `manifest-routing.topicDependencies` 中新增、删除或调整依赖边；
+- 在 `taskToTopicRules[].topics` 中新增引用某个 topic id；
+- 删除或迁移 topic（`f2s-kb-rm` / `f2s-kb-migrate` / `f2s-kb-upgrade`）。
+
+## 1. topic 命名
+
+- **id**：`kebab-case`，与 `manifest-routing.topicPaths` 的 key 一致。
+- **文件名**：`.Knowledge/topics/<topic-id>.md`；若该 topic 与同名 `f2s-*` 技能 / 规则强绑定（如 `f2s-task` / `f2s-req-plan`），文件名可加 `f2s-` 前缀以示同源。
+- **不要**：版本后缀（`-v2` / `-new`）、个人花名、与 `index.md` 行级标题冲突的同义词。
+
+## 2. topic 定位与正文骨架
+
+**topic 的定位**：可执行路由摘要 + 关键边界。topic 可以包含必要的边界说明、关键流程步骤、禁止项、配置摘要——Agent 读完即可执行或判断是否需要继续下钻；**不应承载**完整实现细节、长文背景或可在 stock-doc 里查的原始内容。stock-doc 承载完整背景与长文细节，topic 指向它。
+
+每个 topic 至少包含：
+
+1. **标题与一句话意图**（一行写清"该 topic 解决什么"）；
+2. **适用场景 / 触发词**（与对应 `matchers/<id>.json` `includeAny` 语义一致）；
+3. **核心规则 / 流程**（可执行知识；步骤须可由 Agent 复现）；
+4. **依赖声明**（若 `topicDependencies` 中存在依赖项，正文须显式写一句「执行前须先读依赖主题 `<dep>`」，参考 `topics/f2s-req-plan.md` 首段写法）；
+5. **边界与禁止项**（避免膨胀到隔壁 topic）。
+
+## 3. topicMetadata 判定准则
+
+`topicMetadata` 是治理元数据，只影响盘点、审计和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不改变执行强制性。执行强制性以 `AGENTS.md`、rules、skills 与 topic 正文明确要求为准。
+
+字段：
+
+- `primary`：主分类，单值，取 `feature` / `module` / `config` / `policy`。
+- `tags`：可选，数组，取值范围同 `primary`，不得与 `primary` 重复。用于描述 topic 同时包含的次要性质，仅作审计/阅读预期，不参与路由或执行。
+- `confidence`：取 `manual` / `inferred`。
+
+判定：
+
+1. `topicMetadata` key 必须存在于 `topicPaths`；仅给已存在或本次确认创建的 topicId 写入。
+2. `primary` 取 topic 最核心的性质：读 topic 正文，判断其主要内容属于哪个类型，写入 `primary`。
+3. `config`：配置项、开关、默认值、初始化参数。
+4. `policy`：流程、规则、约束、门禁、禁止项、agent 编排、技能步骤。
+5. `feature`：已落地业务 / 产品能力。
+6. `module`：目录、包、模块边界与工程结构。
+7. topic 同时覆盖多个性质时，最主要性质写 `primary`，其余明确成立的性质写 `tags`（可选数组，元素取值同 `primary`，不得与 `primary` 重复）。
+8. `manual` 仅用于用户或维护者明确确认分类值；有明确证据但未人工确认分类值时写 `inferred`。证据不足时**不写 metadata**，但须在摘要中列出推断方向与依据（如「建议 policy，正文含多处强制约束」），供用户确认后手动补写 `manual`。**禁止仅凭 topicId 名称推断分类，必须 Read topic 正文后再判断。**
+
+禁止：为了分类创建、重命名、拆分 topic；在 topic markdown 正文或 `index.md` 中重复写分类块。
+
+## 4. topicDependencies 判定准则
+
+设当前主题为 A、候选依赖为 B。**四问命中任一即声明 `A → B`**：
+
+1. **前置规则强引用**：A 的执行步骤**显式提到** B 的术语 / 产物 / 落盘约束（例：`f2s-req-plan` 要求「按 `f2s-task` 维护 `.task/`」）。
+2. **缺 B 必出错**：仅读 A 不读 B 能否产出对的结果？答否——典型为 A 写"怎么做"、B 写"在哪做 / 用哪份输入"。
+3. **共享落盘目标**：A、B 写同一组文件且 B 定义写盘格式（如 `.task/`、`.Knowledge/topics/`）。
+4. **fallback 跳转 B**：A 自身覆盖不全，按现有约定回落 B 兜底。
+
+**反向排除**（避免依赖膨胀）：
+
+- 仅术语相邻（都谈"知识库"）→ 不写依赖，靠 `index.md` 语义边界即可。
+- 跨主题信息互查（A 想"了解一下" B）→ 不写依赖，靠 `taskToTopicRules` 次高候选 + `expand` 补召回。
+- **概述 → 详情导航**：大功能主 topic 与其子模块 topic 之间是"关联/导航"关系，不是强前置依赖——子模块 topic 通过各自的 matcher 独立命中，不写 `A → B`；主 topic 正文里写子模块 stock-doc 的可点击链接作为导航入口。
+- **传递依赖不重复声明**：若 `A→B`、`B→C` 已成立，禁止再写 `A→C`（读 B 时会自然带上 C）。
+
+**DAG 与最小化**：`topicDependencies` 必须是 DAG，禁止环；保持最小边集。
+
+**判定时机**：终稿与新 / 改 topic 落盘后，扫正文中**反引号引用的其他 topic id 与规则文件名**，逐个套四问；命中即写入 `manifest-routing.topicDependencies`，**并在新 topic 正文显式写依赖声明**（见骨架第 4 条）。
+
+## 5. 大功能拆分策略
+
+当一个业务功能体量较大时，推荐「主 topic + 子 topic」结构，而非单个大 topic。
+
+**何时拆分（软约束，满足任一评估是否需拆）**：
+
+- 对应 stock-doc 超过 **300–500 行**：建议评估拆分，不强制阻断；
+- matcher `includeAny` 超过 **12 个**：主题过宽信号；
+- topic 正文包含超过 **3 个不相干职责域**的二级标题；
+- `f2s-kb-upgrade` 审计时发现同一 topic 被多种不相干任务类型反复命中。
+
+**拆分方式**：
+
+- **主 topic**（`primary: feature`）：写业务闭环、入口边界、子模块索引，正文里用可点击 stock-doc 链接指向各细节文档；不写子模块的实现细节。
+- **子模块 topic**：按实际语义各自写 `feature` / `module` / `config` / `policy`，不预设类型；各自拥有独立 matcher，通过细分触发词独立命中。
+- **stock-doc**：允许长文；超过阈值时建议拆成多份 focused stock-doc（如 `<功能名>-业务规则_终稿.md`、`<功能名>-数据模型_终稿.md`），每份对应一个子 topic。
+
+**不要做的事**：
+
+- 不用 `topicDependencies` 表达"概述 → 详情"导航关系（见第 4 节反向排除）；
+- 不为拆分而强行制造子 topic，若子模块本身不会被独立路由命中，不必建 topic。
+
+## 6. rule 是否需新建对应 topic
+
+判据：**该 rule 是否会作为用户任务路由命中**。
+
+- **会**（用户问 / 输入会触发该规则的执行）→ 须在 `.Knowledge/topics/` 建对应路由摘要，并在 `taskToTopicRules` 配置入口。例：`f2s-task`（变更追踪用户场景命中）、`f2s-implement-tech-design`（"按方案实现"用户场景命中）。
+- **不会**（仅被其他规则 / SKILL 内部引用，用户不会直接发起）→ **不建** topic。例：`f2s-knowledge-preflight`、`f2s-karpathy-guidelines`、`f2s-config-check`、本条 `f2s-topic-authoring`。
+
+误区：「重要的规则就该有 topic」——重要不等于"用户路由命中"；让消费方 SKILL 在正文里直接 `Read rules/<id>.*` 全文即可，无需走 manifest 路由。
+
+## 7. 写盘权属（指针）
+
+`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/topics/*.md` 的写权约束**以 `f2s-flow2spec-unified-entry` 与各 SKILL 内「写权硬约束」为准**，本条不复述；遇分歧以统一入口与对应 SKILL 为准。
+
+## 禁止项
+
+- 在未读本条的情况下新增 / 修改 topic 或 `topicDependencies`。
+- 为补分类单独创建、重命名或拆分 topic。
+- 在 topic 正文或 `index.md` 中写 `## 概念分类` 等 metadata 副本。
+- 把"重要的规则"硬塞进 `taskToTopicRules`（参见第 4 条）。
+- 用 `topicDependencies` 表达"信息相关"（应通过 `index.md` 语义边界 + matcher 关键词补召回，而非依赖边）。
+- 在 `topicDependencies` 中写传递冗余边或形成环。

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

@@ -2,7 +2,7 @@
 name: f2s-doc-arch
 description: 根据用户说明或文档（或扫描代码）生成项目架构说明初稿，无固定格式，描述清楚即可；触发：项目架构说明、f2s-doc-arch、架构初稿
 ---
-> 执行口径：本技能产物默认写入 `.Knowledge/stock-docs/`，后续由知识库技能链（如 `f2s-doc-final`、`f2s-ctx-build`）同步到 `.Knowledge/topics/index/manifest`。
+> 执行口径：本技能产物默认写入 `.Knowledge/stock-docs/`，后续由知识库技能链（如 `f2s-doc-final`、`f2s-kb-build`）同步到 `.Knowledge/topics/index/manifest`。
 
 ## 编排（主 / 子 agent）
 
@@ -18,7 +18,7 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 
 本技能用于**帮助用户生成项目架构的文档说明**，产出形态类似**初稿**：无固定格式规范，以**描述清楚**为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。
 
-**与 f2s-doc-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-ctx-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进知识库（初稿→终稿→topics/index/manifest），应使用 **`f2s-doc-add`**，**勿用本技能冒充该流程**。
+**与 f2s-kb-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-kb-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进知识库（初稿→终稿→topics/index/manifest），应使用 **`f2s-kb-add`**，**勿用本技能冒充该流程**。
 
 ---
 
@@ -69,19 +69,47 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 
 - 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。
 
+## 大功能拆分建议
+
+扫描或理解完源码/说明后，若识别出以下任一信号，须在初稿**末尾**输出「拆分建议」段落，供用户参考（不阻断生成）：
+
+- 源码总量超过 **~5000 行**，或涉及文件超过 **20 个**；
+- 能明显识别出 **3 个以上不相干职责域**（如接口层 / 核心规则 / 数据模型 / 外部依赖各自独立）；
+- 用户说明本身已提到「多个子模块」或「多个功能」。
+
+**拆分建议格式**（写在初稿末尾，独立节）：
+
+```
+## 拆分建议
+
+当前功能体量较大，建议拆成多份 focused stock-doc，各自对应一个独立 topic：
+
+| 建议文档 | 主要内容 | 建议 topic primary |
+|---|---|---|
+| <功能名>-概述_初稿.md | 入口边界、子模块关系、快速索引 | feature |
+| <功能名>-业务规则_初稿.md | 核心流程、门禁、状态机 | policy |
+| <功能名>-数据模型_初稿.md | 表结构、枚举、模型约定 | module |
+| <功能名>-外部依赖_初稿.md | SOA/QMQ/Redis/风控封装 | config |
+
+拆分后各子 topic 通过各自 matcher 独立命中，主 topic 正文写导航链接；
+不通过 topicDependencies 串联"概述 → 详情"（见 f2s-topic-authoring 第 5 节）。
+```
+
+用户可选择：**A) 按拆分建议分别执行 `f2s-doc-arch`**（推荐），或 **B) 继续用当前单份初稿**进入后续流程。
+
 ## 完成后的下一步（硬约束）
 
-本技能**只产出初稿**；结束时须按下列顺序引导，**禁止**让用户跳过终稿直接 `f2s-ctx-build`：
+本技能**只产出初稿**；结束时须按下列顺序引导，**禁止**让用户跳过终稿直接 `f2s-kb-build`：
 
 1. 告知初稿路径，建议用户先审阅、补充内容。
 2. **下一步必须为 `f2s-doc-final`**：以初稿路径为入参，产出 `.Knowledge/stock-docs/<方案名>_终稿.md`（《终稿模版》规范格式）。
-3. **仅在终稿落盘后**再引导 **`f2s-ctx-build`**，且入参须为终稿路径（含 `_终稿` 或由 `f2s-doc-final` 刚生成）。
-4. **禁止**在完成回复中单独写「请执行 `f2s-ctx-build`」且入参指向 `*_初稿.md`；**禁止**将 `f2s-ctx-build` 与 `f2s-doc-final` 并列成「二选一」。
-5. **唯一例外**：用户**明确要求**跳过终稿、且初稿已人工符合终稿模版——须先说明跳过终稿的风险，再允许指向 `f2s-ctx-build`。
+3. **仅在终稿落盘后**再引导 **`f2s-kb-build`**，且入参须为终稿路径（含 `_终稿` 或由 `f2s-doc-final` 刚生成）。
+4. **禁止**在完成回复中单独写「请执行 `f2s-kb-build`」且入参指向 `*_初稿.md`；**禁止**将 `f2s-kb-build` 与 `f2s-doc-final` 并列成「二选一」。
+5. **唯一例外**：用户**明确要求**跳过终稿、且初稿已人工符合终稿模版——须先说明跳过终稿的风险，再允许指向 `f2s-kb-build`。
 
-**完成回复模板**（须同时包含 `f2s-doc-final` 与 `f2s-ctx-build`，且 ctx-build 在终稿之后）：
+**完成回复模板**（须同时包含 `f2s-doc-final` 与 `f2s-kb-build`，且 ctx-build 在终稿之后）：
 
-> 已生成架构说明初稿：`<初稿路径>`。请先审阅修改；下一步请执行 **`f2s-doc-final <初稿路径>`** 转为终稿，再执行 **`f2s-ctx-build <终稿路径>`** 同步知识路由主题与索引。
+> 已生成架构说明初稿：`<初稿路径>`。请先审阅修改；下一步请执行 **`f2s-doc-final <初稿路径>`** 转为终稿，再执行 **`f2s-kb-build <终稿路径>`** 同步知识路由主题与索引。
 
 ---
 
@@ -97,4 +125,4 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 
 - **不强制格式**：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。
 - **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
-- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-ctx-build`**；不得仅推荐 build。
+- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-kb-build`**；不得仅推荐 build。

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

@@ -1,6 +1,6 @@
 ---
 name: f2s-doc-final
-description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-ctx-build 同步 topics/index/manifest；触发：f2s-doc-final、转成概述模板、终稿模版
+description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-kb-build 同步 topics/index/manifest；触发：f2s-doc-final、转成概述模板、终稿模版
 ---
 
 > 执行口径：初稿/终稿统一写入 `.Knowledge/stock-docs/`；模板优先读取 `.Knowledge/template/终稿模版.md`。
@@ -15,7 +15,7 @@ description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续
 
 # 将 PDF 或 MD 转换为《终稿模版》规范格式（spec → context）
 
-用户会在本技能后附带**至少一个参数**：**第一个参数**为本地 **PDF 文件路径**或 **Markdown 文件路径**（必填）；**第二个参数**（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 **f2s-ctx-build** 技能消费的终稿风格 Markdown 文档。
+用户会在本技能后附带**至少一个参数**：**第一个参数**为本地 **PDF 文件路径**或 **Markdown 文件路径**（必填）；**第二个参数**（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 **f2s-kb-build** 技能消费的终稿风格 Markdown 文档。
 
 **终稿模版仅作提示**：若存在 `.Knowledge/template/终稿模版.md`（来源 `templates/knowledge/template/终稿模版.md`），可读取作为结构参考；不强制套用。
 
@@ -44,7 +44,7 @@ description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续
 4. **输出**：
   - 默认写入 `.Knowledge/stock-docs/<方案名>_终稿.md`（最终产物带 `_终稿` 标识）。
   - 若用户希望指定输出路径，可在命令后附带第二个参数作为输出路径；否则用默认。
-5. **回复**：告知用户已生成 `.Knowledge/stock-docs/<方案名>_终稿.md`，并提示可按 `f2s-ctx-build` 继续同步 `.Knowledge/topics`、`.Knowledge/index.md`（必要时 `manifest`）。
+5. **回复**：告知用户已生成 `.Knowledge/stock-docs/<方案名>_终稿.md`，并提示可按 `f2s-kb-build` 继续同步 `.Knowledge/topics`、`.Knowledge/index.md`（必要时 `manifest`）。
 
 ---
 
@@ -70,7 +70,7 @@ description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续
 
 - 按 **「流程一：用户传入的是 Markdown」** 的步骤 2～5 执行：读取格式规范 → 分析与转换 → 输出为模板格式。
 - **输出建议**：生成 `.Knowledge/stock-docs/<方案名>_终稿.md`。
-- **回复**：告知已生成规范版，并提示可按 `f2s-ctx-build` 继续同步 `.Knowledge/topics` 与索引。
+- **回复**：告知已生成规范版，并提示可按 `f2s-kb-build` 继续同步 `.Knowledge/topics` 与索引。
 
 ---
 
@@ -89,5 +89,5 @@ description: 将 PDF 或 MD 转为《终稿模版》规范格式，便于后续
 
 - 转换时**不要照抄原文**，要按模板**提炼、归纳、补全**，使核心概念、业务规则、关键流程清晰可查。
 - 建议（不强制）保留 **核心概念、业务规则、关键流程** 三个二级标题；其余章节按原文与需求增删，终稿模版仅作提示，不强制套用。
-- 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 `f2s-ctx-build` 同步知识路由主题与索引。
+- 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 `f2s-kb-build` 同步知识路由主题与索引。
 

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

@@ -1,9 +1,9 @@
 ---
 name: f2s-git-commit
-description: 代码写完后提交 Git：检查变更与知识库覆盖；生成带 emoji 首行的提交说明后**可直接 commit**（须在当条回复展示首行，不要求用户单独确认 commit）；**git pull 类拉取须用户先确认**。触发：f2s-git-commit、提交代码、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）。
+> 执行口径：本技能代用户执行 git 操作；不使用 `git add -A` / `git add .`，不跳过 hooks（`--no-verify`），不自动 push。**`git pull` / `git fetch` 合并入本地前必须取得用户对「拉取」的明确确认**；`git commit` 不要求单独一轮「确认」交互（见步骤 3–4）。用户明确要求“快捷提交”时，仅跳过步骤 2 知识库覆盖检查，其余安全步骤照常执行。
 
 ## 编排（主 / 子 agent）
 
@@ -14,6 +14,17 @@ description: 代码写完后提交 Git：检查变更与知识库覆盖；生成
 
 ## 强制流程
 
+### 快捷提交模式
+
+当用户本轮明确说出 **“快捷提交”**、**“快速提交”** 或 **“quick commit”** 时，进入快捷提交模式：
+
+- 跳过 **步骤 2：知识库覆盖检查**，不读取 `.Knowledge/topics/` / `.Knowledge/stock-docs/` 做覆盖判断。
+- 不提示用户先运行 `f2s-kb-sync` / `f2s-kb-feat`。
+- **不跳过**步骤 1 的变更读取与冲突标记检查。
+- **不跳过**步骤 3 的提交信息生成与展示。
+- **不跳过**步骤 4 的精确 `git add <文件列表>`、正常 `git commit` 与 git hooks。
+- **不得**因快捷提交使用 `git add -A` / `git add .` / `--no-verify` / 自动 push。
+
 ### 步骤 1：读取变更（只读）
 
 ```bash
@@ -38,7 +49,9 @@ git diff HEAD
 请先解决冲突后再提交。
 ```
 
-### 步骤 2：知识库覆盖检查（必须）
+### 步骤 2：知识库覆盖检查（默认必须；快捷提交跳过）
+
+若处于**快捷提交模式**，本步骤直接跳过，并在步骤 5 收尾提示中说明“已按快捷提交跳过知识库覆盖检查”。
 
 **先判断 `.Knowledge/` 是否存在：**
 
@@ -160,6 +173,9 @@ git commit -m "<步骤 3 定稿的完整提交信息>"
 
 [若跳过了步骤 2（.Knowledge 不存在）]
 💡 项目尚未初始化 Flow2Spec 知识库，如需接入可运行：flow2spec init
+
+[若快捷提交跳过了步骤 2]
+⚡ 已按快捷提交跳过知识库覆盖检查。
 ```
 
 ## 约束
@@ -168,7 +184,7 @@ git commit -m "<步骤 3 定稿的完整提交信息>"
 - 禁止 `--no-verify`，hook 失败须修复后重试。
 - 禁止 `--amend` 已推送的 commit，除非用户明确要求。
 - 禁止自动 push，commit 完成后停止。
-- 知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）。
+- 默认模式下知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）；快捷提交模式下跳过知识库覆盖检查，不提示补录选项。
 - **`git pull` / `git pull --rebase` / 会改写当前分支工作区内容的 `git fetch` 后续合并操作**：**必须**先向用户说明目的与风险，**取得用户对「拉取」的明确确认**（如用户回复「确认 pull」）后再执行；**禁止**为 commit 而顺带静默 pull。
 - **`git commit`**：**不要求**用户单独回复「确认」；但**禁止完全不展示**拟提交首行就执行 commit（须在当条回复中可见首行后再执行）。
 - 提交信息**首行**须符合步骤 3 的 **emoji + type** 格式（用户已合规给出时可保留）。
@@ -179,7 +195,7 @@ git commit -m "<步骤 3 定稿的完整提交信息>"
 1. 步骤 1 是否检查了 merge conflict（必须为是）。
 2. 是否区分了 staged / unstaged / untracked 三类文件（必须为是）。
 3. 是否用了 `git add -A` / `git add .`（必须为否）。
-4. 知识库检查是否执行或有明确跳过理由（必须为是）。
+4. 知识库检查是否执行或有明确跳过理由（快捷提交 / `.Knowledge` 不存在）（必须为是）。
 5. 步骤 3 是否基于 `git diff` 实际内容生成提交信息（必须为是，而非仅 `--stat`）。
 6. 执行 commit 前是否在当条回复中**展示了拟提交首行**（必须为是）；**不得**要求用户单独「确认 commit」才执行（与策略一致）。
 7. 提交信息**首行**是否为 `<emoji> <type>[(scope)]: <简述>` 且 emoji 与 type 与上表一致（合并 revert 等例外须在展示中说明）。

package/templates/skills/{f2s-doc-add → f2s-kb-add}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: f2s-doc-add
-description: 工作中把已落地能力解析进知识库（多文件聚合）：初稿→终稿→topics/index/manifest；触发：f2s-doc-add、已有能力进知识库、多文件生成上下文
+name: f2s-kb-add
+description: 工作中把已落地能力解析进知识库（多文件聚合）：初稿→终稿→topics/index/manifest；触发：f2s-kb-add、已有能力进知识库、多文件生成上下文
 ---
 
 > 执行口径：本技能只维护 `.Knowledge`，不改配置根 `rules/skills`。
@@ -15,11 +15,11 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
   - **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` 调度、整体验收。
+- 主必控：重合判定、终稿定稿、`f2s-kb-build` 调度、整体验收。
 - 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘。
 - 落盘侧自验。
 
-# f2s-doc-add：多文件聚合 -> 初稿 -> 终稿 -> 知识路由同步
+# f2s-kb-add：多文件聚合 -> 初稿 -> 终稿 -> 知识路由同步
 
 ## 使用时机
 
@@ -58,6 +58,7 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
    - **方案 A（推荐）**：按模块分别生成知识文件 → 每组独立走步骤 1→2→3→4，各自产出 `<模块名>_初稿.md` / `<模块名>_终稿.md`；
    - **方案 B（合并）**：忽略模块边界，合并生成一份 `<方案名>_初稿.md`（原有行为）。
    - **禁止**在未获用户明确选择前默认走方案 B 继续执行。
+5. **单模块但 stock-doc 体量大**：若单份输入文档或聚合后的源码超过 **300–500 行**，或涵盖 **3 个以上不相干职责域**，建议向用户提示"可拆成多份 focused stock-doc，各自对应独立 topic"；用户确认继续则不阻断，但在输出摘要中记录"建议后续拆分"。
 
 ## 步骤 1：适度深度解析
 
@@ -85,11 +86,14 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 
 ## 步骤 4：同步知识路由
 
-基于终稿调用 `f2s-ctx-build` 口径，更新：
+基于终稿调用 `f2s-kb-build` 口径，更新：
 
 - `.Knowledge/topics/`
 - `.Knowledge/index.md`
 - 路由清单（必要时）
+- `manifest-routing.json.topicMetadata`（按需）：仅给已存在或本次确认创建的 topicId 写入 `primary` / `tags` / `confidence`；`tags` 可省略，且不得与 `primary` 重复。分类只用于治理、审计和阅读预期，不参与路由或执行强制性；证据不足时不写 metadata，并在摘要列为待确认；不得为了分类单独创建、重命名或拆分 topic。
+
+> **创作侧准则**：本步骤会触发新增 / 修改 topic 与 `topicDependencies`，**须先 Read** `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再调用 `f2s-kb-build` 口径同步。
 
 ## 输出摘要（必须）
 
@@ -103,7 +107,7 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 
 - 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
 - 若发现已有 `.Knowledge/stock-docs/<能力名>_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
-- 用户要求”先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。
+- 用户要求”先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-kb-build` 同步。
 
 用户输入 3 个文件：`src/auth/login.ts`、`src/payment/checkout.ts`、`src/notification/email.ts`。
 
@@ -124,4 +128,5 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 1. 初稿/终稿路径是否落在 `.Knowledge/stock-docs/`。
 2. 同主题是否避免重复新建。
 3. topic/index/manifest 是否与终稿语义一致。
-4. 输入路径 ≥ 2 时，步骤 0.5 是否执行了多模块检测；若判定为多模块，是否向用户展示了分组并等待了明确选择，未默认合并输出。
+4. 若写入 `topicMetadata`：是否只覆盖已存在或本次已创建的 topicId；`primary` / `tags` / `confidence` 是否合法；是否避免类型前缀命名与重命名。
+5. 输入路径 ≥ 2 时，步骤 0.5 是否执行了多模块检测；若判定为多模块，是否向用户展示了分组并等待了明确选择，未默认合并输出。

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

@@ -0,0 +1,165 @@
+---
+name: f2s-kb-addRules
+description: 把用户口述的规则沉淀进知识库，自动判定「新建主题 / 并入存量主题」并同步路由；不写代码、不创建 .task/；触发：f2s-kb-addRules、新增规则、口述规则、把这条记到知识库
+---
+
+> 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`，不动业务代码，不创建 `.task/`（口述规则属于元配置变更，不是业务变更追踪）。
+
+# f2s-kb-addRules：用户口述规则进知识库
+
+## 与既有技能的边界
+
+- 与 `f2s-kb-feat` 区分：`f2s-kb-feat` 强绑「代码实现 + KB 同步」，命中 `changeTracking.feat` 会创建 `.task/`；本技能**只沉淀规则**，不改代码、不追踪任务。
+- 与 `f2s-kb-build` 区分：`f2s-kb-build` 输入是 `.Knowledge/stock-docs/<file>_终稿.md`；本技能输入是**用户当场口述的规则文本**。
+- 与 `f2s-kb-add` 区分：`f2s-kb-add` 输入是「多文件源码 / 配置」聚合到 stock-docs；本技能跳过 stock-docs，直接落 topic。
+
+## 编排（主 / 子 agent）
+
+- `subAgent` / `switchAgentVerification` 语义以统一入口为唯一事实源（**Cursor/Claude** 读 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`）。本 SKILL 不复述。
+- 默认主 agent 全流程执行——口述规则单条短文，拆子收益低于 context 切换成本。
+- **写权硬约束**：`.Knowledge/manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘。
+- 落盘侧自验。
+
+## 输入
+
+- 一条或一段用户口述的规则文本（自由文本即可，无固定格式）。
+- 用户**不需要**指定目标主题、文件名、`alwaysApply` 等参数；由本技能判定与提议。
+
+## 强制前置：Read 创作侧准则
+
+执行任何步骤前，**须先 Read** `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），后续命名 / 骨架 / 依赖判定 / DAG 最小化 / 写盘权属均以该条为准。
+
+## 步骤 1：意图归一
+
+把用户口述文本归一为可落盘的"规则单元"：
+
+- 抽取**约束句式**（"做 X 时必须 / 禁止 / 优先 Y"）或**流程描述**（"X 的处理顺序是 A→B→C"）；
+- 标识规则**适用场景**（触发条件、文件路径范围、生命周期阶段等）；
+- 不替用户引申、不补未说的边界——口述什么写什么，模糊处保留并在步骤 3 询问。
+
+## 步骤 2：扫存量主题（必须）
+
+- Read `.Knowledge/manifest-routing.json` 取 `topicPaths` 全集；
+- Read `.Knowledge/index.md` 主题表，按主题 id + 一句话意图扫一遍；
+- 必要时按规则正文中的**关键词**逐个 Read 候选 `topics/<id>.md` 头部 10–30 行（不要全文加载所有 topic）；
+- 输出**候选清单**（重合度高 → 低，至多 3 个）作为步骤 3 的输入。
+
+## 步骤 3：新建 vs 并入判定（必须，与用户确认）
+
+向用户**展示候选**，按下列分支提议：
+
+- **高重合**（口述规则明显是某存量主题的细化 / 补充 / 例外）→ 提议「**并入** `topics/<existing>.md`」，并指出拟插入位置（章节名 / 段落锚点）。
+- **无重合 / 低重合**（找不到合适宿主）→ 提议「**新建** `topics/<新 id>.md`」；新 id 由本技能按规则正文生成 **kebab-case**，遵循 `f2s-topic-authoring` 命名约束（无版本后缀、无个人花名、与 `index.md` 既有标题不冲突）。
+- **跨多个主题**（一条口述同时约束 ≥2 个主题）→ **暂停**，向用户呈现拆分选项：
+  - 选项 A：拆为 ≥2 条规则单元，分别并入对应主题；
+  - 选项 B：选主归并到一个主题，其它主题以一行交叉引用提示；
+  - 选项 C：新建一个**总纲性**主题统辖，旧主题加引用——仅在该规则确实横切多个领域时使用。
+
+> 用户未确认前**禁止**落盘 `topics/` / `manifest-routing.json` / `index.md`。
+
+## 步骤 4：落盘（用户确认后执行）
+
+### 4a. 写 `topics/<id>.md`
+
+- **新建**：按 `f2s-topic-authoring` 第 2 节"topic 正文骨架"五点逐项写入（标题与一句话意图 / 适用场景 / 核心规则 / 依赖声明 / 边界与禁止项）；
+- **并入**：在用户确认的章节 / 段落处**手术式插入**——只增加与本次规则直接相关的句段，禁止整文件重写或借机重述背景；
+- 行文遵守 `f2s-flow2spec-unified-entry`「知识库落盘文风」**肯定式优先**；排他性选择例外。
+
+### 4b. `topicDependencies` 判定（必须）
+
+按 `f2s-topic-authoring` 第 4 节四问 + 反向排除 + DAG 最小化，扫新写正文中**反引号引用的其他 topic id / 规则文件名**，逐个判定是否声明依赖：
+
+- 命中 → 在 `manifest-routing.topicDependencies` 增加边，**且**在新 / 改 topic 正文显式写一句「执行前须先读依赖主题 `<dep>`」；
+- 未命中 → 不写依赖，靠 `taskToTopicRules` 次高候选 + `expand` 补召回。
+
+并入存量主题时，若仅是细化既有规则、未引入对新 topic 的强引用，**通常不需要**新增依赖边。
+
+### 4c. 同步路由（仅主 agent 落盘）
+
+- **新建主题**：
+  - 补 `manifest-routing.topicPaths`：`<id> -> .Knowledge/topics/<id>.md`；
+  - 按需补 `manifest-routing.topicMetadata`：口述规则主题通常为 `{ "primary": "policy", "confidence": "inferred" }`；用户明确确认分类可写 `manual`；如同时包含配置项 / 模块 / 能力性质，可写入不与 `primary` 重复的 `tags`；证据不足则不写 metadata，并在摘要列为待确认。分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性；
+  - 视情况补 `taskToTopicRules[]`——**仅当**该规则会作为**用户任务路由命中**（参见 `f2s-topic-authoring` 第 5 节判据）才补；纯被其它规则 / SKILL 引用的内部规则**不进** `taskToTopicRules`；
+  - 若补了 `taskToTopicRules[]`，须新建 `.Knowledge/matchers/<matcherId>.json`，从用户口述中抽取 `includeAny` 关键词（用户原话 + 1–2 个明显近义说法，宁缺勿滥）；
+- **并入存量主题**：
+  - `topicPaths` 不变；
+  - 可按需补齐该 topic 的 `topicMetadata`，但不得为了分类创建、重命名或拆分 topic；
+  - 仅当口述规则**新增了触发场景**时，最小更新对应 `matchers/<id>.json` 的 `includeAny`；否则不动 matcher。
+
+### 4d. 更新 `index.md`
+
+- 新建主题：在主题表新增一行（同主题单行原则）；「关联文档（摘要）」列填「无」或「待补充」（口述规则通常无 stock-docs / req-docs 锚定文档），禁止留空；
+- 并入存量主题：仅在主题意图发生变化时更新该行的「主题意图」摘要列，否则不动。
+
+## 步骤 5：输出摘要（必须）
+
+```markdown
+## 规则捕获结果
+
+### 口述规则
+> <用户原文，1–3 行>
+
+### 落盘决策
+- 模式：新建 / 并入 / 跨主题拆分
+- 目标：.Knowledge/topics/<id>.md（章节：<可选>）
+
+### 知识库变更
+- .Knowledge/topics/<id>.md：<新增 / 修订说明>
+- .Knowledge/manifest-routing.json：<topicPaths / taskToTopicRules / topicDependencies 是否更新与原因>
+- .Knowledge/matchers/<id>.json：<是否更新 includeAny 与原因>
+- .Knowledge/index.md：<是否更新与原因>
+
+### 待用户后续
+- <如无 taskToTopicRules，提示"该规则当前不会被任务路由命中，需要时可补"；其它跟进项一并列出>
+```
+
+## 约束
+
+- 不写代码、不动配置根 `rules/skills`、不创建 `.task/`。
+- 用户未确认「新建 / 并入 / 跨主题拆分」前禁止落盘。
+- 同主题优先并入，避免新建近似主题（参见 `f2s-topic-authoring` 命名"不要"项）。
+- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束）。
+- 路由清单仅做最小改动，不重写无关字段。
+- 行文遵守统一入口「知识库落盘文风」与单文件篇幅软约束（口述规则通常 ≤ 30 行新增正文足矣）。
+
+## 复杂场景示例
+
+**场景 A：高重合并入**
+
+用户口述：「写 commit message 时，第一行必须中文 emoji 开头」。
+扫描发现已存在 `topics/f2s-git-commit.md`（描述 git commit 流程）。
+- 步骤 3 提议：**并入** `topics/f2s-git-commit.md` 的「commit 文风」章节；
+- 步骤 4a 在该章节追加规则段，不改其他章节；
+- 步骤 4b 不新增依赖；
+- 步骤 4c manifest 不动，仅在该 topic 对应 matcher（若存在）中补 1–2 个关键词；
+- 步骤 4d index 不动。
+
+**场景 B：新建主题**
+
+用户口述：「所有面向用户的错误提示必须以动词开头，如『重试』『检查 X』而非『错误：X 失败』」。
+扫描未找到合适宿主。
+- 步骤 3 提议：**新建** `topics/error-message-style.md`；
+- 步骤 4a 按骨架写入；
+- 步骤 4b 评估是否依赖 i18n / 文案规范类既有 topic，命中则声明；
+- 步骤 4c 判断「用户日常对话中是否会触发"错误提示文案"任务路由」——若会，补 `taskToTopicRules` + 新建 matcher；若仅作为内部规范被其它 SKILL 引用，则**不进** `taskToTopicRules`；
+- 步骤 4d index 新增一行。
+
+**场景 C：跨主题拆分**
+
+用户口述：「按方案实现时不能边写边改文档；提交 PR 时必须先跑测试」。
+明显涉及 `f2s-implement-tech-design`（实现纪律）和 `f2s-git-commit`（提交流程）两个主题。
+- 步骤 3 暂停，呈现 A / B / C 三选项；
+- 用户选 A → 拆为两条规则单元，分别并入两个主题；
+- 步骤 4 在两个 topic 中分别落盘，输出摘要列出两条变更。
+
+## 完成后自检
+
+1. 是否在落盘前 Read 了 `rules/f2s-topic-authoring.*` 全文。
+2. 是否在用户未确认「新建 / 并入 / 跨主题拆分」前提前落盘（必须为否）。
+3. 新建 topic：`topicPaths` 是否补全；正文是否含五点骨架；`taskToTopicRules` 与 matcher 的 `includeAny` 是否符合「rule 是否需建对应 topic 路由」判据。
+4. 若写入 `topicMetadata`：key 是否存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否未因分类改 topicId / 文件名。
+5. 并入 topic：是否仅做手术式插入；是否未借机改写无关章节。
+6. `topicDependencies` 是否经四问判定；是否引入冗余传递边或环。
+7. `index.md` 与 `topics/` 文件集合是否一一对应；新建主题是否补「关联文档（摘要）」列。
+8. 是否未触碰配置根 `rules/skills`；是否未创建 `.task/`。
+9. 输出摘要是否齐全（口述原文 / 决策 / 变更 / 待跟进）。

package/templates/skills/{f2s-ctx-build → f2s-kb-build}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: f2s-ctx-build
-description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
+name: f2s-kb-build
+description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索引；触发：生成项目上下文、f2s-kb-build、终稿生成上下文
 ---
 
 > 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`。不再维护 `.Knowledge/manifest-matchers.json`（已废弃聚合文件；`flow2spec init` 会删除遗留副本）。
@@ -14,11 +14,11 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 - **中大变更分支**（`subAgent=true` 且超出上述阈值）：
   - 主 agent 在主会话中列出**文件级契约**：子 A 只写 `.Knowledge/topics/<foo>.md`，子 B 只写 `.Knowledge/matchers/<m-foo>.json`，路径互不重叠；
   - 子 agent 仅落盘契约内文件，不跨边界；
-  - **主 agent 单点**编辑 `.Knowledge/manifest-routing.json` / `.Knowledge/index.md`（补 `taskToTopicRules`、`topicPaths`、`matcherPath`、`topicDependencies`）；
+  - **主 agent 单点**编辑 `.Knowledge/manifest-routing.json` / `.Knowledge/index.md`（补 `taskToTopicRules`、`topicPaths`、`matcherPath`、`topicDependencies`、`topicMetadata`）；
   - 主 agent 做整体验收。
 - **不推荐**：单个子 agent 同时改 manifest / index / 多份 topics / matchers；以及「子 A 写、子 B 验」。
 - **「一子写、主验」**：仅在交付边界极窄（例如只产出 1 个新 matcher 分片草稿，manifest 引用仍由主写）时可接受。
-- **写权硬约束**：`.Knowledge/manifest-routing.json` / `.Knowledge/index.md` **恒由主 agent 落盘**，子 agent 不得触碰。
+- **写权硬约束**：`.Knowledge/manifest-routing.json`（含 `topicMetadata`）/ `.Knowledge/index.md` **恒由主 agent 落盘**，子 agent 不得触碰。
 - 默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。
 
 ## 输入
@@ -52,6 +52,10 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 - 任务触发词（写入对应 `matchers/<matcherId>.json` 的 `includeAny`）
 - 与现有主题的依赖关系（用于 `topicDependencies`）
 
+> **创作侧准则**：本步骤涉及新增 / 修改 topic 与 `topicDependencies`，**须先 Read** `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再继续步骤 3 / 步骤 5。命名、骨架、依赖判定、DAG 最小化、判定时机均以该条为准，本 SKILL 不复述。
+
+> **拆分评估**：若输入 stock-doc 超过 **300–500 行**，或语义分析后发现覆盖 **3 个以上不相干职责域**，须在输出摘要中说明：建议拆成多份 focused stock-doc（各自对应一个独立 topic），用户确认后再分批执行；若用户选择继续生成单个大 topic，不阻断，但在摘要中记录"主题偏大，建议后续拆分"。大功能主 topic 写业务闭环/入口/子模块 stock-doc 导航链接；子模块 topic 各自独立命中，**不通过 `topicDependencies` 串联概述与详情**。
+
 ## 步骤 3：写入 topics
 
 - 目标路径：`.Knowledge/topics/<topic>.md`
@@ -72,6 +76,7 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 - 更新 `manifest-routing.topicPaths`（topicId -> topic 文件路径）
 - 更新 `manifest-routing.taskToTopicRules[]`（任务到主题集合 + matcherId）
 - 更新 `manifest-routing.topicDependencies`（先读依赖后读主主题）
+- 更新 `manifest-routing.topicMetadata`（按需）：仅给已存在或本次确认创建的 topicId 写入 `{ "primary": "feature|module|config|policy", "tags": ["..."], "confidence": "manual|inferred" }`；`tags` 可省略，且不得与 `primary` 重复。分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性。新建 topic 时有明确证据可写 `inferred`；用户确认后才写 `manual`；证据不足时不写 metadata，并在摘要列为待确认。不得为了分类创建、重命名或拆分 topic。
 - 更新 `matchers/<matcherId>.json` 的 `includeAny`（关键词词表；路径须与 `taskToTopicRules[].matcherPath` 一致）
 - 校验 `fallbackTopic`、`topicPaths`、`matcherId` 引用有效
 - 仅做最小改动，不重写无关字段
@@ -91,7 +96,7 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 
 ## 复杂场景示例
 
-用户输入：`f2s-ctx-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。
+用户输入：`f2s-kb-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。
 
 - 若新文档与现有 `<能力>` 主题高度重合：原位更新 `topics/<能力>.md`，不要新建 `<能力>-v2.md`。
 - 若新文档新增子能力：可新增 `topics/<能力>-<子域>.md`，并在 `manifest-routing.topicDependencies` 中声明依赖关系。
@@ -102,7 +107,7 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 1. `.Knowledge/topics/*.md` 与 `manifest-routing.topicPaths` 一一对应。
 2. `index.md` 主题表与 topics 文件集合一致，且每个主题都包含“关联文档（摘要）”。
 3. 每个 `taskToTopicRules[].matcherPath` 文件存在且其中 `id` 与 `matcherId` 一致。
-4. 未触碰配置根 `rules/skills`。
-5. 中大变更时是否按文件级契约拆子（子 A / 子 B 路径互不重叠）。
-6. `manifest-routing.json` / `.Knowledge/index.md` 由主 agent 单点落盘，无子 agent 越权写入。
-
+4. 若写入 `topicMetadata`：key 是否均存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；`tags` 是否未与 `primary` 重复；是否未因分类改 topicId / 文件名。
+5. 未触碰配置根 `rules/skills`。
+6. 中大变更时是否按文件级契约拆子（子 A / 子 B 路径互不重叠）。
+7. `manifest-routing.json` / `.Knowledge/index.md` 由主 agent 单点落盘，无子 agent 越权写入。