@double-codeing/flow2spec 3.0.13 → 3.0.15

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,15 @@
 
 | 路径 | 职责 |
 | --- | --- |
-| `.Knowledge/stock-docs/` | 架构、终稿、沉淀文档 |
-| `.Knowledge/req-docs/` | 需求澄清、技术方案 |
-| `.Knowledge/topics/` | 主题路由文档（用于规则与流程执行） |
+| `docs/` | 产品说明（**中文**）：使用说明、命令说明、设计说明等 |
+| `docs/en/` | 产品说明（**英文**）：与上表一一对应的 6 篇文档，见 [en/README.md](./en/README.md) |
+| `.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 +33,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 +48,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
@@ -61,29 +124,36 @@ graph LR
 
 ### 3. 技能维护闭环
 
+<p><img src="./images/flow-1.png" alt="技能维护闭环" style="max-width:100%;" /></p>
+
+<details>
+<summary>Mermaid 源码</summary>
+
 ```mermaid
 graph LR
     K[".Knowledge/"] --> AI["下次会话\n的 AI"]
-    AI --> C["代码\n变更"]
+    AI --> C["功能迭代"]
 
     C -->|"修复 Bug"| FIX["f2s-kb-fix"] --> K
     C -->|"新增能力"| FEAT["f2s-kb-feat"] --> K
     C -->|"会话结束"| SYNC["f2s-kb-sync"] --> K
     C -->|"提交代码"| CMT["f2s-git-commit\n收口检查"]
-    CMT -->|"未入库则提醒\n→ kb-sync/kb-feat"| K
+    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
 
     NR["新需求"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
-    BE --> IMPL["implement-tech-design"] -->|f2s-kb-feat| K
+    BE --> IMPL["实现xxx技术方案"] -->|自动触发implement-tech-design规则| K
 
     GIT["Git 合并后"] -->|f2s-kb-merge| K
 ```
 
+</details>
+
 七条入口  ·  `f2s-git-commit` 是提交时的知识纪律收口  ·  `.Knowledge/` 是唯一汇聚点  ·  知识驱动 AI，AI 驱动下轮开发
 
 
@@ -439,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. 技能不复述统一入口规则，只引用
 
@@ -566,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.13",
+  "version": "3.0.15",
   "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

@@ -0,0 +1,29 @@
+> **主口径**：模板在 `.Knowledge/template/项目里程碑模版.md`（由 `flow2spec init` 落地）；生成物在 `.Knowledge/stock-docs/<范围名>里程碑.md`。  
+> **执行 `f2s-doc-milestone`**：结构以本模版为准；内容仅来自 **req-docs、git log、.task** 与知识库主题，禁止臆造。  
+> **阶段**：Mx **仅**功能/能力变更；**不得**单独成阶段的联调、测试、验收或纯环境运维；工程性改动并入对应功能阶段。
+
+# （范围名）里程碑
+
+> **范围**：（用户语义说明；未指定时写「整个项目」）  
+> **生成时间**：`YYYY-MM-DD`  
+> **索源**：req-docs · git 命令/tag · `.task` 路径 · 知识库主题（`manifest-routing` / `index.md` 主题一览及本轮所读 `topics/*.md`）
+
+## 总览
+
+| 阶段 | 时间 | 一句话 |
+| --- | --- | --- |
+| M1 （功能变更摘要） | YYYY-MM | （可验证的功能交付，须可被索源支撑；非联调/测试/验收） |
+| M2 … | … | … |
+
+## M1 · （阶段标题）
+
+- **交付**：（列表，可验证）
+- **依据**：（可选）req `…` · commit `hash` · task `…`
+
+## M2 · …
+
+（结构同 M1；总览表中每一行 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

@@ -89,10 +89,10 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
 
 ## 复杂场景示例
 
-用户输入：`f2s-ctx-build .Knowledge/stock-docs/支付回调改造_终稿.md`，且现有 `topics/payment.md` 已存在。
+用户输入：`f2s-ctx-build .Knowledge/stock-docs/回调改造_终稿.md`，且现有 `topics/callback.md` 已存在。
 
-- 若新文档与现有 `payment` 主题高度重合：原位更新 `topics/payment.md`，不要新建 `payment-v2.md`。
-- 若新文档新增“重试补偿”子能力：可新增 `topics/payment-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `payment-retry -> payment`。
+- 若新文档与现有 `callback` 主题高度重合：原位更新 `topics/callback.md`，不要新建 `callback-v2.md`。
+- 若新文档新增「重试补偿」子能力：可新增 `topics/callback-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `callback-retry -> callback`。
 - 更新后同步 `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-milestone/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: f2s-doc-milestone
+description: 据 req-docs、git log、.task 与知识库主题语义生成里程碑（《项目里程碑模版》）；触发：f2s-doc-milestone、生成项目里程碑、里程碑。命令后可附语义化范围。本技能固定子 agent 生成、主 agent 验证，不受 flow2spec.config 编排开关影响
+---
+
+> 执行口径：读 `.Knowledge/template/项目里程碑模版.md`；落盘 **仅** `.Knowledge/stock-docs/<范围名>里程碑.md`（无第二路径参数）。
+
+## 编排（固定，不受项目配置影响）
+
+**本技能不受** `flow2spec.config.json` 中 **`subAgent`**、**`switchAgentVerification`**（及旧键 `subAgentVerification`）**影响**：无论其为 `true` 或 `false`，**一律**按下述分工执行，**禁止**因配置改为「全主会话」或「子 agent 自验即结束」。
+
+| 角色 | 步骤 | 职责 |
+| --- | --- | --- |
+| **主 agent** | 0、3、4 | 读模版与知识库主题索引、解析范围、派子、**验证**、必要时修订、回复用户 |
+| **子 agent** | 1、2 | 采集四源、套模版、**Write 初稿** |
+
+1. **主 agent**：步骤 0 → 下发「采集契约」→ 子 agent 步骤 1–2 落盘初稿。
+2. **主 agent**：步骤 3 对照四源与「重要节点清单」验证（不全文重写；补缺、纠偏、「待确认」）→ 步骤 4 回复。
+3. 子 agent **禁止**宣称「里程碑已验收完成」；终稿以主 agent 验证后为准。
+
+> 步骤 0 仍 **`Read("flow2spec.config.json")`**（满足 `f2s-config-check` 前置），但**不得**用其中的 `subAgent` / `switchAgentVerification` 改变本技能编排。
+
+**子 agent 采集契约（主 agent 派子前写入 prompt）**
+
+| 字段 | 内容 |
+| --- | --- |
+| `scope` | 用户语义范围一句 |
+| `outputPath` | `stock-docs/<范围名>里程碑.md` |
+| `sources` | 见下文「四源」；**须含知识库主题语义** |
+| `template` | `.Knowledge/template/项目里程碑模版.md`（不写模版顶部说明 blockquote） |
+| `delivery` | 完整 Markdown，可直接 `Write` 至 `outputPath` |
+| `stagePolicy` | 见下文「阶段粒度」；契约中须复述一句 |
+
+## 阶段粒度（必须，写入契约）
+
+里程碑 **Mx 仅记录功能/能力变更**：当前仓库（或用户指定范围内）**已落地或可核验**的交付，例如模块/接口/数据模型/领域行为/知识库路由等，且须在四源中有依据。
+
+**不得**单独占一行总览或独立 `## Mx ·` 的阶段类型（无四源交付支撑时禁止臆造；有交付也不得拆成「纯测试/纯联调」阶段）：
+
+- 联调、集成测试、UAT、回归、验收、提测、上线检查（仅过程、无功能 diff）
+- 仅环境/运维动作（执行 DDL、填配置、发版窗口、跨仓排期）且**无**本范围功能交付
+- 以「稳定化 / 工程化 / 收尾」为名、实质仅为上述过程性工作的阶段
+
+**合并规则**：同一次能力迭代内的工程性改动（如 id 类型对齐、分页格式、锁与并发）**并入**对应功能阶段正文，不另起「联调 / 测试 / 验收」阶段。
+
+**缺口处理**：四源仅提及待联调、待验收、环境待补齐而无本范围功能交付 → **不写**对应 Mx；可在 **待确认** 列一句，**禁止**用「计划项」填充总览表。
+
+## 四源（采集与验证均须覆盖）
+
+| 源 | 读什么 | 里程碑里怎么用 |
+| --- | --- | --- |
+| **req-docs** | 范围内 `.Knowledge/req-docs/*.md` | 需求/方案节点、交付摘要 |
+| **git** | `git log --no-merges`、`git tag -l`、`package.json` 版本 | 时间线、大版本/tag、提交锚点 |
+| **`.task`** | `todo.json`、`active/`、`completed/` 下 `task.md` 等 | 任务闭环、已交付步骤 |
+| **知识库主题（语义）** | 见下「主题索源」 | 与 index/manifest 已登记能力对齐，避免漏写「库里已有语义」的阶段 |
+
+### 主题索源（知识库语义，主 agent 步骤 0 须读；子 agent 步骤 1 须读）
+
+1. **`Read(".Knowledge/manifest-routing.json")`**：提取 `topicPaths`、`taskToTopicRules`（及与范围相关的 `topicDependencies`）。
+2. **`Read(".Knowledge/index.md")`**：至少「**主题一览**」表（主题 id、适用场景、关联文档摘要）。
+3. **按需 `Read` `.Knowledge/topics/<topic>.md`**：与范围或 manifest 命中相关的摘要（**禁止**为枚举遍历整个 `topics/`；仅读 manifest/index 已点名的主题，通常 ≤ 全表行数）。
+4. 将主题语义归纳为「能力/场景节点」列表，供子 agent 写入契约；里程碑阶段须能覆盖或于「待确认」说明与某主题相关的缺口。
+
+文首 **「索源」** 一行须写明：本轮读了哪些 topic（id 或 `topics/*.md` 路径），或「无 `.Knowledge` 路由」。
+
+## 入参（仅一个，可选）
+
+命令名之后可跟**一段语义化范围**（自然语言）：
+
+| 用户意图 | 示例 | 落盘文件名 |
+| --- | --- | --- |
+| 整个项目（默认） | 不传 / `整个项目` / `全项目` | `项目里程碑.md` |
+| 某一需求或能力 | `回调改造` / `登录模块` | `<简述>里程碑.md` |
+
+**文件名规则**：后缀 `里程碑.md`；整个项目 → 前缀 `项目`；单一需求 → 语义或 req 标题简述（≤ 20 字）。
+
+**范围收窄**：在四源上按关键词、路径、日期过滤；未传范围则四源全量可追溯（主题索源读 index 全表 + manifest，topics 按需展开）。
+
+## 步骤 0：前置（主 agent）
+
+1. **`Read("flow2spec.config.json")`**（不采纳其 `subAgent` / `switchAgentVerification` 编排本技能）
+2. **`Read(".Knowledge/template/项目里程碑模版.md")`**
+3. **主题索源**（见上：manifest → index 主题一览 → 按需 topics 摘要）
+4. 解析范围 → 确定默认路径 **`stock-docs/<范围名>里程碑.md`**。
+5. **相似文件检查（落盘前必做）**：列出 `.Knowledge/stock-docs/` 下已有 `*里程碑*.md`（含 `*里程碑.md`）。若存在与本次**目标路径相同**或**语义相近**的文件（例如同为「整个项目」的 `项目里程碑.md` 与另一份全项目里程碑、或前缀/范围关键词高度重叠），**须先询问用户**，**禁止**静默覆盖或擅自另存：
+   - **覆盖**：沿用原路径，子 agent 写入时覆盖该文件（验证后仍以该路径为终稿）。
+   - **另生成一份**：改用新路径（建议：范围简述 + `_YYYYMMDD` + `里程碑.md`，或用户指定的 `<简述>里程碑.md`），并在契约中更新 `outputPath`。
+   - 无相似文件，或仅有一个且与目标路径完全一致且用户本轮已明确要「重新生成/覆盖」→ 可不再追问，按默认路径继续。
+6. 向用户复述：范围、**最终** `outputPath`、已读主题数量；若做了相似文件询问，待用户选择后再继续。
+7. 组装「采集契约」（含最终 `outputPath`、主题节点列表）并 **派子 agent** 执行步骤 1–2
+
+## 步骤 1：采集索源（子 agent）
+
+- 按契约完成 **四源** 采集；git **须** 对照 tag 与主版本/semver 跃迁（以本仓库 `git tag` / `package.json` 为准）。
+- 主题语义：核对 manifest/index 中能力与 git/req/task 是否同窗出现；暂无法对齐的记入内部备注供「待确认」。
+
+索源为空：仍生成文档，「待确认」说明缺口；**禁止**训练数据填交付。
+
+## 步骤 2：套模版并落盘（子 agent）
+
+1. `# （范围名）里程碑`；文首范围、时间、**索源（含本轮 topics）**。
+2. 时间升序 **M1、M2…**；总览表与各 `## Mx ·` 一一对应；**每阶段标题与一句话须体现功能变更**，不得用「联调 / 测试 / 验收」作阶段名（见「阶段粒度」）。
+3. 不写模版顶部说明 blockquote。
+4. **`Write`** 至 `outputPath`。
+
+## 步骤 3：验证（主 agent，须执行）
+
+子 agent 落盘后 **必须**验证：**重要节点**是否错误、遗漏或合并过度。
+
+1. **重读四源要点**：git tag/commit、req/task、**index 主题一览 + 已读 topics** 与文稿对照。
+2. **对照「重要节点清单」**：
+
+| 类别 | 检查什么 |
+| --- | --- |
+| 版本 / tag | 四源中的 major tag、`package.json` 版本跃迁是否在总览或 Mx 中体现 |
+| 路线/架构转折 | 四源中出现的目录重组、技术路线替换等重大变更是否单独或合并体现 |
+| 功能交付 | req/git/task 中可核验的能力是否在 Mx 中有对应阶段 |
+| **知识库主题** | 若存在 manifest/index：与范围相关的主题是否覆盖或列入「待确认」 |
+| 任务闭环 | 若存在 `.task/`：已归档任务是否在相关 Mx 中体现 |
+| 依据可追溯 | 每 Mx 交付能否在四源中找到 |
+| 时间线 | 先后合理；同窗多版本是否需拆分 |
+| **阶段粒度** | 是否存在仅联调/测试/验收/环境而无功能交付的 Mx；若有 **删除或并入** 相邻功能阶段 |
+
+3. 遗漏 → 补 Mx（**须为功能变更**）；错误 → 按四源修正；无法确认 → 「待确认」（**禁止**用假 Mx 代替）。
+4. 验证或修订完成后方可步骤 4。
+
+## 步骤 4：回复（主 agent）
+
+落盘路径、阶段数、验证结论（一句）、「待确认」摘要。
+
+## 禁止项
+
+- 禁止用 `subAgent` / `switchAgentVerification` 跳过子生成或跳过主验证。
+- 禁止在 `stock-docs/` 已存在**相似里程碑**且用户未选择「覆盖 / 另生成一份」前派子 agent 或 `Write`。
+- 禁止第二参数改输出路径（路径由范围 + 相似文件询问结果确定）；禁止写入 `req-docs`。
+- 禁止未读四源写交付；禁止子 agent 未经验证即宣称完成。
+- 禁止遍历整个 `matchers/` 或全仓 topics 代替「manifest + index + 按需 topics」。
+- 禁止用训练数据或其它项目的里程碑结构替代**当前仓库**四源；禁止代写与本次 `outputPath` 无关的其它 `stock-docs` 文档。
+- 禁止单独设立联调 / 集成测试 / UAT / 验收 / 纯环境运维类 Mx；禁止在无四源功能交付时写「计划项」阶段。

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` 为路由摘要。