@double-codeing/flow2spec 3.0.14 → 3.0.16

package/docs/{README- → }/347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md

@@ -1,9 +1,14 @@
 # 目录与路径约定
 
+[English](./en/directory-conventions.md)
+
 ## 核心边界
 
-- `.Knowledge/`：只放业务知识文档与索引
-- `配置根`（`.cursor/.claude/.codex`）：放规则与技能入口
+- `.Knowledge/`：**知识环**——业务知识文档与机读路由（见 [体系与原理 §2 多层记忆](./体系与原理.md)）
+- `.task/`：**任务环**——变更追踪与跨会话续作（不在 `.Knowledge/` 内）
+- `配置根`（`.cursor/.claude/.codex`）：**规则环 + 技能环**入口
+
+Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 
 ---
 
@@ -11,13 +16,13 @@
 
 | 路径 | 职责 |
 | --- | --- |
-| `.Knowledge/stock-docs/` | 架构、终稿、沉淀文档 |
-| `.Knowledge/req-docs/` | 需求澄清、技术方案 |
-| `.Knowledge/topics/` | 主题路由文档（用于规则与流程执行） |
+| `.Knowledge/stock-docs/` | **L3** 架构、终稿、沉淀长文档 |
+| `.Knowledge/req-docs/` | **L3** 需求澄清、技术方案长文档 |
+| `.Knowledge/topics/` | **L2** 主题摘要（硬约束、边界、路由指针） |
 | `.Knowledge/template/` | 终稿/技术方案模板 |
 | `.Knowledge/index.md` | 人类可读索引 |
-| `.Knowledge/manifest-routing.json` | 机器可读路由骨架（task/topic/dependencies） |
-| `.Knowledge/matchers/*.json` | 关键词分片（`id/includeAny`），由 `manifest-routing.taskToTopicRules[].matcherPath` 直链指向 |
+| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`） |
+| `.Knowledge/matchers/*.json` | **L1** 关键词分片（`id/includeAny`），由 `matcherPath` 直链；**match** 只读一片 |
 | `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 |
 | `.task/` | 变更追踪任务清单目录（`active/` 进行中，`completed/` 已归档且目录名为 **`<YYYYMMDD>-<task-name>`**（日期在前），`todo.json` 活跃任务索引）；仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建 |
 | `配置根/rules/` | 规则文件（Cursor `.mdc`，Claude `.md`） |
@@ -26,7 +31,7 @@
 | `.codex/AGENTS.md` | Codex 统一入口与加载说明 |
 | `flow2spec.config.json` | 项目根配置，控制 `subAgent`、`switchAgentVerification`、`changeTracking`（嵌套对象，含 `feat` / `fix` / `implement` 三个子项） |
 
-> 多端提示与路径表见 [Flow2Spec使用说明 § 一](./Flow2Spec使用说明.md)（详表单点维护）；**权威仍为 Read(`flow2spec.config.json`)**。
+> 多端提示与路径表见 [使用说明 § 一](./使用说明.md)（详表单点维护）；**权威仍为 Read(`flow2spec.config.json`)**。
 
 ---
 
@@ -41,7 +46,7 @@
 
 ## 相关文档
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-命令说明](./README-命令说明.md)
-- [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [使用说明](./使用说明.md)
+- [命令说明](./命令说明.md)
+- [体系与原理](./体系与原理.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)

package/docs/{Flow2Spec- → }/350/256/276/350/256/241/350/257/264/346/230/216.md

@@ -1,5 +1,7 @@
 # Flow2Spec 设计说明
 
+[English](./en/design-principles.md)
+
 ## 解决的问题
 
 ```
@@ -19,6 +21,67 @@
 
 ## 核心设计
 
+### 0. Memory Coding 与仓内四环
+
+**Memory Coding**：把必须长期记住的上下文**编码进可提交仓库**（可 PR、可 review），而不是押在模型 Memory 或聊天里。
+
+仓内 **四环**（规则环与技能环分列，勿合并为「规则+技能」）：
+
+| 环 | 落点 | 职责 |
+| --- | --- | --- |
+| 知识环 | `.Knowledge/` | 路由 + 主题 + 存量/需求文档 |
+| 任务环 | `.task/` | 跨会话续作、用户代办 |
+| 规则环 | 各工具 `rules` / `AGENTS.md` | 怎么读、怎么做（缺口闸门、路由顺序） |
+| 技能环 | `f2s-*` / `skills/` | 维护知识、触发 feat/fix/sync 等 |
+
+```mermaid
+graph TB
+    subgraph MC["Memory Coding · 仓内四环"]
+        KR["知识环 .Knowledge/"]
+        TR["任务环 .task/"]
+        RR["规则环 rules"]
+        SR["技能环 f2s-*"]
+    end
+    SR -->|"维护 ↑"| KR
+    RR -->|"读与做 ↓"| KR
+    TR -.->|"并列，不在 .Knowledge 内"| KR
+```
+
+Flow2Spec 提供的是 **Memory Coding 的落盘与维护闭环**，不是「又一个 RAG 知识库」。
+
+### 0.1 知识环：多层记忆结构
+
+知识环内部是 **横读 + 纵链** 的多层结构（与下文「渐进式路由」「topicDependencies」对应）：
+
+```mermaid
+graph TB
+    subgraph H["横读 · 渐进式收窄"]
+        L0["L0 manifest-routing"]
+        L1["L1 matchers 分片"]
+        L2["L2 topics 摘要"]
+        L3["L3 stock-docs / req-docs"]
+        L0 --> L1 --> L2 --> L3
+    end
+    subgraph V["纵链 · topicDependencies"]
+        T1["通用约定"]
+        T2["子域边界"]
+        T3["端上白名单"]
+        T4["本域细则"]
+        T1 --> T2 --> T3 --> T4
+    end
+    L2 --- V
+```
+
+| 层级 | 路径 | 作用 |
+| --- | --- | --- |
+| L0 | `manifest-routing.json` | 机读路由、依赖声明 |
+| L1 | `matchers/*.json` | 关键词命中，**match** 只读一片 |
+| L2 | `topics/*.md` | 硬约束摘要；**expand** 拉依赖 |
+| L3 | `stock-docs/`、`req-docs/` | 长文档，按需下钻 |
+| 纵链 | `topicDependencies` | 主题级前置，所有任务共享 |
+
+读取流水线：`match → expand → verify → act`（详见 [体系与原理 §4](./体系与原理.md)）。
+
 ### 1. 知识与规则分离
 
 ```mermaid
@@ -78,7 +141,7 @@ graph LR
     CMT -->|"未入库则提醒\n-> kb-sync/kb-feat"| K
 
     D1["架构文档"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
-    D2["PDF 方案"] -->|f2s-doc-pdf| FIN
+    D2["PDF/初稿"] -->|f2s-doc-final| FIN
     FIN --> CTX["f2s-ctx-build"] --> K
 
     OLD["存量代码/文档"] -->|f2s-doc-add| K
@@ -446,7 +509,7 @@ f2s-kb-sync 三种输入方式
 | **Codex `AGENTS.md` + `renderProjectConfigBlock`** | 顶部 **Read** 硬约束 + **init 快照表**（与磁盘不一致时以 Read 为准）。 |
 | **知识库 `config-precheck` 主题** | 路由命中时只提供**摘要**与链向 Codex 长文，**不**替代 Read JSON。 |
 
-**权威仍为**项目根 JSON 的 **Read** 结果；各层为提示而非第二份真值源。操作侧完整表格与路径见 **[Flow2Spec使用说明 § 一、`f2s-*` 与 `flow2spec.config.json`](./Flow2Spec使用说明.md)**；口述节奏见 **[Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)**。
+**权威仍为**项目根 JSON 的 **Read** 结果；各层为提示而非第二份真值源。操作侧完整表格与路径见 **[使用说明 § 一、`f2s-*` 与 `flow2spec.config.json`](./使用说明.md)**；口述节奏见 **[Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)**。
 
 #### 6. 技能不复述统一入口规则，只引用
 
@@ -573,9 +636,9 @@ flow2spec.config.json
 
 ## 相关文档
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-命令说明](./README-命令说明.md)
-- [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [使用说明](./使用说明.md)
+- [命令说明](./命令说明.md)
+- [体系与原理](./体系与原理.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)
 - [Flow2Spec-演讲稿](./Flow2Spec-演讲稿.md)
 

package/package.json

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

package/templates/knowledge/template//345/220/216/347/253/257/346/212/200/346/234/257/346/250/241/347/211/210.md

@@ -30,7 +30,7 @@
 ## 4. 外部对接和内部调用
 
 - 二级标题：`## 外部对接和内部调用`
-- 简要列出：依赖的外部 HTTP/RPC/券台/订单等；本服务内部会调用的模块或方法（不必展开到每个参数）。
+- 简要列出：依赖的外部 HTTP/RPC/消息队列等；本服务内部会调用的模块或方法（不必展开到每个参数）。
 
 ---
 

package/templates/knowledge/template//347/273/210/347/250/277/346/250/241/347/211/210.md

@@ -1,5 +1,4 @@
-> **主口径（统一知识库）**：终稿模板与终稿文档统一维护在 `/.Knowledge/template/` 与 `/.Knowledge/stock-docs/`。
-> 本模板唯一来源为 `templates/knowledge/template/终稿模版.md`。
+> **主口径（统一知识库）**：终稿模板与终稿文档统一维护在 `.Knowledge/template/` 与 `.Knowledge/stock-docs/`。
 
 # 终稿概述模版
 

package/templates/knowledge/template//351/241/271/347/233/256/351/207/214/347/250/213/347/242/221/346/250/241/347/211/210.md

@@ -1,4 +1,4 @@
-> **主口径**：模板在 `templates/knowledge/template/项目里程碑模版.md`；生成物在 `.Knowledge/stock-docs/<范围名>里程碑.md`。  
+> **主口径**：模板在 `.Knowledge/template/项目里程碑模版.md`（由 `flow2spec init` 落地）；生成物在 `.Knowledge/stock-docs/<范围名>里程碑.md`。  
 > **执行 `f2s-doc-milestone`**：结构以本模版为准；内容仅来自 **req-docs、git log、.task** 与知识库主题，禁止臆造。  
 > **阶段**：Mx **仅**功能/能力变更；**不得**单独成阶段的联调、测试、验收或纯环境运维；工程性改动并入对应功能阶段。
 

package/templates/knowledge/topics/f2s-req-plan.md

@@ -2,7 +2,7 @@
 
 > 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。  
 > **`.task/` 真值源**：配置根 **`rules/f2s-task.*`**（Codex：`.codex/topics/f2s-task.md`）。  
-> 设计背景：[Flow2Spec 任务清单与变更追踪](../stock-docs/<任务清单说明>.md)（可选）。
+> 设计背景（可选）：[任务清单与变更追踪](../stock-docs/<任务清单说明>.md)。
 
 ## 依赖
 

package/templates/knowledge/topics/f2s-task.md

@@ -1,7 +1,7 @@
 # f2s-task（路由摘要）
 
 > 长文见配置根 **`rules/f2s-task.*`**。  
-> 体系化设计说明（两种模式、目录、`todo.json`）：[Flow2Spec 任务清单与变更追踪](../stock-docs/Flow2Spec-任务清单与变更追踪.md)。
+> 体系化设计说明（可选）：在 `stock-docs/` 自建任务清单说明后，于本主题或 `index.md` 中链接，例如 `../stock-docs/<任务清单说明>.md`。
 
 ## 作用
 

package/templates/rules/f2s-flow2spec-unified-entry.mdc

@@ -81,6 +81,7 @@ alwaysApply: true
 
 ## 禁止项
 
+- **`templates/` 可下发约束**（经 `init` 会克隆到任意业务仓）：技能/规则/知识模板正文中的示例须**中性**——勿写特定业务域名称、单一组织 npm 包名、仅 Flow2Spec 产品仓存在的 `docs/` 路径；用 `<能力>`、`src/<模块>/` 等占位。
 - 使用 `git worktree` 或隔离目录跑子任务后，**禁止**在未 `git worktree remove` / 未交接删除命令的情况下结束会话（见上文「Git worktree 与子任务工作目录卫生」）。
 - 未查看 `.Knowledge/manifest-routing.json` 前，禁止进行全仓无范围扫描；`.Knowledge/index.md` 在需确认主题语义时再读，禁止与 manifest 交替重复读取以代替决策。
 - 禁止把 `stock-docs` 作为直接编码输入文档；按方案实现应使用 `req-docs`。

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

@@ -13,4 +13,4 @@ alwaysApply: false
 - **`.Knowledge/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；`f2s-ctx-build`、`f2s-doc-final`、`f2s-doc-arch`、`f2s-doc-add` 的文档落盘优先在此。`sourceDoc` 统一写 `.Knowledge/stock-docs/<文件名>.md`。
 - **`.Knowledge/req-docs/`**：需求澄清、技术方案（前后端/数据/任务等）、`f2s-doc-pdf` 输出的「按方案实现」MD；`implement-tech-design` 的触发范围为 `.Knowledge/req-docs/**/*.md`。
 
-完整约定与链接表见仓库 **`docs/README-目录与路径约定.md`**（包内说明；用户项目无此目录时以 init 写入的 **skills** 与 **rules** 为准）。
+完整约定见本规则与 **`skills/stock-docs-vs-req-docs/SKILL.md`**；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。

package/templates/rules/f2s-task.mdc

@@ -138,12 +138,12 @@ alwaysApply: true
 # <任务名> 上下文
 
 ## 涉及文件
-- `src/payment/callback.js`
-- `src/payment/retry.js`
+- `src/<模块>/callback.js`
+- `src/<模块>/retry.js`
 
 ## 相关资料
-- `.Knowledge/req-docs/payment-spec.md`
-- `.Knowledge/stock-docs/payment-arch.md`
+- `.Knowledge/req-docs/<能力>-spec.md`
+- `.Knowledge/stock-docs/<能力>-arch.md`
 
 ## 用户代办清单
 - 见同目录 `user-todos.md`（须用户执行的项统一写在该文件，勿仅在对话中罗列）
@@ -175,7 +175,7 @@ alwaysApply: true
 
 ## 2026-05-09
 
-- [ ] 在预发 MySQL 执行：`.Knowledge/req-docs/xxx.sql`（先备份）
+- [ ] 在目标环境执行：`.Knowledge/req-docs/xxx.sql`（先备份）
 - [ ] 在配置中心打开功能开关 `feature.foo.enabled`
 
 ## 2026-05-10

package/templates/skills/f2s-ctx-build/SKILL.md

@@ -25,6 +25,8 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 
 - 接收一个参数：URL 或本地路径。
 - 本地路径必须位于 `.Knowledge/stock-docs/`。
+- **须为终稿**：推荐文件名含 `_终稿.md`，或已由 **`f2s-doc-final`** 规范化；**禁止**以 `f2s-doc-arch` 产出的 `*_初稿.md` 作为入参直接执行本技能。
+- 若入参路径含 **`_初稿`**、或用户刚完成架构初稿尚未执行 `f2s-doc-final`：**停止**，回复须先执行 **`f2s-doc-final <初稿路径>`**，待终稿落盘后再以终稿路径调用本技能。
 - 若传入 `.Knowledge/req-docs/`，提示用户先整理为 `stock-docs` 终稿后再执行。
 
 ## 生成原则
@@ -89,10 +91,10 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 
 ## 复杂场景示例
 
-用户输入：`f2s-ctx-build .Knowledge/stock-docs/支付回调改造_终稿.md`，且现有 `topics/payment.md` 已存在。
+用户输入：`f2s-ctx-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。
 
-- 若新文档与现有 `payment` 主题高度重合：原位更新 `topics/payment.md`，不要新建 `payment-v2.md`。
-- 若新文档新增“重试补偿”子能力：可新增 `topics/payment-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `payment-retry -> payment`。
+- 若新文档与现有 `<能力>` 主题高度重合：原位更新 `topics/<能力>.md`，不要新建 `<能力>-v2.md`。
+- 若新文档新增子能力：可新增 `topics/<能力>-<子域>.md`，并在 `manifest-routing.topicDependencies` 中声明依赖关系。
 - 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。
 
 ## 完成后自检

package/templates/skills/f2s-ctx-rm/SKILL.md

@@ -39,7 +39,7 @@ description: 删除某 stock-docs 文档对应的知识主题与索引映射；
 
 ## 复杂场景示例
 
-用户输入文件名片段“支付”，匹配到 2 个主题文档。
+用户输入文件名片段「回调」，匹配到 2 个主题文档。
 
 - 先列出两个候选并要求用户确认删除范围，避免误删。
 - 删除后同步清理路由清单失效引用；若删到了 `fallbackTopic`，必须先指定新的兜底主题再落盘。

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

@@ -88,7 +88,7 @@ description: 工作中把已落地能力解析进知识库（多文件聚合）
 用户输入 6 个文件（代码、配置、旧文档混合），其中 2 个路径不可读。
 
 - 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
-- 若发现已有 `.Knowledge/stock-docs/支付能力_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
+- 若发现已有 `.Knowledge/stock-docs/<能力名>_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
 - 用户要求“先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。
 
 ## 约束

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

@@ -25,7 +25,7 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 ## 入参（均可选）
 
 | 参数           | 说明                                                                                                                                                              |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| -------------- | -------------------------- |
 | **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `.Knowledge/stock-docs/xxx.md`、`.Knowledge/req-docs/README.md`、`README.md`）。不传则进入「无输入」流程。 |
 | **第二个参数** | 可选。输出文件路径；若不传，默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。 |
 
@@ -68,7 +68,20 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 ## 引导与迭代
 
 - 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。
-- 生成初稿后，可提示用户：可根据需要修改 `.Knowledge/stock-docs/xxx架构说明_初稿.md`，若需转为《终稿模版》规范格式，可再按 **f2s-doc-final** 技能，以该路径为入参得到终稿，再按 **f2s-ctx-build** 同步知识路由主题与索引。
+
+## 完成后的下一步（硬约束）
+
+本技能**只产出初稿**；结束时须按下列顺序引导，**禁止**让用户跳过终稿直接 `f2s-ctx-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`。
+
+**完成回复模板**（须同时包含 `f2s-doc-final` 与 `f2s-ctx-build`，且 ctx-build 在终稿之后）：
+
+> 已生成架构说明初稿：`<初稿路径>`。请先审阅修改；下一步请执行 **`f2s-doc-final <初稿路径>`** 转为终稿，再执行 **`f2s-ctx-build <终稿路径>`** 同步知识路由主题与索引。
 
 ---
 
@@ -84,4 +97,4 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
 
 - **不强制格式**：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。
 - **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
-- 完成后用一句话总结：已生成架构说明初稿的路径，并视情况提示可补充的内容或下一步（如 f2s-doc-final、f2s-ctx-build）。
+- 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-ctx-build`**；不得仅推荐 build。

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

@@ -70,7 +70,7 @@ description: 据 req-docs、git log、.task 与知识库主题语义生成里程
 | 用户意图 | 示例 | 落盘文件名 |
 | --- | --- | --- |
 | 整个项目（默认） | 不传 / `整个项目` / `全项目` | `项目里程碑.md` |
-| 某一需求或能力 | `支付回调改造` / `登录模块` | `<简述>里程碑.md` |
+| 某一需求或能力 | `回调改造` / `登录模块` | `<简述>里程碑.md` |
 
 **文件名规则**：后缀 `里程碑.md`；整个项目 → 前缀 `项目`；单一需求 → 语义或 req 标题简述（≤ 20 字）。
 

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

@@ -46,7 +46,7 @@ git diff HEAD
 
 **存在时执行覆盖检查：**
 
-1. 从 `git diff HEAD` 及 untracked 文件路径推断本次变更涉及的**功能模块**（如：支付、订单、用户认证等）。
+1. 从 `git diff HEAD` 及 untracked 文件路径推断本次变更涉及的**功能模块**（以仓库内目录/包名为准，勿臆测未出现的业务名）。
 2. 读取 `.Knowledge/topics/` 目录列表与 `.Knowledge/stock-docs/` 目录列表。
 3. 对比步骤 1 推断出的功能模块，判断对应文档是否已在知识库中登记。
 4. 得出结论：**已覆盖 / 部分覆盖 / 未覆盖**。

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

@@ -59,7 +59,7 @@ description: 根据用户指出的实现或规则错误修正代码，并默认
 
 ## 复杂场景示例
 
-用户指出"订单回调幂等实现错误"，但未给明确文件范围。
+用户指出「某回调接口幂等实现错误」，但未给明确文件范围。
 
 - 先按最小可行范围修复已定位的回调处理链路，并在摘要中说明"可继续扩展全仓同类修复"。
 - 同步更新 `topics` 中幂等规则段落，避免后续再次生成错误实现。

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

@@ -88,7 +88,7 @@ description: 可显式给出能力或零输入推断；先输出知识库更新
 
 用户仅说“/f2s-kb-sync 同步一下”，未给能力清单。
 
-- 步骤 1 先做最小推断（例如支付、订单两个高频能力），并给出推断依据。
+- 步骤 1 先做最小推断（例如从 `git diff` / 目录名归纳 1～2 个能力域），并给出推断依据。
 - 步骤 2 必须输出大纲并等待“确认”；未确认前禁止写入任何 `.Knowledge` 文件。
 - 用户确认后只执行大纲内条目；若用户中途缩小范围，未执行项写入收尾摘要。
 

package/templates/skills/stock-docs-vs-req-docs/SKILL.md

@@ -32,4 +32,4 @@ description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-doc
 
 ## 详细约定
 
-见 Flow2Spec 包内 **`docs/README-目录与路径约定.md`**；技能顺序与 **f2s-doc-arch** / **f2s-doc-add** 见 **`docs/README-命令说明.md`**。具体步骤以配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**）为准。
+以本技能对照表与配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**、**f2s-doc-arch**）为准；`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 为路由摘要。

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

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