flow2spec

区分 .Knowledge/stock-docs（存量上下文）与 .Knowledge/req-docs（需求与技术方案）；禁止混用路径与链出目标

> **唯一长文**：本文件为 **stock-docs-vs-req-docs** 的完整约定。`.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-stock-docs-vs-req-docs.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。

# stock-docs 与 req-docs

- **`.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** 为准）。

>

# 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`（无代办时文件可保持占位说明）

根据 .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/`。
- 若传入 `.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/payment.md` 已存在。

- 若新文档与现有 `payment` 主题高度重合：原位更新 `topics/payment.md`，不要新建 `payment-v2.md`。
- 若新文档新增“重试补偿”子能力：可新增 `topics/payment-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `payment-retry -> payment`。
- 更新后同步 `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 越权写入。

删除某 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 由主单点落盘。

工作中把已落地能力解析进知识库（多文件聚合）：初稿→终稿→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`

若已有同主题沉淀，优先原位更新，避免重复主题和重复索引行。

## 步骤 1：适度深度解析

- 小文件通读；
- 大文件优先结构与关键片段（导出、接口、配置、流程）；
- 不确定内容显式标注“待确认”，禁止编造。
- 若任一拆子阈值满足（输入路径 ≥ 5 / 单源 > ~3000 行 / 多路径总量 > ~10000 行）且 `subAgent=true`，按 B 模式（默认）或 C 模式（达成切换判据时）拆子并行只读扫描；否则主全流程。**启用拆子时，子 agent 必须按主手写 inventory 与扫描契约执行，不得自行增删源路径。**

## 步骤 2：生成初稿

- 默认输出：`.Knowledge/stock-docs/<方案名>_初稿.md`
- 初稿建议结构：
  - 概述
  - 来源清单（含不可读文件）
  - 分模块归纳
  - 交叉关系
  - 待确认项

## 步骤 3：生成终稿

- 参考 `.Knowledge/template/终稿模版.md`
- 输出：`.Knowledge/stock-docs/<方案名>_终稿.md`
- 若用户要求“先审初稿”，则停在初稿并等待确认

## 步骤 4：同步知识路由

基于终稿调用 `f2s-ctx-build` 口径，更新：

- `.Knowledge/topics/`
- `.Knowledge/index.md`
- 路由清单（必要时）

## 输出摘要（必须）

1. 初稿/终稿路径
2. 更新的 topic/index/路由清单 路径
3. 未完成项与原因（如路径无效、信息不足）

## 复杂场景示例

用户输入 6 个文件（代码、配置、旧文档混合），其中 2 个路径不可读。

- 先继续处理可读文件，初稿中明确列出不可读路径和缺口，不因部分失败中断全流程。
- 若发现已有 `.Knowledge/stock-docs/支付能力_终稿.md`：优先在该终稿上修订，而不是新建重复终稿。
- 用户要求“先审初稿”：必须停在初稿，等待确认后再生成终稿并进入 `f2s-ctx-build` 同步。

## 约束

- 终稿 `sourceDoc` 仅指向 `.Knowledge/stock-docs/*`
- 不改配置根 `rules/skills`
- 同主题优先更新，不平行新建重复知识
- `manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 落盘（写权硬约束），子 agent 不得触碰

## 完成后自检

1. 初稿/终稿路径是否落在 `.Knowledge/stock-docs/`。
2. 同主题是否避免重复新建。
3. topic/index/manifest 是否与终稿语义一致。

根据用户说明或文档（或扫描代码）生成项目架构说明初稿，无固定格式，描述清楚即可；触发：项目架构说明、f2s-doc-arch、架构初稿

> 执行口径：本技能产物默认写入 `.Knowledge/stock-docs/`，后续由知识库技能链（如 `f2s-doc-final`、`f2s-ctx-build`）同步到 `.Knowledge/topics/index/manifest`。

## 编排（主 / 子 agent）

- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
- 当 `subAgent=true` 时，从以下两种子策略择一：
  - **B 模式（默认，单轮并行）**：主先产出「inventory（入口 + 核心模块名，主手写）」+「扫描契约（可读路径 / 禁扫目录 / 统一产出字段）」→ 子 agent 并行只读扫表 → 主一轮合并去重 → 写 `stock-docs` 初稿 → 用户确认与验收在主 agent 内完成。
  - **C 模式（多轮纠偏）**：切换判据为以下任一 —— 多 workspace / monorepo、目录极深或源路径 > 20 条、首轮子表矛盾或空洞明显、多源叙述重合 / 矛盾严重。
- **子交付硬约束**：子 agent 不得自行裁剪目录范围，必须按主手写 inventory 执行；子交付按「子交付 YAML schema」（字段：`source` / `scope` / `cross_refs` / `pending`），禁止散文式回传。
- **写权硬约束**：`.Knowledge/index.md` / `manifest-routing.json` 恒由主 agent 落盘，子 agent 不得触碰。
- 落盘侧自验；本 SKILL 不绑定交叉校验。

# 生成项目架构说明（初稿）

本技能用于**帮助用户生成项目架构的文档说明**，产出形态类似**初稿**：无固定格式规范，以**描述清楚**为目标。用户可提供纯文字说明、已有文档，或在不提供时由 AI 扫描代码生成（不推荐，仅作兜底）。

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

---

## 入参（均可选）

| 参数           | 说明                                                                                                                                                              |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `.Knowledge/stock-docs/xxx.md`、`.Knowledge/req-docs/README.md`、`README.md`）。不传则进入「无输入」流程。 |
| **第二个参数** | 可选。输出文件路径；若不传，默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。 |

**注意**：不传任何说明或文档时，将使用 **AI 扫描项目代码与目录** 生成架构说明初稿，**不保证质量**。执行时**必须先提示用户**：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才继续。

---

## 执行流程

### 1. 若用户提供了说明或文档

1. **读取与理解**
   - 若第一参数是**文档路径**：在配置根的父目录下按路径读取该文件内容（支持 .md、.txt 等文本格式）。
   - 若第一参数是**纯文字说明**：直接以用户输入为「用户说明」。
2. **结合项目补充**
   - 根据用户说明中的**代码路径、模块名、入口**等线索，结合配置根的父目录下的实际目录结构、关键文件（如 package.json、入口文件、配置文件）进行**归纳与补全**。
   - 若用户说明较宽泛（如只说了「一个后台系统」），**主动引导**用户补充：主要代码路径、模块/包划分、入口与启动方式、与外部系统的边界等，便于生成更贴合的架构说明。
3. **生成初稿**
   - 若启用拆子（B 模式），子 agent 必须按主手写 inventory 执行扫描，交付遵循子交付 YAML schema。
   - 产出一份**项目架构说明**：可包含但不限于：项目定位、技术栈、目录/模块划分、关键路径与入口、配置与部署要点、与文档产物阶段的对应说明（若适用）。
   - **无固定格式**：采用清晰的标题与段落即可，不强制套用《终稿模版》。
4. **输出**
   - 默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`；若用户传入第二参数则写入该路径。
   - 若目录不存在则先创建。

### 2. 若用户未提供任何说明或文档

1. **提醒并确认**
   - 明确说明：「**未收到任何参数。** 不传递说明或文档时，将使用 AI 扫描项目代码与目录生成架构说明初稿，**不保证质量**，且易遗漏重点、难以区分主次。建议先提供一段简要说明或已有文档（如 README、设计 doc）再执行本技能。」
   - **必须询问用户**：「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」
   - 仅当用户**明确确认**（如回复「确认」「是」「直接扫描」等）后，才继续步骤 2；若用户未确认或表示取消，则不再执行扫描与生成。
2. **扫描与生成**
   - 基于配置根的父目录：列出主要目录与代表性文件（可结合 package.json、常见入口与配置文件名），归纳出「目录结构、疑似模块、入口与配置」等。
   - 生成一份**架构说明初稿**，并在文中注明「本初稿由扫描项目结构生成，建议结合业务说明与代码细节进一步补充」。
3. **输出**
   - 同上，默认 `.Knowledge/stock-docs/架构说明_初稿.md`，或用户指定的第二参数。

---

## 引导与迭代

- 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。
- 生成初稿后，可提示用户：可根据需要修改 `.Knowledge/stock-docs/xxx架构说明_初稿.md`，若需转为《终稿模版》规范格式，可再按 **f2s-doc-final** 技能，以该路径为入参得到终稿，再按 **f2s-ctx-build** 同步知识路由主题与索引。

---

## 路径与输出约定

- 所有路径均相对于**配置根的父目录**。
- **默认输出**：`.Knowledge/stock-docs/架构说明_初稿.md`；项目名取自 `package.json` 的 `name`（去掉 scope 与非法字符）或当前目录名。
- 若用户传入第二参数为输出路径，则优先使用该路径；若目录不存在则先创建。

---

## 约束与注意

- **不强制格式**：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。
- **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
- 完成后用一句话总结：已生成架构说明初稿的路径，并视情况提示可补充的内容或下一步（如 f2s-doc-final、f2s-ctx-build）。

将 PDF 或 MD 转为《终稿模版》规范格式，便于后续用 f2s-ctx-build 同步 topics/index/manifest；触发：f2s-doc-final、转成概述模板、终稿模版

> 执行口径：初稿/终稿统一写入 `.Knowledge/stock-docs/`；模板优先读取 `.Knowledge/template/终稿模版.md`。

## 编排（主 / 子 agent）

- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
- **默认不拆子**：MD / PDF → 终稿模版的连贯性最好，由主会话一气呵成完成理解、套模版与定稿。
- **可选拆子**（仅当 `subAgent=true` 且大体量 / 多文件，阈值：PDF **> 50 页** 或 **> ~5MB 文本**）：子 agent 做「套模版、排版与结构搬运」**草稿**；主 agent 对照终稿模版、识别缺口并向用户追问、与用户对齐并**定稿 / 验收**；**子 agent 不得单独宣称终稿已合规**。
- 不为「格式转换可独立」默认拆子：终稿合规依赖模版语义 + 业务表述，主侧验收成本通常仍在。
- 校验：落盘侧 agent 自验，本 SKILL 不绑定交叉校验。

# 将 PDF 或 MD 转换为《终稿模版》规范格式（spec → context）

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

**终稿模版仅作提示**：若存在 `.Knowledge/template/终稿模版.md`（来源 `templates/knowledge/template/终稿模版.md`），可读取作为结构参考；不强制套用。

## 内嵌模板结构（当项目内无 `.Knowledge/template/终稿模版.md` 时使用）

规范要求：

- **一级标题**：方案名（如 `# xxx 技术方案设计`）。
- **二级标题至少包含**：`## 核心概念`、`## 业务规则`、`## 关键流程`；其余可按需增删（如 状态与流转、接口、配置/表设计/错误码、实现位置与对接方式）。
- **核心概念**：用表格列出术语、实体、关键 ID（列：概念、说明）。
- **状态与流转**：若有状态机，用列表写状态及流转；若无可简述或省略。
- **业务规则**：列表写约束、校验、配置项。
- **关键流程**：按「用户侧或系统侧」主流程，列表写流程名、步骤简述、入口接口/方法、结果。
- **可选章节**：接口、配置/表设计/错误码、实现位置与对接方式，按需保留并填写。

---

## 流程一：用户传入的是 Markdown（.md）

1. **读取**用户传入的 `.md` 文件内容。
2. **参考格式**（不强制）：若存在 `.Knowledge/template/终稿模版.md`，可读取作为结构提示；否则可参考下方内嵌模板结构。
3. **分析与转换**：
  - 理解原文主题与结构，提炼「方案名」「核心概念」「业务规则」「关键流程」及与原文相关的其他章节（如状态与流转、接口、配置/表设计/错误码、实现位置等）。
  - 将内容重组为结构清晰的终稿风格 Markdown：一级标题为方案名；建议至少包含 核心概念、业务规则、关键流程 三个二级标题，其余按原文有无与需要增删；表格/列表格式可参考模版，不必完全一致。
  - 若原文缺少某节，可标「（待补充）」或根据原文推断补全；若原文结构已清晰，可保留原文章节命名。
4. **输出**：
  - 默认写入 `.Knowledge/stock-docs/<方案名>_终稿.md`（最终产物带 `_终稿` 标识）。
  - 若用户希望指定输出路径，可在命令后附带第二个参数作为输出路径；否则用默认。
5. **回复**：告知用户已生成 `.Knowledge/stock-docs/<方案名>_终稿.md`，并提示可按 `f2s-ctx-build` 继续同步 `.Knowledge/topics`、`.Knowledge/index.md`（必要时 `manifest`）。

---

## 流程二：用户传入的是 PDF（.pdf）

分两步完成：**先 PDF → 初稿 MD，用户确认后再 初稿 MD → 模板格式 MD**。

### 步骤 A：首次执行（传入 PDF 路径）

1. **尝试读取 PDF**：按用户传入路径读取 PDF（可为绝对路径，或相对项目根；如 `.Knowledge/stock-docs/xxx.pdf`）。
  - 若当前环境可解析 PDF 文本：提取正文，转为 Markdown 初稿（保留标题层级、列表、段落，表格若可识别则保留）。
  - 若无法直接读取 PDF（如仅能拿到二进制）：回复用户可将 PDF 内容转存为 `.Knowledge/stock-docs/xxx.md` 后再执行。
2. **生成初稿**：
  - 将提取出的内容保存为 `.Knowledge/stock-docs/<方案名>_初稿.md`（方案名可从 PDF 文件名或首标题推断）。
  - 在回复中**展示初稿的全文或主要结构**，并明确说明：
    - 「初稿已保存为 `.Knowledge/stock-docs/<方案名>_初稿.md`，请检查并修改。」
    - 「确认无误后，请执行：`f2s-doc-final .Knowledge/stock-docs/<方案名>_初稿.md`。」
3. **本轮不进行模板格式转换**，仅完成 PDF → 初稿 MD。

### 步骤 B：用户确认后再次执行（传入初稿 .md 路径）

当用户**再次执行本技能并传入初稿的 .md 路径**（如 `.Knowledge/stock-docs/技术方案设计_初稿.md`）时：

- 按 **「流程一：用户传入的是 Markdown」** 的步骤 2～5 执行：读取格式规范 → 分析与转换 → 输出为模板格式。
- **输出建议**：生成 `.Knowledge/stock-docs/<方案名>_终稿.md`。
- **回复**：告知已生成规范版，并提示可按 `f2s-ctx-build` 继续同步 `.Knowledge/topics` 与索引。

---

## 路径与输出约定

- 所有路径均相对于项目根；初稿/终稿统一放在 `.Knowledge/stock-docs/`。
- **输入**：第一个参数为文件路径（必填），如 `.Knowledge/stock-docs/方案.pdf` 或 `.Knowledge/stock-docs/方案_初稿.md`；第二个参数可选。
- **输出**：
  - PDF 首次：`.Knowledge/stock-docs/<方案名>_初稿.md`
  - MD 或初稿 MD：`.Knowledge/stock-docs/<方案名>_终稿.md`
- 若 `.Knowledge/stock-docs/` 目录不存在，先创建再写入。

---

## 约束与注意

- 转换时**不要照抄原文**，要按模板**提炼、归纳、补全**，使核心概念、业务规则、关键流程清晰可查。
- 建议（不强制）保留 **核心概念、业务规则、关键流程** 三个二级标题；其余章节按原文与需求增删，终稿模版仅作提示，不强制套用。
- 完成后一句话总结：已生成初稿/终稿路径，并说明下一步可用 `f2s-ctx-build` 同步知识路由主题与索引。

将 PDF 技术方案转为 Markdown 并保存到 req-docs，可补全流程说明；触发：PDF转MD、按方案实现前的 PDF

> 执行口径：技术方案文档统一落在 `.Knowledge/req-docs/`；规则能力仍由配置根 `rules/skills` 加载。

## 编排（主 / 子 agent）

- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本文不复述。
- **默认不拆子**：追问-落盘必须在主 agent 内完成（子 agent 无法向用户追问）。
- **可选拆子**：仅当 `subAgent=true` 且 PDF 规模超阈值（**> 50 页 或 > ~5MB 文本**）时启用；子 agent 仅负责 PDF→MD 首稿并落盘 `.Knowledge/req-docs/<名>.md`，**不向用户追问、不写「流程说明」章节**；主 agent 接手后续追问与流程图补写。
- 校验默认由落盘侧 agent 自验；本 SKILL 不绑定交叉校验。

# 将 PDF 技术方案文档转为 Markdown（并补全流程说明）

用户会在本技能后附带**一个参数**：**PDF 技术方案文档的本地路径**（如 `~/Downloads/技术方案.pdf`，或 `.Knowledge/req-docs/某草稿.pdf`）。请按以下步骤执行，将 PDF 转为 Markdown 并保存到 `.Knowledge/req-docs/`，必要时引导用户补全流程说明。

## 步骤 1：读取 PDF 并转为 Markdown

1. 若启用拆子（PDF > 50 页 或 > ~5MB），子 agent 仅负责 PDF→MD 首稿并落盘 `req-docs/<名>.md`，不追问、不写流程说明；主 agent 接手后续步骤。**读取**用户传入的 PDF 文件，提取其中的**文字内容**（表格、章节、列表、代码块等尽量保留结构），整理为 Markdown 格式。
2. **保存到** `.Knowledge/req-docs/`，推荐路径：`.Knowledge/req-docs/<方案名>.md`。文件名为原 PDF 文件名去掉 `.pdf` 后加 `.md`。
3. 若目录不存在，先创建再写入。
4. 保存后告知用户：「已将该 PDF 转为 Markdown 并保存为 `xxx.md`。」

---

## 步骤 2：向用户提问获取流程图（可选但推荐）

PDF 内嵌的**流程图**无法被直接解析为步骤与分支，若需按图实现代码，需用户配合提供。

1. 向用户说明：「文档中可能包含流程图，我无法从 PDF 中解析图中的步骤与分支。若您后续会根据技术方案实现代码（见 `implement-tech-design` 规则），建议补全流程说明：
  - **方式一**：将相关流程图以**图片形式**发到本次对话中，我将解析后以文字形式写入上述 MD；  
  - **方式二**：直接以**文字描述**每个接口/流程的步骤（如：1. 是否登录 2. 查某表 3. 判断某字段 → 返回结果），我将原样写入上述 MD。  
   若文档无流程图或暂不提供，可回复「跳过」，我将结束本技能。」
2. **若用户回复「跳过」或明确表示无需流程说明**：告知用户「在对话中提供上述 MD 路径并说明按技术方案实现代码，我将按 `implement-tech-design` 规则执行。」并结束。
3. **若用户提供流程图（图片或文字）**：进入步骤 3。

---

## 步骤 3：将流程说明写入该 MD

1. 若用户提供的是**图片**：解析图片中的步骤、判断分支与返回，整理为文字步骤。
2. 若用户提供的是**文字**：直接采用。
3. 在该 MD 文件末尾（或新增「流程说明」章节）**追加**流程内容，格式示例：

```markdown
## 流程说明（由用户提供 / 由流程图解析）

### 示例接口 A
1. 前端发起请求
2. 后端：查询某表最后一条记录
3. 判断：是否有某 ID？是 → 返回 true，否 → 返回 false
4. 返回结果

### 示例接口 B
1. 是否登录 → 否 返回 401
2. 是否过期 → 是 返回 403
…
```

1. 保存后告知用户：「流程说明已写入 `xxx.md`。接下来请在对话中提供该 MD 路径并说明要按技术方案实现代码，我将按 `implement-tech-design` 规则执行。」

---

## 约束与小结

- **路径**：用户传入的 PDF 路径可为绝对路径或相对项目根。输出 MD 建议保存在 `.Knowledge/req-docs/<方案名>.md`（`req-docs` 放实现文档，`stock-docs` 放知识沉淀源文档）。
- **本技能仅负责**：PDF → Markdown 转换 + 可选流程说明补全；不执行代码实现。完成后可提示用户：在对话中提供生成的 MD 路径并说明按技术方案实现，AI 将按 **f2s-implement-tech-design.mdc** 执行。

代码写完后提交 Git：检查变更与知识库覆盖；生成带 emoji 首行的提交说明后**可直接 commit**（须在当条回复展示首行，不要求用户单独确认 commit）；**git pull 类拉取须用户先确认**。触发：f2s-git-commit、提交代码、git commit、帮我提交

> 执行口径：本技能代用户执行 git 操作；不使用 `git add -A` / `git add .`，不跳过 hooks（`--no-verify`），不自动 push。**`git pull` / `git fetch` 合并入本地前必须取得用户对「拉取」的明确确认**；`git commit` 不要求单独一轮「确认」交互（见步骤 3–4）。

## 编排（主 / 子 agent）

- `subAgent` / `switchAgentVerification` 语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`。
- 本技能全程在主 agent 完成（**pull 的确认**不可下放子 agent；`git commit` 不要求单独一轮用户确认，见步骤 3–4）。

# f2s-git-commit（提交代码）

## 强制流程

### 步骤 1：读取变更（只读）

```bash
git status --short
git diff HEAD
```

- 从 `git status --short` 区分三类文件：
  - **Staged**：已 `git add`，前缀为 `M `、`A `、`D `（首列非空）
  - **Unstaged**：已追踪但未 add，前缀为 ` M`、` D`（次列非空）
  - **Untracked**：`??` 前缀，新文件尚未追踪
- 若三类均为空（nothing to commit），直接告知用户并结束。

**冲突检查（必须，先于一切）**：

扫描所有变更文件内容，若任意文件包含 `<<<<<<<`、`=======`、`>>>>>>>` 冲突标记，立即终止并提示：

```
❌ 检测到未解决的 merge conflict：
  - <文件路径>

请先解决冲突后再提交。
```

### 步骤 2：知识库覆盖检查（必须）

**先判断 `.Knowledge/` 是否存在：**

- 若 `.Knowledge/manifest-routing.json` 不存在：跳过本步骤，在步骤 5 收尾提示「项目尚未初始化 Flow2Spec 知识库，建议运行 flow2spec init」，继续步骤 3。

**存在时执行覆盖检查：**

1. 从 `git diff HEAD` 及 untracked 文件路径推断本次变更涉及的**功能模块**（如：支付、订单、用户认证等）。
2. 读取 `.Knowledge/topics/` 目录列表与 `.Knowledge/stock-docs/` 目录列表。
3. 对比步骤 1 推断出的功能模块，判断对应文档是否已在知识库中登记。
4. 得出结论：**已覆盖 / 部分覆盖 / 未覆盖**。

> 判断粗粒度即可：有对应 topic 或 stock-docs 文档即视为已覆盖；若知识库为空或找不到相关文档则视为未覆盖。

**未覆盖或部分覆盖时（必须提示）：**

```
⚠️  本次变更涉及以下能力尚未入知识库：
  - <能力描述>

建议在提交前同步知识库，可选：
  A) 现在运行 f2s-kb-sync 补录，完成后自动继续提交流程
  B) 先提交，稍后手动补录（输入 B 确认）
  C) 取消本次提交（输入 C）
```

- 选 **A**：提示用户运行 `f2s-kb-sync` 或 `f2s-kb-feat` 补录；用户补录完成后在**同一会话声明已补录**或**再次触发本技能**时，从步骤 1 或步骤 3 继续（**不要求**为「继续 commit」单独打字确认，与步骤 3–4 一致）。
- 选 **B**：记录未覆盖能力描述，在步骤 5 收尾提示中输出。
- 选 **C**：终止本技能。

### 步骤 3：生成提交信息草稿（必须）

读取 `git diff HEAD`（内容过长时取前 300 行），基于实际变更内容生成提交信息。

#### 首行格式（必须）：类型图标 + Conventional Commits

**首行**须同时满足：

1. **以一个 emoji 开头**（与下表 `type` 对应，**禁止**用多个装饰 emoji 堆叠）。
2. 紧跟 **一个 ASCII 空格**，再写 **小写 `type`**、英文冒号 `:`、**一个空格**、**中文或英文简述**。
3. **可选 scope**：使用 Conventional 的 `type(scope):`，紧跟在 `type` 之后、冒号之前，例如 `🐛 fix(auth): 修复登录态丢失`。
4. 首行总长度建议 **≤ 72 个字符**（含 emoji；过宽时优先缩短描述）。

**推荐模板（单行）**：

```text
<emoji> <type>[(scope)]: <简述>
```

无 scope 时省略括号段，例如：`🚀 feat: 简述`。

**`type` → 首字符 emoji（固定选用下表，便于检索与发布说明）**：

| `type` | emoji | 典型场景 |
|--------|--------|----------|
| `feat` | 🚀 | 新功能、对用户可见的能力增量 |
| `fix` | 🐛 | 缺陷修复、线上/测试问题 |
| `docs` | 📚 | 仅文档、注释、README、知识库正文类 |
| `style` | 💄 | 纯格式、缩进、分号等不改变行为的排版 |
| `refactor` | ♻️ | 重构、改名、无行为变化的结构调整 |
| `perf` | ⚡ | 性能优化 |
| `test` | 🧪 | 测试用例、测试桩、快照 |
| `build` | 🏗️ | 打包、依赖、编译脚本、artifact |
| `ci` | 👷 | CI 配置、流水线、自动化脚本 |
| `chore` | 🔧 | 杂项、工具脚本、非 build/ci 的维护性改动 |
| `revert` | ↩️ | 回滚某次提交 |

**示例**：

```text
🚀 feat: 支持xxx活动缓存预热
🐛 fix(coupon): 领券窗口边界条件错误
📚 docs: 补充公共模块 QConfig 说明
♻️ refactor: 提取拼团校验为独立函数
🔧 chore: 升级 ESLint 配置
```

**正文（可选）**：第二行起可为列表或段落，**不要求**每行再加 emoji；若需条目，用 `- ` 即可。

**用户已给出首行时**：若已含上表之一且 emoji 与 `type` 一致，**尊重用户文案**；若仅有 `type:` 无 emoji，**须补全 emoji** 再进入步骤 4。

**与 `git commit` 的确认策略（必须）**：

- 在**同一条 assistant 回复**中：**先**展示拟提交说明的**首行**（及可选正文），**随后立即**执行步骤 4（`git add` 逐项 + `git commit`）。**不要求**用户再回复「确认」才允许 commit。
- 若用户在该轮对话中**已先写明**提交说明且合规，可直接使用并进入步骤 4，仍须在执行前**复述首行**再 commit。
- 用户若明确表示「改提交说明 / 换一个 type」：改稿后仍在本策略下**展示即提交**，不增加「请回复确认」门槛。

### 步骤 4：执行提交（展示说明后立即执行）

根据步骤 1 的三类文件分别处理：

```bash
# 1. Unstaged 文件：需先 add
git add <unstaged 文件列表>

# 2. Untracked 文件：需先 add
git add <untracked 文件列表>

# 3. Staged 文件：已 add，无需重复操作

# 执行提交
git commit -m "<步骤 3 定稿的完整提交信息>"
```

- 禁止使用 `git add -A` / `git add .`，仅 add 步骤 1 中明确列出的文件。
- 若 pre-commit hook 失败：输出完整错误信息，提示用户修复后重新触发本技能，**不**使用 `--no-verify` 绕过。
- 若 commit 成功：读取 commit hash（`git rev-parse --short HEAD`）并进入步骤 5。

### 步骤 5：收尾提示

```
✅ commit <hash> 完成
   <提交信息首行>

[若步骤 2 选了 B]
📌 提醒：以下能力仍未入知识库，建议在合并前补录：
  - <能力描述>
  可运行：f2s-kb-sync 或 f2s-kb-feat

[若跳过了步骤 2（.Knowledge 不存在）]
💡 项目尚未初始化 Flow2Spec 知识库，如需接入可运行：flow2spec init
```

## 约束

- 禁止使用 `git add -A` / `git add .`，只 add 已确认的变更文件。
- 禁止 `--no-verify`，hook 失败须修复后重试。
- 禁止 `--amend` 已推送的 commit，除非用户明确要求。
- 禁止自动 push，commit 完成后停止。
- 知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）。
- **`git pull` / `git pull --rebase` / 会改写当前分支工作区内容的 `git fetch` 后续合并操作**：**必须**先向用户说明目的与风险，**取得用户对「拉取」的明确确认**（如用户回复「确认 pull」）后再执行；**禁止**为 commit 而顺带静默 pull。
- **`git commit`**：**不要求**用户单独回复「确认」；但**禁止完全不展示**拟提交首行就执行 commit（须在当条回复中可见首行后再执行）。
- 提交信息**首行**须符合步骤 3 的 **emoji + type** 格式（用户已合规给出时可保留）。
- 存在 merge conflict 标记时必须终止，不得继续。

## 完成后自检

1. 步骤 1 是否检查了 merge conflict（必须为是）。
2. 是否区分了 staged / unstaged / untracked 三类文件（必须为是）。
3. 是否用了 `git add -A` / `git add .`（必须为否）。
4. 知识库检查是否执行或有明确跳过理由（必须为是）。
5. 步骤 3 是否基于 `git diff` 实际内容生成提交信息（必须为是，而非仅 `--stat`）。
6. 执行 commit 前是否在当条回复中**展示了拟提交首行**（必须为是）；**不得**要求用户单独「确认 commit」才执行（与策略一致）。
7. 提交信息**首行**是否为 `<emoji> <type>[(scope)]: <简述>` 且 emoji 与 type 与上表一致（合并 revert 等例外须在展示中说明）。
8. 若 pre-commit 失败，是否跳过了 hook（必须为否）。
9. 若步骤 2 选 B，收尾提示是否包含未补录提醒。
10. 若步骤 2 选 A，是否在用户补录或再次触发后继续流程（**不要求**为继续 commit 单独要确认）。
11. 若本流程中曾需要 `git pull`：是否在执行前取得用户对 **pull** 的明确确认（必须为是）；未涉及 pull 则标 N/A。

Flow2Spec 内置的 Karpathy 式编码纪律：澄清假设、极简实现、手术式修改、可验证目标。默认由同名 topic 规则 alwaysApply 随 init 落盘；显式调用本技能时重申四条。

# 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`**为准。

新增能力时补全实现与知识库；已实现则仅同步知识库；触发：f2s-kb-feat、新增能力

> 执行口径：`f2s-kb-feat` 默认同步 `.Knowledge`，无需用户额外提出"请同步知识库"。

## 编排（主 / 子 agent）

- `subAgent` 与 `switchAgentVerification` 的语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本处不复述。
- **代码子包**（新增 / 修改实现代码）：`subAgent=true` 时可外包给子 agent 执行。
- **文档子包**（rules / skills / topics / stock-docs 文风类改动）：默认不拆，由主 agent 写，以保证「现行真值覆盖 / 篇幅上限 / 禁历史否定堆砌」等文风合规。
- 若确需外包文档改动：子侧只输出「原位替换 diff」（before / after 小段），不得整文件重写；主合并落盘。
- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘，子 agent 不得触碰。
- 落盘侧自验。

# /新增能力（f2s-kb-feat）

## 输入

- 用户描述新增能力、场景、边界、可选路径。

## 步骤

**步骤 0：变更追踪（仅当 `changeTracking.feat: true`）**

执行前读取 `flow2spec.config.json`，若 `changeTracking.feat: true`：

- 检查 `.task/todo.json` 是否存在活跃任务，将用户描述与 `keywords` 匹配。
- 命中 → 加载对应 `task.md`，展示剩余清单，在已有任务中继续。
- 无命中 → 创建新任务（见 `f2s-task` 规则），将步骤 1–4 写入 `task.md` 作为任务 checklist。
- **执中必写盘**：每完成 `task.md` 中一步，**同一会话内**立即 `Edit` 将该步 `[ ]`→`[x]`；禁止把打钩积压到「收尾/归档」一步、禁止口头完成代替写盘（见 `f2s-task`「中断与会话结束」「归档门禁」）。
- **用户代办**：凡须用户改库、配环境、点平台等项，**同会话内**追加写入 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`）；新建任务时若尚无代办，仍应创建该文件（可占位）。

1. 判断能力状态：未实现 / 部分实现 / 已实现。
2. 补齐代码实现（已实现则跳过此步）。
3. 同步知识库（默认执行）：
   - `.Knowledge/stock-docs/`：能力说明与使用方式
   - `.Knowledge/topics/`：新增/修订主题规则与流程
   - `.Knowledge/index.md`：主题索引
   - 路由清单：路由或依赖变化时最小更新
4. 输出摘要（能力点、实现、知识库变更）。

## 输出摘要格式（建议）

```markdown
## 新增能力：<能力名>

### 能力范围
- <能力点1>
- <能力点2>

### 实现
- <文件路径>：<改动说明>（若未改代码则写"已有实现"）

### 知识库
- .Knowledge/stock-docs/<文件>.md：<新增/修订说明>
- .Knowledge/topics/<topic>.md：<新增/修订说明>
- .Knowledge/index.md：<更新说明>
- .Knowledge/manifest-routing.json：<是否更新与原因>
- .Knowledge/matchers/<id>.json：<是否更新 includeAny 与原因>
```

## 复杂场景示例

用户要求"新增失败重试队列能力"，且代码中已有半成品实现。

- 先判断为"部分实现"，补齐缺口代码而非重做整模块。
- 同步新增或修订 `topics/retry-queue.md`，并更新 `index` 入口说明。
- 若该能力需任务路由命中（如"重试队列改造"），补充 `manifest.taskToTopicRules`。

## 约束

- 与旧约定冲突时：**改写到当前真值**，不要另起「（不再与某 X 有关）」等历史否定句。
- 与现有主题重合时优先原位更新。
- 至少落一处知识库更新，避免"代码有了但不可检索"。
- 不改配置根 `rules/skills`。
- 文档子包默认不拆；必要外包子侧仅出 before/after diff 片段，主合并落盘；`manifest-routing.json` / `.Knowledge/index.md` 恒主落盘（写权硬约束）。

## 知识库落盘文风（必须，防赘述）

写 `stock-docs` / `topics` / `index` 时遵守：

1. **增量最小**：只追加或改写与**本次能力**直接相关的句段；禁止因「同步知识库」而全文重述背景、需求复述、与实现无关的教程式铺垫。
2. **现行真值覆盖（禁止历史否定堆砌）**：约定从「与 A 有关」变为「与 B 有关」等时，应**删除或原位改写**与旧约定冲突的句子，正文只写**当前成立**的关系（例如直接写与 B 的边界与流程）。**禁止**在正确句后再叠「（不再与 A 有关）」「已与 A 脱钩」「原与 A 有关现已改」等括号、脚注或对照旧版的赘述。仅在用户明确要求写「迁移 / breaking 说明」时，可单开一小节简要列旧→新，且仍避免正文逐句否定旧版。
3. **不重复叙事**：同一事实在 `stock-docs` 与 `topics` **不要各写一长篇**；择一处写清可执行约定，另一处用短段落 + 链接指向，或仅列要点与引用路径。
4. **条文化优先**：`topics` 以规则、边界、步骤、错误与配置要点为主；能用列表/表格表达的不用长段落。
5. **篇幅上限（软约束）**：单次同步中，对**同一文件**的新增正文合计不宜超过约 **80 行**（不含代码块行）；超出则拆分为新 topic、或先写「摘要 + 详见代码路径/另一文档」，禁止单文件堆叠重复说明。
6. **`index.md`**：只改与本次主题相关的行/表项，禁止整表或整节复制粘贴式刷新。
7. **禁止**：重复解释 Flow2Spec 目录分工、重复贴用户对话全文、与本次 diff 无关的「历史回顾」大段。

## 完成后自检

1. 能力描述与代码实现是否一致。
2. 新增能力是否可通过 topic 被检索。
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` 已存在；有用户代办时内容已与会话结论一致。

根据用户指出的实现或规则错误修正代码，并默认同步知识库；触发：f2s-kb-fix、修正实现规则

> 执行口径：`f2s-kb-fix` 默认"修代码 + 同步 `.Knowledge`"，无需用户额外要求"请同步知识库"。

## 编排（主 / 子 agent）

- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本处不复述。
- 代码子包（bug 修复类实现代码）：`subAgent=true` 时可外包给子 agent 执行。
- 文档子包（rules / skills / topics / stock-docs 等文风类改动）：默认不拆，由主 agent 直接编写，以保证「现行真值覆盖 / 篇幅上限 / 禁历史否定堆砌」等文风合规。
- 若确需外包文档改动：子侧**只输出「原位替换 diff」**（before / after 小段），**不得整文件重写**；由主 agent 合并落盘。
- 写权硬约束：`manifest-routing.json` / `.Knowledge/index.md` 恒由主 agent 落盘，子 agent 不得触碰。
- 落盘侧自验。

# /修正能力（f2s-kb-fix）

## 输入

- 用户描述违规点、正确写法、可选范围。

## 步骤

**步骤 0：变更追踪（仅当 `changeTracking.fix: true`）**

执行前读取 `flow2spec.config.json`，若 `changeTracking.fix: true`：

- 检查 `.task/todo.json` 是否存在活跃任务，将用户描述与 `keywords` 匹配。
- 命中 → 加载对应 `task.md`，展示剩余清单，在已有任务中继续。
- 无命中 → 创建新任务（见 `f2s-task` 规则），将步骤 1–4 写入 `task.md` 作为任务 checklist。
- **执中必写盘**：每完成 `task.md` 中一步，**同一会话内**立即 `Edit` 将该步 `[ ]`→`[x]`；禁止积压打钩或口头完成代替写盘（见 `f2s-task`「中断与会话结束」「归档门禁」）。
- **用户代办**：凡须用户改库、配环境、回归验证等项，**同会话内**追加写入 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`）；新建任务时若无代办可写占位说明。

1. 明确违规点与影响范围（不清先追问）。
2. 修复代码实现。
3. 同步知识库（默认执行）：
   - `.Knowledge/stock-docs/`：修订约定说明
   - `.Knowledge/topics/`：修订对应主题规则/流程
   - `.Knowledge/index.md`：更新主题索引
   - 路由清单：若路由受影响则最小更新
4. 输出摘要（代码改动 + 知识库改动）。

## 输出摘要格式（建议）

```markdown
## 修正结果：<约定简述>

### 代码
- <文件路径>：<改动说明>

### 知识库
- .Knowledge/stock-docs/<文件>.md：<新增/修订说明>
- .Knowledge/topics/<topic>.md：<新增/修订说明>
- .Knowledge/index.md：<更新说明>
- .Knowledge/manifest-routing.json：<是否更新与原因>
- .Knowledge/matchers/<id>.json：<是否更新与原因>
```

## 复杂场景示例

用户指出"订单回调幂等实现错误"，但未给明确文件范围。

- 先按最小可行范围修复已定位的回调处理链路，并在摘要中说明"可继续扩展全仓同类修复"。
- 同步更新 `topics` 中幂等规则段落，避免后续再次生成错误实现。
- 若该修复影响任务路由（例如新增"幂等修复"主题），再最小更新 `manifest`。

## 约束

- 与旧约定冲突时：**改写到当前真值**，不要叠写「（不再与某 X 有关）」等对照旧版的赘句。
- 同主题优先原位更新。
- 范围不明时按最小可行范围修复并说明。
- 不改配置根 `rules/skills`。
- 文档子包默认不拆；必要外包子侧仅出 before/after diff 片段，主合并落盘；`manifest-routing.json` / `.Knowledge/index.md` 恒主落盘（写权硬约束）。

## 知识库落盘文风（必须，防赘述）

写 `stock-docs` / `topics` / `index` 时遵守：

1. **增量最小**：只改与**本次修复**直接相关的段落或列表项；禁止借机重述整份方案、整段历史背景或与修复无关的说明。
2. **现行真值覆盖（禁止历史否定堆砌）**：修复后约定从「与 A 有关」变为「与 B 有关」等时，应**删除或原位改写**仍写着旧约定的句子，正文只保留**当前成立**的表述。**禁止**叠写「（不再与 A 有关）」「原错误地与 A 绑定」等对照旧版的括号或脚注；除非用户明确要求「迁移说明」，否则不写旧→新对照长文。
3. **不重复叙事**：`stock-docs` 与 `topics` 不就同一修复各写长篇；一处写清「错因 / 正确约定 / 注意点」，另一处简短引用或链到该段。
4. **条文化优先**：以「错误表现 → 根因 → 正确行为 / 边界」为序的短列表为主，避免散文式展开。
5. **篇幅上限（软约束）**：单次同步中，对**同一文件**的新增或替换正文合计不宜超过约 **60 行**（不含代码块行）；超出则只保留与修复相关的最小说明，其余用「见提交/见某路径」代替。
6. **`index.md`**：仅更新受影响的索引行或摘要列，禁止无关整表重写。
7. **禁止**：重复粘贴用户报错全文（可摘一行标识 + 链接）、重复解释 Flow2Spec 用法。

## 完成后自检

1. 代码修复是否覆盖用户点名范围。
2. 主题文档是否与修复后的实现一致。
3. `index` 是否指向正确主题。
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` 已存在；有用户代办时内容已与会话结论一致。

解决 Git 合并后编辑器上下文冲突；可选传入冲突文件；实现侧冲突仅罗列待用户确认；触发：合并上下文冲突、f2s-kb-merge

## 编排（主 / 子 agent）

- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。
- **子 agent 职责**（仅当 `subAgent=true`）：只做**冲突扫描 + 按类别对照表**，每条包含五字段 —— `file` / `category`（文档索引 / 总览规则 / 模块规则 / 技能 / 说明文档 / 实现类 / 依赖元数据）/ `ours_summary` / `theirs_summary` / `recommendation`（并集 / 保留某侧 / 并入必须项 / 待用户选）。
- **子 agent 不出成品合并稿**，避免主 agent 二次重写。
- **主 agent 职责**：按策略落盘 + 实现类决策 + 验收。
- 默认落盘侧自验，本技能不绑定交叉校验。

# /合并上下文冲突（f2s-kb-merge）

在 **rebase / merge** 后出现 `<<<<<<<` / `=======` / `>>>>>>>` 时，优先**自动合并「AI 与开发者上下文」相关文件**，保证索引、规则、技能与说明文档互相对齐；**涉及可执行实现、部署或依赖声明的冲突不擅自合并**，需**向用户展示双方差异并等待确认**后再改。

## 传参（可选）

- **不传参**：在工作区内**自行检索**仍存在冲突标记的文件，再按本技能分类与策略处理（含全量扫描后的摘要）。
- **传参**：用户可指定**一个或多个仍含冲突的文件**（随消息 @ 文件或列出路径均可）。助手**优先只处理这些文件**中的冲突；若其中含「禁止自动合并」类别，仍只罗列差异与建议，**不擅自写入**。指定文件处理完毕后，可询问用户是否需要对工作区做**补充扫描**。

## 适用范围（可自动合并）

以下**类别**内的冲突，按本技能**合并策略**处理，**无需**逐行征求确认（除非两侧表述**互斥**且无法判断应以何为准）：

| 类别                 | 说明                                                                 |
| -------------------- | -------------------------------------------------------------------- |
| 文档索引             | 承载「文档 ↔ 规则 / 技能」映射的索引表文件                           |
| 项目总览规则         | 规则目录中的总入口文件                                               |
| 模块规则             | 同套规则目录下的其余规则片段                                         |
| 技能                 | 技能目录下的 SKILL 说明文件                                          |
| 上下文说明文档       | 与规则、技能配套的说明类 Markdown                                    |
| 索引联动的纯说明文档 | 由项目约定存放、仅被索引或规则引用、**不含可执行实现语义**的说明文档 |

## 禁止自动合并（须用户确认）

以下冲突**不得**在未获用户明确选择前合并：

- **应用或服务实现源码**（业务逻辑、接口实现、数据访问等）
- **会改变对外暴露行为**的配置（路由、函数注册、中间件链、运行入口等）
- **依赖与构建元数据**（依赖声明、锁文件、构建与部署脚本等）
- **集中维护外部资源清单的实现模块**：若两侧**条目集合或注册内容不同**，属运行行为差异，须用户确认保留范围（助手可建议「并集 + 去重」，**待用户同意**后再写入）

**处理方式**：列出冲突文件、简述两侧意图，给出推荐方案，**请用户选定**后再改上述范围中的文件。

## 合并策略（上下文类）

1. **删除所有** Git 冲突标记（`<<<<<<<` / `=======` / `>>>>>>>`），不得残留。
2. **索引表**
   - 同一索引行的 **Rules / Skills / 链接列**：做**并集**，路径去重、空格分隔。
   - 仅在一侧出现的**独立索引行**：合并后**保留**，避免丢失条目。
3. **总览规则**
   - 同一主题下多条 bullet：合并为**信息完整的单条或并列多条**，**不丢弃**任一侧独有的约束或引用。
4. **长文档中的表格**
   - 描述**不同维度能力**的行：**并集保留**。
   - 描述**同一主题**的重复行：合并为**一条**连贯表述，涵盖两侧要点。
5. **rules / skills**
   - 优先保留**更具体、约束更清晰**的表述；另一侧独有的**必须 / 禁止**条款**并入**，避免规则回退。
6. **链接与路径**
   - 统一为仓库内可解析的相对路径，并与总览规则中的索引入口一致。

## 执行步骤

1. **确定范围**：若用户已指定冲突文件，仅以这些文件为范围；否则全工作区检索冲突标记（或结合 IDE 冲突列表）。再按**适用范围**分类。
   - 若启用拆子，子 agent 按子交付对照表 schema（`file` / `category` / `ours_summary` / `theirs_summary` / `recommendation` 五字段）产出分类表；主 agent 接手后续落盘 / 决策 / 验收步骤。
2. **上下文类**：按合并策略直接修改并保存。
3. **实现类**：只输出对比摘要与建议，**不修改文件**直至用户确认。
4. **输出摘要**（Markdown）：已解决文件 + 要点；待确认文件 + 两侧差异 + 建议。
5. 对**已处理文件**再次确认**无**冲突标记残留；若未做全量扫描，可提示用户是否补充扫描。

## 与相关命令的关系

- **`/修正实现规则`（f2s-kb-fix）**：用户已指明问题点后的**定向修正**与文档/规则同步。
- **本技能**：合并产生的**批量冲突**，侧重**编辑器上下文与说明文档**同**实现侧**分离处理。

## 何时使用

- merge / rebase 后，**规则 / 技能 / 索引 / 配套说明文档**出现冲突（可全量处理，也可只处理用户指定的冲突文件）。
- 需要一次性对齐「索引 ↔ 规则 ↔ 技能 ↔ 说明文档」，且**避免误合并实现或部署相关改动**时。

旧版知识库一次性迁到 `.Knowledge`：以配置根 `docs-index.md` + 规则统一入口（旧版 `rules/main.md(c)` 或新版包 `rules/f2s-flow2spec-unified-entry.md(c)`）为主索引线索，全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能），并全量迁移 `stock-docs`/`req-docs`；**迁移验收后必选**落盘 `.Knowledge/migration-report.md`（迁移对照表 + 拟删除路径列表）；**收尾必选**删除已迁旧的 `rules/`、已迁业务 `skills/`、旧版 `docs-index.md`/`index-doc.md`；用户只**核对/修订删除清单（排除项）**；触发：f2s-kb-migrate、知识库迁移、旧版迁移

> 执行口径：这是 `f2s-*` 技能流程，不是 CLI 子命令。迁移目标包含：
> 1) 结构层：`.Knowledge/topics`、`.Knowledge/index.md`、`.Knowledge/manifest-routing.json`、`.Knowledge/matchers/*.json`
> 2) 文档层：`.Knowledge/stock-docs`、`.Knowledge/req-docs`
>
> **硬边界**：`skills/f2s-*`（各 agent 配置根下）属于 Flow2Spec 包技能/执行层能力，**不得**写入 `.Knowledge`（含 `topics/stock-docs/req-docs`），也不得作为“业务技能迁移”的源；**不得**在本流程中删除（版本对齐走 `flow2spec init` / 包升级）。
>
> **基线规则保留清单（不得删除）**：`rules/f2s-flow2spec-unified-entry.md(c)`、`rules/f2s-implement-tech-design.md(c)`、`rules/f2s-stock-docs-vs-req-docs.md(c)`。

## 编排（主 / 子 agent）

- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
- **子 agent 职责**（仅当 `subAgent=true`）：在主给定清单下做搬运工作、生成 `migration-report.md` 的**草案片段**；产出一律以 patch 形式提交，由主 agent 合并落盘。
- **主必控**：
  - `.Knowledge/.migrate-state.json` **写权归主**（状态机事实源，主 / 子抢写会致队列错位）；
  - `migration-report.md` 的 **「删除执行记录」** 小节恒由主 agent 追加；
  - **删除清单确认**与闭环收尾必主完成。
- **写权硬约束**：`manifest-routing.json` / `.Knowledge/index.md` / `.Knowledge/.migrate-state.json` / 迁移报告「删除执行记录」均恒由主 agent 落盘。
- 默认落盘侧自验；本 SKILL 不绑定交叉校验。

# f2s-kb-migrate（旧版知识库 -> 新版知识库）

## 与 `f2s-kb-upgrade` 为何并存

| 技能 | 解决的问题 |
| --- | --- |
| **本技能 `f2s-kb-migrate`** | **一次性结构搬家**：旧索引（`docs-index.md` / `index-doc.md`）、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **`.Knowledge`**，并处理删除清单与 `migration-report.md`。 |
| **`f2s-kb-upgrade`** | **知识库模板升级技能（唯一「升级」口径）**：按 **`skills/f2s-kb-upgrade/SKILL.md`** 全文执行；其中代跑 **`flow2spec init`** 以对齐 **`manifest-routing` + `matchers/`** 与各 agent **`rules`/`skills`**；含 **V1 / 现行库（V2+）** 分流（旧项目须 **migrate 后再跑本技能**；**V2+ 含 npm v3.x 等已上 `.Knowledge` 的项目**，见 `f2s-kb-upgrade` 步骤 0）。 |

- **迁移验收、删除清单确认完成后**：应提醒或代用户执行 **`f2s-kb-upgrade` 技能全文**（其中 **步骤 2** 会代跑 **`flow2spec init`**），把 Flow2Spec 包版本、路由分片与配置根产物对齐到当前包。**勿**让用户以为「单独执行 `init`」即完成知识库模板升级。
- **已在稳定使用 `.Knowledge` 且无旧索引负担的项目**：不要重复跑本技能；日常包/模板对齐走 **`f2s-kb-upgrade`** 技能即可（不是只跑 `init`）。

**为何各 agent 下都有同名 `SKILL.md`？** 各工具只读各自配置根下的 `skills/`；`flow2spec init` 会向所选 agent **同步** `templates/skills/` 中的内容。

## 本命令做什么（对外口径）

把旧版“散落在配置根的文档索引 + 规则 + 业务技能 + stock/req 文档树”，**整体搬迁并改写到新版 `.Knowledge`**，完成后再做**旧版入口与旧版业务产物清理**，实现与旧版知识库组织方式的切割。

必须覆盖的对象：

1. **索引入口**：配置根 `docs-index.md`（兼容 `index-doc.md`）中声明/映射到的业务文档与规则线索。
2. **规则入口**：`rules/main.md` / `rules/main.mdc`（旧版常见）或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容历史命名 `rules/flow2spec-unified-entry.md(c)`）中声明/引用的规则集合（以及 `rules/` 下其它业务规则文件）。
3. **业务技能**：各 agent 配置根 `skills/` 下除 `f2s-*` 以外的业务技能目录（全量盘点）。
4. **文档树**：旧版 `stock-docs/`、`req-docs/`（或同义目录）**全量**迁入 `.Knowledge` 对应目录。

对“索引未覆盖”的对象：

- 先输出候选清单（路径 + 推断理由：命名/目录/引用关系）。
- **默认必须让用户确认**是否纳入迁移；仅当证据非常充分（例如被 `rules/main` / `f2s-flow2spec-unified-entry` 显式引用、或被已索引文档明确引用）才允许 Agent 自行判定纳入，并在迁移摘要中写明判定依据。

迁移完成后的清理（**必选收尾**；且迁移结果无失败、无待确认项；**`skills/f2s-*` 永不删除**）：

- **必须执行**：删除旧版 **`rules/` 中已迁移业务规则文件**（含 `main.md(c)` 若仅作为旧入口），但**不得删除**基线规则保留清单中的 3 个 `f2s-*` 根规则文件。
- **必须执行**：删除旧版 **业务** `skills/` 下**已迁移**的子目录（**排除** `f2s-*`；若某目录下仍有未迁完项则不得删该目录，须先补齐或从清单剔除）。
- **必须执行**：删除旧版入口 **`docs-index.md`**（兼容 **`index-doc.md`**），避免与 `.Knowledge/index.md` 双入口并存。
- **默认一并列入删除子清单**（用户可在清单中排除）：旧版 **`stock-docs/`**、**`req-docs/`** 源目录（仅当对应文档层迁移验收通过、无失败/无待确认项时执行实际删除）。

**用户确认的含义（重要）**：

- **不是**询问「要不要做清理」；清理是流程的一部分。
- **而是**输出**默认全选的「删除路径清单」**（规则文件逐条、业务 skill 目录逐条、索引文件名、以及可选的旧文档根目录），请用户**核对**；用户只能：
  - 回复「**确认清单**」按当前清单执行删除；或
  - 回复「**排除：<路径…>**」从清单中移除指定项后再执行（移除项须写入 `.migrate-state.json` 的 `notes[]` 并说明原因）。
- 若用户要求**暂缓删除某路径**，须在清单中保留该项并结束本轮清理（状态文件 `status=paused`），**不得**假装已完成迁移闭环。

## 适用场景

- 项目仍在使用旧版知识组织（`docs-index.md` / `index-doc.md` + `rules/main.md(c)` 或 `rules/f2s-flow2spec-unified-entry.md(c)`（兼容旧 `flow2spec-unified-entry.md(c)`）+ 业务 `skills/` + 散落 `stock-docs`/`req-docs`）。
- 希望迁移到新版 `.Knowledge`，并且按主题逐个确认，避免一次性大改。
- 需要 **req-docs / stock-docs 全量** 迁入 `.Knowledge`，并与旧版知识库目录/表述做切割（路径、索引、主题文案统一到新架构口径）。

## 输入

- 可选输入：
  - 旧版规则统一入口路径：`rules/main.md` / `rules/main.mdc` 和/或 `rules/f2s-flow2spec-unified-entry.md` / `rules/f2s-flow2spec-unified-entry.mdc`（兼容旧 `rules/flow2spec-unified-entry.md(c)`）
  - 旧版 `index-doc.md`（或 `docs-index.md`）路径
  - 旧版存量文档目录（如 `stock-docs/`、`docs/stock/`）
  - 旧版需求文档目录（如 `req-docs/`、`docs/req/`）
  - 迁移范围（全部主题 / 指定主题）
- 不提供时，先在仓库中定位上述文件并向用户确认。

## 断点续迁状态文件（必须启用）

- 状态文件路径：`.Knowledge/.migrate-state.json`
- 作用：记录迁移进度，支持会话中断后恢复，不重复迁移已完成项。
- 初始化时机：用户确认“开始迁移”后立即创建。
- 结束时机：
  - 全部迁移完成且用户确认结束：删除状态文件。
  - 用户主动“停止”：保留状态文件，等待下次恢复。
- `.migrate-state.json` 只由主 agent 写；子 agent 以 patch 片段提交由主合并（写权硬约束）。

建议字段（最小集）：

```json
{
  "version": "1",
  "status": "running",
  "currentStage": "inventory|orphans|topics|stock-docs|req-docs|cleanup",
  "topicQueue": [],
  "topicDone": [],
  "bizRuleQueue": [],
  "bizRuleDone": [],
  "bizSkillQueue": [],
  "bizSkillDone": [],
  "stockQueue": [],
  "stockDone": [],
  "reqQueue": [],
  "reqDone": [],
  "pendingManual": [],
  "failed": [],
  "notes": [],
  "updatedAt": "ISO-8601"
}
```

更新规则（必须执行）：

1. 每完成 1 个主题、1 个业务技能目录、1 个业务规则文件或 1 个文档文件后，立即落盘更新状态文件。
2. 收到“重试 <topic|file>”时，先回滚该项状态，再执行重试。
3. 收到“继续”时，优先读取状态文件，从未完成队列继续。
4. 收到“停止”时，写入 `status=paused` 并结束本轮。
5. 收到恢复请求时，先展示状态摘要（当前阶段、剩余数量、失败/待确认项）并等待用户确认继续。

## 强制流程（分阶段执行）

### 步骤 1：读取旧版映射

1. 读取 `docs-index.md`（兼容 `index-doc.md`），提取“业务文档 -> 规则/主题”映射（**主索引**）。
2. 读取 **`rules/main.md`（兼容 `main.mdc`）** 或 **`rules/f2s-flow2spec-unified-entry.md`（兼容 `f2s-flow2spec-unified-entry.mdc`；兼容旧 `flow2spec-unified-entry.md(c)`）**（二者通常只存在其一），提取模块/主题目录线索（**与索引交叉校验**）。
3. **全量盘点业务规则文件**：扫描 `rules/` 下除以下文件外的业务规则文件，建立 `bizRuleQueue`（去重）：
   - 统一入口：`main.md(c)`、`f2s-flow2spec-unified-entry.md(c)`、`flow2spec-unified-entry.md(c)`（兼容旧命名）
   - 基线保留：`f2s-implement-tech-design.md(c)`、`f2s-stock-docs-vs-req-docs.md(c)`
4. **全量盘点业务技能**：扫描各 agent 配置根 `skills/` 目录，**排除** `f2s-*`，其余目录一律进入 `bizSkillQueue`（去重）。
5. 扫描旧版 `stock-docs` 与 `req-docs` 候选来源目录（若存在）。
6. 生成待迁移清单并展示给用户确认：
   - 主题清单（去重、排序）
   - 业务规则文件清单（`bizRuleQueue`）
   - 业务技能目录清单（`bizSkillQueue`）
   - `stock-docs` 文件清单
   - `req-docs` 文件清单
7. 文档分类口径（必须明确）：
   - 来源路径命中 `stock-docs`（含同义目录如 `docs/stock`） -> 迁移到 `.Knowledge/stock-docs`
   - 来源路径命中 `req-docs`（含同义目录如 `docs/req`） -> 迁移到 `.Knowledge/req-docs`
   - 无法判定的文件 -> 列入“待人工确认清单”，未确认前不迁移
8. 计算“索引外候选”（`orphans`）：
   - `bizRuleQueue` 中未被 `docs-index` / 统一入口（`rules/main` 或 `f2s-flow2spec-unified-entry`）覆盖的文件
   - `bizSkillQueue` 中未被索引映射覆盖的目录
   - 对每一项默认要求用户确认是否迁移；仅在高置信引用场景允许 Agent 自判纳入，并将依据追加写入状态文件 `notes[]`（不得破坏 JSON 可解析性）。
9. 用户确认清单后，初始化状态文件并写入队列（inventory/orphans/topics/stock/req）。

### 步骤 2：逐主题迁移（结构层核心）

对每个主题按以下顺序执行：

1. 汇总该主题旧资料：
   - 相关 `rules/*.md(c)`（业务规则）
   - 相关 **业务** `skills/<非 f2s-*>`（将其内容合并进主题叙述/流程，不复制为 `.Knowledge` 下的技能文件）
   - 索引映射中的**业务文档**路径
   - **不得**包含 `skills/f2s-*` 下任何文件
2. 生成或更新 `.Knowledge/topics/<topic>.md`：
   - 正文表述统一为新架构口径（`.Knowledge` 分层、`manifest` 路由、`stock-docs`/`req-docs` 分工）。
   - 去除旧版独有路径/术语（如旧 `docs-index` 根路径、旧散落目录名），改为指向 `.Knowledge/...` 或相对 `.Knowledge` 的稳定路径。
3. 更新 `.Knowledge/index.md` 的主题索引行，并同步维护“关联文档（摘要）”列（每主题 1-3 条关键 `stock-docs/req-docs` **可点击 Markdown 链接**，格式：`[标题](相对路径)`）。
4. 按需更新路由清单：
   - `.Knowledge/manifest-routing.json`：`topicPaths`、`taskToTopicRules[]`、`topicDependencies`、`fallbackTopic`
   - `.Knowledge/matchers/<matcherId>.json`：`includeAny`（与 `manifest-routing.taskToTopicRules[].matcherPath` 一致）
5. 输出本主题迁移摘要并**暂停**，提示用户：
   - 回复“继续”迁移下一个主题
   - 或回复“停止”终止本轮
   - 或回复“重试 <topic>”重做当前主题

> 未收到“继续”前，不得迁移下一个主题。
> 每完成一个主题，必须先更新状态文件再进入等待。

### 步骤 3：迁移 `stock-docs`（文档层）

当步骤 2 全部完成后，执行：

1. 按“来源目录相对路径”迁移到 `.Knowledge/stock-docs/<relative-path>`，不做平铺。
2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。
3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。
4. 全部完成后输出 `stock-docs` 子摘要（成功/失败/待确认）。

> 未收到“继续”前，不得迁移下一个文件。
> 每完成一个文件，必须先更新状态文件再进入等待。

### 步骤 4：迁移 `req-docs`（文档层）

当 `stock-docs` 阶段完成后，执行：

1. 按“来源目录相对路径”迁移到 `.Knowledge/req-docs/<relative-path>`，不做平铺。
2. 默认场景视为在旧版仓库首次迁移到新版知识库，目标路径按“不存在”执行。
3. 每迁移 1 个文件输出一次结果并暂停，等待“继续 / 停止 / 重试 <文件>”。
4. 全部完成后输出 `req-docs` 子摘要（成功/失败/待确认）。

> 未收到“继续”前，不得迁移下一个文件。
> 每完成一个文件，必须先更新状态文件再进入等待。

### 步骤 5：全部迁移完成后的收尾（必选：迁移报告落盘 + 删除清单确认）

当主题（步骤 2）与文档层 `stock-docs` / `req-docs`（步骤 3–4）**全部验收通过**（无失败、无阻塞性待确认项，或已在报告中单列）后，按顺序执行以下子步骤。

#### 5.0 迁移报告（必选：写入项目 Markdown）

1. **必须**在项目仓库中创建或覆盖文件：**`.Knowledge/migration-report.md`**（相对项目根；与 `.Knowledge` 同库，便于评审与留痕）。
2. 报告正文须至少包含两大块（可用表格或分级列表，路径一律用**相对项目根**的 POSIX 风格）：
   - **「迁移对照表」**：
     - **主题**：每个已迁移 `topic` → 旧侧来源（对应 `rules/*.md(c)`、业务 `skills/<dir>`、`docs-index` 映射行摘要）→ 新路径 `.Knowledge/topics/<topic>.md`；并注明本次是否改写了 `.Knowledge/index.md` / 路由清单相关字段。
     - **`stock-docs`**：每条 **源路径 → `.Knowledge/stock-docs/...` 目标路径**（含跳过的文件及原因，若无则写「无」）。
     - **`req-docs`**：同上。
   - **「拟删除路径清单」**：与下文步骤 5.2 中向用户展示的**默认全选删除清单**逐项一致（`rules/` 下每个文件、业务 `skills/` 下每个待删目录、`docs-index`/`index-doc`、以及可选列入的旧 `stock-docs/`/`req-docs/` 根目录）；每条建议用 `- [ ] <路径>`，便于人类勾选核对。
3. 若用户随后在步骤 5.2 中发出 **「排除：<路径…>」**，须在**执行物理删除前**更新同一文件：追加或在「用户排除项」小节中写明排除路径与原因，并同步更新「拟删除路径清单」勾选状态或列表，使**磁盘上的报告与最终删除集合一致**。
4. 在步骤 5.2 第 3 步按最终清单**执行完物理删除后**，须在**同一文件末尾**追加小节 **`## 删除执行记录`**（含执行时间、实际已删路径列表；未删项注明原因与 `status=paused` 等），不得仅留在对话里。
5. 迁移报告的「删除执行记录」小节恒由主 agent 追加，子 agent 不得直接写入（写权硬约束）。

> **禁止**：未完成 `.Knowledge/migration-report.md` 落盘即进入物理删除或结束本轮迁移闭环。

#### 5.1 总摘要（对话内，可与报告摘要一致）

- 已迁移主题列表
- 新增/更新的 `.Knowledge` 文件
- 已迁移 `stock-docs` 文件
- 已迁移 `req-docs` 文件
- 未迁移或失败项

#### 5.2 必选清理阶段（删除清单确认，不得跳过）

1. 输出**默认全选**的「**删除路径清单**」（须与 `migration-report.md` 中「拟删除路径清单」同源），至少包含：
   - 旧版 **`rules/`** 下每个将删除的**业务规则**文件路径（可含 `main.md(c)`；**不含**基线保留清单中的 `f2s-*` 根规则）
   - 旧版 **业务** `skills/` 下每个将删除的子目录路径（**不含** `f2s-*`）
   - 旧版 **`docs-index.md` / `index-doc.md`**
   - （可选子清单）旧版 **`stock-docs/`**、**`req-docs/`** 根目录：仅当文档迁移验收通过且无待确认项时列入；用户可排除。
2. 等待用户回复 **「确认清单」** 或 **「排除：<路径…>」** 更新清单；**禁止**使用「是否执行清理」类二选一提问。
3. 按**最终清单**执行删除；**不得**删除清单外的路径；**不得**删除 **`skills/f2s-*`**。
4. 收尾完成后处理状态文件：
   - 本轮完整完成：删除 `.Knowledge/.migrate-state.json`
   - 本轮暂停/中止：保留 `.Knowledge/.migrate-state.json`（`status=paused`），并记录未删路径与原因

## 输出摘要格式（建议）

```markdown
## 主题迁移完成：<topic>

### 来源
- rules: <旧路径...>
- 业务文档: <索引映射中的文档路径...>
- 映射: <docs-index / index-doc 行或文档名>

### 已写入
- .Knowledge/topics/<topic>.md
- .Knowledge/index.md（更新 <x> 行）
- .Knowledge/manifest-routing.json（更新字段：...）
- .Knowledge/matchers/<id>.json（更新 `includeAny` 等：...）

### 下一步
- 回复“继续”迁移下一个主题
- 回复“停止”结束迁移
```

```markdown
## 文档迁移完成：<stock-docs|req-docs>/<file>

### 来源
- source: <旧路径...>

### 已写入
- .Knowledge/<stock-docs|req-docs>/<relative-path>

### 下一步
- 回复“继续”迁移下一个文件
- 回复“停止”结束迁移
```

## 约束

- 必须逐主题确认，不可批量跳过确认直接全量迁移。
- `stock-docs` / `req-docs` 必须逐文件确认，不可无确认批量迁移。
- 文档迁移必须保留来源目录相对路径，不可平铺为单层文件名。
- **`f2s-*` 技能不得进入 `.Knowledge`，不得在主题迁移中合并进 `topics`。**
- **业务** `skills/`（非 `f2s-*`）必须纳入全量盘点；索引未覆盖项默认必须用户确认后才可迁移。
- 未完成全部主题前，禁止删除旧业务 `rules/` 与**非 `f2s-*`** 的旧业务 `skills/`；基线保留清单中的 `f2s-*` 根规则文件始终不得删除。
- 未完成文档迁移前，禁止删除旧文档目录。
- 删除旧目录前必须完成「**删除路径清单**」核对（允许排除项），**禁止**用「是否清理」替代清单确认。
- 迁移过程只改 `.Knowledge` 与（**最终删除清单**确认后）对清单内旧路径的删除，不改业务代码。
- 必须维护 `.Knowledge/.migrate-state.json`，禁止只在内存中维护迁移进度。
- 主题与文档层迁移验收通过后，**必须先**写入 `.Knowledge/migration-report.md`（含迁移对照表与拟删除路径清单），再进入物理删除；报告与对话内删除清单须同源可追溯。
- `.migrate-state.json` / `migration-report.md` 的删除执行记录 / `manifest-routing.json` / `.Knowledge/index.md` 均恒主落盘。

## 迁移报告模板（落盘 `migration-report.md` 时建议结构）

以下骨架可直接复制后填空；路径均为相对项目根。

```markdown
# 知识库迁移报告

- **生成时间（ISO-8601）**：<...>
- **配置根（如 `.cursor/`）**：<...>

## 迁移对照表

### 主题（旧来源 → 新路径）

| topic ID | 旧 rules / 旧业务 skills / 索引线索 | 新路径 |
| --- | --- | --- |
| <id> | <...> | `.Knowledge/topics/<id>.md` |

### stock-docs（源 → 目标）

| 源路径 | 目标路径 | 备注 |
| --- | --- | --- |
| <...> | `.Knowledge/stock-docs/...` | 成功 / 跳过原因 |

### req-docs（源 → 目标）

| 源路径 | 目标路径 | 备注 |
| --- | --- | --- |
| <...> | `.Knowledge/req-docs/...` | 成功 / 跳过原因 |

## 拟删除路径清单（默认全选；与对话内清单一致）

- [ ] `<路径>`（`rules/` 下逐文件）
- [ ] `<路径>`（业务 `skills/<dir>`，不含 `f2s-*`）
- [ ] `.cursor/docs-index.md`（或实际路径）
- [ ] （可选）旧 `stock-docs/` / `req-docs/` 根目录

## 用户排除项（如有）

- （无则写「无」）

## 失败或未迁移项（如有）

- （无则写「无」）

## 删除执行记录

（仅在执行物理删除后追加：时间、已删列表、未删及原因）
```

## 完成后自检

1. 主题总数是否与旧映射总数对齐（允许用户显式跳过）。
2. `manifest.topics[].path` 是否都存在。
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 单点落盘。

可显式给出能力或零输入推断；先输出知识库更新大纲，确认后写入 topics/index/manifest；触发：f2s-kb-sync、全局同步、知识库同步、已实现能力

> 执行口径：本技能只维护 `.Knowledge`，默认不改配置根 `rules/skills`。

## 编排（主 / 子 agent）

- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。
- 步骤 1（素材汇总）：`subAgent=true` 时可拆子并行，仅只读汇总，不得落盘。
- 步骤 2（大纲 + 用户确认）：必主 agent 完成，确认权不可下放子 agent。
- 步骤 3（落盘）：`subAgent=true` 时可按已确认大纲拆子逐项落盘；硬约束：子落盘前必须前置加载近邻 2–3 个主题的开头摘要，做叙事风格对齐。
- 写权硬约束：`manifest-routing.json` 与 `.Knowledge/index.md` 恒由主 agent 单点落盘，禁止下放。
- 校验：默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。

# f2s-kb-sync（先大纲后写入）

## 输入（可选）

1. 用户显式给出“已实现能力列表”
2. 零输入：由 Agent 基于当前上下文推断
3. 辅助材料：`@` 文件、需求文档、架构说明等

## 强制流程（不可颠倒）

### 步骤 1：收集素材（只读）

- 汇总用户目标、范围、优先级
- 汇总已实现能力（用户指定 + Agent 推断）
- 对照现有知识库：
  - `.Knowledge/topics/`
  - `.Knowledge/index.md`
  - `.Knowledge/manifest-routing.json`
  - `.Knowledge/matchers/*.json`（与路由中 `matcherPath` 对应的分片）
  - `.Knowledge/stock-docs/`

### 步骤 2：输出《更新大纲》（必须）

大纲至少包含：

1. 同步目标
2. 能力清单（用户指定 / Agent 推断 / 合并结果）
3. 信息来源
4. 拟改文件清单（精确到路径）
5. 不改动范围
6. 等待用户确认提示

> 未确认前禁止落盘修改。

### 步骤 3：确认后写入

> 硬约束：若启用拆子，子 agent 落盘前必须读取近邻 2–3 个主题的开头摘要，确保叙事风格一致；`manifest-routing.json` 与 `.Knowledge/index.md` 由主 agent 单点落盘，子 agent 无写权。

按大纲逐项更新：

- `.Knowledge/topics/*.md`
- `.Knowledge/index.md`（同步主题路由表的“关联文档（摘要）”列）
- 路由清单（按需）
- `.Knowledge/stock-docs/*.md`（按需补充索源文档）

### 步骤 4：收尾摘要

- 列出已修改路径与目的
- 列出未执行项与原因

## 输出摘要格式（建议）

```markdown
## 知识库同步结果

### 已确认能力范围
- <能力1>
- <能力2>

### 已修改文件
- .Knowledge/topics/<topic>.md：<修改说明>
- .Knowledge/index.md：<修改说明>
- .Knowledge/manifest-routing.json：<修改说明或“未改动”>
- .Knowledge/matchers/<id>.json：<修改说明或“未改动”>
- .Knowledge/stock-docs/<doc>.md：<修改说明或“未改动”>

### 未执行项
- <项>：<原因>
```

## 复杂场景示例

用户仅说“/f2s-kb-sync 同步一下”，未给能力清单。

- 步骤 1 先做最小推断（例如支付、订单两个高频能力），并给出推断依据。
- 步骤 2 必须输出大纲并等待“确认”；未确认前禁止写入任何 `.Knowledge` 文件。
- 用户确认后只执行大纲内条目；若用户中途缩小范围，未执行项写入收尾摘要。

## 约束

- 先大纲，后写入
- 小步增补，避免整文件重写
- 同主题优先原位更新
- `index.md` 每个主题需包含 `stock-docs/req-docs` 的摘要级**可点击 Markdown 链接**（格式：`[标题](相对路径)`，1-3 条，允许写“无”）
- 不改配置根 `rules/skills`

## 完成后自检

1. 是否存在未确认即写入（必须为否）。
2. topic 文件与 index 行是否一一对应，且“关联文档（摘要）”已同步更新。
3. manifest 中 `topics` / `taskToTopicRules` / `topicDependencies` 是否仍引用有效路径。
4. 是否误改配置根 `rules/skills`（必须为否）。
5. 步骤 2 大纲 + 用户确认未下放子 agent；步骤 3 子落盘前已加载近邻 2–3 主题摘要；manifest / index 由主单点落盘。

知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。

> 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。

# f2s-kb-upgrade（知识库模板升级技能）

**术语（必须）**：**「升级」「升级命令」「知识库升级」** 仅指按本文件 **`f2s-kb-upgrade`** 执行的完整技能流程。**`flow2spec init`** 是 CLI **初始化/落盘**命令；本技能 **步骤 2** 会代跑它，**禁止**把用户单独执行的 `init` 或 CLI 帮助里的 `init` 表述为「升级命令」。

## 边界（避免误区）

- **`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`。

## 编排（主 / 子 agent）

- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
- **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。
- **主必控**（主 agent 不可下放）：
  1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。
  2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。
  3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。
  4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。
  5. **校验摘要**：校验结论与输出摘要由主 agent 汇总。
- **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。
- 本 SKILL 不绑定交叉校验；落盘侧自验。

## 与 `f2s-kb-migrate` 为何并存

| 技能 | 解决的问题 |
| --- | --- |
| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 |
| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**（包内 `manifest-matchers.json` 仅作 init 合并种子，**不落盘**到 `.Knowledge`），刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将包内 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 |

- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。
- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。

**为何 Cursor / Claude / Codex 下各有一份同名 `SKILL.md`？**  
各工具只加载**本配置根**下的 `skills/`（例如 Codex 仅 `.codex/skills/`）。内容应以 **`templates/skills/`**（或包发布物）为源保持一致；`flow2spec init` 会向所选 agent 目录**同步落盘**。

## 目标

当用户说「帮我升级知识库模板 / 跑 f2s-kb-upgrade / 同步最新 Flow2Spec」时，Agent **按本技能 `f2s-kb-upgrade` 全文流程执行**（含代跑 `flow2spec init`、清理、校验、摘要）；**勿**把仅执行 `init` 等同于完成本技能。

## 默认行为

1. 本技能步骤 2 代跑 **`flow2spec init`** 时，默认 **增量落盘**（不带 `--reset-knowledge`）。
2. 仅当用户明确要求「覆盖重置」时，才在 `init` 末尾追加 `--reset-knowledge`。
3. 优先写入用户指定的 agent；未指定时默认 `cursor claude codex`。

## init 与技能自更新（必须）

本技能在 **步骤 2** 会执行 **`flow2spec init`**；`init` 会把包内 **`templates/skills/`** 等同步到各 agent **配置根**，因此 **`init` 成功结束后**，本仓库里的 **`skills/f2s-kb-upgrade/SKILL.md`** **可能被新版本覆盖**，与当前对话里已缓存的旧说明不一致。

**闭环（防旧条令）**：

1. **`init` 前**（推荐）：记下当前配置根内 **`skills/f2s-kb-upgrade/SKILL.md`** 的标识（如 `mtime`、文件大小或正文 hash）。  
2. **`init` 成功结束后**：**重新读取磁盘上** 该 **`SKILL.md` 全文**（Cursor：`.cursor/skills/f2s-kb-upgrade/SKILL.md`；Claude：`.claude/skills/...`；Codex：`.codex/skills/...`，与本次 `init` 写入的 agent 一致）。  
3. **若相对步骤 1 有变化**（或刚升级 Flow2Spec 包、无法确认是否无变）：**必须以最新 SKILL 为准**，**从下文「步骤 0」起完整再执行一遍**本技能（含版本分流、是否再次 `init`、校验与摘要——一律按新版字面）；可循环直至**连续两轮**读到的 SKILL **无变化**，或用户明确要求停止。  
4. **若无变化**：继续执行步骤 3 及以后。

> 口径：**本技能步骤 2 执行 `init` 后** → 再读最新 `f2s-kb-upgrade/SKILL.md` → 有变则 **整技能重跑**；不要仅凭会话记忆执行 **本技能**。

## 强制流程

### 步骤 0：版本判定与分流（必须，先于 init）

> **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。

**V1 — 旧版知识组织（须先迁移再 init）**  
命中**任一**强信号则按 V1：

- 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或  
- 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。

**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。

**现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）**  
同时满足：

- 存在 **`.Knowledge/manifest-routing.json`**，且 **`topicPaths` / `taskToTopicRules`** 可用；  
- 业务文档已以 **`.Knowledge/stock-docs`、`req-docs`、`topics`** 为主（可与 V1 刚结束状态衔接）。

**历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。

**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。

### 步骤 1：确认本技能内 `init` 模式（必须）

- 若用户未明确「覆盖重置」，本技能步骤 2 默认 **增量 `init`**。
- 若用户提到「全部按模板覆盖/重置」，二次确认后再使用 `--reset-knowledge`。

### 步骤 2：执行命令（代用户跑 shell）

在目标项目根目录执行以下其一：

1. 优先（推荐升级到最新包）：
   - `npx @double-codeing/flow2spec@latest init <agents...>`
2. 若项目已固定使用本地安装：
   - `npx flow2spec init <agents...>`
3. 覆盖重置时：
   - 在上述命令末尾追加 `--reset-knowledge`

> `<agents...>` 示例：`cursor claude codex`。

**步骤 2 完成后**：立刻执行上文 **「init 与技能自更新」**：重读 **`skills/f2s-kb-upgrade/SKILL.md`**；若有更新则 **从步骤 0 整技能重跑**，再回到步骤 3（避免用旧版 SKILL 做后续校验）。

### 步骤 3：旧主题模板清理与引用修复（若存在则必须执行）

**本技能步骤 2** `flow2spec init` 成功后，先执行「旧文件清理 + 引用修复」：

1. 清理旧主题文件（仅在文件存在时删除）：
   - `.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）：
   - `templates/knowledge/index.md`
   - `templates/knowledge/manifest-routing.json`
   - `.Knowledge/index.md`（按需人工或技能侧改路径/段落）
   - `.Knowledge/manifest-routing.json`
3. 引用更新目标：
   - `.Knowledge/topics/f2s-flow2spec-architecture.md`
   - `.Knowledge/topics/f2s-implement-tech-design.md`
   - `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md`

> 口径：只清理“旧命名主题文件”，不删除带 `f2s-` 前缀的新主题文件。

### 步骤 3b：`index.md` 融合与 `template/index.template.md`（必须执行）

> **范围**：本条「融合」**仅在本技能内由 Agent 落盘 `.Knowledge/index.md`**；**不要求、也不假设**修改 Flow2Spec 包内 **`cli.js` / `lib/init.js`** 等 JS。`init` 行为仍以仓库现行为准（仅复制快照等）。

**`flow2spec init` 在本流程中的角色**：把包内 **`templates/knowledge/index.md` 原样复制**到 **`.Knowledge/template/index.template.md`**，作为**包版外壳对照**；**不**替代本步骤对 **`index.md`** 的融合书写。

#### 融合规则（必须遵守）

0. **写权归属**：本步骤的 `.Knowledge/index.md` 融合恒由主 agent 执行并落盘；子 agent 不得直接写入（写权硬约束）。
1. **对照源**  
   - **包版全文**：**`.Knowledge/template/index.template.md`**（与当前包 `templates/knowledge/index.md` 一致）。  
   - **项目现状**：**`.Knowledge/index.md`**。

2. **项目自身维护区（锚点：包模板 `index.md` 约第 18–19 行）**  
   - 以包模板行号为参照：**从二级标题 `## 主题一览` 起**（对应模板中紧接上一段 `---` 之后的 **`## 主题一览`** 与节首空行，即常见 **第 18–19 行**），**直至本节结束**：即到 **紧挨在 `## 命中与执行`（含括号说明）之前的那个 `---` 之前**的整块内容（含「主题一览」下的表格、节内说明段落等）。  
   - 该整块 **必须保留来自当前项目 `.Knowledge/index.md` 的正文**（由业务与 **f2s-*** 维护）；**禁止**用包模板同一段落**整体替换**覆盖（避免丢失业务主题行与摘要列）。  
   - **允许**在该块内做**最小必要修补**：例如为包新增的 `topicPaths` 主题**补行**、按 **`manifest-routing.json` 的 `topicPaths`** 改正「路径」列、与快照对比后补上包模板里**新增**的表格列说明——仍以保留项目已有行为主。

3. **必须与包模板一致的部分**  
   - **上述维护区之外**的所有内容（含 **`## 主题一览` 之前**从文件开头到该节前、以及 **`## 命中与执行` 及之后**直到文件结尾）：须与 **`.Knowledge/template/index.template.md`** 中对应段落 **一致**（以包版为准；diff 后以模板覆盖项目侧旧文）。

4. **产出**  
   - 将融合后的完整 **`index.md`** 写回 **`.Knowledge/index.md`**。  
   - **diff** 结论与是否改动写入步骤 5 摘要。

5. **与 `--reset-knowledge` 的关系**  
   - 若用户已 `reset`，`.Knowledge/index.md` 可能被模板整文件覆盖，仍须按本条 **2** 从备份或版本控制恢复「主题一览」块后再与包外壳做 **3** 的合并（若仓库无备份，则按 `topicPaths` + 快照**重建**主题表并让用户确认）。

### 步骤 4：校验本技能执行结果（必须）

至少校验：

1. 步骤 2 的 `flow2spec init` 是否成功退出（exit code = 0）。
2. init 输出是否包含 **路由清单与 `.Knowledge` 的结论**（已对齐/已最新/reset 覆盖等），以及 **`index.template.md` 已复制** 一行（若包内缺 `index.md` 则无此行）。
3. `manifest-routing` 与各 `matcherPath` 分片是否可解析，且 `topicPaths` / `matcherId` 引用均有效。
4. 存在 **`.Knowledge/template/index.template.md`**；已按步骤 **3b** 完成 **`index.md` 融合**（维护区保留 + 其余与包版一致）或写明待用户处理原因。
5. 配置根产物是否存在：
   - Cursor/Claude：`rules/`、`skills/`
   - Codex：`.codex/AGENTS.md`、`skills/`

### 步骤 5：输出结果摘要（必须）

输出以下信息：

- 执行命令（含 agent 与是否 reset）
- 是否成功
- 旧主题模板清理结论（删了哪些 / 哪些本就不存在）
- `index/manifest` 引用修复结论
- **index**：`index.template.md` 是否已生成；**`index.md` 融合**是否完成（锚点 **18–19「主题一览」节**保留、其余与包版一致）及 `topicPaths` / diff 结论（步骤 3b）
- **SKILL 自更新**：`init` 后是否重读 `f2s-kb-upgrade/SKILL.md`；是否因文件变化 **整技能重跑**及轮次（见「init 与技能自更新」）
- manifest / matchers 对齐结论（随 init 输出）
- 关键文件校验结论
- 如失败，给出下一步可执行修复建议

## 输出摘要模板（建议）

```markdown
## f2s-kb-upgrade 执行结果

- 本技能内代跑命令：`<实际执行的 flow2spec init ...>`
- init 模式：`增量` / `覆盖重置（--reset-knowledge）`
- 执行结果：`成功` / `失败`

### 核心校验
- 旧主题文件：`已清理` / `无需清理`
- 引用修复：`已更新` / `已一致`
- **index（快照 + 融合）**：`快照已复制` / `index.md 已融合` / `待处理（见备注）`
- **f2s-kb-upgrade SKILL**：`init 后无变化` / `已按新版重跑 N 轮` / `待确认`
- manifest-routing / matchers 分片：`已与模板对齐` / `已是最新` / `reset 覆盖`
- topics.path：`全部存在` / `存在缺失（见下）`
- agent 产物：`通过` / `异常（见下）`

### 备注
- <失败原因或后续建议>
```

## 约束

- 不把“请用户自行运行命令”作为默认方案；优先由 Agent 直接执行。
- 未经明确同意，不执行 `--reset-knowledge`。
- 不修改业务代码；仅按 **本技能 `f2s-kb-upgrade`** 流程与结果做校验。
- 步骤 3b `.Knowledge/index.md` 融合与 `manifest-routing.json` 均恒由主 agent 落盘（写权硬约束）；子 agent 仅可代跑 shell 命令。

## 完成后自检

1. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。
2. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**，并在有变化时 **整技能重跑**（见「init 与技能自更新」）。
3. 是否已实际执行 shell 命令（而非只给建议）。
4. 是否明确标注增量 or reset 模式。
5. 是否已处理旧主题文件清理与 `index/manifest` 引用修复。
6. 是否已执行 **步骤 3b**：**融合** `index.md`（**主题一览**节起至命中与执行前为项目维护区，其余同包版），并核对 `topicPaths`。
7. 是否输出了 manifest 与关键路径校验结果。
8. 若失败，是否给出下一步具体命令建议。
9. 步骤 3b 的 `index.md` 融合由主 agent 完成并落盘，无子 agent 越权写入。

执行任何 f2s-* 技能前强制读取 flow2spec.config.json，确定 subAgent 与 switchAgentVerification 实际值

# f2s 技能前置强制步骤

**执行任何 `f2s-*` 技能的第一个动作，必须用 Read 工具读取项目根 `flow2spec.config.json`**，获取 `subAgent` 与 `switchAgentVerification` 的实际值，再决定后续编排方式。

```
必须执行：Read("flow2spec.config.json")  ← 技能正文任何步骤之前
```

| 读取结果 | 行为 |
|---------|------|
| `subAgent: true` | 按技能 SKILL.md 的 B/C 模式派子 agent 并行扫描，主 agent 合并落盘 |
| `subAgent: false` | 全部在主 agent 内完成，不得拆子 agent |
| `switchAgentVerification: true` | 子 agent 落盘的由主 agent 校验；主 agent 落盘的由子 agent 校验（须 subAgent=true 且已拆子任务） |
| `switchAgentVerification: false` | 落盘侧自验，不交叉 |
| 文件不存在 | 所有字段均视为 `false` |

**Claude Code**：若已启用 `f2s-config-inject` PreToolUse hook，调用 `f2s-*` Skill 时会注入配置摘要；**文件缺失、JSON 损坏或 hook 异常时也会注入说明与默认语义**，不静默。仍建议在存疑或刚改过配置时用 `Read` 与磁盘核对。

### changeTracking（变更追踪）

| 字段 | 生效技能 | 行为 |
|------|---------|------|
| `changeTracking.feat: true` | `f2s-kb-feat` | **步骤 0 必须执行**：创建或续作 `.task/active/` 变更追踪任务 |
| `changeTracking.feat: false` | `f2s-kb-feat` | 步骤 0 跳过，不创建 `.task/` 目录 |
| `changeTracking.fix: true` | `f2s-kb-fix` | **步骤 0 必须执行**：创建或续作 `.task/active/` 变更追踪任务 |
| `changeTracking.fix: false` | `f2s-kb-fix` | 步骤 0 跳过，不创建 `.task/` 目录 |
| `changeTracking.implement: true` | `f2s-implement-tech-design` | **步骤 2.5 写入任务清单、步骤 2.6 随实现同步打钩 `task.md`、步骤 5 满足归档门禁后归档** |
| `changeTracking.implement: false` | `f2s-implement-tech-design` | 步骤 2.5、2.6 和步骤 5 的变更追踪部分跳过 |

**禁止在未读该文件的情况下进入技能正文的任何执行步骤。**

Flow2Spec 统一知识库入口，按 .Knowledge 渐进式读取

# Flow2Spec 统一入口规则

本项目知识库已统一到 `.Knowledge/`，请按以下顺序读取，避免无范围检索。

## 项目根 CLI 开关（必须按需读取）

业务仓库**项目根** `flow2spec.config.json`（`flow2spec init` 在文件缺失时从包模板补齐）含布尔字段 **`subAgent`**、**`switchAgentVerification`**（**切换 agent 校验**），默认 `false`。执行任意 **`f2s-*` 技能**或与 Flow2Spec 初始化相关的说明前，须读取该文件；技能或规则中凡写「仅当 `subAgent` / `switchAgentVerification` 为 true」的步骤，**必须按文件实际值决定是否执行**；缺失字段或文件不存在时均视为 `false`。

> **`init` 与择路**：包模板 **`templates/rules/f2s-flow2spec-unified-entry.mdc`** 经 **`flow2spec init`** 写入业务仓库配置根 **`rules/f2s-flow2spec-unified-entry.*`**，并（去 frontmatter）镜像 **`.codex/topics/f2s-flow2spec-unified-entry.md`**；两处正文同源，按需读一处即可。技能引「统一入口」时，在 **Codex** 以 **`.codex/topics/f2s-flow2spec-unified-entry.md`** 为准。

### 两字段语义（模板约定）

- **`subAgent`**：`f2s-*` 技能若规定某步骤「用子 agent 执行」，则 **`true`** 时按技能使用子 agent，**`false`** 时在主 agent 内完成。用户可在对话中要求「**仅当**本项为 **`true`** 时，由主 agent **动态判断**哪些子任务适合交给子 agent」——**仅当配置为 `true` 时该要求有效**；配置为 `false` 时凡依赖拆子 agent 的该段说明**不生效**，全部在主 agent 完成。**各 `f2s-*` 在工作哪一阶段必须或建议使用子 agent** 由包内技能正文逐步约定，**当前尚未在模板层给出统一阶段表**；以技能为准并受本项约束。
- **`switchAgentVerification`（切换 agent 校验）**：落盘或变更后的**验证/复核**（对照清单、diff、自检）**不是**「一律在主 agent」；默认以**落盘侧所在 agent 为「当前 agent」**，在该会话内完成校验（**子 agent 落盘的就在子 agent 内验，主 agent 落盘的就在主 agent 内验**）。**仅当**① 配置 **`switchAgentVerification` 为 `true`**，**且** ② **当前 `f2s-*` 技能正文**对该步骤**明确写出**「当 **`switchAgentVerification`** 为 **`true`**」时，才启用**交叉校验**：**子 agent 落盘的 → 由主 agent 校验**；**主 agent 落盘的 → 由子 agent 校验**（**须**已存在子 agent 会话，即 **`subAgent` 为 `true`** 且实际拆出子任务；若 **`subAgent` 为 `false`**，无子侧可承接，**「主落盘→子验」不发生**，校验**全部在主 agent 内**完成）。配置为 `false`、或技能未写依赖本项、或用户仅泛泛要求「给对方验」的：**不**启用交叉，仍在**落盘侧 agent**内完成验证。

### Git worktree 与子任务工作目录卫生（`subAgent: true` 或并行子任务时必读）

部分环境会为子 agent / 并行尝试创建 **独立 `git worktree`** 或等价隔离目录。规则如下：

1. **谁创建谁收尾**：子侧创建则子侧在返回前尽量清理；若子会话已结束无法清理，**主 agent 合并结果后**必须执行清理，**禁止**依赖「稍后自动回收」。
2. **收尾动作（必须）**：对**仅为本次子任务**添加的 worktree，在合并或丢弃该子任务结果后执行 `git worktree remove <path>`（工作区干净仍失败时再用 `git worktree remove --force <path>`，**须确认**该路径无他人未提交修改）；随后 `git worktree list` 自检，**禁止**留下已知孤儿路径。
3. **中断 / 用户换题前**：若本会话曾添加 worktree，在结束前**必须**完成上述移除或在 `task.md`「## 备注」写明残留路径与删除命令，并视情况写入 **`user-todos.md`** 请用户本地执行（见 `f2s-task`）。
4. **禁止**：子任务已结束、主分支已继续开发，仍长期保留仅用于尝试的 worktree 目录（易造成混淆提交、磁盘堆积）。

## 读取顺序（必须）

1. 先读 `.Knowledge/manifest-routing.json`，优先按 `taskToTopicRules` 路由；按需根据 `matcherPath` 读取 matcher 分片获取 `includeAny` 关键词；无法命中时进入补召回阶段。
   - 若命中主题在 `topicDependencies` 中存在依赖，先读依赖主题，再读主主题。
   - 路由清单仅通过 `f2s-*` 技能流程维护，不依赖额外 CLI 子命令。
2. `.Knowledge/index.md` 按需读取，仅用于确认主题语义与边界。
3. 再读 `.Knowledge/topics/<topic>.md`（**路由摘要**：主题 id、路径约定、下一步指针）；若主题为 **`implement-tech-design`** 或 **`stock-docs-vs-req-docs`**，**必须继续读取**配置根 **`rules/f2s-implement-tech-design.*` / `rules/f2s-stock-docs-vs-req-docs.*` 全文**作为执行依据（`.Knowledge/topics` 内同名文件不重复长文）。
4. 若需要背景，再读 `.Knowledge/stock-docs/<doc>.md`。
5. 仅在前四步不足时下钻业务源码。
6. 命中后必须执行 `match -> expand -> verify -> act`：
   - `match`：先取主候选；
   - `expand`：展开 `topicDependencies`，并保留次高候选做补充校验；
   - `verify`：执行前做缺口检查（关键主题/边界/上下文是否缺失）；
   - `act`：仅在置信度足够时执行；低置信度必须先澄清。
7. 仅在以下条件之一成立时，允许执行跨 matcher 全量补检索（top-k）：
   - `taskToTopicRules` 无命中；
   - 主候选与次候选分差过小（低置信度）；
   - 缺口检查失败（关键主题/依赖/上下文缺失）；
   - 用户明确要求“全量检查/不要遗漏”。

## 任务分流

- 技术方案实现：先读 `.Knowledge/topics/f2s-implement-tech-design.md`（摘要），再读 **`rules/f2s-implement-tech-design.*` 全文**；需求文档默认位于 `.Knowledge/req-docs/`。
- 目录边界判断：先读 `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md`（摘要），再读 **`rules/f2s-stock-docs-vs-req-docs.*` 全文**。

## 机读事实源口径（规则层）

- `taskToTopicRules`：任务路由第一优先级。
- `taskToTopicRules[].matcherPath`：匹配词分片直链路径，按需读取单个 matcher 文件。
- `taskToTopicRules[].matcherId`：matcher 的稳定标识，需与 matcher 分片内 `id` 一致。
- `topicDependencies`：主主题命中后先加载依赖主题。
- `matcherPath(includeAny)`：任务关键词匹配词表。
- `fallbackTopic`：任务与关键词都未命中时必须读取，但仅作低置信度兜底，不是最终执行依据。
- `.Knowledge/manifest-routing.json + matcherPath 分片文件` 是机读事实源（关键词仅在 `matchers/*.json`）。
- `.Knowledge/index.md` 不是机读事实源，仅作人读导航与语义边界校验。
- 进入 `fallbackTopic` 后，必须先补召回或澄清，再决定是否执行改动。

## 知识缺口与对策（分场景）

| 情况 | 对策 |
| --- | --- |
| **1a 库里有文档但未配路由** | 用 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 补 `taskToTopicRules`、`matcherPath` 分片、`topicPaths`；扩充 `includeAny` 覆盖用户常用说法。Agent 侧：走 `fallbackTopic` 分诊并提示「需补路由」，**不**靠全仓扫文件代替配置。 |
| **1b 命中了但上下文不够** | 先 `expand`（`topicDependencies` + 次高候选），再 `verify` 点名缺哪份 `stock-docs`/`req-docs` 或哪段 topic；仍不足则 **向用户要文档或路径**，不要无门槛跨 matcher 全量补检索。**Agent 若需下钻源码**：须先对用户做**可见的缺口说明**（已读 KB、缺什么、拟读哪 1～2 个文件），见 **`f2s-knowledge-preflight`**「缺口闸门」；**禁止**无说明地连续 `Grep`/乱序探源。 |
| **2 库里没有对应文档** | 一次读完 routing + 已命中 matcher + 相关 topic 后，在回复中 **明确承认知识库无覆盖**，再选：下钻业务代码 / 请用户补充 `req-docs` 或 PRD。**禁止**用反复读清单假装「再找一遍就会有」。**下钻源码前**同样须满足 **`f2s-knowledge-preflight`**「缺口闸门」的可见说明。 |
| **2a 反复读清单耗 token** | **同一任务线内** `manifest-routing.json` 视为稳定快照：再次全文读取须说明理由（例如用户声明已通过 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 等更新路由或知识、或**手动编辑**了 manifest/matcher）。**勿将**仅执行 **`flow2spec init`** 等同于「业务知识库已更新」：`init` 以模板补齐、配置根落盘与包级路由结构对齐为主；**stock-docs / req-docs、topics 路由摘要、matchers 词条**由 **`f2s-*` 技能流程**维护；**包模板 `templates/rules/*.mdc`** 为 Flow2Spec 规则事实源，`init` 同步到配置根 **`rules/*.mdc`**（或等价扩展名）并镜像 **`.codex/topics/*.md`**（条数与包模板一致，含统一入口与专题长文）。只读 **当前规则对应的单个** `matcherPath`；不要为枚举而遍历整个 `matchers/` 目录。`index.md` 仅在需核对主题语义时打开，禁止与 manifest 交替「刷清单」。 |

### 知识缺口的执行层要点（避免「表里有写、行为没做」）

- **「向用户说明」「明确承认无覆盖」必须是用户可见的自然语言**，不得仅在内部分析或工具链中隐含带过；细则与停步条件见 **`f2s-knowledge-preflight`**（缺口闸门、探索次数上限）。
- **禁止**在命中 **1b / 2** 后，未做上述可见说明便进入「多文件 + 依赖目录」的链式探源；每出现一个新的「入口符号」就再 `Grep` 一轮，属于典型反模式。
- **HTTP 状态、错误正文、重定向与否**等事实，**不得以训练数据或他库经验代答**；须以当前仓库内**本次已读到的实现**为准。

## 禁止项

- 使用 `git worktree` 或隔离目录跑子任务后，**禁止**在未 `git worktree remove` / 未交接删除命令的情况下结束会话（见上文「Git worktree 与子任务工作目录卫生」）。
- 未查看 `.Knowledge/manifest-routing.json` 前，禁止进行全仓无范围扫描；`.Knowledge/index.md` 在需确认主题语义时再读，禁止与 manifest 交替重复读取以代替决策。
- 禁止把 `stock-docs` 作为直接编码输入文档；按方案实现应使用 `req-docs`。
- 禁止把 `fallbackTopic` 当作最终命中直接实施改动。
- 禁止在不满足触发门槛时执行跨 matcher 全量补检索。

当用户要求根据技术方案文档实现可运行交付物时，按本规则执行（读文档、列任务、确认、实现、待完成列表与提醒）。用户会在对话中提供技术方案文档路径（MD 或 PDF）；若为 PDF，先按 f2s-doc-pdf 转为 MD 再继续。

> **唯一长文**：本文件为 **implement-tech-design** 的完整执行条令。`.Knowledge/topics/f2s-implement-tech-design.md` 仅为路由摘要；**Codex** 读取 `.codex/topics/f2s-implement-tech-design.md`（由 `flow2spec init` 从本文件自动镜像）作为等效条令。

> 执行口径：统一知识库路径为 `/.Knowledge/`。下文所有路径均按 `.Knowledge` 约定解释。

# 基于技术方案实现交付物（通用）

当用户要求根据**技术方案文档**实现可运行交付物时（用户会提供文档路径，如 `.Knowledge/req-docs/xxx.md` 或 PDF），按以下约定执行。

**目录约定**：`.Knowledge/req-docs/` 放“用于实现”的技术方案；`.Knowledge/stock-docs/` 放沉淀文档，不作为直接编码输入。

**触发说明**：本规则在打开 `req-docs` 下 `.md` 时自动加载（`**/req-docs/**/*.md`）。若对话前未打开技术方案，可在对话中 @ 本规则后再提供路径。

- 若用户提供的是 PDF：先执行 `f2s-doc-pdf`，将 PDF 转为 `.Knowledge/req-docs/` 下 MD，再继续。
- 若用户提供的是 MD/文本：直接读取并进入实现流程。

---

## 一、目标与原则

- **目标**：基于技术方案实现可运行交付物，并与项目现有约定保持一致。交付物可以是前端页面/组件、后端接口/服务、数据处理逻辑、任务编排、脚本与配置等（按方案实际范围裁剪）。
- **原则**：
  1. **先列任务再动手**：先输出「实现任务列表」，再提问与实现。
  2. **先读后做**：先完整理解方案、边界、依赖、验收标准，再编码。
  3. **对齐项目约定**：目录、命名、依赖、封装方式、错误处理与项目既有风格一致。
  4. **缺项即问**：文档未明确的关键决策先向用户确认；未回复项进入待完成列表。
  5. **实现后可执行**：必须给出验证方式与外部待办，确保用户可落地验收。

---

## 二、方案要素与实现映射（通用）

| 技术方案内容 | 实现动作（按项目约定落地） |
| --- | --- |
| 需求目标 / 范围 / 非目标 | 明确本次实现边界，避免超范围开发。 |
| 关键流程 / 状态流转 / 时序 | 实现主流程与分支，关键判断处加简短注释。 |
| 数据结构 / 协议 / 字段约束 | 落地类型定义、模型、校验器或契约层。 |
| 接口 / 事件 / 消息 | 实现调用入口、事件处理、订阅或回调（按方案涉及项选择）。 |
| 页面 / 组件 / 交互 | 实现 UI 结构、状态管理、交互流程与容错提示（若方案涉及）。 |
| 配置 / 开关 / 环境差异 | 在项目约定位置注册并读取，补齐默认值和降级策略。 |
| 错误码 / 异常策略 / 重试 | 统一错误返回与日志策略，保持与现有封装一致。 |
| 发布 / 路由 / 权限 / 任务调度 | 实现对应代码并提醒用户完成平台侧配置（若方案涉及）。 |

### 流程图处理（重要）

- 若流程图是 PDF/图片且无文字步骤，先向用户索要文字版流程或补充文档；
- 若已有文字步骤，严格按顺序和分支实现；
- 无法确认分支时先提问，或按默认策略实现并写入待完成列表。

---

## 三、执行步骤

### 步骤 1：输入标准化

- PDF 输入：先执行 `f2s-doc-pdf`，得到 `.Knowledge/req-docs/*.md`。
- MD/文本输入：直接读取。

### 步骤 2：理解方案与上下文

1. 读取技术方案全文，提取：目标、范围、流程、接口/交互、数据、配置、依赖、验收条件。
2. 读取项目约定（如 README、`.Knowledge/stock-docs/`、架构说明、既有模块）以对齐实现风格。
3. 若流程图缺文字说明，先记录缺口，进入步骤 3 一并向用户确认。

### 步骤 2.5：先输出实现任务列表（必做）

在提问或编码前，必须先输出任务列表（可按方案裁剪）：

```markdown
## 实现任务列表（基于《xxx》技术方案）

| 序号 | 任务项 | 说明 |
| --- | --- | --- |
| 1 | 核心结构与数据契约 | 落地类型/模型/校验规则，明确输入输出。 |
| 2 | 业务流程实现 | 按流程图/文字步骤实现主链路与分支。 |
| 3 | 对外能力接入 | 接口/事件/页面交互等对外入口实现。 |
| 4 | 配置与异常处理 | 配置注册、错误处理、重试/降级策略。 |
| 5 | 验证与收尾 | 自测说明、待完成列表、平台侧提醒。 |
```

若 `changeTracking.implement: true`，在输出任务列表后，按 `f2s-task` 规则将本清单写入 `.task/active/<task-name>/task.md`。

### 步骤 2.6：变更追踪与 `task.md` / `user-todos.md` 同步（仅当 `changeTracking.implement: true`）

- 每完成实现任务列表中一项对应工作，**同一会话内**用 `Edit` 更新 `.task/active/<task-name>/task.md` 中对应 `[ ]`→`[x]`，禁止积压到收尾、禁止口头完成代替写盘（见 `f2s-task`「执行中」「中断与会话结束」）。
- 执行过程中每出现**须用户执行**的项（改库、配环境等），**同会话内**追加到 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`「user-todos.md」）。

### 步骤 3：实现前提问（必做，不可跳过）

进入编码前，必须一次性列出未明确项并请用户确认。常见问题：

- **范围与验收**：本次必须交付什么，哪些明确不做；
- **技术边界**：实现在哪个模块/端（前端、后端、脚本、数据任务等）；
- **依赖与契约**：外部接口、消息协议、数据源、鉴权方式；
- **配置与环境**：配置 key、环境差异、默认值与灰度策略；
- **流程图缺口**：分支条件、失败回退、超时与重试策略；
- **发布约束**：路由、权限、调度、部署步骤是否已具备。

若用户未回复某项：按合理默认或占位实现，并在待完成列表中标注“需用户确认”。

### 步骤 4：按任务列表实现

按方案与项目实际裁剪顺序，建议：

1. 先落地数据/契约与公共抽象；
2. 再实现主流程与核心能力；
3. 再接入入口层（接口/页面/事件/任务）；
4. 最后补齐配置、异常处理、日志与测试辅助。

要求：复用现有依赖与封装；与项目命名/目录/风格一致；关键分支要可读、可维护。

### 步骤 5：收尾输出（必做）

1. **待完成列表（必须）**：列出所有待用户或平台补齐项；
2. **实现后提醒清单（必须）**：按实际涉及内容提醒配置、依赖、数据、发布、权限、调度等；
3. **验证建议（建议）**：给出最小可执行验证步骤（本地、测试环境或回归路径）。
4. **用户代办落盘（仅当 `changeTracking.implement: true`）**：将步骤 5 第 1–2 点中**须用户亲自执行**的条目（改库脚本、配置、审批等）**同步追加**到 `.task/active/<task-name>/user-todos.md`（若尚无该文件则先创建，见 `f2s-task`）；禁止仅出现在对话或方案尾部的列表而不写入该文件。
5. 若 `changeTracking.implement: true`：**先确认** `task.md`「步骤」已全部 `[x]`（或备注已记录取消项），满足 `f2s-task` 归档门禁后，再将 `.task/active/<task-name>/` 移至 `.task/completed/<YYYYMMDD>-<task-name>/`，并从 `todo.json` 删除对应条目；禁止在仍有 `[ ]` 时归档。

---

## 四、可选补充

- 若方案命名不明确，可先给出命名建议并请用户确认；
- 若方案跨度大，可按“最小可用版本 -> 增量迭代”拆分阶段交付；
- 若用户希望沉淀知识库，可提醒后续用 `f2s-ctx-build` 同步主题与路由。

---

## 五、约束与小结

- PDF 必须先转 MD，再进入实现流程；
- 不得跳过步骤 2.5（任务列表）与步骤 3（实现前提问）直接编码；
- 若 `changeTracking.implement: true`：不得跳过步骤 2.6（随实现进度写回 `task.md` checkbox，并追加 `user-todos.md`）；归档须满足 `f2s-task` 归档门禁；
- 输出中必须包含待完成列表与实现后提醒清单；若 `changeTracking.implement: true`，其中用户侧项须同步写入 `user-todos.md`；
- 内容保持通用，不预设“仅后端”场景，按方案实际范围裁剪实现对象。

完成时可用一句话总结：已基于《xxx》技术方案完成本轮实现并给出待完成与验证建议，请按清单补齐平台与环境侧配置后验收。

Karpathy 式编码行为准则：先澄清假设、极简实现、只改必要处、用可验证目标驱动执行。与 f2s-* 规则并存；流程类硬约束以 f2s 为准。

# Karpathy 式编码行为准则

> 来源与同步：[forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)（MIT），思想来自 [Andrej Karpathy 对 LLM 写代码常见问题的观察](https://x.com/karpathy/status/2015883857489522876)。与项目内 Flow2Spec / `f2s-*` 规则**并行**；若某条与 f2s 强制步骤冲突，**以 f2s 与项目约定为准**。

用于减少常见「模型写代码」失误的行为约定。

**取舍：** 这些准则偏向**稳妥而非一味求快**；对明显琐碎的修改（如单行笔误）可自行把握，不必条条刻板执行。

## 1. 先想清楚再写代码

**不要默认、不要藏困惑、把权衡摆到台面上。**

动手实现前：

- **假设要说清楚**；不确定就问，不要猜。
- **有多种理解时并列说明**，不要悄悄选一种就跑。
- **若有更简单做法**，主动提出；该反对时要反对。
- **说不清就停**：点名哪里困惑，再向用户要信息。

## 2. 简单优先

**用最少代码解决问题，不做臆测性扩展。**

- 不要超出需求加功能。
- 不要为只用一次的代码抽抽象。
- 不要加未被要求的「灵活性」「可配置」。
- 不要为几乎不可能的场景堆错误处理。
- 若写了 200 行其实 50 行就够，**重写**。

自问：「资深工程师会不会觉得过度设计？」若是，就简化。

## 3. 手术式修改

**只动该动的；只收拾自己弄乱的。**

改已有代码时：

- 不要顺手「优化」相邻代码、注释或格式。
- 不要重构没坏的东西。
- **风格对齐现有代码**，即使你个人偏好不同。
- 若发现与任务无关的死代码，**可以提一嘴，不要擅自删**。

若你的改动产生了孤儿引用/变量：

- **删掉因你这次改动而不再使用的** import、变量、函数。
- **不要**在用户未要求时删除**原本就存在**的死代码。

检验标准：**每一行改动都能追溯到用户的明确诉求。**

## 4. 目标驱动执行

**先定义成功标准，再循环直到可验证地达成。**

把任务变成可验证目标，例如：

- 「加校验」→「先写非法入参测试，再改到通过」
- 「修 bug」→「先写能复现的测试，再改到通过」
- 「重构 X」→「前后测试套件均通过」

多步骤任务可写简短计划：

```
1. [步骤] → 验证：[检查方式]
2. [步骤] → 验证：[检查方式]
3. [步骤] → 验证：[检查方式]
```

成功标准越具体，越能独立迭代；含糊的「跑通就行」会逼出反复追问。

---

**准则在起作用的信号：** diff 里无关改动变少、因过度设计返工变少、**澄清问题出现在实现之前**而不是做错之后。

普通提问也须先读 .Knowledge 机读路由，再搜代码；硬约束首工具调用

# Flow2Spec 知识库首读（KB Preflight）

本条与 `f2s-flow2spec-unified-entry` **并存**；凡涉及**当前仓库**内实现、配置、排错与 Flow2Spec 知识路由的回答，**以本条约束「何时必须先读磁盘上的知识库」为准**。统一入口中的读取顺序在**满足本条之后**继续适用。

## 适用范围（须执行首读）

用户问题若可能依赖下列任一类信息，即视为「须先走知识库」：

- 当前仓库中的**实现代码**、目录与模块约定、构建/部署/运行时行为、`.Knowledge/`、`f2s-*` 技能、`manifest-routing` 所描述的主题路由等；
- 用户未明确声明「与当前仓库无关」、但语境明显依赖本仓库事实时。

## 硬约束：首工具调用

在给出实质性结论或修改建议之前：

1. **在本轮用户消息下**，若尚未用工具读取过 **`.Knowledge/manifest-routing.json`**，则 **第一个** 使用的代码/知识库类工具 **必须** 为：

   `Read` → 路径 **`.Knowledge/manifest-routing.json`**（项目根相对路径，与统一入口一致）。

2. 读完 manifest 后，再按 `taskToTopicRules` / `matcherPath` **按需** `Read` **单个** matcher 分片与 **`.Knowledge/topics/<topic>.md`**（及 `topicDependencies`），然后才允许对 **除 `.Knowledge/` 以外的业务源码路径** 使用 `SemanticSearch`、`Grep` 或 `Read`。

3. **禁止**：在未执行步骤 1 的情况下，用「凭记忆/凭训练数据」直接断言本仓库特有的路径、配置或行为；若 manifest 或 topic 已明确覆盖，**须以 KB 为准**，源码用于印证或补全 KB 未写细节。

4. **回答末尾（简短一行即可）**：注明本轮依据的 KB 路径（例如「已读 manifest + `topics/<topic>.md`」）；若 manifest 无命中且已读 `fallbackTopic` 对应 topic，写明「走 fallback 分诊」。

## 可跳过首读（极少数）

- 用户仅询问 **IDE/编辑器本身**用法、且与当前仓库目录无关；
- 用户给出 **绝对路径 + 明确指令**（例如「只把该行改为 x」）且与业务知识无关的纯机械编辑；
- **同一会话内**已对当前工作区执行过 `Read(".Knowledge/manifest-routing.json")` 且用户未要求「重新路由/全量检查」的**直接续问**：可在回答首句写「manifest 已读本会话，沿用上次路由」，**不再重复 Read** manifest。

## 知识缺口与下钻源码（防「grep 死循环」）

与 **`f2s-flow2spec-unified-entry`** 中 **「知识缺口与对策」** 一致；命中 **1b（命中但上下文不够）** 或 **2（库里没有对应文档）** 时，还须遵守：

1. **先对用户说明，再扩工具**：在已读 `manifest-routing.json` 与应读的 `topics/*.md`（及依赖 topic）之后，若仍**无法仅凭 KB** 精确回答用户问题，**必须先**用自然语言说明：**已读哪些 KB 路径**、**仍缺哪类信息**、**你打算只读哪 1～2 个源码文件**或**请用户补哪篇文档**；不得沉默地连续堆叠「再找入口」式探索。
2. **探索次数上限**：在未向用户发出上述缺口说明前，**禁止**连续发起 **4 次及以上**仅以扩大搜索面为目的的 `Grep` / 无明确目标的 `SemanticSearch`。说明并获用户默许（或问题明确要求追到底）后，再有序下钻。
3. **单点下钻优先**：若仅需确认行为细节，应优先 **Read 一个**与问题最相关的实现文件并据此作答；**禁止**为同一子问题在无新假设的情况下链式深入第三方依赖目录中多文件，除非用户明确要求通读依赖。

### 缺口闸门（针对「规则有写、执行跳过」）

当且仅当已读完 **manifest + 应读 topics** 后，仍判定为 **1b / 2**、且**下一步**要使用指向**业务源码树**（非 `.Knowledge/`）的 `Read` / `Grep` / `SemanticSearch` 时：

- **必须先**产出一段**终端用户可见**的自然语言（可与简短结论同屏），且至少包含：**(a)** 已读的 KB 路径；**(b)** 缺口一句（topic 缺哪类信息或库中无文档）；**(c)** 拟打开的 **1～2 个具体文件路径**或征询用户是否先补 `req-docs`/stock-docs。
- **禁止**在**从未**输出过满足 (a)(b)(c) 的可见说明的情况下，连续发起多轮仅用于「再找入口」的源码侧工具调用（此即「规则已写但未先做缺口说明」的执行层遗漏）。
- 下钻后给出**行为、状态码、错误文案**等事实时，**须以本次实际读到的源码与契约为准**；不得凭推测或与当前仓库无关的外部项目经验填写。

上述 (a)(b)(c) 与 **`f2s-flow2spec-unified-entry`** 表中「向用户要文档或路径」「明确承认知识库无覆盖」**同一语义**：不得用「已在内心判定为 1b」代替**已对用户写出**的缺口说明。

### 与执行环境的交互（权限、确认类噪音）

在带沙箱或权限门控的 IDE 中，**短时间连续**发起多轮 `Grep` / `SemanticSearch` / 大范围读盘，常表现为**对同类权限或确认的重复询问**。这与 Flow2Spec 规则是否写明无直接关系，多由**探索链过长、无停止条件**放大。遵守本节「缺口闸门」「探索次数上限」与下文「检索体积与作答节奏」、优先单文件 `Read`，可显著减少此类打扰。

## 检索体积与作答节奏（降低多轮扫描、体感变慢）

本节针对 **Codex / 终端 IDE** 等环境中「一次问答多轮 `grep`、输出量巨大、总耗时长」的常见根因，与「首读 manifest」**不冲突**：仍须先 `Read` manifest，再收窄搜索面。

1. **`Grep` / 文本搜索范围**：在已读命中 topic 且其中给出**具体文件或目录路径**时，搜索**不得**大于该路径；无路径时再缩到**单一**最可能目录（如 `src/utils/` 或 `src/functions/<活动目录>/`）。**禁止**在无用户明确要求「全仓检查」且未满足统一入口「全量补检索触发门槛」时，对 **`src/` 根、`src/functions` 全域、`.Knowledge` 等多处并列**做一次超大范围扫描。
2. **大命中量时**：若单次搜索命中行数明显过多，应**停止扩大关键词或路径**，改为优先 **`Read` topic 或 stock-docs 已点名的 1～2 个主文件**；仍不足再缩小模式或目录做**第二次**窄 `Grep`。
3. **两阶段作答**：用户未明确要求「列出全部实现细节 / 通读依赖 / 审计全链路」时，在 manifest + 应读 topics（及 stock/req 中 topic 已指明的材料）已足以形成结论时，**可先输出对用户有用的短答案**；实现细节、额外文件清单仅在用户追问依据或「展开」时再下钻，**禁止**仅为自验完备而拉长探索链。
4. **避免重复读盘**：本会话内已对某文件做过**全文** `Read` 且无新用户指令或新假设时，**禁止**再次对该文件发起等价全文 `Read`。

## 对 Agent 自检

若你发现自己在回答当前仓库相关问题时尚未 `Read` manifest，**须立即停止补写**，先 `Read` manifest 与命中 topic，再更正或续答。

根据澄清后的需求基于项目知识库/Skills/Rules 生成后端技术文档；触发：生成后端技术文档、后端技术方案

> 执行口径：业务文档统一在 `/.Knowledge/`，本技能只产出 `.Knowledge/req-docs` 方案文档并参考 `.Knowledge` 内知识，不修改配置根 `rules/skills`。

## 编排（主 / 子 agent）

- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。
- **拆子前提（硬约束）**：当 `subAgent=true` 时，主 agent **必须先**抽取一份「项目约定摘要」作为子 agent 的强制上下文，覆盖：对外契约规范、错误与返回约定、异步/集成规范、数据与存储约定、工程结构、模块边界，合计 **< 80 行**。若未做该前置，**不拆子**——验收返工成本 > 拆子收益，强行拆子得不偿失。
- **子职责**：多源只读（`.Knowledge/topics`、`stock-docs`、澄清后的 `req-docs`、模版）+ 按 `.Knowledge/template/后端技术模版.md` 写 `req-docs` 方案初稿。
- **主职责**：契约定稿、对照模版与澄清文档验收、处理接口/流程一致性。
- **校验**：默认落盘侧自验；本技能不绑定交叉校验。

# 根据需求生成后端技术文档

用户在对话中提供**已澄清的需求**（或需求摘要、PRD 路径），并可选择附带**需求条件**（如范围限定、必须/禁止使用的技术、优先级等）。你需要基于业务知识文档（`.Knowledge/`）和当前 agent 已加载的 rules/skills，输出一份可直接用于实现的后端技术文档。

**用途**：本技能产出的技术方案**供后续代码实现使用**，开发按该文档实现功能。不用于生成 Rules/Skills。

**结构范本**：技术方案按 `.Knowledge/template/后端技术模版.md` 的章节顺序与书写要求输出。**接口与处理流程写在同一处**：每个接口小节内同时给出契约（请求/返回）与**处理流程**（分步说明、分支与错误码引用），**不要**再单独拆「接口及流程说明」「关联接口调用流程」「流程说明」等大章重复描述同一接口。

---

## 输入

- **第一参数（必填）**：澄清后的需求描述，或**需求/PRD 文档路径**（如 `.Knowledge/req-docs/xxx.md`、`.Knowledge/stock-docs/需求_终稿.md`）。
- **后续参数或用户补充（可选）**：需求条件与约束，例如：
  - 范围（只做某模块、某端）
  - 必须/禁止使用的中间件、接口风格
  - 与现有某模块的边界
  - 性能、安全、合规要求

---

## 输出结构

生成文档时，**按 `.Knowledge/template/后端技术模版.md` 中的章节顺序与书写要求**输出；与需求无关的整节可省略。执行本技能时请**先读取该模版**作为结构与表述参考。

---

## 拆子前置（可选，仅当 `subAgent=true`）

主 agent 在拆子前，必须产出「项目约定摘要」作为子 agent 的**强制输入**，否则**不拆子**。摘要篇幅上限 **< 80 行**，必须包含以下 6 类条款（技术栈无关，按项目实际填具体值）：

1. **对外契约规范**：接口 / 事件 / 消息 / 脚本入口的命名、版本、鉴权、分页、通用返回字段等契约约定。
2. **错误与返回约定**：错误码体系来源、前缀 / 分段规则、必选字段（如 code / message / data）、状态分层。
3. **异步 / 集成规范**：消息队列 / 定时任务 / 外部服务调用的命名、消费者组织、重试与幂等约定。
4. **数据与存储约定**：库 / 表 / 字段 / 缓存 / 文件 / 搜索等命名规范、主键 / 索引 / 时间字段约定、分库分表策略（若有）。
5. **工程结构**:  后端模块分层（如 controller / service / dao / domain，或等价命名）与包路径 / 目录约定。
6. **模块边界**：本方案涉及的既有模块与其他模块的调用 / 数据边界。

未完成该前置即拆子，视为违反硬约束；摘要完成后方可将子任务交付子 agent。

---

## 步骤

1. **读取需求**：从用户提供的路径或正文获取需求内容；若有需求条件，一并纳入。
2. **加载项目上下文**：主动读取并运用：
   - `.Knowledge/topics/` 下与接口、配置、MQ、数据相关的主题规则/流程；
   - `.Knowledge/stock-docs/` 下的背景文档与历史技术方案；
   - **结构对照 `.Knowledge/template/后端技术模版.md`**。
3. **对齐项目约定**：接口命名、目录结构、配置中心、QMQ、错误码、表命名等与现有项目一致。
4. **撰写文档**：按 `.Knowledge/template/后端技术模版.md` 书写；**每个接口下写全处理流程**，避免接口与流程两张皮。若启用拆子，子 agent 以「项目约定摘要」+ 澄清文档为强制输入，禁止自行扩展读取范围。
5. **输出位置**：默认 `.Knowledge/req-docs/<方案名>_技术方案.md`；若用户指定路径则用该路径。完成后提示：技术方案已就绪，可据此进行代码实现。

---

## 约束

- 所有路径相对于项目根目录（与 `.Knowledge` 同级）。
- 生成的是**后端技术文档**，不写前端 UI 细节（接口契约与入参出参除外）。
- 不臆造与项目不符的约定；不确定时标注「待与项目约定确认」。
- **原则**：接口小节 = 契约 + 处理流程，二者不拆章重复；结构以 `.Knowledge/template/后端技术模版.md` 为准。

针对 PRD/需求反问直到清楚，再可用 f2s-req-backend 出技术方案；触发：需求澄清、PRD 澄清

## 编排（主 / 子 agent）

- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。
- 本技能默认**不拆子**：无论 `subAgent` 真值，澄清流程全程在主会话进行（追问与用户对齐强依赖连续同会话，拆子必断上下文）。
- 校验口径为**落盘侧自验**，本技能不绑定交叉校验。

# 需求澄清

> 执行口径：澄清文档统一落盘到 `.Knowledge/req-docs/`。

**入参**：可选。PRD 全文、需求描述或文档路径（如 `.Knowledge/req-docs/xxx.md`）；不传则按当前对话内容澄清。后续回复可补需求条件。

**行为**：找出需求中的模糊表述、未定义概念、缺失信息、矛盾、与实现相关但未说明的点 → 分组、具体可答地反问 → 根据回答迭代追问，直到流程、边界、异常、关键概念无歧义。不替用户做业务假设，不清楚就问。

**结束**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 `.Knowledge/req-docs/`。输出完文档后，再提示使用 `f2s-req-backend` 生成技术方案，供后续代码实现。

根据技术方案/需求描述/变更描述规划并实现任务；始终创建任务清单，支持子 agent 并行实现代码；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单

# 需求任务规划与实现（f2s-req-plan）

从需求/技术方案出发，完整覆盖「规划 → 实现」链路。不依赖 `changeTracking` 配置，始终创建任务清单。知识库同步由用户后续按需调用 `f2s-kb-feat` / `f2s-kb-sync` 完成。

## 编排（主 / 子 agent）

- `subAgent` / `switchAgentVerification` 语义以统一入口为唯一事实源：**Cursor/Claude** 读 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`。
- **步骤 1（解析）**：`subAgent=true` 时可拆子 agent 并行读多份文档/模块，仅只读，不落盘。
- **步骤 2（草稿确认）**：必须主 agent，确认权不可下放。
- **步骤 3（落盘任务清单）**：`task.md` / `context.md` / `user-todos.md` 可交子 agent 写初稿；**`user-todos.md` 中「执行中识别的用户代办」追加**优先主 agent 合并写盘，避免并发覆盖；`todo.json` 恒由主 agent 单点写入。
- **步骤 4（实现代码）**：`subAgent=true` 时可按任务清单拆子 agent 并行实现各模块；**合并子 agent 结果后**，主 agent 须按 **`f2s-flow2spec-unified-entry`**「Git worktree 与子任务工作目录卫生」清理仅为子任务创建的 worktree / 隔离目录，并 `git worktree list` 自检。
- **步骤 5（归档）**：主 agent 完成。
- **步骤 6（摘要）**：主 agent 完成。
- 落盘侧自验；`switchAgentVerification=true` 且技能正文明确标注时才启用交叉校验。

## 输入（任选其一）

- 技术方案文档路径（`.Knowledge/req-docs/*.md` 或 PDF）
- 需求描述 / 变更描述（自由文本）

## 步骤

### 步骤 1：解析输入

`subAgent=true` 时，可拆子 agent 并行执行（只读，不落盘）：

- 读取技术方案 / 需求文档全文，提取目标、范围、主要工作项、涉及文件路径
- 读取项目现有约定（`.Knowledge/stock-docs/`、架构说明）对齐实现上下文
- 若输入为 PDF，先执行 `f2s-doc-pdf` 转为 MD，再继续

子 agent 只输出「解析结果摘要」（目标、工作项列表、涉及文件）交主 agent 汇总；`subAgent=false` 时主 agent 直接完成。

### 步骤 2：输出草稿并确认（必须主 agent）

主 agent 基于步骤 1 汇总，输出规划草稿：

1. **任务名称建议**（snake_case，如 `alipay_refund_feat`）
2. **实现任务清单草稿**（每步独立可 checkbox）
3. **涉及文件列表**
4. **等待用户确认**

> 未确认前禁止创建任何文件或写任何代码。

### 步骤 3：落盘任务清单

确认后：

- **主 agent**：在 `todo.json` 新增条目（`linkedSkill: "f2s-req-plan"`）
- **主 agent（`subAgent=false`）/ 子 agent（`subAgent=true`）**：
  - 创建 `.task/active/<task-name>/task.md`
  - 创建 `.task/active/<task-name>/context.md`
  - 创建 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`：固定文件名；尚无用户代办时写入简短占位说明即可）

### 步骤 4：实现代码

`subAgent=true` 时，按任务清单将各模块拆子 agent 并行实现：

- 子 agent 只写实现代码
- 子 agent 完成后向主 agent 汇报改动摘要（文件路径 + 改动说明）
- `subAgent=false` 时主 agent 按清单逐项实现

实现原则：

- 复用现有依赖与封装，不引入不必要抽象
- 与项目命名 / 目录 / 风格一致
- 未实现或部分实现的能力补齐，不重做

每完成清单中一步，立即用 `Edit` / `Write` 将 `task.md` 对应 checkbox 由 `[ ]` 改为 `[x]`，禁止批量勾选，禁止口头完成代替写盘（长记忆以磁盘 `task.md` 为准；见 `f2s-task`）。

凡产生**须用户执行**的项（改库、配环境、审批等），**同会话内**追加写入 `user-todos.md`（见 `f2s-task`「user-todos.md」）；子 agent 若回报此类项，由主 agent 合并追加，禁止仅写在对话中。

### 步骤 5：归档任务

**仅当** `task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后：将 `.task/active/<task-name>/` 整体移至 `.task/completed/<YYYYMMDD>-<task-name>/`，从 `todo.json` 删除对应条目。若仍有 `[ ]`，禁止归档，应先补打钩或修订清单（与 `f2s-task` 归档门禁一致）。

### 步骤 6：输出摘要

```markdown
## f2s-req-plan 完成：<任务名>

### 实现
- <文件路径>：<改动说明>

### 待办（如需同步知识库）
- 可后续调用 f2s-kb-sync 补充知识库

### 用户代办（须用户在本机/平台完成）
- 详见 `.task/active/<task-name>/user-todos.md`（归档后在 `completed/.../` 同路径）
```

## 约束

- 不依赖 `changeTracking` 配置，始终创建任务清单
- 步骤 2（草稿确认）必须主 agent，未确认前禁止落盘
- `todo.json` 恒主 agent 单点写入
- 禁止批量勾选 checkbox，逐步执行
- 用户代办必须追加到 `user-todos.md`，禁止仅对话交付（见 `f2s-task`）

## 完成后自检

1. 任务清单步骤是否全部勾选（且已为磁盘上的 `[x]`，非仅对话宣称）。
2. 实现代码是否覆盖草稿确认的范围。
3. 满足归档门禁后：`.task/active/<task-name>/` 已移至 `completed/`（含 `user-todos.md`），`todo.json` 条目已删除。
4. 凡有用户代办意图的，磁盘上 `user-todos.md` 已创建且与会话结论一致（无代办则可为占位说明）。
5. 若曾拆子 agent / 并行实现且环境可能创建 **`git worktree`**：已按 **`f2s-flow2spec-unified-entry`** 清理或已交接删除命令；未使用 worktree 则标 N/A。

文档目录 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/**）。

## 详细约定

见 Flow2Spec 包内 **`docs/README-目录与路径约定.md`**；技能顺序与 **f2s-doc-arch** / **f2s-doc-add** 见 **`docs/README-命令说明.md`**。具体步骤以配置根 **`skills/<技能名>/SKILL.md`**（如 **f2s-ctx-build**、**f2s-doc-add**）为准。

Event hooks configuration

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Skill",
      "script": "scripts/f2s-config-inject.js",
      "description": "在调用 f2s-* Skill 前注入 flow2spec.config.json 配置摘要"
    }
  ]
}

Flow2Spec 插件首次安装引导：检测知识库是否初始化，未初始化时提示用户运行 f2s-kb-upgrade

---
description: Flow2Spec 插件首次安装引导：检测知识库是否初始化，未初始化时提示用户运行 f2s-kb-upgrade
alwaysApply: true
---

# Flow2Spec 安装后引导

## 检测条件

当用户首次与你对话，或你发现以下任一情况时，**必须主动提示**：

1. 项目根不存在 `.Knowledge/manifest-routing.json`
2. 项目根不存在 `flow2spec.config.json`

## 提示内容

```
👋 检测到 Flow2Spec 插件已安装，但项目知识库尚未初始化。

建议运行以下命令完成初始化：

  /f2s-kb-upgrade

该命令会：
• 在项目根生成 .Knowledge/ 知识库骨架（manifest-routing + matchers + topics）
• 生成 flow2spec.config.json 配置文件
• 对齐规则与技能到最新版本

初始化完成后，你可以通过 /f2s-doc-arch 或 /f2s-ctx-build 开始沉淀项目知识。
```

## 约束

- 每个会话**最多提示一次**，不重复打扰。
- 若用户已有 `.Knowledge/manifest-routing.json`，说明已初始化，**不提示**。
- 若用户明确表示不需要知识库（如"我只用规则"），尊重选择，不再提示。