🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

@double-codeing/flow2spec

Package Overview
Dependencies
Maintainers
1
Versions
34
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@double-codeing/flow2spec - npm Package Compare versions

Comparing version
3.0.19
 to
3.1.0
templates/rules/f2s-topic-authoring.mdc

Sorry, the diff of this file is not supported yet

+132
templates/skills/f2s-kb-add/SKILL.md
---
name: f2s-kb-add
description: 工作中把已落地能力解析进知识库（多文件聚合）：初稿→终稿→topics/index/manifest；触发：f2s-kb-add、已有能力进知识库、多文件生成上下文
---
> 执行口径：本技能只维护 `.Knowledge`，不改配置根 `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-kb-build` 调度、整体验收。
- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘。
- 落盘侧自验。
# f2s-kb-add：多文件聚合 -> 初稿 -> 终稿 -> 知识路由同步
## 使用时机
- 某能力已在代码中落地，但信息分散在多个文件，需沉淀为可检索知识。
- 与 `f2s-doc-arch` 区分：`doc-arch` 产出架构初稿；`doc-add` 产出“已落地能力”知识沉淀链路。
## 输入
| 参数 | 必填 | 说明 |
| --- | --- | --- |
| 文件路径列表 | 是 | 一个或多个路径（空格/换行/`@`）；支持源码、配置、文档 |
| 方案名 | 否 | 用于生成 `<方案名>_初稿.md`、`<方案名>_终稿.md` |
| 初稿/终稿路径 | 否 | 默认放 `.Knowledge/stock-docs/` |
无有效路径时中止并要求用户补充。
## 步骤 0：重合判定（重要）
执行前先对照：
- `.Knowledge/index.md`
- `.Knowledge/topics/*.md`
- `.Knowledge/stock-docs/*.md`
若已有同主题沉淀，优先原位更新，避免重复主题和重复索引行。
## 步骤 0.5：多模块检测（输入路径 ≥ 2 时必须执行）
1. **目录聚合**：按路径中的功能层目录（如 `src/<模块名>/`、顶层目录名）对文件分组。
2. **判定规则**（满足任一即判定为「多模块」）：
- 文件分属 ≥ 2 个不同顶层功能目录（如 `auth/`、`payment/`）；
- 用户在输入中明确提及「多个功能 / 不同模块 / 分别处理」等；
- 文件名前缀明显不同且无共同父目录。
3. **单模块（未触发判定）**：不中断，继续步骤 1，按现有单输出逻辑生成 `<方案名>_初稿.md`。
4. **多模块（触发判定）**：**暂停**，向用户展示分组结果，并询问：
- **方案 A（推荐）**：按模块分别生成知识文件 → 每组独立走步骤 1→2→3→4，各自产出 `<模块名>_初稿.md` / `<模块名>_终稿.md`；
- **方案 B（合并）**：忽略模块边界，合并生成一份 `<方案名>_初稿.md`（原有行为）。
- **禁止**在未获用户明确选择前默认走方案 B 继续执行。
5. **单模块但 stock-doc 体量大**：若单份输入文档或聚合后的源码超过 **300–500 行**，或涵盖 **3 个以上不相干职责域**，建议向用户提示"可拆成多份 focused stock-doc，各自对应独立 topic"；用户确认继续则不阻断，但在输出摘要中记录"建议后续拆分"。
## 步骤 1：适度深度解析
- 小文件通读；
- 大文件优先结构与关键片段（导出、接口、配置、流程）；
- 不确定内容显式标注”待确认”，禁止编造。
- 若任一拆子阈值满足（输入路径 ≥ 5 / 单源 > ~3000 行 / 多路径总量 > ~10000 行）且 `subAgent=true`，按 B 模式（默认）或 C 模式（达成切换判据时）拆子并行只读扫描；否则主全流程。**启用拆子时，子 agent 必须按主手写 inventory 与扫描契约执行，不得自行增删源路径。**
## 步骤 2：生成初稿
- 默认输出：`.Knowledge/stock-docs/<方案名>_初稿.md`
- 初稿建议结构：
- 概述
- 来源清单（含不可读文件）
- 分模块归纳
- 交叉关系
- 待确认项
## 步骤 3：生成终稿
- 参考 `.Knowledge/template/终稿模版.md`
- 输出：`.Knowledge/stock-docs/<方案名>_终稿.md`
- **必须填写 `## 来源文件` 小节**，列出步骤 1 实际读取的原始源文件路径
- 若用户要求”先审初稿”，则停在初稿并等待确认
## 步骤 4：同步知识路由
基于终稿调用 `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` 口径同步。
## 输出摘要（必须）
1. 初稿/终稿路径
2. 更新的 topic/index/路由清单 路径
3. 未完成项与原因（如路径无效、信息不足）
## 复杂场景示例
用户输入 6 个文件（代码、配置、旧文档混合），其中 2 个路径不可读。
- 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
- 若发现已有 `.Knowledge/stock-docs/<能力名>_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
- 用户要求”先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-kb-build` 同步。
用户输入 3 个文件：`src/auth/login.ts`、`src/payment/checkout.ts`、`src/notification/email.ts`。
- 步骤 0.5 检测到文件分属 `auth/`、`payment/`、`notification/` 三个不同顶层功能目录，判定为「多模块」。
- 向用户展示分组：`auth` 组 1 个文件、`payment` 组 1 个文件、`notification` 组 1 个文件；询问方案 A（分别生成）或方案 B（合并）。
- 用户选方案 A：按 `auth`、`payment`、`notification` 三组各走步骤 1→2→3→4，分别产出 `auth_初稿.md`、`payment_初稿.md`、`notification_初稿.md`。
- **禁止**在用户选择前直接合并三个模块生成 `综合_初稿.md`。
## 约束
- 终稿 `sourceDoc` 仅指向 `.Knowledge/stock-docs/*`
- 不改配置根 `rules/skills`
- 同主题优先更新，不平行新建重复知识
- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束），子 agent 不得触碰
## 完成后自检
1. 初稿/终稿路径是否落在 `.Knowledge/stock-docs/`。
2. 同主题是否避免重复新建。
3. topic/index/manifest 是否与终稿语义一致。
4. 若写入 `topicMetadata`：是否只覆盖已存在或本次已创建的 topicId；`primary` / `tags` / `confidence` 是否合法；是否避免类型前缀命名与重命名。
5. 输入路径 ≥ 2 时，步骤 0.5 是否执行了多模块检测；若判定为多模块，是否向用户展示了分组并等待了明确选择，未默认合并输出。
+165
templates/skills/f2s-kb-addRules/SKILL.md
---
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. 输出摘要是否齐全（口述原文 / 决策 / 变更 / 待跟进）。
+113
templates/skills/f2s-kb-build/SKILL.md
---
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` 会删除遗留副本）。
# 根据文档生成项目上下文（topics/index/路由清单）
## 编排（主 / 子 agent）
- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本 SKILL 不复述。
- **首选分支（小变更 → 主全流程）**：当本次改动 **≤ 2 个新 / 改主题**，**且 ≤ 1 个新 matcher**，**且无跨主题批量引用调整** 时，全流程在主 agent 完成，不拆子。
- **中大变更分支**（`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`、`topicMetadata`）；
- 主 agent 做整体验收。
- **不推荐**：单个子 agent 同时改 manifest / index / 多份 topics / matchers；以及「子 A 写、子 B 验」。
- **「一子写、主验」**：仅在交付边界极窄（例如只产出 1 个新 matcher 分片草稿，manifest 引用仍由主写）时可接受。
- **写权硬约束**：`.Knowledge/manifest-routing.json`（含 `topicMetadata`）/ `.Knowledge/index.md` **恒由主 agent 落盘**，子 agent 不得触碰。
- 默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。
## 输入
- 接收一个参数：URL 或本地路径。
- 本地路径必须位于 `.Knowledge/stock-docs/`。
- **须为终稿**：推荐文件名含 `_终稿.md`，或已由 **`f2s-doc-final`** 规范化；**禁止**以 `f2s-doc-arch` 产出的 `*_初稿.md` 作为入参直接执行本技能。
- 若入参路径含 **`_初稿`**、或用户刚完成架构初稿尚未执行 `f2s-doc-final`：**停止**，回复须先执行 **`f2s-doc-final <初稿路径>`**，待终稿落盘后再以终稿路径调用本技能。
- 若传入 `.Knowledge/req-docs/`，提示用户先整理为 `stock-docs` 终稿后再执行。
## 生成原则
1. **拆解**：文档较长或包含多块独立能力时，拆分为多个 topic；避免把无关能力塞到同一主题。
2. **分工**：
- `topics/`：规则与流程正文（可执行知识）
- `index.md`：主题索引与语义说明（人读入口）
- `manifest-routing.json` + `taskToTopicRules[].matcherPath` 指向的 `matchers/*.json`：任务路由与关键词词表（机读入口）
## 步骤 1：获取文档内容
- URL：抓取正文；无法访问时提示用户先落地到 `.Knowledge/stock-docs/*.md`。
- 本地路径：读取 Markdown 文档，提炼主题与能力边界。
## 步骤 2：语义分析（必须）
从文档中提炼：
- 主题名与主题意图（可形成 topic id）
- 核心概念与关键流程
- 业务规则与边界条件
- 任务触发词（写入对应 `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`
- 若已存在同主题：优先增量更新，避免重复主题。
- 若为新主题：新增文件并补充清晰标题、适用场景、规则与流程。
## 步骤 4：更新 index
- 更新 `.Knowledge/index.md` 的主题路由表。
- 保证“同主题单行”。
- 主题路由表需维护“关联文档（摘要）”列：每个主题补充 1-3 条关键文档**可点击 Markdown 链接**（格式：`[标题](相对路径)`，优先 `stock-docs/req-docs`）。
- 若某主题暂无可公开文档，写“无”或“待补充”，禁止留空导致歧义。
- 若新增/删除主题，索引同步调整，避免孤儿路径。
## 步骤 5：更新路由清单（按需）
- 本步骤由主 agent 落盘（写权硬约束），子 agent 不得执行。
- 更新 `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` 引用有效
- 仅做最小改动，不重写无关字段
## 路径与引用约束
- `sourceDoc` 或文档引用统一指向 `.Knowledge/stock-docs/<文件名>.md`
- 禁止把 `.Knowledge/req-docs/` 作为 topic 的 `sourceDoc`
- 禁止改写配置根 `rules/skills`
## 输出摘要（必须）
- 新增/更新的 topic 文件
- `index` 更新项
- 路由清单更新项（如有）
- 失败或跳过项及原因
## 复杂场景示例
用户输入：`f2s-kb-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。
- 若新文档与现有 `<能力>` 主题高度重合：原位更新 `topics/<能力>.md`，不要新建 `<能力>-v2.md`。
- 若新文档新增子能力：可新增 `topics/<能力>-<子域>.md`，并在 `manifest-routing.topicDependencies` 中声明依赖关系。
- 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。
## 完成后自检
1. `.Knowledge/topics/*.md` 与 `manifest-routing.topicPaths` 一一对应。
2. `index.md` 主题表与 topics 文件集合一致，且每个主题都包含“关联文档（摘要）”。
3. 每个 `taskToTopicRules[].matcherPath` 文件存在且其中 `id` 与 `matcherId` 一致。
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 越权写入。
+61
templates/skills/f2s-kb-rm/SKILL.md
---
name: f2s-kb-rm
description: 删除某 stock-docs 文档对应的知识主题与索引映射；触发：删除项目上下文、f2s-kb-rm
---
> 执行口径：仅维护 `.Knowledge`，不改配置根 `rules/skills`。
## 编排（主 / 子 agent）
- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。不在此复述。
- 默认主 agent 全流程执行（单点删除拆子收益低）。
- 拆子阈值：仅当 `subAgent=true` 且**批量删除一次 ≥ 5 主题**时，才拆子执行删除与清引用。
- 主必控：范围确认、`fallbackTopic` 重指。
- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘。
- 验证：默认落盘侧自验；本 SKILL 不绑定交叉校验。
# 删除文档对应的项目上下文
## 输入
- 一个参数：`.Knowledge/stock-docs/<文件名>.md` 路径，或可匹配文件名片段。
## 执行步骤
1. 读取 `.Knowledge/index.md`，匹配目标文档相关主题。
2. 删除对应 `.Knowledge/topics/<topic>.md` 文件。
3. 从 `.Knowledge/index.md` 移除匹配项并写回。
4. 更新路由清单：
- `.Knowledge/manifest-routing.json`：移除失效 `topicPaths`、`taskToTopicRules`、`topicDependencies`、`topicMetadata` 引用
- 对应 `matchers/<matcherId>.json`：移除失效规则或 `includeAny` 词条（与已删 `task`/`matcherId` 对齐）
- 若删除了 `fallbackTopic`，必须指定新的兜底主题
- **创作侧准则**：本步会调整 `topicDependencies`（删除被依赖主题或孤儿边），须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），核对 DAG 与最小化约束后再落盘。
## 输出摘要（必须）
- 已删除的 topic 文件列表
- `.Knowledge/index.md` 删除的条目
- 路由清单调整的字段
- 未执行项（若有）
## 复杂场景示例
用户输入文件名片段「回调」，匹配到 2 个主题文档。
- 先列出两个候选并要求用户确认删除范围，避免误删。
- 删除后同步清理路由清单失效引用；若删到了 `fallbackTopic`，必须先指定新的兜底主题再落盘。
- 最终摘要中写清：删除了哪些 topic、保留了哪些 topic、为什么。
## 约束
- 匹配多义时先询问用户确认。
- 仅删除命中主题，不影响其它主题。
- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束）；范围确认与 `fallbackTopic` 重指不可下放给子 agent。
## 完成后自检
1. 被删 topic 是否仍被 `manifest` 引用（必须为否）。
2. `index` 是否仍存在失效主题路径（必须为否）。
3. `topicMetadata` 是否仍引用已删除 topic（必须为否）。
4. `fallbackTopic` 是否仍有效。
5. 未在低于拆子阈值（< 5 主题）时强行拆子；manifest / index 由主单点落盘。
+1
-1
docs/.mermaid-cache.json

@@ -24,3 +24,3 @@ {

{
"content": "graph LR\n K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n AI --> C[\"功能迭代\"]\n\n C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n FIN --> CTX[\"f2s-ctx-build\"] --> K\n\n OLD[\"存量代码/文档\"] -->|f2s-doc-add| K\n\n NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-backend\"]\n BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
"content": "graph LR\n K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n AI --> C[\"功能迭代\"]\n\n C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n FIN --> CTX[\"f2s-kb-build\"] --> K\n\n OLD[\"存量代码/文档\"] -->|f2s-kb-add| K\n\n NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-backend\"]\n BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
"hash": "6335fa6eda40",

@@ -27,0 +27,0 @@ "marker": "MERMAID_6335fa6eda40"

+3
-3
docs/en/architecture.md

@@ -37,3 +37,3 @@ [中文](../体系与原理.md) | [English](./architecture.md)

| --- | --- | --- | --- |
| **L0 routing** | `manifest-routing.json` | task→topic, `topicDependencies`, `topicPaths` | First read (machine source of truth) |
| **L0 routing** | `manifest-routing.json` | task→topic, `topicDependencies`, `topicPaths`, `topicMetadata` | First read (machine source of truth) |
| **L1 matcher shard** | `matchers/<id>.json` | `includeAny` triggers | **match**: one shard only |

@@ -78,3 +78,3 @@ | **L2 topic summary** | `topics/<topic>.md` | Hard constraints, boundaries, pointers | **expand**: pull dependency topics |

- Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-ctx-build`
- Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-kb-build`
- Implementation chain: `.Knowledge/req-docs/*.md` -> `implement-tech-design` -> code

@@ -170,2 +170,2 @@ - Maintenance chain: `f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge`

- [Directory Conventions](./directory-conventions.md)
- [Usage Scenarios](./usage-scenarios.md)
- [Usage Scenarios](./usage-scenarios.md)
+15
-38
docs/en/commands-reference.md

@@ -11,5 +11,5 @@ [中文](../命令说明.md) | [English](./commands-reference.md)

| `/f2s-doc-final` | Convert PDF / draft to standardized final-draft format | Doc Curation |
| `/f2s-ctx-build` | Sync final drafts into knowledge base routing (topics / matchers / manifest) | Doc Curation |
| `/f2s-doc-add <path>` | Aggregate multi-file implemented capabilities into knowledge base | Doc Curation |
| `/f2s-ctx-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
| `/f2s-kb-build` | Sync final drafts into knowledge base routing (topics / matchers / manifest) | Doc Curation |
| `/f2s-kb-add <path>` | Aggregate multi-file implemented capabilities into knowledge base | Doc Curation |
| `/f2s-kb-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
| `/f2s-doc-pdf` | Convert PDF technical proposal to Markdown, save to req-docs | Doc Curation |

@@ -44,3 +44,3 @@ | `/f2s-req-clarify` | Clarify requirements via multi-round Q&A | Requirements |

- **Prerequisite**: None
- **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-ctx-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
- **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-kb-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
- **Output**: `.Knowledge/stock-docs/<Architecture Overview>_draft.md`

@@ -64,3 +64,3 @@

**How It Works**: Unstructured or heterogeneous documents (PDF/drafts) are normalized against the built-in final-draft template: core concept tables, business rules, key flows, configuration, error handling, and other standard sections are extracted; missing section markers are filled in; the output is a consistently structured `_final.md`. The final draft is the standard input for `f2s-ctx-build`, keeping knowledge-base entry structure uniform.
**How It Works**: Unstructured or heterogeneous documents (PDF/drafts) are normalized against the built-in final-draft template: core concept tables, business rules, key flows, configuration, error handling, and other standard sections are extracted; missing section markers are filled in; the output is a consistently structured `_final.md`. The final draft is the standard input for `f2s-kb-build`, keeping knowledge-base entry structure uniform.

@@ -74,3 +74,3 @@ **Use Cases**:

- **Prerequisite**: PDF document or draft document
- **Next Step**: `f2s-ctx-build` (final draft imported into the knowledge base)
- **Next Step**: `f2s-kb-build` (final draft imported into the knowledge base)
- **Output**: `.Knowledge/stock-docs/<Document>_final.md`

@@ -90,3 +90,3 @@

### `f2s-ctx-build`
### `f2s-kb-build`

@@ -125,7 +125,7 @@ **Purpose**: Synchronizes documents from `stock-docs/` (architecture, final drafts) into the knowledge base routing system, generating/updating topic files, the index, manifest-routing, and matchers.

### `f2s-doc-add`
### `f2s-kb-add`
**Purpose**: Parses already-implemented capabilities (aggregated from multiple files) into the knowledge base. Suitable when code already exists but lacks documentation, or when multiple documents need to be imported into the knowledge base in a unified manner.
**How It Works**: Aggregates capability descriptions from multiple scattered sources (code, config, loose docs) and runs the full "draft → final draft → topics/index/manifest" pipeline. Unlike `f2s-ctx-build`, the input differs: `ctx-build` is driven from a single existing final draft; `doc-add` aggregates many scattered sources first, then follows the same pipeline. It closes the gap of "implementation exists but documentation does not."
**How It Works**: Aggregates capability descriptions from multiple scattered sources (code, config, loose docs) and runs the full "draft → final draft → topics/index/manifest" pipeline. Unlike `f2s-kb-build`, the input differs: `ctx-build` is driven from a single existing final draft; `doc-add` aggregates many scattered sources first, then follows the same pipeline. It closes the gap of "implementation exists but documentation does not."

@@ -159,7 +159,7 @@ **Use Cases**:

### `f2s-ctx-rm`
### `f2s-kb-rm`
**Purpose**: Deletes corresponding knowledge topics and index mappings based on `stock-docs` documents. Only removes reference relationships in the knowledge base, not the source documents themselves.
**How It Works**: The inverse of `f2s-ctx-build` — given a `stock-docs` document path, locate its task→topic rules in `manifest-routing.json`, the corresponding `matchers/<id>.json` shard, `topics/<topic>.md`, and entries in `index.md`, and remove those references one by one. If a topic has no remaining task references after deletion, remove that topic file. Source documents are left in place; the user may delete them physically if desired.
**How It Works**: The inverse of `f2s-kb-build` — given a `stock-docs` document path, locate its task→topic rules in `manifest-routing.json`, the corresponding `matchers/<id>.json` shard, `topics/<topic>.md`, and entries in `index.md`, and remove those references one by one. If a topic has no remaining task references after deletion, remove that topic file. Source documents are left in place; the user may delete them physically if desired.

@@ -196,3 +196,3 @@ **Use Cases**:

- **Output**: `.Knowledge/req-docs/<Proposal>.md`
- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-backend` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-ctx-build`
- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-backend` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-kb-build`

@@ -416,3 +416,3 @@ **Sub-Agent Invocation**:

- **Feature**: First outputs a knowledge base update outline, then writes only after user confirmation
- **Difference from `f2s-ctx-build`**: `ctx-build` is driven from `stock-docs`; `kb-sync` infers from the conversation/code
- **Difference from `f2s-kb-build`**: `ctx-build` is driven from `stock-docs`; `kb-sync` infers from the conversation/code

@@ -537,11 +537,5 @@ **Sub-Agent Invocation**:

### `f2s-karpathy-guidelines`
**Trigger Words**: `alwaysApply` (always on; no explicit trigger needed)
**Purpose**: Flow2Spec's built-in Karpathy-style coding discipline to improve the quality of agent coding decisions.
**How It Works**: Four behavioral constraints distilled from Andrej Karpathy's observations on common LLM coding mistakes, applied as an `alwaysApply` rule that implicitly governs all `f2s-*` skill runs: (1) think before coding (state assumptions; ask when unsure); (2) simplicity first (minimum code to solve the problem); (3) surgical edits (touch only what must change; match existing style); (4) goal-driven execution (define verifiable success criteria, then iterate). When these guidelines conflict with mandatory `f2s-*` steps, the `f2s-*` steps win.
---
---

@@ -570,22 +564,5 @@ ### `f2s-task`

### `stock-docs-vs-req-docs`
**Trigger Words**: stock-docs, req-docs, implemented capability, where to put the technical proposal, PDF final draft
**Purpose**: Distinguishes the boundary between the knowledge archival directory and the requirements implementation directory.
**How It Works**: "Purpose isolation" to avoid mixing folders — `stock-docs/` holds archived existing knowledge (architecture, final drafts), consumed by `ctx-build` for ingestion into the knowledge base and **must not** be used directly as coding input; `req-docs/` holds implementation-facing requirements and technical proposals, consumed by the `implement-tech-design` rule to drive coding. Writers and readers are fully separated so "stock descriptions are not mistaken for coding contracts" and "implementation proposals are not mistaken for capability archival."
**Directory Division**:
| Directory | Purpose | When It Is Written |
|-----------|---------|-------------------|
| `stock-docs/` | Archival of existing knowledge (architecture, final drafts) | `f2s-doc-arch`, `f2s-doc-final`, `f2s-ctx-build` |
| `req-docs/` | Requirements and technical proposals (driving implementation) | `f2s-req-backend`, `f2s-doc-pdf`, manual placement |
**Use Cases**:
- Unsure where a document should go
- Need to clarify the division of labor between stock-docs and req-docs
---
---

@@ -592,0 +569,0 @@ ### `implement-tech-design`

+4
-4
docs/en/design-principles.md

@@ -103,5 +103,5 @@ [中文](../设计说明.md) | [English](./design-principles.md)

D2["PDF/draft"] -->|f2s-doc-final| FIN
FIN --> CTX["f2s-ctx-build"] --> K
FIN --> CTX["f2s-kb-build"] --> K
OLD["Existing Code/Docs"] -->|f2s-doc-add| K
OLD["Existing Code/Docs"] -->|f2s-kb-add| K

@@ -263,3 +263,3 @@ NR["New Requirement"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]

b7e9d1 f2s-kb-fix: fix RestTemplate injection conventions
c2a8f0 f2s-ctx-build: onboard order service architecture docs
c2a8f0 f2s-kb-build: onboard order service architecture docs
d5b3e9 f2s-kb-sync: consolidate payment retry queue design

@@ -526,3 +526,3 @@

───────────────────── ─────────────────────
1. Write topics/xxx.md f2s-ctx-rm stock-docs/xxx.md
1. Write topics/xxx.md f2s-kb-rm stock-docs/xxx.md
2. Write matchers/m-xxx.json ↓

@@ -529,0 +529,0 @@ 3. Register in manifest-routing Automatically cleans up topics/ + manifest

+26
-3
docs/en/directory-conventions.md

@@ -24,3 +24,3 @@ [中文](../目录与路径约定.md) | [English](./directory-conventions.md)

| `.Knowledge/index.md` | Human-readable index |
| `.Knowledge/manifest-routing.json` | **L0** Machine-readable routing skeleton (task/topic/`topicDependencies`) |
| `.Knowledge/manifest-routing.json` | **L0** Machine-readable routing skeleton (task/topic/`topicDependencies`/`topicMetadata`) |
| `.Knowledge/matchers/*.json` | **L1** Keyword fragments (`id/includeAny`); **match** reads one shard via `matcherPath` |

@@ -42,3 +42,3 @@ | `.Knowledge/migration-report.md` | Migration comparison table and deletion path list written by `f2s-kb-migrate` |

1. `.Knowledge/topics` is the knowledge routing topic layer; it is allowed and encouraged to be maintained via `f2s-*` skills.
2. `f2s-ctx-build` reads from `.Knowledge/stock-docs` and updates `.Knowledge/topics`, `.Knowledge/index.md`, `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json`.
2. `f2s-kb-build` reads from `.Knowledge/stock-docs` and updates `.Knowledge/topics`, `.Knowledge/index.md`, `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json`.
3. Implementation tasks uniformly read from `.Knowledge/req-docs/*.md`.

@@ -49,2 +49,25 @@ 4. `manifest-routing.json` and `matchers/*.json` are maintained by `f2s-*` skill workflows; `.Knowledge/manifest-matchers.json` is no longer used (`flow2spec init` will delete legacy files).

## Topic Metadata
`manifest-routing.json.topicMetadata` is machine-readable governance metadata for topics. It is only used for inventory, filtering, routing audits, upgrade gap checks, and reading expectations; it does not participate in matcher hits, does not decide whether a topic is read, is not a source of execution constraints, and must not drive `topicId` or filename changes. Execution constraints always come from explicit requirements in `AGENTS.md`, rules, skills, or topic bodies.
`topicMetadata` is independent from `topicPaths`, and each key must be a topicId already present in `topicPaths`. When creating a new topic, metadata may be written if there is clear evidence; classification alone must not create, rename, or split topics.
| Field | Values | Meaning |
| --- | --- | --- |
| `primary` | `feature` / `module` / `config` / `policy` | Single primary classification. Read the topic body and write the type that best represents its core content. |
| `tags` | Array of `feature` / `module` / `config` / `policy` | Optional secondary classes; values must not repeat `primary`. |
| `confidence` | `manual` / `inferred` | `manual` means human-confirmed; `inferred` means evidence-backed inference. When evidence is insufficient, do not write metadata and list it as pending confirmation in the summary. |
Type meanings:
| Type | Reading expectation |
| --- | --- |
| `feature` | Landed business or product capability background |
| `module` | Directory, package, module boundary, and engineering structure |
| `config` | Configuration items, switches, defaults, initialization parameters |
| `policy` | Process, rule, constraint, gate, prohibition, agent orchestration, skill step |
---
## Related Documents

@@ -55,2 +78,2 @@

- [Architecture](./architecture.md)
- [Usage Scenarios](./usage-scenarios.md)
- [Usage Scenarios](./usage-scenarios.md)
+6
-6
docs/en/usage-guide.md

@@ -22,3 +22,3 @@ [中文](../使用说明.md) | [English](./usage-guide.md)

> **`init` and "knowledge base upgrade" are two different things**: `init` only handles structural alignment — business semantics (topics content, routing terms, stock-docs/req-docs) are maintained by skills like `f2s-doc-add`, `f2s-kb-fix`, `f2s-kb-feat`, `f2s-kb-sync`, `f2s-ctx-build`, etc. For cross-version upgrades, use `f2s-kb-upgrade`. **Do not treat a standalone `init` as an upgrade command.**
> **`init` and "knowledge base upgrade" are two different things**: `init` only handles structural alignment — business semantics (topics content, routing terms, stock-docs/req-docs) are maintained by skills like `f2s-kb-add`, `f2s-kb-fix`, `f2s-kb-feat`, `f2s-kb-sync`, `f2s-kb-build`, etc. For cross-version upgrades, use `f2s-kb-upgrade`. **Do not treat a standalone `init` as an upgrade command.**

@@ -83,7 +83,7 @@ ### `f2s-*` and `flow2spec.config.json`: Multi-Client, Multi-Layered Reminders (Authority Remains the Disk JSON)

```
New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-ctx-build
PDF/draft ingestion: f2s-doc-final → f2s-ctx-build
New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-kb-build
PDF/draft ingestion: f2s-doc-final → f2s-kb-build
```
Integrate architecture descriptions or PDF final drafts into knowledge routing (generates topics/matchers/manifest-routing). To ingest a PDF into the knowledge base, use `f2s-doc-final` then `f2s-ctx-build`. `f2s-doc-pdf` only converts a PDF to Markdown under `req-docs/` for editing; it is **not** the recommended path for "PDF straight to coding."
Integrate architecture descriptions or PDF final drafts into knowledge routing (generates topics/matchers/manifest-routing). To ingest a PDF into the knowledge base, use `f2s-doc-final` then `f2s-kb-build`. `f2s-doc-pdf` only converts a PDF to Markdown under `req-docs/` for editing; it is **not** the recommended path for "PDF straight to coding."

@@ -93,7 +93,7 @@ ### Backfilling Existing Capabilities

```
f2s-doc-add # Aggregate multiple files, extract from source code / documents
f2s-kb-add # Aggregate multiple files, extract from source code / documents
f2s-kb-sync # Infer already-implemented capabilities from current session
```
Use these when code has already been shipped but the knowledge base has no record. `f2s-doc-add` is suitable for batch imports; `f2s-kb-sync` is suitable for real-time consolidation at the end of a session.
Use these when code has already been shipped but the knowledge base has no record. `f2s-kb-add` is suitable for batch imports; `f2s-kb-sync` is suitable for real-time consolidation at the end of a session.

@@ -100,0 +100,0 @@ ### Routine Maintenance

+1
-1
docs/en/usage-scenarios.md

@@ -76,3 +76,3 @@ [中文](../使用案例-模拟对话.md) | [English](./usage-scenarios.md)

> f2s-ctx-build .Knowledge/stock-docs/order-service-architecture-final.md
> f2s-kb-build .Knowledge/stock-docs/order-service-architecture-final.md

@@ -79,0 +79,0 @@ **Agent**

+2
-2
docs/体系与原理.md

@@ -39,3 +39,3 @@ # 体系与原理

| --- | --- | --- | --- |
| **L0 路由索引** | `manifest-routing.json` | task→topic、`topicDependencies`、`topicPaths` | 会话首读（机读事实源） |
| **L0 路由索引** | `manifest-routing.json` | task→topic、`topicDependencies`、`topicPaths`、`topicMetadata` | 会话首读（机读事实源） |
| **L1 关键词分片** | `matchers/<id>.json` | `includeAny` 触发词 | **match**：只打开命中的一个分片 |

@@ -80,3 +80,3 @@ | **L2 主题摘要** | `topics/<topic>.md` | 硬约束摘要、边界、下一步指针 | **expand**：拉齐依赖主题 |

- 文档沉淀链：`f2s-doc-arch` → `f2s-doc-final` → `f2s-ctx-build`
- 文档沉淀链：`f2s-doc-arch` → `f2s-doc-final` → `f2s-kb-build`
- 实现链：`.Knowledge/req-docs/*.md` → `implement-tech-design` → 代码

@@ -83,0 +83,0 @@ - 维护链：`f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge`

+1
-1
docs/使用案例-模拟对话.md

@@ -76,3 +76,3 @@ # Flow2Spec 使用案例（模拟对话）

> f2s-ctx-build .Knowledge/stock-docs/订单服务架构说明_终稿.md
> f2s-kb-build .Knowledge/stock-docs/订单服务架构说明_终稿.md

@@ -79,0 +79,0 @@ **Agent**

+6
-6
docs/使用说明.md

@@ -24,3 +24,3 @@ # Flow2Spec 使用说明

> **`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` 当作升级命令**。
> **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-kb-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-kb-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。

@@ -87,7 +87,7 @@ ### `f2s-*` 与 `flow2spec.config.json`：多端多重提示（权威仍为磁盘 JSON）

```
新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-ctx-build
PDF/初稿沉淀： f2s-doc-final → f2s-ctx-build
新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-kb-build
PDF/初稿沉淀： f2s-doc-final → f2s-kb-build
```
把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 `f2s-doc-final` 转为终稿再 `f2s-ctx-build`；`f2s-doc-pdf` 仅把 PDF 转为 `req-docs/` 下的 Markdown 便于编辑，**不**作为「PDF 直驱编码」的推荐路径。
把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 `f2s-doc-final` 转为终稿再 `f2s-kb-build`；`f2s-doc-pdf` 仅把 PDF 转为 `req-docs/` 下的 Markdown 便于编辑，**不**作为「PDF 直驱编码」的推荐路径。

@@ -97,7 +97,7 @@ ### 存量能力补录

```
f2s-doc-add # 多文件聚合，从源码/文档提取
f2s-kb-add # 多文件聚合，从源码/文档提取
f2s-kb-sync # 从当前会话推断已实现能力
```
代码已落地但知识库没有记录时使用。`f2s-doc-add` 适合批量导入，`f2s-kb-sync` 适合会话结束时的即时沉淀。
代码已落地但知识库没有记录时使用。`f2s-kb-add` 适合批量导入，`f2s-kb-sync` 适合会话结束时的即时沉淀。

@@ -104,0 +104,0 @@ ### 日常维护

+15
-41
docs/命令说明.md

@@ -11,5 +11,5 @@ # 工作流与技能说明

| `/f2s-doc-final` | PDF / 初稿转《终稿模版》规范格式 | 文档沉淀 |
| `/f2s-ctx-build` | 终稿文档同步到知识库路由（生成 topics / matchers / manifest） | 文档沉淀 |
| `/f2s-doc-add <路径>` | 已落地能力多文件聚合入知识库 | 文档沉淀 |
| `/f2s-ctx-rm` | 删除某 stock-docs 文档对应的知识主题与索引映射 | 文档沉淀 |
| `/f2s-kb-build` | 终稿文档同步到知识库路由（生成 topics / matchers / manifest） | 文档沉淀 |
| `/f2s-kb-add <路径>` | 已落地能力多文件聚合入知识库 | 文档沉淀 |
| `/f2s-kb-rm` | 删除某 stock-docs 文档对应的知识主题与索引映射 | 文档沉淀 |
| `/f2s-doc-pdf` | PDF 技术方案转 Markdown，保存到 req-docs | 文档沉淀 |

@@ -46,3 +46,3 @@ | `/f2s-req-clarify` | 需求澄清，多轮问答明确需求边界 | 需求与方案 |

- **前置**：无
- **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-ctx-build`（**须终稿入参**；初稿不可直驱 build）
- **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-kb-build`（**须终稿入参**；初稿不可直驱 build）
- **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`

@@ -70,3 +70,3 @@

**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-ctx-build` 的标准输入物，确保知识库入口的结构一致性。
**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-kb-build` 的标准输入物，确保知识库入口的结构一致性。

@@ -82,3 +82,3 @@ **使用场景**：

- **前置**：PDF 文档或初稿文档
- **后续**：`f2s-ctx-build`（终稿入库）
- **后续**：`f2s-kb-build`（终稿入库）
- **输出**：`.Knowledge/stock-docs/<文档>_终稿.md`

@@ -102,3 +102,3 @@

### `f2s-ctx-build`
### `f2s-kb-build`

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

### `f2s-doc-add`
### `f2s-kb-add`
**作用**：将已落地能力（多文件聚合）解析进知识库。适用于代码已实现但缺少文档，或已有多个文档需要统一入库的场景。
**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-ctx-build` 的区别在于输入：`ctx-build` 从已有的单份终稿驱动，`doc-add` 从多个散落源聚合后再走同一管线。本质是补齐「有实现无文档」的缺口。
**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-kb-build` 的区别在于输入：`ctx-build` 从已有的单份终稿驱动，`doc-add` 从多个散落源聚合后再走同一管线。本质是补齐「有实现无文档」的缺口。

@@ -184,7 +184,7 @@ **使用场景**：

### `f2s-ctx-rm`
### `f2s-kb-rm`
**作用**：按 stock-docs 文档删除对应的知识主题与索引映射。仅删除知识库中的引用关系，不删除源文档本身。
**工作原理**：`f2s-ctx-build` 的逆操作——给定一份 `stock-docs` 文档路径，定位其在 `manifest-routing.json` 中的 task→topic 规则、对应的 `matchers/<id>.json` 分片、`topics/<topic>.md` 文件以及 `index.md` 中的行项，逐一清除引用。若删除后某 topic 无任何 task 引用，则移除该 topic 文件。源文档本身保留不动，用户可自行决定是否物理删除。
**工作原理**：`f2s-kb-build` 的逆操作——给定一份 `stock-docs` 文档路径，定位其在 `manifest-routing.json` 中的 task→topic 规则、对应的 `matchers/<id>.json` 分片、`topics/<topic>.md` 文件以及 `index.md` 中的行项，逐一清除引用。若删除后某 topic 无任何 task 引用，则移除该 topic 文件。源文档本身保留不动，用户可自行决定是否物理删除。

@@ -226,3 +226,3 @@ **使用场景**：

- **输出**：`.Knowledge/req-docs/<方案>.md`
- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-backend` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-ctx-build`
- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-backend` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-kb-build`

@@ -485,3 +485,3 @@ **子 agent 调用**：

- **特点**：先输出知识库更新大纲，用户确认后才写入
- **与 `f2s-ctx-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断
- **与 `f2s-kb-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断

@@ -631,11 +631,5 @@ **子 agent 调用**：

### `f2s-karpathy-guidelines`
**触发词**：`alwaysApply`（始终生效，无需显式触发）
**作用**：Flow2Spec 内置的 Karpathy 式编码行为准则，约束 Agent 的编码决策质量。
**工作原理**：从 Andrej Karpathy 对 LLM 写代码常见失误的观察中提炼四条行为约束，作为 `alwaysApply` 规则在所有 `f2s-*` 技能执行时隐式生效：① 先想清楚再写代码（假设要说清楚，不确定就问）；② 简单优先（用最少代码解决问题）；③ 手术式修改（只动该动的，风格对齐现有代码）；④ 目标驱动执行（先定义可验证的成功标准再循环迭代）。当这些准则与 `f2s-*` 强制步骤冲突时，以 `f2s-*` 为准。
---
---

@@ -666,25 +660,5 @@ ### `f2s-task`

### `stock-docs-vs-req-docs`
**触发词**：stock-docs、req-docs、已落地能力、技术方案放哪、PDF 终稿
**作用**：区分知识沉淀目录与需求实现目录的边界。
**工作原理**：通过「用途隔离」避免文档混放——`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 与 req-docs 的分工
---
---

@@ -691,0 +665,0 @@ ### `implement-tech-design`

+26
-3
docs/目录与路径约定.md

@@ -24,3 +24,3 @@ # 目录与路径约定

| `.Knowledge/index.md` | 人类可读索引 |
| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`） |
| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`/`topicMetadata`） |
| `.Knowledge/matchers/*.json` | **L1** 关键词分片（`id/includeAny`），由 `matcherPath` 直链；**match** 只读一片 |

@@ -42,3 +42,3 @@ | `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 |

1. `.Knowledge/topics` 是知识路由主题层，允许并鼓励通过 `f2s-*` 技能维护。
2. `f2s-ctx-build` 从 `.Knowledge/stock-docs` 读，更新 `.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`。
2. `f2s-kb-build` 从 `.Knowledge/stock-docs` 读，更新 `.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`。
3. 实现类任务统一读取 `.Knowledge/req-docs/*.md`。

@@ -49,2 +49,25 @@ 4. `manifest-routing.json` 与 `matchers/*.json` 由 `f2s-*` 技能流程维护；不再使用 `.Knowledge/manifest-matchers.json`（`flow2spec init` 会删除遗留文件）。

## 主题元数据
`manifest-routing.json.topicMetadata` 是 topic 的机读治理元数据，只用于盘点、过滤、路由审计、升级补缺和阅读预期；不参与 matcher 命中，不决定是否读取 topic，不作为执行强制性的事实源，也不驱动 `topicId` 或文件名变化。执行强制性始终以 `AGENTS.md`、rules、skills 与 topic 正文中的明确要求为准。
`topicMetadata` 独立于 `topicPaths`，key 必须是 `topicPaths` 中已存在的 topicId。新增 topic 时有明确证据可同步写入；仅补分类不得创建 topic、重命名 topic 或拆分 topic。
| 字段 | 取值 | 说明 |
| --- | --- | --- |
| `primary` | `feature` / `module` / `config` / `policy` | 单值主分类。取 topic 最核心的性质，读 topic 正文后写入。 |
| `tags` | `feature` / `module` / `config` / `policy` 数组 | 可选次要分类，不得与 `primary` 重复。 |
| `confidence` | `manual` / `inferred` | `manual` 为人工确认；`inferred` 为有明确证据推断；证据不足时不写 metadata，并在摘要列为待确认。 |
类型含义：
| 类型 | 阅读预期 |
| --- | --- |
| `feature` | 已落地业务/产品能力背景 |
| `module` | 目录、包、模块边界与工程结构 |
| `config` | 配置项、开关、默认值、初始化参数 |
| `policy` | 流程、规则、约束、门禁、禁止项、agent 编排、技能步骤 |
---
## 相关文档

@@ -55,2 +78,2 @@

- [体系与原理](./体系与原理.md)
- [使用案例-模拟对话](./使用案例-模拟对话.md)
- [使用案例-模拟对话](./使用案例-模拟对话.md)
+4
-4
docs/设计说明.md

@@ -145,5 +145,5 @@ # Flow2Spec 设计说明

D2["PDF/初稿"] -->|f2s-doc-final| FIN
FIN --> CTX["f2s-ctx-build"] --> K
FIN --> CTX["f2s-kb-build"] --> K
OLD["存量代码/文档"] -->|f2s-doc-add| K
OLD["存量代码/文档"] -->|f2s-kb-add| K

@@ -298,3 +298,3 @@ NR["新需求"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]

b7e9d1 f2s-kb-fix: 修正 RestTemplate 注入约定
c2a8f0 f2s-ctx-build: 订单服务架构说明入库
c2a8f0 f2s-kb-build: 订单服务架构说明入库
d5b3e9 f2s-kb-sync: 沉淀支付重试队列设计

@@ -552,3 +552,3 @@

───────────────────── ─────────────────────
1. 写 topics/xxx.md f2s-ctx-rm stock-docs/xxx.md
1. 写 topics/xxx.md f2s-kb-rm stock-docs/xxx.md
2. 写 matchers/m-xxx.json ↓

@@ -555,0 +555,0 @@ 3. 在 manifest-routing 注册 自动清除 topics/ + manifest

+116
-1
lib/init.js

@@ -24,2 +24,5 @@ const path = require("path");

const KNOWLEDGE_TOPIC_TYPES = ["feature", "module", "config", "policy"];
const KNOWLEDGE_TOPIC_CONFIDENCE = ["manual", "inferred"];
function ensureDir(dir) {

@@ -179,2 +182,41 @@ if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });

function normalizeTopicMetadataEntry(entry) {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
if (!KNOWLEDGE_TOPIC_TYPES.includes(entry.primary)) return null;
const confidence =
typeof entry.confidence === "string" &&
KNOWLEDGE_TOPIC_CONFIDENCE.includes(entry.confidence)
? entry.confidence
: null;
if (!confidence) return null;
const result = { primary: entry.primary, confidence };
if (Array.isArray(entry.tags) && entry.tags.length > 0) {
const validTags = dedupeStringArray(entry.tags).filter(
(t) =>
KNOWLEDGE_TOPIC_TYPES.includes(t) &&
t !== entry.primary,
);
if (validTags.length > 0) result.tags = validTags;
}
return result;
}
function mergeTopicMetadata(templateMetadata, existingMetadata, topicPaths) {
const out = {};
const topicIds = new Set(Object.keys(topicPaths || {}));
// existingMetadata 先写，templateMetadata 后写覆盖——模板优先
for (const metadata of [existingMetadata, templateMetadata]) {
if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
continue;
}
for (const [topicId, entry] of Object.entries(metadata)) {
if (!topicIds.has(topicId)) continue;
const normalized = normalizeTopicMetadataEntry(entry);
if (!normalized) continue;
out[topicId] = normalized;
}
}
return out;
}
function buildMergedRouting(templateRouting, existingRouting) {

@@ -228,2 +270,10 @@ const mergedTaskRules = unionByKey(

};
const mergedTopicMetadata = mergeTopicMetadata(
templateRouting.topicMetadata,
existingRouting.topicMetadata,
knownMerged.topicPaths,
);
if (Object.keys(mergedTopicMetadata).length > 0) {
knownMerged.topicMetadata = mergedTopicMetadata;
}

@@ -554,2 +604,55 @@ const knownKeys = new Set(Object.keys(knownMerged));

if (routing.topicMetadata !== undefined) {
if (
!routing.topicMetadata ||
typeof routing.topicMetadata !== "object" ||
Array.isArray(routing.topicMetadata)
) {
throw new Error("topicMetadata 必须是对象。");
}
for (const [topicId, metadata] of Object.entries(routing.topicMetadata)) {
if (!topicIds.has(topicId)) {
throw new Error(`topicMetadata 引用了不存在的 topic：${topicId}`);
}
if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
throw new Error(`topicMetadata.${topicId} 必须是对象。`);
}
for (const key of Object.keys(metadata)) {
if (!["primary", "tags", "confidence"].includes(key)) {
throw new Error(`topicMetadata.${topicId} 包含未知字段：${key}`);
}
}
if (!KNOWLEDGE_TOPIC_TYPES.includes(metadata.primary)) {
throw new Error(
`topicMetadata.${topicId}.primary 非法：${metadata.primary}`,
);
}
if (!KNOWLEDGE_TOPIC_CONFIDENCE.includes(metadata.confidence)) {
throw new Error(
`topicMetadata.${topicId}.confidence 非法：${metadata.confidence}`,
);
}
if (metadata.tags !== undefined) {
if (!Array.isArray(metadata.tags)) {
throw new Error(`topicMetadata.${topicId}.tags 必须是数组。`);
}
const seenTags = new Set();
for (const tag of metadata.tags) {
if (!KNOWLEDGE_TOPIC_TYPES.includes(tag)) {
throw new Error(`topicMetadata.${topicId}.tags 包含非法值：${tag}`);
}
if (tag === metadata.primary) {
throw new Error(
`topicMetadata.${topicId}.tags 不应与 primary 重复：${tag}`,
);
}
if (seenTags.has(tag)) {
throw new Error(`topicMetadata.${topicId}.tags 包含重复值：${tag}`);
}
seenTags.add(tag);
}
}
}
}
const matcherMap =

@@ -673,5 +776,17 @@ matcherData?.matchers && typeof matcherData.matchers === "object"

ensureDir(skillsDest);
for (const name of fs.readdirSync(skillsSrc)) {
const templateNames = new Set(fs.readdirSync(skillsSrc));
for (const name of templateNames) {
copyRecursive(path.join(skillsSrc, name), path.join(skillsDest, name));
}
// 删除配置根中以 f2s- 开头、但已不存在于 templates/skills/ 的旧 skill 目录
// 只清理 Flow2Spec 管理的 skill，不触碰用户自定义 skill
// LEGACY_SKILLS：非 f2s- 开头的历史旧名，也需一并清理
const LEGACY_SKILLS = new Set(["stock-docs-vs-req-docs"]);
if (fs.existsSync(skillsDest)) {
for (const name of fs.readdirSync(skillsDest)) {
if ((name.startsWith("f2s-") || LEGACY_SKILLS.has(name)) && !templateNames.has(name)) {
fs.rmSync(path.join(skillsDest, name), { recursive: true, force: true });
}
}
}
}

@@ -678,0 +793,0 @@ }

+2
-2
package.json
{
"name": "@double-codeing/flow2spec",
"version": "3.0.19",
"description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则 f2s-karpathy-guidelines，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
"version": "3.1.0",
"description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
"homepage": "https://github.com/Lands-1203/Flow2Spec#readme",

@@ -6,0 +6,0 @@ "repository": {

+15
-6
README.en.md

@@ -53,6 +53,6 @@ # Flow2Spec — Let AI Always Know What You're Doing

## What Flow2Spec Does (3 Things)
## What Flow2Spec Does
**① Remembers project context across devices and sessions**
`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant.
**① Remembers project context across sessions**
`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant — 4.7 MB of source code compressed to ~300 lines of precise context.

@@ -65,2 +65,11 @@ **② Routing manifest means AI doesn't dig through your repo**

**④ Full pipeline from requirements to code**
`/f2s-req-clarify` asks questions until requirements are unambiguous. `/f2s-req-backend` generates a ready-to-implement technical proposal into `req-docs/`. AI implements from the proposal — no relying on verbal agreements.
**⑤ Task checklists track progress across sessions**
When `changeTracking` is enabled, skills like `f2s-kb-feat` / `f2s-kb-fix` automatically create a `task.md` with checkboxes. Each step is checked off immediately to disk. New sessions auto-load the remaining checklist — no relying on memory. User-side todos (run SQL, set env vars, click approvals) go into `user-todos.md`, separate from AI steps.
**⑥ Document-driven: PDF / MD straight into the knowledge base**
`/f2s-kb-add` aggregates source files into draft → final → topics. `/f2s-doc-final` converts any PDF or MD into the canonical final-draft format. External docs and legacy proposals all become routable knowledge.
---

@@ -108,3 +117,3 @@

2. `/f2s-doc-add <folder path>` — Import any feature modules that haven't been added yet
2. `/f2s-kb-add <folder path>` — Import any feature modules that haven't been added yet

@@ -122,3 +131,3 @@ > Do this selectively before starting development when you notice a module's knowledge is missing from the knowledge base.

/f2s-req-backend ← generate technical proposal
natural language: implement the proposal above ← AI starts coding
natural language: implement the proposal above ← AI starts coding (task checklist auto-created when changeTracking is on)
(debug and verify)

@@ -150,3 +159,3 @@ /f2s-kb-feat add xxx capability ← if something's missing

| `/f2s-git-commit` | Commit code |
| `/f2s-doc-add <path>` | Import API module into knowledge base |
| `/f2s-kb-add <path>` | Import API module into knowledge base |

@@ -153,0 +162,0 @@ For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Commands Reference](./docs/en/commands-reference.md)

+3
-3
README.md

@@ -69,3 +69,3 @@ # Flow2Spec — 让 AI 一直知道你在做什么

**⑥ 文档驱动：PDF / MD 一键入知识库**
`/f2s-doc-add` 把已落地能力的源码聚合成初稿 → 终稿 → topics，`/f2s-doc-final` 把 PDF 或任意 MD 转成规范终稿格式。外部文档、历史方案都能变成可路由的知识。
`/f2s-kb-add` 把已落地能力的源码聚合成初稿 → 终稿 → topics，`/f2s-doc-final` 把 PDF 或任意 MD 转成规范终稿格式。外部文档、历史方案都能变成可路由的知识。

@@ -114,3 +114,3 @@ ---

2. `/f2s-doc-add <文件夹路径>` — 把还没入库的功能模块路径补进来
2. `/f2s-kb-add <文件夹路径>` — 把还没入库的功能模块路径补进来

@@ -155,3 +155,3 @@ > 这一步在进入开发前，发现没有某个模块能力的知识的时候选择性的去做

| `/f2s-git-commit` | 提交代码 |
| `/f2s-doc-add <路径>` | 接口模块入知识库 |
| `/f2s-kb-add <路径>` | 接口模块入知识库 |

@@ -158,0 +158,0 @@ 更多命令详见 [使用说明](./docs/使用说明.md) · [命令说明](./docs/命令说明.md)

+5
-5
templates/AGENTS.md

@@ -33,2 +33,3 @@ # Flow2Spec 项目入口

- 若命中主题含 `topicDependencies`，先读依赖主题再读主主题。
- 若存在 `topicMetadata`，仅将其中 `primary` / `tags` 作为阅读预期：`config` 关注配置项 / 开关 / 默认值；`policy` 关注正文中的必须 / 禁止 / 门禁 / 流程约束；`feature` 作为已落地能力背景；`module` 作为目录 / 包 / 模块边界背景。`topicMetadata` 不参与 matcher 命中，不决定是否读取 topic，不改变执行强制性；无明确分类证据时不写 metadata，并在摘要列为待确认。
- `manifest` 仅通过 `f2s-*` 技能流程维护，不假设存在额外 CLI 命令。

@@ -53,3 +54,3 @@ 2. **人工索引按需读取**：仅在需要校验主题语义与边界时读取 **`./.Knowledge/index.md`**。

- 禁止跳过 **`./.Knowledge/manifest-routing.json`**、按需 `matcherPath` 分片与 **`./.Knowledge/topics/`** 直接全仓检索或直接编码；**`./.Knowledge/index.md`** 按需读取，不可替代上述机读链。
- 同一任务线内避免重复全文读取 **`./.Knowledge/manifest-routing.json`**（除非用户说明已通过 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 等更新路由或知识、或手动改了 manifest；**勿将**仅执行 `flow2spec init` 当作业务知识库已更新）；禁止为枚举而遍历整个 **`./.Knowledge/matchers/`**；禁止 **`./.Knowledge/index.md`** 与 routing 交替「刷清单」。
- 同一任务线内避免重复全文读取 **`./.Knowledge/manifest-routing.json`**（除非用户说明已通过 `f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 等更新路由或知识、或手动改了 manifest；**勿将**仅执行 `flow2spec init` 当作业务知识库已更新）；禁止为枚举而遍历整个 **`./.Knowledge/matchers/`**；禁止 **`./.Knowledge/index.md`** 与 routing 交替「刷清单」。
- 禁止把 **`./.Knowledge/stock-docs/`** 作为“按方案实现代码”的直接输入文档。

@@ -66,3 +67,3 @@ - Flow2Spec 执行条令以 **`./AGENTS.md`**（完整）、**`./.codex/topics/f2s-*.md`** 与 **`./.codex/skills/`** 为准；**`.codex/AGENTS.md`** 仅为目录指针，不可替代根 `AGENTS.md`；勿使用仓库内 **非上述路径** 的同名条令文件作为执行依据，以免口径分叉。

3. `./.Knowledge/index.md`（按需，用于语义校验）
4. `./.Knowledge/topics/<topic>.md`（摘要；涉及统一入口、路由细则、`implement-tech-design` / `stock-docs-vs-req-docs` 等时，按需续读下文 **「专题长文」** 所列 `./.codex/topics/f2s-*.md`）
4. `./.Knowledge/topics/<topic>.md`（摘要；涉及统一入口、路由细则、`implement-tech-design` / `f2s-doc-routing` 等时，按需续读下文 **「专题长文」** 所列 `./.codex/topics/f2s-*.md`）
5. `./.Knowledge/stock-docs/<doc>.md`（按需）

@@ -80,3 +81,3 @@ 6. 业务代码（按需；路径以仓库内实际目录为准）

- 不在此处维护静态主题列表，避免与知识库演进漂移。
- 每次任务均以 **`./.Knowledge/manifest-routing.json`** 的 `topicPaths`、`taskToTopicRules`、`fallbackTopic` 为唯一路由事实，并按每条规则的 `matcherPath` 读取 matcher 分片。
- 每次任务均以 **`./.Knowledge/manifest-routing.json`** 的 `topicPaths`、`taskToTopicRules`、`fallbackTopic` 为唯一路由事实，并按每条规则的 `matcherPath` 读取 matcher 分片；`topicMetadata` 只作治理与阅读预期，不是路由事实源。
- 若路由清单与 **`./.Knowledge/index.md`** 语义不一致，以路由清单为准并提示用户同步修正。

@@ -90,3 +91,3 @@

- **implement-tech-design**：`./.codex/topics/f2s-implement-tech-design.md`
- **stock-docs-vs-req-docs**：`./.codex/topics/f2s-stock-docs-vs-req-docs.md`
- **f2s-doc-routing**：`./.codex/topics/f2s-stock-docs-vs-req-docs.md`

@@ -97,3 +98,2 @@ 同目录下另有：

- **`./.codex/topics/f2s-config-check.md`**：内容与上文「先 Read **`./flow2spec.config.json`**」一致并含 **changeTracking** 细表；**仅**在需核对细表时按需打开，不必与上列三条并列必读。
- **`./.codex/topics/f2s-karpathy-guidelines.md`**：通用编码行为准则（先澄清、极简、手术式修改、可验证目标）；与 f2s 路由/任务条令**并行**，硬冲突时以 **f2s 条令**为准。

@@ -100,0 +100,0 @@ 执行 Flow2Spec 相关任务时，先读本文件（**`./AGENTS.md`**）与 **`./.Knowledge/manifest-routing.json`**，再按需打开上列 **`./.codex/topics/*.md`** 文件。

+4
-4
templates/knowledge/index.md

@@ -26,3 +26,3 @@ # Flow2Spec Knowledge Index

| implement-tech-design | `.Knowledge/topics/f2s-implement-tech-design.md` | 按技术方案实现代码 | req：[技术方案](.Knowledge/req-docs/<技术方案>.md)（必填） |
| stock-docs-vs-req-docs | `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` | stock-docs / req-docs 目录分工 | stock：[目录边界说明](.Knowledge/stock-docs/<目录边界说明>.md)（可选） |
| f2s-doc-routing | `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` | stock-docs / req-docs 目录分工 | stock：[目录边界说明](.Knowledge/stock-docs/<目录边界说明>.md)（可选） |
| fallback-triage | `.Knowledge/topics/f2s-fallback-triage.md` | 未命中或低置信度：分诊与澄清 | stock：[路由分诊说明](.Knowledge/stock-docs/<分诊说明>.md)（可选） |

@@ -34,3 +34,3 @@ | config-precheck | `.Knowledge/topics/f2s-config-precheck.md` | 执行 `f2s-*` 前读 `flow2spec.config.json` / 编排开关 | Codex 长文：仓库根 `.codex/topics/f2s-config-check.md`；[路由摘要](topics/f2s-config-precheck.md) |

每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。
其中 **`implement-tech-design`**、**`stock-docs-vs-req-docs`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。
其中 **`implement-tech-design`**、**`f2s-doc-routing`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。

@@ -67,3 +67,3 @@ ---

| --- | --- |
| 有文档但没配到（1a） | 维护侧：`f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 补路由与 `includeAny`。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
| 有文档但没配到（1a） | 维护侧：`f2s-kb-build` / `f2s-kb-sync` / `f2s-kb-add` 补路由与 `includeAny`。执行侧：分诊主题澄清任务类型，**不**用全仓扫替代 manifest。 |
| 配到了但不够（1b） | 走依赖与次高候选 → `verify` 点名缺哪篇文档；仍缺则向用户要路径或补 `req-docs`。 |

@@ -73,2 +73,2 @@ | 库里没有（2） | 承认缺口 → 代码下钻或请用户补需求/方案文档。 |

**说明**：「路由/知识已更新」指 `f2s-*`（如 `f2s-ctx-build`、`f2s-kb-sync`、`f2s-doc-add`、`f2s-kb-fix` 等）产出或手改 `manifest-routing` / `matchers` 分片；**`flow2spec init` 不撰写业务文档**，以模板补齐与配置根落盘为主，勿与知识库内容更新混为一谈。
**说明**：「路由/知识已更新」指 `f2s-*`（如 `f2s-kb-build`、`f2s-kb-sync`、`f2s-kb-add`、`f2s-kb-fix` 等）产出或手改 `manifest-routing` / `matchers` 分片；**`flow2spec init` 不撰写业务文档**，以模板补齐与配置根落盘为主，勿与知识库内容更新混为一谈。
+34
-5
templates/knowledge/manifest-routing.json

@@ -9,3 +9,3 @@ {

"implement-tech-design": [
"stock-docs-vs-req-docs"
"f2s-doc-routing"
],

@@ -16,5 +16,34 @@ "f2s-req-plan": [

},
"topicMetadata": {
"implement-tech-design": {
"primary": "policy",
"confidence": "manual"
},
"f2s-doc-routing": {
"primary": "policy",
"confidence": "manual"
},
"fallback-triage": {
"primary": "policy",
"confidence": "manual"
},
"config-precheck": {
"primary": "config",
"tags": [
"policy"
],
"confidence": "manual"
},
"f2s-task": {
"primary": "policy",
"confidence": "manual"
},
"f2s-req-plan": {
"primary": "policy",
"confidence": "manual"
}
},
"topicPaths": {
"implement-tech-design": ".Knowledge/topics/f2s-implement-tech-design.md",
"stock-docs-vs-req-docs": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md",
"f2s-doc-routing": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md",
"fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md",

@@ -39,3 +68,3 @@ "config-precheck": ".Knowledge/topics/f2s-config-precheck.md",

"topics": [
"stock-docs-vs-req-docs",
"f2s-doc-routing",
"implement-tech-design"

@@ -49,3 +78,3 @@ ]

"topics": [
"stock-docs-vs-req-docs"
"f2s-doc-routing"
]

@@ -70,2 +99,2 @@ },

]
}
}
+2
-2
templates/knowledge/template/终稿模版.md

@@ -5,3 +5,3 @@ > **主口径（统一知识库）**：终稿模板与终稿文档统一维护在 `.Knowledge/template/` 与 `.Knowledge/stock-docs/`。

> 本模板用于将「架构说明」「功能/技术方案」等文档整理为**终稿**形态，便于 **f2s-ctx-build** 技能更新 `.Knowledge/topics`、`.Knowledge/index.md` 与（按需）路由清单（`manifest-routing` + `matchers/*.json`）。
> 本模板用于将「架构说明」「功能/技术方案」等文档整理为**终稿**形态，便于 **f2s-kb-build** 技能更新 `.Knowledge/topics`、`.Knowledge/index.md` 与（按需）路由清单（`manifest-routing` + `matchers/*.json`）。
> 适用：后端服务、前端/客户端、全栈、产品与设计说明等，按需保留或省略章节。

@@ -103,2 +103,2 @@ > **在 Flow2Spec 中**：主模板路径为 `.Knowledge/template/终稿模版.md`；配置根不再写入 `template/` 副本。

- 至少保留 **核心概念、业务规则、关键流程** 三个二级标题，其余按需增删。
- 保存为 `.Knowledge/stock-docs/<方案名>_终稿.md` 后，按 **f2s-ctx-build** 技能、以该路径为入参即可更新 `.Knowledge/topics`、`.Knowledge/index.md`，并在需要时更新路由清单。
- 保存为 `.Knowledge/stock-docs/<方案名>_终稿.md` 后，按 **f2s-kb-build** 技能、以该路径为入参即可更新 `.Knowledge/topics`、`.Knowledge/index.md`，并在需要时更新路由清单。
+2
-2
templates/knowledge/topics/f2s-fallback-triage.md

@@ -37,3 +37,3 @@ # fallback-triage

> 当前任务未命中路由。请确认：**这个领域的文档是否已录入知识库？**
> - 是 → 可能是路由词条缺失，建议执行 `f2s-ctx-build` / `f2s-kb-sync` 补充路由后重试
> - 是 → 可能是路由词条缺失，建议执行 `f2s-kb-build` / `f2s-kb-sync` 补充路由后重试
> - 否 → 知识库当前无此覆盖，可选择：下钻业务源码 / 补充 `req-docs` 后按方案实现

@@ -51,3 +51,3 @@ > - 不确定 → 请检查 `.Knowledge/stock-docs/` 是否有相关文档，再告知

| 已命中主题，补齐上下文后 | 跳转至该 topic，按 `match → expand → verify → act` 执行 |
| 用户确认文档已录入，路由词条缺失 | 提示执行 `f2s-ctx-build` / `f2s-kb-sync` 补路由，本次暂停或下钻源码 |
| 用户确认文档已录入，路由词条缺失 | 提示执行 `f2s-kb-build` / `f2s-kb-sync` 补路由，本次暂停或下钻源码 |
| 用户确认库中无覆盖 | 提供两条路：下钻源码 / 补充 `req-docs` 后实现 |

@@ -54,0 +54,0 @@ | 用户不确定，仍无法定位 | 停止执行，向用户说明原因，等待明确指令 |

+3
-3
templates/knowledge/topics/f2s-stock-docs-vs-req-docs.md

@@ -1,2 +0,2 @@

# stock-docs-vs-req-docs（路由摘要）
# f2s-doc-routing（路由摘要）

@@ -8,3 +8,3 @@ > **唯一长文**：Cursor / Claude 以配置根 **`rules/f2s-stock-docs-vs-req-docs.md(c)`** 为准。

- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`stock-docs-vs-req-docs`**。
- 供 `manifest-routing.topicPaths`、**`topicDependencies`** 与 `index.md` 锚定主题 id **`f2s-doc-routing`**。
- 仅保留**目录分工**记忆点。

@@ -16,3 +16,3 @@

| --- | --- |
| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-ctx-build` / `f2s-doc-final` 等优先落盘。 |
| `.Knowledge/stock-docs/` | 架构、终稿、沉淀；`f2s-kb-build` / `f2s-doc-final` 等优先落盘。 |
| `.Knowledge/req-docs/` | 需求澄清、**技术方案**、按方案实现时的 MD 输入。 |

@@ -19,0 +19,0 @@ 

+37
-9
templates/skills/f2s-doc-arch/SKILL.md

@@ -5,3 +5,3 @@ ---

---
> 执行口径：本技能产物默认写入 `.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`。

@@ -22,3 +22,3 @@ ## 编排（主 / 子 agent）

**与 f2s-doc-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-ctx-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进知识库（初稿→终稿→topics/index/manifest），应使用 **`f2s-doc-add`**，**勿用本技能冒充该流程**。
**与 f2s-kb-add 的分工**：本技能**只**负责「架构说明类**初稿**」这一环，默认**不**在同一技能内写终稿、不直接执行 **f2s-kb-build**。若用户在工作中要把**已做好的能力**依据多份相关文件路径**一次**解析进知识库（初稿→终稿→topics/index/manifest），应使用 **`f2s-kb-add`**，**勿用本技能冒充该流程**。

@@ -74,15 +74,43 @@ ---

## 大功能拆分建议
扫描或理解完源码/说明后，若识别出以下任一信号，须在初稿**末尾**输出「拆分建议」段落，供用户参考（不阻断生成）：
- 源码总量超过 **~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 <终稿路径>`** 同步知识路由主题与索引。

@@ -103,2 +131,2 @@ ---

- **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-ctx-build`**；不得仅推荐 build。
- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-kb-build`**；不得仅推荐 build。
+5
-5
templates/skills/f2s-doc-final/SKILL.md
---
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、转成概述模板、终稿模版
---

@@ -18,3 +18,3 @@

用户会在本技能后附带**至少一个参数**：**第一个参数**为本地 **PDF 文件路径**或 **Markdown 文件路径**（必填）；**第二个参数**（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 **f2s-ctx-build** 技能消费的终稿风格 Markdown 文档。
用户会在本技能后附带**至少一个参数**：**第一个参数**为本地 **PDF 文件路径**或 **Markdown 文件路径**（必填）；**第二个参数**（可选）为输出文件路径，若提供则覆盖默认输出位置。请根据文件类型按下列流程执行，输出便于后续由 **f2s-kb-build** 技能消费的终稿风格 Markdown 文档。

@@ -48,3 +48,3 @@ **终稿模版仅作提示**：若存在 `.Knowledge/template/终稿模版.md`（来源 `templates/knowledge/template/终稿模版.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`）。

@@ -75,3 +75,3 @@ ---

- **输出建议**：生成 `.Knowledge/stock-docs/<方案名>_终稿.md`。
- **回复**：告知已生成规范版，并提示可按 `f2s-ctx-build` 继续同步 `.Knowledge/topics` 与索引。
- **回复**：告知已生成规范版，并提示可按 `f2s-kb-build` 继续同步 `.Knowledge/topics` 与索引。

@@ -95,3 +95,3 @@ ---

- 建议（不强制）保留 **核心概念、业务规则、关键流程** 三个二级标题；其余章节按原文与需求增删，终稿模版仅作提示，不强制套用。
- 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 `f2s-ctx-build` 同步知识路由主题与索引。
- 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 `f2s-kb-build` 同步知识路由主题与索引。
+8
-6
templates/skills/f2s-kb-feat/SKILL.md

@@ -41,3 +41,4 @@ ---

- `.Knowledge/index.md`：主题索引
- 路由清单：路由或依赖变化时最小更新
- 路由清单：路由、依赖或 `topicMetadata` 变化时最小更新
- **创作侧准则**：本步若新增 / 修改 topic、`topicMetadata` 或 `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。
4. 输出摘要（能力点、实现、知识库变更）。

@@ -98,6 +99,7 @@

3. `index` 与 `manifest` 是否同步更新。
4. 知识库变更是否可再压缩：删掉与本次变更无关的套话后，规则与链接是否仍完整。
5. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：若现行规则已写清，此类句应删或并入用户要求的迁移小节。
6. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。
7. 若 `changeTracking.feat: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才将 `.task/active/<task-name>/` 归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。
8. 若 `changeTracking.feat: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。
4. 若写入 `topicMetadata`：key 是否存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否未因分类创建、重命名或拆分 topic。
5. 知识库变更是否可再压缩：删掉与本次变更无关的套话后，规则与链接是否仍完整。
6. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：若现行规则已写清，此类句应删或并入用户要求的迁移小节。
7. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。
8. 若 `changeTracking.feat: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才将 `.task/active/<task-name>/` 归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。
9. 若 `changeTracking.feat: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。
+8
-6
templates/skills/f2s-kb-fix/SKILL.md

@@ -41,3 +41,4 @@ ---

- `.Knowledge/index.md`：更新主题索引
- 路由清单：若路由受影响则最小更新
- 路由清单：若路由、依赖或 `topicMetadata` 受影响则最小更新
- **创作侧准则**：本步若新增 / 修改 topic、`topicMetadata` 或 `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。
4. 输出摘要（代码改动 + 知识库改动）。

@@ -95,6 +96,7 @@

4. 若更新了 `manifest`，路由字段是否仍可解析。
5. 知识库变更是否可再压缩：删套话后约定是否仍清晰。
6. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：现行规则已写清则应删。
7. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。
8. 若 `changeTracking.fix: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。
9. 若 `changeTracking.fix: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。
5. 若写入 `topicMetadata`：key 是否存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否未因分类创建、重命名或拆分 topic。
6. 知识库变更是否可再压缩：删套话后约定是否仍清晰。
7. 是否仍存在「否定旧版 / 不再与某物有关」类赘句：现行规则已写清则应删。
8. 子 agent 未整文件重写文档；manifest / index 由主 agent 单点落盘。
9. 若 `changeTracking.fix: true`：`task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后，才归档至 `completed/` 并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时移动目录（与 `f2s-task` 归档门禁一致）。
10. 若 `changeTracking.fix: true`：`user-todos.md` 已存在；有用户代办时内容已与会话结论一致。
+12
-10
templates/skills/f2s-kb-migrate/SKILL.md

@@ -167,5 +167,6 @@ ---

- 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。
- **创作侧准则**：本步生成 / 重写 topic 或调整 `topicMetadata` / `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。
3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。
4. 按需更新路由清单：
- `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`fallbackTopic`
- `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`topicMetadata`、`fallbackTopic`
- `.Knowledge/matchers/<matcherId>.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致）

@@ -349,10 +350,11 @@ 5. 输出本主题迁移摘要并**暂停**，提示用户：

3. `index` 是否可定位到每个已迁移主题。
4. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。
5. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。
6. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。
7. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。
8. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。
9. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。
10. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。
11. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。
12. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。
4. `topicMetadata` 是否只引用 `topicPaths` 已存在 topicId；`primary` / `tags` / `confidence` 是否合法。
5. `.Knowledge/stock-docs`、`.Knowledge/req-docs` 是否与确认迁移清单一致。
6. 待人工确认清单是否已清空；未清空则禁止删除旧文档目录。
7. 旧业务 `rules/`、**非 `f2s-*`** 的旧业务 `skills/`、旧版索引及（若列入清单）旧文档目录是否已按**最终删除清单**执行删除；基线保留清单中的 3 个 `f2s-*` 根规则是否仍保留。
8. 旧版入口 `docs-index.md` / `index-doc.md` 与 `rules/main.md(c)` 是否已按清单删除（且 `.Knowledge` 已可替代其职责），或是否因用户排除而**明确保留**并写入 `notes[]`。
9. 状态文件是否与迁移结果一致（完成则删除，暂停则保留且 `status=paused`）。
10. `.Knowledge/index.md` 是否已为每个主题同步“关联文档（摘要）”列（可写“无”，但不得留空）。
11. `skills/f2s-*` 是否未被误删、未被写入 `.Knowledge`。
12. `.Knowledge/migration-report.md` 是否已落盘且包含 **迁移对照表**、**拟删除路径清单**；若已执行删除，是否已追加 **「删除执行记录」** 并与实际磁盘状态一致。
13. 状态机文件与删除执行记录未被子 agent 越权写入；manifest / index 由主 agent 单点落盘。
+13
-5
templates/skills/f2s-kb-sync/SKILL.md

@@ -37,2 +37,6 @@ ---

- `.Knowledge/stock-docs/`
- **主题粒度扫描**：对已有 topic 粗扫以下信号，命中时在步骤 2 大纲中列为"建议拆分"（不阻断同步流程）：
- 对应 stock-doc 超过 **300–500 行**；
- `includeAny` 词数超过 **12 个**；
- topic 正文包含超过 **3 个不相干职责域**的二级标题。

@@ -47,4 +51,5 @@ ### 步骤 2：输出《更新大纲》（必须）

4. 拟改文件清单（精确到路径）
5. 不改动范围
6. 等待用户确认提示
5. 主题同步计划：说明每个能力是“更新已有主题”还是“创建新主题”，并列出 topicId、topic 文件、index 行、manifest/matcher 变更；如涉及 `topicMetadata`，列出 `primary` / `tags` / `confidence` 候选和证据；无明确证据时写“不分类 / 暂不写入”
6. 不改动范围
7. 等待用户确认提示

@@ -56,2 +61,4 @@ > 未确认前禁止落盘修改。

> 硬约束：若启用拆子，子 agent 落盘前必须读取近邻 2–3 个主题的开头摘要，确保叙事风格一致；`manifest-routing.json` 与 `.Knowledge/index.md` 由主 agent 单点落盘，子 agent 无写权。
>
> **创作侧准则**：本步若新增 / 修改 topic、`topicMetadata` 或 `topicDependencies`，须先 Read `rules/f2s-topic-authoring.*` 全文（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`），再落盘。

@@ -62,3 +69,3 @@ 按大纲逐项更新：

- `.Knowledge/index.md`（同步主题路由表的“关联文档（摘要）”列）
- 路由清单（按需）
- 路由清单（按需）；若创建新 topic，须同步 `topicPaths`、必要的 `taskToTopicRules` / matcher 分片；可在证据明确时写 `topicMetadata`，但分类只用于治理、审计和阅读预期，不参与路由命中或执行强制性，不得为了分类创建、重命名或拆分 topic
- `.Knowledge/stock-docs/*.md`（按需补充索源文档）

@@ -112,3 +119,4 @@

3. manifest 中 `topics` / `taskToTopicRules` / `topicDependencies` 是否仍引用有效路径。
4. 是否误改配置根 `rules/skills`（必须为否）。
5. 步骤 2 大纲 + 用户确认未下放子 agent；步骤 3 子落盘前已加载近邻 2–3 主题摘要；manifest / index 由主单点落盘。
4. 若写入 `topicMetadata`：key 是否均存在于 `topicPaths`；`primary` / `tags` / `confidence` 是否合法；是否避免类型前缀命名。
5. 是否误改配置根 `rules/skills`（必须为否）。
6. 步骤 2 大纲 + 用户确认未下放子 agent；步骤 3 子落盘前已加载近邻 2–3 主题摘要；manifest / index 由主单点落盘。
+27
-11
templates/skills/f2s-kb-upgrade/SKILL.md

@@ -14,4 +14,5 @@ ---

- **`flow2spec init` 不写业务知识**：不替代 `f2s-doc-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-ctx-build` 等对 `stock-docs` / `req-docs` / `topics` 正文与业务向路由词条的维护。
- 本技能跑通的是 **包版本下的目录、模板占位、路由结构对齐**；用户若说「把新能力写进知识库」，应引导 **`f2s-kb-sync` / `f2s-doc-add`** 等，而非仅 `f2s-kb-upgrade`。
- **`flow2spec init` 不写业务知识**：不替代 `f2s-kb-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-kb-build` 等对 `stock-docs` / `req-docs` / `topics` 正文与业务向路由词条的维护。
- 本技能跑通的是 **包版本下的目录、模板占位、路由结构对齐**；用户若说「把新能力写进知识库」，应引导 **`f2s-kb-sync` / `f2s-kb-add`** 等，而非仅 `f2s-kb-upgrade`。
- 本技能负责存量 `topicMetadata` 审计：`primary` / `tags` 仅用于治理、审计、盘点和阅读预期，不参与路由命中或执行强制性；执行强制性仍以 `AGENTS.md`、rules、skills 与 topic 正文为准。

@@ -115,8 +116,8 @@ ## 编排（主 / 子 agent）

1. 清理旧主题文件（仅在文件存在时删除）：
> **skill 目录自动对齐**：`flow2spec init` 现已自动删除配置根 `skills/` 中不再存在于 `templates/skills/` 的旧目录（重命名/删除的 skill 如 `f2s-ctx-build`、`f2s-doc-add`、`f2s-rule-capture`、`stock-docs-vs-req-docs` 等），**无需 Agent 手动清理**。
1. 清理旧命名主题文件（仅在文件存在时删除，均为无 `f2s-` 前缀的旧版遗留）：
- `.Knowledge/topics/flow2spec-architecture.md`
- `.Knowledge/topics/implement-tech-design.md`
- `.Knowledge/topics/stock-docs-vs-req-docs.md`
- `templates/knowledge/topics/implement-tech-design.md`
- `templates/knowledge/topics/stock-docs-vs-req-docs.md`
2. 修复引用（仅在文件存在时更新；**`.Knowledge/index.md` 正文不由 init 改写**，见步骤 3b）：

@@ -127,3 +128,3 @@ - `templates/knowledge/index.md`

- `.Knowledge/manifest-routing.json`
3. 引用更新目标：
3. 引用更新目标（确认使用新名）：
- `.Knowledge/topics/f2s-flow2spec-architecture.md`

@@ -133,4 +134,17 @@ - `.Knowledge/topics/f2s-implement-tech-design.md`

> 口径：只清理“旧命名主题文件”，不删除带 `f2s-` 前缀的新主题文件。
> 口径：只清理”旧命名主题文件”，不删除带 `f2s-` 前缀的现行主题文件。
### 步骤 3a：`topicMetadata` 存量审计（必须执行）
1. 读取 `.Knowledge/manifest-routing.json`，以 `topicPaths` 为主题全集。
2. 校验 `topicMetadata`：key 必须存在于 `topicPaths`；`primary` 仅允许 `feature` / `module` / `config` / `policy`；`tags` 若存在须为数组，元素取值同 `primary` 且不得与 `primary` 重复；`confidence` 仅允许 `manual` / `inferred`。
3. 对 `topicPaths` 中缺少 metadata 的主题做分类分析：**必须 Read 对应 `.Knowledge/topics/<id>.md` 正文**，禁止仅凭 topicId 名称推断。证据明确则写入 `inferred`；证据不足时**不写 metadata**，但须在摘要中列出推断方向与依据（如「建议 policy，正文含多处强制约束」），供用户确认后手动补写 `manual`。
4. 分类判断以 `f2s-topic-authoring` 准则第 3 节为准，Agent 基于 topic 正文判断主要性质，写 `primary`；同时覆盖多个性质时其余写 `tags`（可选）。
5. 禁止因为补分类创建、重命名或拆分 topic。
6. **主题粒度审计**（不阻断升级，仅列入摘要）：逐项检查，命中任一信号时在步骤 5 摘要中列为「建议拆分」：
- 对应 stock-doc 超过 **300–500 行**；
- `includeAny` 词数超过 **12 个**；
- topic 正文包含超过 **3 个不相干职责域**的二级标题；
- 该 topic 同时被多种不相干任务类型频繁命中（可从 `taskToTopicRules` 和 matcher 词宽度判断）。
### 步骤 3b：`index.md` 融合与 `template/index.template.md`（必须执行）

@@ -203,2 +217,3 @@

- **index（快照 + 融合）**：`快照已复制` / `index.md 已融合` / `待处理（见备注）`
- **topicMetadata（存量审计）**：`已补齐` / `待用户确认`；列出新增 / 修正 / 删除的 topicId
- **f2s-kb-upgrade SKILL**：`init 后无变化` / `已按新版重跑 N 轮` / `待确认`

@@ -227,5 +242,6 @@ - manifest-routing / matchers 分片：`已与模板对齐` / `已是最新` / `reset 覆盖`

5. 是否已处理旧主题文件清理与 `index/manifest` 引用修复。
6. 是否已执行 **步骤 3b**：**融合** `index.md`（**主题一览**节起至命中与执行前为项目维护区，其余同包版），并核对 `topicPaths`。
7. 是否输出了 manifest 与关键路径校验结果。
8. 若失败，是否给出下一步具体命令建议。
9. 步骤 3b 的 `index.md` 融合由主 agent 完成并落盘，无子 agent 越权写入。
6. 是否已执行 **步骤 3a**：审计 `topicMetadata`，确保无孤儿 key / 非法 primary / 非法 confidence；缺失旧主题已按证据补 `inferred` 或列为待确认。
7. 是否已执行 **步骤 3b**：**融合** `index.md`（**主题一览**节起至命中与执行前为项目维护区，其余同包版），并核对 `topicPaths`。
8. 是否输出了 manifest 与关键路径校验结果。
9. 若失败，是否给出下一步具体命令建议。
10. 步骤 3b 的 `index.md` 融合由主 agent 完成并落盘，无子 agent 越权写入。
-108
templates/skills/f2s-ctx-build/SKILL.md
---
name: f2s-ctx-build
description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
---
> 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`。不再维护 `.Knowledge/manifest-matchers.json`（已废弃聚合文件；`flow2spec init` 会删除遗留副本）。
# 根据文档生成项目上下文（topics/index/路由清单）
## 编排（主 / 子 agent）
- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本 SKILL 不复述。
- **首选分支（小变更 → 主全流程）**：当本次改动 **≤ 2 个新 / 改主题**，**且 ≤ 1 个新 matcher**，**且无跨主题批量引用调整** 时，全流程在主 agent 完成，不拆子。
- **中大变更分支**（`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 做整体验收。
- **不推荐**：单个子 agent 同时改 manifest / index / 多份 topics / matchers；以及「子 A 写、子 B 验」。
- **「一子写、主验」**：仅在交付边界极窄（例如只产出 1 个新 matcher 分片草稿，manifest 引用仍由主写）时可接受。
- **写权硬约束**：`.Knowledge/manifest-routing.json` / `.Knowledge/index.md` **恒由主 agent 落盘**，子 agent 不得触碰。
- 默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。
## 输入
- 接收一个参数：URL 或本地路径。
- 本地路径必须位于 `.Knowledge/stock-docs/`。
- **须为终稿**：推荐文件名含 `_终稿.md`，或已由 **`f2s-doc-final`** 规范化；**禁止**以 `f2s-doc-arch` 产出的 `*_初稿.md` 作为入参直接执行本技能。
- 若入参路径含 **`_初稿`**、或用户刚完成架构初稿尚未执行 `f2s-doc-final`：**停止**，回复须先执行 **`f2s-doc-final <初稿路径>`**，待终稿落盘后再以终稿路径调用本技能。
- 若传入 `.Knowledge/req-docs/`，提示用户先整理为 `stock-docs` 终稿后再执行。
## 生成原则
1. **拆解**：文档较长或包含多块独立能力时，拆分为多个 topic；避免把无关能力塞到同一主题。
2. **分工**：
- `topics/`：规则与流程正文（可执行知识）
- `index.md`：主题索引与语义说明（人读入口）
- `manifest-routing.json` + `taskToTopicRules[].matcherPath` 指向的 `matchers/*.json`：任务路由与关键词词表（机读入口）
## 步骤 1：获取文档内容
- URL：抓取正文；无法访问时提示用户先落地到 `.Knowledge/stock-docs/*.md`。
- 本地路径：读取 Markdown 文档，提炼主题与能力边界。
## 步骤 2：语义分析（必须）
从文档中提炼：
- 主题名与主题意图（可形成 topic id）
- 核心概念与关键流程
- 业务规则与边界条件
- 任务触发词（写入对应 `matchers/<matcherId>.json` 的 `includeAny`）
- 与现有主题的依赖关系（用于 `topicDependencies`）
## 步骤 3：写入 topics
- 目标路径：`.Knowledge/topics/<topic>.md`
- 若已存在同主题：优先增量更新，避免重复主题。
- 若为新主题：新增文件并补充清晰标题、适用场景、规则与流程。
## 步骤 4：更新 index
- 更新 `.Knowledge/index.md` 的主题路由表。
- 保证“同主题单行”。
- 主题路由表需维护“关联文档（摘要）”列：每个主题补充 1-3 条关键文档**可点击 Markdown 链接**（格式：`[标题](相对路径)`，优先 `stock-docs/req-docs`）。
- 若某主题暂无可公开文档，写“无”或“待补充”，禁止留空导致歧义。
- 若新增/删除主题，索引同步调整，避免孤儿路径。
## 步骤 5：更新路由清单（按需）
- 本步骤由主 agent 落盘（写权硬约束），子 agent 不得执行。
- 更新 `manifest-routing.topicPaths`（topicId -> topic 文件路径）
- 更新 `manifest-routing.taskToTopicRules[]`（任务到主题集合 + matcherId）
- 更新 `manifest-routing.topicDependencies`（先读依赖后读主主题）
- 更新 `matchers/<matcherId>.json` 的 `includeAny`（关键词词表；路径须与 `taskToTopicRules[].matcherPath` 一致）
- 校验 `fallbackTopic`、`topicPaths`、`matcherId` 引用有效
- 仅做最小改动，不重写无关字段
## 路径与引用约束
- `sourceDoc` 或文档引用统一指向 `.Knowledge/stock-docs/<文件名>.md`
- 禁止把 `.Knowledge/req-docs/` 作为 topic 的 `sourceDoc`
- 禁止改写配置根 `rules/skills`
## 输出摘要（必须）
- 新增/更新的 topic 文件
- `index` 更新项
- 路由清单更新项（如有）
- 失败或跳过项及原因
## 复杂场景示例
用户输入：`f2s-ctx-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。
- 若新文档与现有 `<能力>` 主题高度重合：原位更新 `topics/<能力>.md`，不要新建 `<能力>-v2.md`。
- 若新文档新增子能力：可新增 `topics/<能力>-<子域>.md`，并在 `manifest-routing.topicDependencies` 中声明依赖关系。
- 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。
## 完成后自检
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 越权写入。
-59
templates/skills/f2s-ctx-rm/SKILL.md
---
name: f2s-ctx-rm
description: 删除某 stock-docs 文档对应的知识主题与索引映射；触发：删除项目上下文、f2s-ctx-rm
---
> 执行口径：仅维护 `.Knowledge`，不改配置根 `rules/skills`。
## 编排（主 / 子 agent）
- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。不在此复述。
- 默认主 agent 全流程执行（单点删除拆子收益低）。
- 拆子阈值：仅当 `subAgent=true` 且**批量删除一次 ≥ 5 主题**时，才拆子执行删除与清引用。
- 主必控：范围确认、`fallbackTopic` 重指。
- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘。
- 验证：默认落盘侧自验；本 SKILL 不绑定交叉校验。
# 删除文档对应的项目上下文
## 输入
- 一个参数：`.Knowledge/stock-docs/<文件名>.md` 路径，或可匹配文件名片段。
## 执行步骤
1. 读取 `.Knowledge/index.md`，匹配目标文档相关主题。
2. 删除对应 `.Knowledge/topics/<topic>.md` 文件。
3. 从 `.Knowledge/index.md` 移除匹配项并写回。
4. 更新路由清单：
- `.Knowledge/manifest-routing.json`：移除失效 `topicPaths`、`taskToTopicRules`、`topicDependencies` 引用
- 对应 `matchers/<matcherId>.json`：移除失效规则或 `includeAny` 词条（与已删 `task`/`matcherId` 对齐）
- 若删除了 `fallbackTopic`，必须指定新的兜底主题
## 输出摘要（必须）
- 已删除的 topic 文件列表
- `.Knowledge/index.md` 删除的条目
- 路由清单调整的字段
- 未执行项（若有）
## 复杂场景示例
用户输入文件名片段「回调」，匹配到 2 个主题文档。
- 先列出两个候选并要求用户确认删除范围，避免误删。
- 删除后同步清理路由清单失效引用；若删到了 `fallbackTopic`，必须先指定新的兜底主题再落盘。
- 最终摘要中写清：删除了哪些 topic、保留了哪些 topic、为什么。
## 约束
- 匹配多义时先询问用户确认。
- 仅删除命中主题，不影响其它主题。
- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束）；范围确认与 `fallbackTopic` 重指不可下放给子 agent。
## 完成后自检
1. 被删 topic 是否仍被 `manifest` 引用（必须为否）。
2. `index` 是否仍存在失效主题路径（必须为否）。
3. `fallbackTopic` 是否仍有效。
4. 未在低于拆子阈值（< 5 主题）时强行拆子；manifest / index 由主单点落盘。
-127
templates/skills/f2s-doc-add/SKILL.md
---
name: f2s-doc-add
description: 工作中把已落地能力解析进知识库（多文件聚合）：初稿→终稿→topics/index/manifest；触发：f2s-doc-add、已有能力进知识库、多文件生成上下文
---
> 执行口径：本技能只维护 `.Knowledge`，不改配置根 `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 落盘。
- 落盘侧自验。
# f2s-doc-add：多文件聚合 -> 初稿 -> 终稿 -> 知识路由同步
## 使用时机
- 某能力已在代码中落地，但信息分散在多个文件，需沉淀为可检索知识。
- 与 `f2s-doc-arch` 区分：`doc-arch` 产出架构初稿；`doc-add` 产出“已落地能力”知识沉淀链路。
## 输入
| 参数 | 必填 | 说明 |
| --- | --- | --- |
| 文件路径列表 | 是 | 一个或多个路径（空格/换行/`@`）；支持源码、配置、文档 |
| 方案名 | 否 | 用于生成 `<方案名>_初稿.md`、`<方案名>_终稿.md` |
| 初稿/终稿路径 | 否 | 默认放 `.Knowledge/stock-docs/` |
无有效路径时中止并要求用户补充。
## 步骤 0：重合判定（重要）
执行前先对照：
- `.Knowledge/index.md`
- `.Knowledge/topics/*.md`
- `.Knowledge/stock-docs/*.md`
若已有同主题沉淀，优先原位更新，避免重复主题和重复索引行。
## 步骤 0.5：多模块检测（输入路径 ≥ 2 时必须执行）
1. **目录聚合**：按路径中的功能层目录（如 `src/<模块名>/`、顶层目录名）对文件分组。
2. **判定规则**（满足任一即判定为「多模块」）：
- 文件分属 ≥ 2 个不同顶层功能目录（如 `auth/`、`payment/`）；
- 用户在输入中明确提及「多个功能 / 不同模块 / 分别处理」等；
- 文件名前缀明显不同且无共同父目录。
3. **单模块（未触发判定）**：不中断，继续步骤 1，按现有单输出逻辑生成 `<方案名>_初稿.md`。
4. **多模块（触发判定）**：**暂停**，向用户展示分组结果，并询问：
- **方案 A（推荐）**：按模块分别生成知识文件 → 每组独立走步骤 1→2→3→4，各自产出 `<模块名>_初稿.md` / `<模块名>_终稿.md`；
- **方案 B（合并）**：忽略模块边界，合并生成一份 `<方案名>_初稿.md`（原有行为）。
- **禁止**在未获用户明确选择前默认走方案 B 继续执行。
## 步骤 1：适度深度解析
- 小文件通读；
- 大文件优先结构与关键片段（导出、接口、配置、流程）；
- 不确定内容显式标注”待确认”，禁止编造。
- 若任一拆子阈值满足（输入路径 ≥ 5 / 单源 > ~3000 行 / 多路径总量 > ~10000 行）且 `subAgent=true`，按 B 模式（默认）或 C 模式（达成切换判据时）拆子并行只读扫描；否则主全流程。**启用拆子时，子 agent 必须按主手写 inventory 与扫描契约执行，不得自行增删源路径。**
## 步骤 2：生成初稿
- 默认输出：`.Knowledge/stock-docs/<方案名>_初稿.md`
- 初稿建议结构：
- 概述
- 来源清单（含不可读文件）
- 分模块归纳
- 交叉关系
- 待确认项
## 步骤 3：生成终稿
- 参考 `.Knowledge/template/终稿模版.md`
- 输出：`.Knowledge/stock-docs/<方案名>_终稿.md`
- **必须填写 `## 来源文件` 小节**，列出步骤 1 实际读取的原始源文件路径
- 若用户要求”先审初稿”，则停在初稿并等待确认
## 步骤 4：同步知识路由
基于终稿调用 `f2s-ctx-build` 口径，更新：
- `.Knowledge/topics/`
- `.Knowledge/index.md`
- 路由清单（必要时）
## 输出摘要（必须）
1. 初稿/终稿路径
2. 更新的 topic/index/路由清单 路径
3. 未完成项与原因（如路径无效、信息不足）
## 复杂场景示例
用户输入 6 个文件（代码、配置、旧文档混合），其中 2 个路径不可读。
- 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
- 若发现已有 `.Knowledge/stock-docs/<能力名>_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
- 用户要求”先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。
用户输入 3 个文件：`src/auth/login.ts`、`src/payment/checkout.ts`、`src/notification/email.ts`。
- 步骤 0.5 检测到文件分属 `auth/`、`payment/`、`notification/` 三个不同顶层功能目录，判定为「多模块」。
- 向用户展示分组：`auth` 组 1 个文件、`payment` 组 1 个文件、`notification` 组 1 个文件；询问方案 A（分别生成）或方案 B（合并）。
- 用户选方案 A：按 `auth`、`payment`、`notification` 三组各走步骤 1→2→3→4，分别产出 `auth_初稿.md`、`payment_初稿.md`、`notification_初稿.md`。
- **禁止**在用户选择前直接合并三个模块生成 `综合_初稿.md`。
## 约束
- 终稿 `sourceDoc` 仅指向 `.Knowledge/stock-docs/*`
- 不改配置根 `rules/skills`
- 同主题优先更新，不平行新建重复知识
- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束），子 agent 不得触碰
## 完成后自检
1. 初稿/终稿路径是否落在 `.Knowledge/stock-docs/`。
2. 同主题是否避免重复新建。
3. topic/index/manifest 是否与终稿语义一致。
4. 输入路径 ≥ 2 时，步骤 0.5 是否执行了多模块检测；若判定为多模块，是否向用户展示了分组并等待了明确选择，未默认合并输出。
-20
templates/skills/f2s-karpathy-guidelines/SKILL.md
---
name: f2s-karpathy-guidelines
description: Flow2Spec 内置的 Karpathy 式编码纪律：澄清假设、极简实现、手术式修改、可验证目标。默认由同名 topic 规则 alwaysApply 随 init 落盘；显式调用本技能时重申四条。
license: MIT
---
# f2s-karpathy-guidelines
`flow2spec init` 将 npm 包内 **`templates/rules/f2s-karpathy-guidelines.mdc`** 去 frontmatter 后写入 **`./.codex/topics/f2s-karpathy-guidelines.md`**（相对仓库根，**`alwaysApply`** 语义以源 `.mdc` 的 frontmatter 为准）。
**显式使用本技能时**：在回复中简要重申并遵守以下四条（与 **`./.codex/topics/f2s-karpathy-guidelines.md`** 全文一致；冲突时以 **f2s 流程条令** 为准）。
1. **先想清楚再写代码**：假设说清；多解并列；说不清就停、先问。
2. **简单优先**：最少代码解决问题；无臆测功能/抽象/配置。
3. **手术式修改**：只动任务相关行；不顺带「优化」无关代码；只删自己改动产生的孤儿。
4. **目标驱动**：先定义可验证成功标准（测试、检查项），再迭代到满足。
cursor/claude: 完整条文以磁盘上 **`rules/f2s-karpathy-guidelines.mdc`**为准。
或 Codex 侧 **`.codex/topics/f2s-karpathy-guidelines.md`**为准。
-35
templates/skills/stock-docs-vs-req-docs/SKILL.md
---
name: stock-docs-vs-req-docs
description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-docs、req-docs、f2s-ctx-build、f2s-doc-arch、f2s-doc-add、已落地能力、技术方案放哪、PDF 终稿
---
## 编排（主 / 子 agent）
- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。
- 本技能为**说明型**，**不拆子**（无拆子收益），主 agent 短答即可。
- 落盘侧自验（本技能通常不产生落盘）。
# stock-docs 与 req-docs（技能）
## 何时使用
- 用户问「文档放哪」「PDF 转完放哪」「生成 Rules 用哪个目录」「技术方案目录」等。
- 实现或命令执行时需要选择 `.Knowledge/stock-docs/` 还是 `.Knowledge/req-docs/`。
- 区分 **f2s-doc-arch**（架构说明**初稿**）与 **f2s-doc-add**（**工作中**把**已落地能力**从多文件解析进上下文）：二者产物都落在 **stock-docs/**，与 **req-docs** 无关；分工见 **`skills/f2s-doc-arch/SKILL.md`**、**`skills/f2s-doc-add/SKILL.md`**。
## 核心对照
| 目录 | 位置 | 用途 |
|------|------|------|
| **stock-docs** | `.Knowledge/stock-docs/` | **存量上下文源** -> `f2s-ctx-build` 入参；`f2s-doc-final` 初稿/终稿；`f2s-doc-arch` 架构初稿；`f2s-doc-add` 聚合读源后的初稿与终稿 |
| **req-docs** | `.Knowledge/req-docs/` | 需求与技术方案 -> 按 `implement-tech-design` 写代码、`f2s-doc-pdf` 输出 |
## 常见错误
- 把 **仅用于实现代码** 的 `.Knowledge/req-docs/xxx.md` 当作 `f2s-ctx-build` 入参（应先把符合终稿范式的内容放到 `.Knowledge/stock-docs/` 再生成上下文）。
- 在 Rule 内链到 **`req-docs/`**（应链到 **stock-docs** 中的源文档）。
- 把 **f2s-doc-add** / **f2s-doc-arch** 产出的初稿、终稿误存到 **req-docs**（应始终在 **stock-docs/**）。
## 详细约定
以本技能对照表与配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**、**f2s-doc-arch**）为准；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。
templates/rules/f2s-flow2spec-unified-entry.mdc

Sorry, the diff of this file is not supported yet

templates/rules/f2s-implement-tech-design.mdc

Sorry, the diff of this file is not supported yet

templates/rules/f2s-karpathy-guidelines.mdc

Sorry, the diff of this file is not supported yet

templates/rules/f2s-stock-docs-vs-req-docs.mdc

Sorry, the diff of this file is not supported yet