@double-codeing/flow2spec 2.2.3 → 3.0.8

package/templates/rules/f2s-task.mdc

@@ -0,0 +1,202 @@
+---
+name: f2s-task
+description: >
+  变更追踪：代码变更时自动创建并维护 .task/ 下的任务清单，支持跨会话续作。
+  仅当 flow2spec.config.json 中 changeTracking.feat / fix / implement 之一为 true 时，对应技能生效。
+  触发词：changeTracking、任务追踪、变更追踪、续作、继续上次任务
+alwaysApply: true
+---
+
+# f2s-task（变更追踪规则）
+
+## 生效条件
+
+各技能按自身子项判断：
+
+- `f2s-kb-feat`：读 `changeTracking.feat`
+- `f2s-kb-fix`：读 `changeTracking.fix`
+- `f2s-implement-tech-design`：读 `changeTracking.implement`
+
+若对应子项为 `false` 或字段不存在，**该技能内的变更追踪步骤不执行**，直接跳过。
+
+> `f2s-req-plan` 命令不受此条件约束，始终执行（见 `skills/f2s-req-plan/SKILL.md`）。
+
+## 目录结构
+
+```
+.task/
+├── todo.json                          ← 活跃任务索引，仅主 agent 写
+├── active/
+│   └── <task-name>/
+│       ├── task.md                    ← checklist（执行步骤）
+│       ├── context.md                 ← 涉及文件路径、相关资料链接
+│       └── user-todos.md              ← 须用户执行的代办（改库、配环境等），见下文
+└── completed/
+    └── <YYYYMMDD>-<task-name>/
+        ├── task.md
+        ├── context.md
+        └── user-todos.md              ← 随任务一并归档，便于验收后逐项消项
+```
+
+**归档目录命名**：`completed/` 下文件夹名为 **`<YYYYMMDD>-<task-name>`**（**本地日历日期 8 位在前**，`<task-name>` 与 `active/` 下一致、为 snake_case；便于按时间排序）。**新归档一律使用本格式**；仓库中已有的旧式 `<task-name>-<YYYYMMDD>` 目录可保留，择机人工重命名即可。
+
+## todo.json 结构
+
+```json
+[
+  {
+    "name": "任务名称",
+    "folder": ".task/active/<task-name>/",
+    "keywords": ["关键词1", "关键词2"],
+    "linkedSkill": "f2s-kb-fix",
+    "createdAt": "YYYY-MM-DD"
+  }
+]
+```
+
+**写权约束**：`todo.json` 仅由主 agent 写，禁止子 agent 修改。
+
+## 任务开始（代码变更前）
+
+1. 检查 `.task/todo.json` 是否存在活跃任务。
+2. 将用户输入与各条目 `keywords` 匹配：
+   - 命中一个 → 加载对应 `task.md`、`context.md`，**若存在** `user-todos.md` 则一并加载，展示剩余清单与未消用户代办
+   - 命中多个 → 列出候选，让用户选择
+   - 无命中 → 确认任务名称后创建新任务
+3. 创建新任务（无命中时）：
+   a. 确认任务名称（snake_case，简短描述变更内容）
+   b. 在 `.task/active/<task-name>/` 创建文件夹
+   c. 将本次工作步骤写入 `task.md`
+   d. 将涉及文件路径和相关资料链接写入 `context.md`
+   e. **创建 `user-todos.md`**（固定文件名，与 `task.md` 同目录）：见下文「`user-todos.md` 格式与写盘义务」；尚无代办时可写入占位说明
+   f. 在 `todo.json` 新增条目（仅主 agent 写）
+
+## 执行中
+
+- 每完成一个步骤，**立即**用 `Edit` / `Write` 将 `task.md` 中对应 checkbox 由 `[ ]` 改为 `[x]`（与代码改动同等对待，**禁止**仅靠会话内口头宣称「已完成」代替磁盘更新）
+- 禁止批量勾选或跳步
+- **用户代办须落盘**：凡须任务责任人（用户）在本机、数据库、配置平台或流程上完成的项（例如执行 DDL/DML、填密钥、点审批、发版、补数据），**同一会话内**追加写入 `user-todos.md`（`Edit` 追加小节或列表项），**禁止**仅在对话里交代而不写入该文件；可与对话摘要并存，以磁盘文件为交接真值
+
+## 中断与会话结束（硬约束）
+
+- **长记忆以 `task.md` 的 checkbox 为真值**：下一会话通过「首个仍为 `[ ]` 的步骤」定位进度；未写盘则续作失真。
+- 本会话内每真实完成 `task.md` 所列一步：**当步**打钩，不得积压到归档前一次性勾选。
+- 若用户结束对话、工具流中断、或预计无法继续：在结束前至少打钩**已真实完成**的步骤，并在「## 备注」写明阻塞原因或「下一会话从步骤 N 继续」；**禁止**在未更新 `task.md` 的情况下直接结束（否则等同丢失进度信号）。
+- 中断前若本会话已识别出**用户代办**：**必须**写入或追加到 `user-todos.md`，避免下一会话丢失「交给用户的事」。
+- 若本会话为子任务创建过 **`git worktree`** 或等价隔离目录：结束前按 **`f2s-flow2spec-unified-entry`**「Git worktree 与子任务工作目录卫生」完成移除或写明残留路径与删除命令（必要时写入 `user-todos.md`）。
+
+## 任务完成
+
+**归档门禁（须先于移动目录自检）**：
+
+- 将目录移入 `completed/` **当且仅当** `task.md` 的「## 步骤」下，与本次交付相关的条目**全部为 `[x]`**（或用户明确取消的项已在「## 备注」说明，且对应列表项已改为 `[x]` / 已删除该项并注明取消）。
+- 若仍存在 `[ ]`：**禁止**移动 `active` → `completed/`、**禁止**从 `todo.json` 删除该条目；应先回到「执行中」补完或改清单后再归档。
+
+完成上述门禁后：
+
+1. 将 `.task/active/<task-name>/` 整体移至 `.task/completed/<YYYYMMDD>-<task-name>/`
+2. 从 `todo.json` 删除该条目
+3. 若 `todo.json` 变为空数组，删除该文件
+
+## 新会话续作
+
+新会话开始时，若存在 `.task/todo.json`：
+
+1. 读取全部活跃任务
+2. 将用户首条消息与各条目 `keywords` 匹配
+3. 命中则展示剩余 checklist，**若存在 `user-todos.md` 则摘要其中仍为 `- [ ]` 的用户代办**，并提示「检测到未完成任务，是否继续？」
+4. 用户确认后：**若 `linkedSkill` 非空，先加载对应技能规则文件（配置根 `skills/<linkedSkill>/SKILL.md`）作为执行上下文**，再按 `task.md` 剩余步骤继续——技能的落盘约束、文风规则、自检清单全部生效，与首次调用一致
+5. 无命中则不打扰，正常响应
+
+**孤儿 `active/`（`todo.json` 缺失或损坏）**：若磁盘上仍存在 `.task/active/<task-name>/` 且其中 `task.md` 含未勾选步骤，应 `Read` 该 `task.md` 并提示用户是否续作；续作前宜按「任务开始」一节恢复或补写 `todo.json`（仅主 agent），避免进度仅存在于已归档目录而无法关联活跃索引。
+
+## task.md 格式
+
+```markdown
+# <任务名>
+
+## 步骤
+- [ ] 步骤1
+- [ ] 步骤2
+- [x] 步骤3（已完成）
+
+## 备注
+<执行中的发现、决策等>
+```
+
+## context.md 格式
+
+```markdown
+# <任务名> 上下文
+
+## 涉及文件
+- `src/payment/callback.js`
+- `src/payment/retry.js`
+
+## 相关资料
+- `.Knowledge/req-docs/payment-spec.md`
+- `.Knowledge/stock-docs/payment-arch.md`
+
+## 用户代办清单
+- 见同目录 `user-todos.md`（须用户执行的项统一写在该文件，勿仅在对话中罗列）
+```
+
+## user-todos.md 格式与写盘义务
+
+**路径**：`.task/active/<task-name>/user-todos.md`（归档后位于 `.task/completed/<YYYYMMDD>-<task-name>/user-todos.md`）。**固定文件名** `user-todos.md`，便于 Hook 与脚本引用。
+
+**用途**：汇总 **Agent 无法代劳**、必须由用户（或持权人在平台）完成的项，例如：
+
+- 在指定环境执行 SQL / 迁移脚本（可引用 `req-docs` 或仓库内 `.sql` 路径）
+- 配置中心 / 环境变量 / 密钥 / 白名单
+- 发布、审批、工单、外部系统开关
+
+**写盘义务**：
+
+1. **创建任务时**（`f2s-task`「任务开始」步骤 3.e）：创建该文件；可含简短说明 + 空列表。
+2. **执行中**：每出现一类新的用户代办，**当次**追加（推荐按日期分二级标题 `## YYYY-MM-DD`，下列 `- [ ]` 可勾选项或步骤编号）。
+3. **与 `task.md` 分工**：`task.md` 管 Agent 侧步骤 checkbox；`user-todos.md` 管用户侧待办；**勿**把「仅用户可执行」的长操作说明只写在 `task.md` 步骤正文代替本文件。
+4. **续作**：加载任务时 `Read` 本文件，向用户展示仍未勾选的 `- [ ]` 项（若有）。
+
+**示例结构**：
+
+```markdown
+# 用户代办清单
+
+> Agent 追加；用户完成后可将对应 `- [ ]` 改为 `- [x]` 或删除该行。
+
+## 2026-05-09
+
+- [ ] 在预发 MySQL 执行：`.Knowledge/req-docs/xxx.sql`（先备份）
+- [ ] 在配置中心打开功能开关 `feature.foo.enabled`
+
+## 2026-05-10
+
+- [ ] 生产发版后回写实际版本号到本文档备注
+```
+
+## 推荐 Hook 配置（Claude Code）
+
+在项目 `.claude/settings.json` 中添加，每次文件变更前将活跃任务注入上下文：
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "node -e \"try{const f='.task/todo.json',fs=require('fs');if(fs.existsSync(f)){const t=JSON.parse(fs.readFileSync(f,'utf8'));if(t.length)console.log('[task] 活跃任务: '+t.map(x=>x.name).join(', '))}}catch(e){}\" 2>/dev/null || true"
+      }]
+    }]
+  }
+}
+```
+
+## 禁止项
+
+- 禁止子 agent 写入 `todo.json`
+- 禁止在所有步骤完成前将任务移至 `completed/`
+- 禁止批量勾选 checkbox（必须逐步勾选）
+- 禁止在 `changeTracking.feat` / `changeTracking.fix` / `changeTracking.implement` 均为 `false` 或字段不存在时创建 `.task/` 目录（`f2s-req-plan` 不受此约束）
+- 禁止在已使用 `.task/` 的任务中，将「须用户执行的代办」**仅**写在对话或仅写在 `task.md` 而**不**追加到 `user-todos.md`（无代办时文件可保持占位说明）

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

@@ -1,204 +1,105 @@
 ---
+name: f2s-ctx-build
+description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
 
-## name: f2s-ctx-build
-description: 根据 stock-docs 文档生成 Rules、Skills 与文档索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
+> 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`。不再维护 `.Knowledge/manifest-matchers.json`（已废弃聚合文件；`flow2spec init` 会删除遗留副本）。
 
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 `**.cursor/`**、`**.claude/**`、`**.codex/**`）。下文 `**配置根/...**` 指该目录下的相对路径。
+# 根据文档生成项目上下文（topics/index/路由清单）
 
-# 根据文档生成项目上下文（Rules、Skills、文档索引）
+## 编排（主 / 子 agent）
 
-用户会在本技能后附带**一个参数**：要么是一个 **URL**（如 `https://xxx.com/doc`），要么是一个**本地路径**，且路径应指向 **配置根/stock-docs/** 下的 Markdown（PDF/初稿/终稿/架构说明等**存量上下文源**，用于生成 Rules、Skills）。**不要**把 `**配置根/req-docs/`**（按方案实现代码的技术方案目录）当作本技能入参；若用户只持有该目录下的方案，应提示先将符合《终稿模版》的文档复制或整理到 `**配置根/stock-docs/**` 再执行。请按以下步骤执行，用你的**大模型能力**分析文档并生成完整架构。
+- 两字段（`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 不绑定交叉校验。
 
-**文档产物阶段约定**：doc 中的产物一般分为 **原稿**、**初稿**、**终稿**；本技能生成的 **Rules、Skills 文件名与目录名不带 `_终稿` 等后缀**，与现有约定一致（如 `<主题>-context.mdc`、`<主题>-context/SKILL.md`）。
+## 输入
 
-**生成原则：拆解与分工**  
-本技能生成的所有产物须遵循以下两点，执行时即按此执行，而非事后补救：
+- 接收一个参数：URL 或本地路径。
+- 本地路径必须位于 `.Knowledge/stock-docs/`。
+- 若传入 `.Knowledge/req-docs/`，提示用户先整理为 `stock-docs` 终稿后再执行。
 
-1. **拆解**：根据文档篇幅与领域块数量，决定是「单 Rule + 单 Skill」还是「索引入口 + 多条专题 Rule/Skill」。篇幅长或含多块独立内容（如接口约定、消息队列、配置、公共工具等）时，应拆成索引入口 + 多条按场景/主题的 Rule 与 Skill，使单条更聚焦、按需加载。
-2. **分工**：
-  - **Rules**：承担**约束、约定、作用范围**；一条 alwaysApply 的索引入口 + 若干条用 globs 限定在相关路径的专题规则；正文写「必须/禁止/约定」类内容。
-  - **Skills**：承担**领域知识、操作步骤、示例**；一个总览 skill + 若干专题 skill；description 写清触发词与使用场景，正文写概念、流程、方法表、示例。
+## 生成原则
 
----
+1. **拆解**：文档较长或包含多块独立能力时，拆分为多个 topic；避免把无关能力塞到同一主题。
+2. **分工**：
+  - `topics/`：规则与流程正文（可执行知识）
+  - `index.md`：主题索引与语义说明（人读入口）
+  - `manifest-routing.json` + `taskToTopicRules[].matcherPath` 指向的 `matchers/*.json`：任务路由与关键词词表（机读入口）
 
 ## 步骤 1：获取文档内容
 
-- 若用户给出的是 **HTTPS/HTTP URL**：使用你可用的网络请求能力（如 web fetch）拉取该 URL 的页面内容。若你所在环境无法访问该 URL（如内网），则回复用户说明「请将页面内容复制到项目内 `配置根/stock-docs/xxx.md`，再执行本技能并传入路径 `配置根/stock-docs/xxx.md`」。
-- 若用户给出的是**本地路径**：从配置根的父目录读取该文件（须为 `**配置根/stock-docs/…`**，如 `配置根/stock-docs/功能描述.md`）。若路径落在 `**配置根/req-docs/**`（技术方案目录），应提醒用户：本技能入参须为 **stock-docs** 下的存量源文档；请先将符合《终稿模版》的内容整理到 `**stock-docs/`** 再执行。
-
-得到的内容可能是 Markdown、HTML 或富文本，请先提取出**正文**（若是 HTML 可提取 body 内的文本或转成可读的 Markdown）。
-
----
-
-## 文档路径与链接约定（必守，避免引用错误）
-
-生成任何产物时，**必须**按下列规则写文档路径与链接。**路径写错会导致 Cursor 中链接失效、AI 无法正确打开源文档，务必严格按表执行。**
-
+- URL：抓取正文；无法访问时提示用户先落地到 `.Knowledge/stock-docs/*.md`。
+- 本地路径：读取 Markdown 文档，提炼主题与能力边界。
 
-| 写入位置                         | 文档所在目录（固定）                    | 引用该文档时的写法                                                                                                                                                                                                |
-| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **配置根/rules/*.mdc**          | 文档在 `配置根/stock-docs/<文件名>.md` | 链接 **必须** 写为 `[文档标题](../stock-docs/<文件名>.md)`，即 href 为 `**../stock-docs/<文件名>.md`**（从 配置根/rules 到 配置根/stock-docs 的相对路径）。                                                                                 |
-| **配置根/skills/<主题>/SKILL.md** | 同上                            | 链接 **必须** 写为 `[文档标题](../../stock-docs/<文件名>.md)`，即 href 为 `**../../stock-docs/<文件名>.md`**（从 配置根/skills/xxx 到 配置根/stock-docs 的相对路径）。                                                                      |
-| **配置根/docs-index.md**        | 同上                            | 文档路径列：显示可写 `配置根/stock-docs/<文件名>.md`；链接 href **必须** 为 `**stock-docs/<文件名>.md`**（因 docs-index 位于配置根下，同级的 **stock-docs** 目录即 `stock-docs/<文件名>.md`）。示例：`[配置根/stock-docs/技术方案设计.md](stock-docs/技术方案设计.md)`。 |
-| **frontmatter 的 sourceDoc**  | 同上                            | **必须** 写为 `**配置根/stock-docs/<文件名>.md`**（与用户传入的本地路径一致；若用户传的是相对路径如 `配置根/stock-docs/xxx.md`，即用该值）。                                                                                                          |
+## 步骤 2：语义分析（必须）
 
+从文档中提炼：
 
-**正确示例（按位置抄写格式）：**
+- 主题名与主题意图（可形成 topic id）
+- 核心概念与关键流程
+- 业务规则与边界条件
+- 任务触发词（写入对应 `matchers/<matcherId>.json` 的 `includeAny`）
+- 与现有主题的依赖关系（用于 `topicDependencies`）
 
-- Rule 内：`[技术方案设计](../stock-docs/技术方案设计.md)`
-- Skill 内：`[技术方案设计](../../stock-docs/技术方案设计.md)`
-- docs-index 表格单元格：`[配置根/stock-docs/技术方案设计.md](stock-docs/技术方案设计.md)`
-- frontmatter：`sourceDoc: 配置根/stock-docs/技术方案设计.md`
+## 步骤 3：写入 topics
 
-**常见错误（禁止）：**
+- 目标路径：`.Knowledge/topics/<topic>.md`
+- 若已存在同主题：优先增量更新，避免重复主题。
+- 若为新主题：新增文件并补充清晰标题、适用场景、规则与流程。
 
-- **禁止** 在 Rule 内使用 `../../stock-docs/` 或 `req-docs/`（配置根下技术方案目录，非 stock-docs）—— 会 404。
-- **禁止** 在 Skill 内使用 `../stock-docs/` 或 `req-docs/`（配置根下技术方案目录，非 stock-docs）—— 会 404。
-- **禁止** 在 docs-index 内使用 `../stock-docs/` 或 `配置根/stock-docs/xxx.md` 作为链接 href —— 应仅为 `stock-docs/<文件名>.md`。
-- **禁止** 在链接或 sourceDoc 中混用目录：生成上下文的链出与 **sourceDoc** 仅指向 `**stock-docs/`**；勿把 `**配置根/req-docs/**` 下的技术方案当作本技能产物的链出目标。
-- **禁止** 在 sourceDoc 中写相对路径如 `../stock-docs/xxx.md` 或 `**配置根/req-docs/xxx.md`** —— 必须为 `配置根/stock-docs/<文件名>.md`。
-
-**记忆要点**：默认文档目录为 `**配置根/stock-docs/`**（与项目约定一致）；Rule 内链出用 `../stock-docs/`，Skill 内链出用 `../../stock-docs/`，docs-index 内链出用 `stock-docs/`；sourceDoc 用 `配置根/stock-docs/<文件名>.md`。生成后自检所有链接与 sourceDoc，确保层级正确、与项目约定目录一致。
-
----
-
-## 步骤 2：用大模型分析文档
-
-请你**完整理解**该文档，并提炼出：
-
-- **主题/标题**：文档的核心主题，用作生成产物的命名（如「订单功能」→ 文件名/目录名用英文或拼音如 `order`，或保留中文如 `订单功能描述`）。
-- **核心概念**：术语表、名词解释、关键实体（如订单、创建、加入、完成、失败等）。
-- **状态与流转**：若有状态机、流程，请整理出状态名与流转条件。
-- **业务规则**：约束、限购、时效、支付与退款、库存等要点。
-- **关键流程**：用户侧或系统侧的主要流程（创建、加入、完成、失败处理等）。
-
----
+## 步骤 4：更新 index
 
-## 步骤 3：生成并写入以下产物
-
-请**直接创建或覆盖**以下文件，保证格式正确、内容由你分析后生成（不要照抄原文，要提炼与结构化）。生成前先根据**拆解与分工**原则判断：本次是生成「单 rule + 单 skill」还是「索引入口 + 多条专题 rule/skill」。
-
-**路径提醒**：写入 Rule/Skill/docs-index 时，文档链接 href 和 sourceDoc **必须**严格按「文档路径与链接约定」表执行——Rule 仅用 `../stock-docs/<文件名>.md`，Skill 仅用 `../../stock-docs/<文件名>.md`，docs-index 仅用 `stock-docs/<文件名>.md`，sourceDoc 仅用 `配置根/stock-docs/<文件名>.md`。勿凭印象写错层级。
+- 更新 `.Knowledge/index.md` 的主题路由表。
+- 保证“同主题单行”。
+- 主题路由表需维护“关联文档（摘要）”列：每个主题补充 1-3 条关键文档**可点击 Markdown 链接**（格式：`[标题](相对路径)`，优先 `stock-docs/req-docs`）。
+- 若某主题暂无可公开文档，写“无”或“待补充”，禁止留空导致歧义。
+- 若新增/删除主题，索引同步调整，避免孤儿路径。
 
-**main.mdc 与 docs-index.md 的区别**  
+## 步骤 5：更新路由清单（按需）
 
-- **main.mdc**（`配置根/rules/main.mdc`）：**项目的总概述和索引**，固定命名 **main**，**唯一** alwaysApply 的 rule。给 AI 看的「体系结构 + 模块一览 + 公共能力入口」，让 AI 大致知道项目结构，需要时再去读各模块的 rule/skill；并在正文中**强制约定**「先查 `docs-index.md` 再下钻」（见 3.0 正文第 4 点），以落实渐进式读取。  
-- **docs-index.md**（`配置根/docs-index.md`）：**需求/文档索引**，按文档列出的表格（文档路径、Rules、Skills、简要说明），供人与 AI 查「某文档对应哪些产物」。不参与 alwaysApply，**须由 main 正文显式要求 Agent 在定位文档↔产物时优先读取**，否则不会自动进入上下文。
+- 本步骤由主 agent 落盘（写权硬约束），子 agent 不得执行。
+- 更新 `manifest-routing.topicPaths`（topicId -> topic 文件路径）
+- 更新 `manifest-routing.taskToTopicRules[]`（任务到主题集合 + matcherId）
+- 更新 `manifest-routing.topicDependencies`（先读依赖后读主主题）
+- 更新 `matchers/<matcherId>.json` 的 `includeAny`（关键词词表；路径须与 `taskToTopicRules[].matcherPath` 一致）
+- 校验 `fallbackTopic`、`topicPaths`、`matcherId` 引用有效
+- 仅做最小改动，不重写无关字段
 
-### 3.0 main.mdc（项目总概述与索引，唯一 alwaysApply）
+## 路径与引用约束
 
-- **路径**：`配置根/rules/main.mdc`（**固定命名**，不可改为其他文件名）
-- **frontmatter**：`description: 项目总概述与索引，体系结构、模块一览、能力入口`，`alwaysApply: true`
-- **正文结构**（简短；含下述第 4 点为优先，总行数可略超 50 行，**不得省略第 4 点**）：
-  1. **项目结构**：按当前项目实际目录与约定，用通用表述写接口与模块的划分（如对客接口、公共/功能模块等），**不要写仅本项目特有的结构名**（如某团队、某产品线专属目录名），以便本技能复用于其他项目。
-  2. **模块一览**（表格）：列「模块名」「说明」「详细约定加载方式」。每行对应一个功能模块：说明该模块用途；加载方式写「打开项目约定的该模块路径时自动加载对应 rule；或查阅 配置根/stock-docs/xxx、配置根/skills/xxx」。
-  3. **公共能力入口**（若有）：接口与上下文、消息队列、配置、公共工具等入口的简短描述 + 指向对应 rule，并写实现位置（按项目约定，如 ctx 注入、MQ 辅助、配置辅助、模型、公共工具等）。
-  4. **全文索引与渐进式读取（必填）**：须单独成段或小节，至少包含以下语义（可压缩措辞，不可删掉任一条）：
-    - **映射表位置**：「文档路径 ↔ Rules / Skills」的完整表在 `**配置根/docs-index.md`**（`docs-index` 非 alwaysApply，不会自动进上下文，须按需打开）。
-    - **读取顺序**：当要根据**某份 stock-docs 文档、某需求/模块名**定位应遵循的规则或应加载的技能时，**应先读取 `docs-index.md`**，在表中找到对应行，再按 **Rules**、**Skills** 列给出的路径打开 `.mdc` / `SKILL.md`；需要长文细节时再打开 **stock-docs** 链出的源文档；仍不足再下钻**业务源码**。
-    - **避免**：在未查 `docs-index.md`、未锁定相关 Rule/Skill 前，对工作区做**无范围**的大面积检索，或通读与当前问题**无关**的长文档。
-  5. 文末可再单列一行链接提示：**全文索引文件**：`配置根/docs-index.md`（与第 4 点呼应即可）。
-- **main.mdc 的更新时机**：每次执行本技能时，**可能**会更新 main.mdc，**也可能**不更新。  
-  - **会更新**：若本次文档属于「功能模块」或「公共模块说明」类，需在 main 的「模块一览」或「公共能力入口」中体现，则更新 main（若 main 不存在则先创建；若已存在则只更新与本次文档相关的部分，不删已有且无关的模块行）。  
-  - **不更新**：若本次文档不涉及项目总概述与索引（如单次需求说明、不纳入体系结构的文档），则**不修改** main.mdc，仅生成/更新该文档对应的专题 Rules、Skills 及 docs-index 即可。
+- `sourceDoc` 或文档引用统一指向 `.Knowledge/stock-docs/<文件名>.md`
+- 禁止把 `.Knowledge/req-docs/` 作为 topic 的 `sourceDoc`
+- 禁止改写配置根 `rules/skills`
 
-### 3.1 Rules（专题规则，一律非 alwaysApply）
+## 输出摘要（必须）
 
-- **路径**：`配置根/rules/<主题>-ctx.mdc`（或拆解后的多条，如 common-interface-ctx.mdc）
-- **按配置根区分（必守）**：
-  - `**.cursor/`（Cursor）**：规则文件扩展名 `**.mdc`**；路径范围用 `**globs:**`；专题规则 `**alwaysApply: false**`；总览 `**main.mdc**` 唯一 `**alwaysApply: true**`。
-  - `**.claude/`（Claude Code）**：规则须为 `**.md`**（Claude Code 不加载 `.mdc`）；路径范围用 `**paths:**`，**不要**写 `**globs:`**；**不要**写 `**alwaysApply`**（无 `paths` 的规则与会话一并加载）。若项目同时存在 `.cursor/` 与 `.claude/`，生成或更新 `**.claude/rules/**` 时须按上表写 `**.md**` + `**paths:**`。`flow2spec init claude` 已对包内模板做自动转换，手工新增规则时请对齐官方文档。
-- **格式**（以 **Cursor `.mdc`** 为默认表述；**Claude** 将 `globs`→`paths`、扩展名 `.md` 即可）：
-  - frontmatter：`description: <一句话说明本规则>`，**禁止** `alwaysApply: true`（唯一 alwaysApply 为 main.mdc）
-  - **globs（必填，仅 Cursor）**：按主题限定在相关路径，例如功能模块 → `globs: "**/functions/<模块名>/**"`；接口与 ctx → `globs: "**/functions/**/*.js"`；消息队列消费 → `globs: "**/qmq/**/*.js"` 或项目约定的 MQ 消费目录；公共工具 → `globs: "**/utils/common.js"` 或项目约定的工具路径。**Claude Code 下改为 `paths:`，键名同列表写法。**
-  - `alwaysApply: false`（仅 Cursor；Claude 专题规则不写此项）
-  - **版本管理（必填）**：`sourceDoc: <本次命令入参，即 配置根/stock-docs/xxx.md>`，`generatedAt: "<当前时间东八区北京时间，ISO 8601 如 2026-01-28T20:00:00+08:00>"`
-  - 正文：提炼的**核心概念、关键流程、规则要点**（Markdown，简洁可读）+ **文档链接**（链接 href 必须为 `../stock-docs/<文件名>.md`，见「文档路径与链接约定」）
-- **与 main.mdc 的联动**：仅当本次**会更新** main.mdc 时（见 3.0「main.mdc 的更新时机」）：若本次是功能模块，生成/更新该 rule 后**必须**在 main 的「模块一览」中增加或更新该模块行；若本次是公共模块说明，在 main 的「公共能力入口」中体现即可。若本次**不更新** main，则不改 main.mdc。
+- 新增/更新的 topic 文件
+- `index` 更新项
+- 路由清单更新项（如有）
+- 失败或跳过项及原因
 
-### 3.2 Skills
+## 复杂场景示例
 
-- **路径**：`配置根/skills/<主题>/SKILL.md`（主题建议用英文或拼音，如 `order-context`，避免仅中文目录名）
-- **格式**：
-  - frontmatter：`name: <主题>-context`，`description: <何时使用本技能，写清触发场景>`
-  - **版本管理（必填）**：`sourceDoc: <本次命令入参，即 配置根/stock-docs/xxx.md>`，`generatedAt: "<当前时间东八区北京时间，ISO 8601 +08:00>"`
-  - 正文：何时使用、核心概念（表或列表）、关键流程、业务规则要点、**详细文档链接**（链接 href 必须为 `../../stock-docs/<文件名>.md`，见「文档路径与链接约定」）。
+用户输入：`f2s-ctx-build .Knowledge/stock-docs/支付回调改造_终稿.md`，且现有 `topics/payment.md` 已存在。
 
-### 3.3 docs-index.md（需求/文档索引）
+- 若新文档与现有 `payment` 主题高度重合：原位更新 `topics/payment.md`，不要新建 `payment-v2.md`。
+- 若新文档新增“重试补偿”子能力：可新增 `topics/payment-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `payment-retry -> payment`。
+- 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。
 
-- **路径**：`配置根/docs-index.md`
-- **操作**：若文件不存在，先创建表头：
-  ```markdown
-  # 需求/文档索引
-
-  | 需求/模块 | 文档路径 | Rules | Skills | 简要说明 |
-  | --------- | -------- | ----- | ------ | -------- |
-  ```
-  然后**追加一行**，且**必须填写 Rules、Skills 列**：
-  - **Rules**：本次生成的 Rule 路径，多个用顿号或空格分隔，如 `配置根/rules/<主题>-context.mdc` 或 `配置根/rules/common-interface-ctx.mdc`。注意：main.mdc 不在此列逐文档列出（main 为总索引，与单文档非一对一）。
-  - **Skills**：本次生成的 Skill 路径，多个用顿号或空格分隔，如 `配置根/skills/<主题>-context/SKILL.md` 或 `配置根/skills/common-modules-context/SKILL.md`、`配置根/skills/common-modules-mq-usage/SKILL.md`。
-  - **文档路径与链接（必守）**：文档路径列显示 `配置根/stock-docs/<文件名>.md`；链接 **必须** 为 `[配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md)`，即 href 只能是 `**stock-docs/<文件名>.md`**（见上文「文档路径与链接约定」）。勿写成 `../stock-docs/` 或误指 `**req-docs/**`。
-- 行示例：`| <文档标题> | [配置根/stock-docs/<文件名>.md](stock-docs/<文件名>.md) | <Rules 路径> | <Skills 路径> | <一两句摘要> |`
-- 若文件已存在且表头无 Rules、Skills 列，则先补全表头再追加；追加时仍须填写 Rules、Skills 列。
-- **同一文档只占一行**：若该文档路径（或文档标题）在表中已有行，则**更新该行**（覆盖 Rules、Skills、简要说明），不要追加新行，便于日后「修改文档后重新生成」时索引保持一对一。
-
-### 3.4 更新与索源（版本管理）
-
-版本管理服务于**更新 docs 时方便更新与索源**：
-
-- **索源**  
-  - **从产物找文档**：Rule/Skill 的 frontmatter 中 `sourceDoc` 即源文档路径，`generatedAt` 即本次生成时间。  
-  - **从文档找产物**：查 `配置根/docs-index.md` 中该文档所在行的 **Rules**、**Skills** 列，即由该文档生成的全部 Rule/Skill 路径。
-- **更新流程**  
-  - 修改某份文档后，对该文档**再次执行本技能**并传入同一路径（如 `配置根/stock-docs/技术方案设计.md`），即可覆盖并更新该文档对应的全部 Rules、Skills；文档索引中该文档所在行的 Rules、Skills、简要说明会一并更新。  
-  - 无需手动查找要改哪些 Rule/Skill：一次按 doc 执行即可。
-
-### 3.5 按需拆解与加详（执行要点）
-
-当文档**篇幅较长**或**领域清晰**（如同时包含「接口约定、消息队列、配置、公共工具」等多块独立内容）时，**必须**按前述拆解与分工做**拆分 + 适度加详**，使 Rules、Skills 按场景加载、单条更聚焦。
-
-**Rules 拆分建议：**
-
-- **唯一 alwaysApply** 为 **main.mdc**（见 3.0）；不再为单文档单独建 alwaysApply 的「索引入口」rule。各文档对应的索引入口统一合并到 main.mdc 的「模块一览」或「公共能力入口」中。
-- 按**主题**拆成的多条 rule 一律 **alwaysApply: false**，每条用 **globs** 限定在相关路径，例如：
-  - 功能模块 → `globs: "**/functions/<模块名>/**"`
-  - 接口与 ctx 约定 → `globs: "**/functions/**/*.js"`
-  - 消息队列约定 → `globs: "**/qmq/**/*.js"` 或项目约定的 MQ 消费目录
-  - 公共工具约定 → `globs: "**/utils/common.js"` 或项目约定路径
-- 每条 rule 的 frontmatter 中 **且必须含** `sourceDoc`、`generatedAt`（同上），正文写该主题的**核心概念、关键流程、规则要点**，可带简短示例；单条建议 <50 行。生成功能模块 rule 后必须在 main.mdc 的「模块一览」中追加/更新对应行。
-
-**Skills 拆分建议：**
-
-- 保留 1 个**总览** skill：路径如 `配置根/skills/<主题>-context/SKILL.md`，内容为项目/文档总览、各能力入口、关键流程摘要，并在正文中说明「具体某类问题见 xxx-usage 技能」。
-- 按**高频场景**再拆 1 ～ 2 个专题 skill，例如：
-  - 消息队列发送与消费 → 路径如 `配置根/skills/<主题>-mq-usage/SKILL.md`，description 写清触发词（如「消息队列、发送、topic/subject、消费、MQ 辅助」），正文写定义、发送、消费步骤与示例。
-  - 公共工具方法 → 路径如 `配置根/skills/<主题>-utils-usage/SKILL.md`，description 写清触发词（如「公共工具、加密、日志、外部服务、风控、用户、支付、工具方法」），正文写完整方法表、分类、示例。
-- 各 skill 的 **description** 必须写清「何时使用、触发词」，便于 Cursor 按问题匹配到对应技能；每条 skill 的 frontmatter **必须含** `sourceDoc`、`generatedAt`（同上）。
-
-**加详要点：**
-
-- 在**专题** rule/skill 中写「必要细节」：示例代码、完整方法表、步骤与注意点；总览/索引入口保持简短，指向详细文档或专题 rule/skill。
-- 若文档本身较短、主题单一，则按 3.1、3.2 生成单 rule、单 skill 即可；此时仍须遵守**分工**：Rule 写约束与约定，Skill 写知识与步骤。
-
----
-
-## 步骤 4：若输入是 URL，保存原文到项目
-
-若用户提供的是 **URL**，请将你拉取到的**原始正文**保存到项目内 `**配置根/stock-docs/<主题>.md`**（或项目约定的文档目录），以便后续引用。主题名可从文档标题或 URL 路径推断，并做合法文件名处理。
-
----
+## 完成后自检
 
-## 约束与注意
-
-- 所有路径均相对于**配置根的父目录**。
-- **文档路径与链接（必守）**：一律按上文「文档路径与链接约定」执行。Rule 内链到文档 **仅允许** `../stock-docs/<文件名>.md`；Skill 内链到文档 **仅允许** `../../stock-docs/<文件名>.md`；docs-index 内链到文档 **仅允许** `stock-docs/<文件名>.md`。sourceDoc 仅允许 `配置根/stock-docs/<文件名>.md`。勿将 `**配置根/req-docs/`** 下的技术方案当作本技能产物的链出目标（链出**仅**指向 **stock-docs**）。
-- **版本管理**：每条 Rule 与每条 Skill 的 frontmatter 必须含 `sourceDoc`（`配置根/stock-docs/xxx.md`）、`generatedAt`（东八区北京时间 ISO 8601 +08:00），便于更新时索源与重新生成。
-- 生成前可先确认 `配置根/rules`、`配置根/skills`、`配置根/stock-docs` 目录存在，不存在则创建。
-- **完成后自检（路径必查）**：
-  1. 每个 `.mdc` 中指向源文档的链接 href 是否为 `**../stock-docs/<文件名>.md`**（不是 `../../stock-docs/` 或误链到 `req-docs/`）。
-  2. 每个 `配置根/skills/**/SKILL.md` 中指向源文档的链接 href 是否为 `**../../stock-docs/<文件名>.md**`（不是 `../stock-docs/` 或误链到 `req-docs/`）。
-  3. `docs-index.md` 中该文档行的链接 href 是否为 `**stock-docs/<文件名>.md**`（不是 `../stock-docs/` 或裸路径）。
-  4. 所有 Rule/Skill 的 frontmatter 中 `sourceDoc` 是否为 `**配置根/stock-docs/<文件名>.md**`。
-  5. 链接目标与项目约定的文档目录一致（若约定为 `配置根/stock-docs/`，则勿用 `**配置根/req-docs/**` 作为链接目标）。
-  完成后用一句话总结：已生成 Rules、Skills、文档索引及（若适用）配置根/stock-docs 下的原文备份；并确认「文档路径与链接约定」已遵守。
+1. `.Knowledge/topics/*.md` 与 `manifest-routing.topicPaths` 一一对应。
+2. `index.md` 主题表与 topics 文件集合一致，且每个主题都包含“关联文档（摘要）”。
+3. 每个 `taskToTopicRules[].matcherPath` 文件存在且其中 `id` 与 `matcherId` 一致。
+4. 未触碰配置根 `rules/skills`。
+5. 中大变更时是否按文件级契约拆子（子 A / 子 B 路径互不重叠）。
+6. `manifest-routing.json` / `.Knowledge/index.md` 由主 agent 单点落盘，无子 agent 越权写入。
 

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

@@ -1,63 +1,59 @@
 ---
 name: f2s-ctx-rm
-description: 删除某 stock-docs 文档对应的 Rules、Skills 及索引中的相关描述；触发：删除项目上下文、f2s-ctx-rm
+description: 删除某 stock-docs 文档对应的知识主题与索引映射；触发：删除项目上下文、f2s-ctx-rm
 ---
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
 
-# 删除文档对应的项目上下文（Rules、Skills、docs-index、main 中的相关描述）
+> 执行口径：仅维护 `.Knowledge`，不改配置根 `rules/skills`。
 
-用户在对话中提供**一个参数**：与 **f2s-ctx-build** 技能索源一致，为 **`配置根/stock-docs/`** 下某文档的**本地路径**（如 `配置根/stock-docs/技术方案设计.md`）或**文档路径/文件名中可匹配的片段**（如 `技术方案设计.md`）。请按以下步骤执行，**直接删除**匹配到的产物并更新索引与 main。
+## 编排（主 / 子 agent）
 
----
-
-## 步骤 1：解析用户输入路径
-
-- 用户给出的是**本地路径**（如 `配置根/stock-docs/技术方案设计.md`）或**文件名/片段**（如 `技术方案设计.md`）。
-- 用于在 docs-index 中匹配「文档路径」列：若文档路径列是链接 `[配置根/stock-docs/xxx.md](stock-docs/xxx.md)` 或纯路径 `配置根/stock-docs/xxx.md`，则匹配路径或文件名包含用户输入即可。
-
----
-
-## 步骤 2：读取 docs-index 并匹配行
+- 两字段（`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 不绑定交叉校验。
 
-- **路径**：`配置根/docs-index.md`（相对于配置根的父目录）。
-- **操作**：读取该文件，解析表格；找到**文档路径**列与用户输入**匹配**的所有行（一行即对应一份文档及其 Rules、Skills）。
-- 若**没有匹配到任何行**，则回复用户：「未在 docs-index 中找到与“<用户输入>”匹配的文档行，无需删除。」并结束。
+# 删除文档对应的项目上下文
 
----
-
-## 步骤 3：删除匹配行中的 Rules、Skills 及空目录
-
-对**每一个**匹配到的行：
+## 输入
 
-1. **Rules 列**：取该列内容，按顿号、逗号或空格拆成多个路径；每个路径相对于配置根的父目录（如 `配置根/rules/<主题>-context.mdc`）。**删除**这些文件（若文件不存在则忽略）。
-2. **Skills 列**：取该列内容，同样拆成多个路径（如 `配置根/skills/<主题>-context/SKILL.md`）。**删除**这些文件；删除后**必须**检查该 Skill 所在的父目录，若目录已空（无其它文件），**必须删除该空目录**，避免留下空文件夹。
+- 一个参数：`.Knowledge/stock-docs/<文件名>.md` 路径，或可匹配文件名片段。
 
----
+## 执行步骤
 
-## 步骤 4：从 docs-index 中移除匹配行并写回
+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`，必须指定新的兜底主题
 
-- **路径**：`配置根/docs-index.md`。
-- **操作**：从该文件的表格中**删除**所有在步骤 2 中匹配到的行，保留表头与分隔行，其余行不变。若删除后表格仅剩表头与分隔行，可保留空表或仅保留表头，由你决定，保持格式合法即可。
-- **写回**：将修改后的内容**写回** `配置根/docs-index.md`，确保文件已更新。
+## 输出摘要（必须）
 
----
+- 已删除的 topic 文件列表
+- `.Knowledge/index.md` 删除的条目
+- 路由清单调整的字段
+- 未执行项（若有）
 
-## 步骤 5：更新 main.mdc，删除与该文档相关的公共描述
+## 复杂场景示例
 
-- **路径**：`配置根/rules/main.mdc`。
-- **操作**：读取 main.mdc，根据被删除的文档类型做**有选择的删除**，不改变 main 的固定结构与其它无关模块：
+用户输入文件名片段“支付”，匹配到 2 个主题文档。
 
-  1. **若被删除的文档对应「功能模块」**（如某业务/功能模块）：在 main 的 **「模块一览」** 表格中，删除与该文档/该模块对应的那一行。不要动「项目结构」「公共能力入口」等其它部分。
-  2. **若被删除的文档对应「公共模块说明」**：删除 main 中的 **「公共能力入口」** 整节（从 `## 公共能力入口` 到下一个 `##` 或到 `**全文索引**` 之前的所有内容）。若删除后希望保留小节标题但内容为空，可保留 `## 公共能力入口` 下一行写「（暂无）」等，由你决定，保持 main 可读即可。
+- 先列出两个候选并要求用户确认删除范围，避免误删。
+- 删除后同步清理路由清单失效引用；若删到了 `fallbackTopic`，必须先指定新的兜底主题再落盘。
+- 最终摘要中写清：删除了哪些 topic、保留了哪些 topic、为什么。
 
-- 若 main.mdc 不存在，则跳过本步骤。
-- **写回**：将修改后的 main.mdc 写回 `配置根/rules/main.mdc`。
+## 约束
 
----
+- 匹配多义时先询问用户确认。
+- 仅删除命中主题，不影响其它主题。
+- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束）；范围确认与 `fallbackTopic` 重指不可下放给子 agent。
 
-## 约束与注意
+## 完成后自检
 
-- 所有路径均相对于**配置根的父目录**。
-- 只删除 docs-index 中**匹配到的行**对应的 Rules、Skills，以及 main 中**与该文档相关的**模块一览行或公共能力入口节，不要删除其它文档对应的规则或 main 的其它结构。
-- **拿捏不定时向用户确认**：若对某文件、某行或 main 中某段描述是否属于本次要删除的范围**拿捏不定**（例如匹配到多行、路径歧义、main 中模块与文档对应关系不明确等），**不要自行决定**，应列出选项并**向用户提问**「是否删除 xxx？」待用户确认后再执行。
-- 完成后用一句话总结：已删除与“<用户输入>”匹配的文档行、对应 Rules/Skills、并已更新 docs-index 与 main.mdc 中的相关描述。
+1. 被删 topic 是否仍被 `manifest` 引用（必须为否）。
+2. `index` 是否仍存在失效主题路径（必须为否）。
+3. `fallbackTopic` 是否仍有效。
+4. 未在低于拆子阈值（< 5 主题）时强行拆子；manifest / index 由主单点落盘。