---
description: 读取 03-tasks.md，按依赖图调度子 agent 并行执行原子任务；本轮任务验收通过后自动串联评审与执行验收（/kb-review → /kb-test）
argument-hint: "[变更目录或 scan-id] [补充说明]"
---

> Pi 包 `@suwenguang/pi-kb`：运行时包根为环境变量 `PI_KB_ROOT`（由 `extensions/kb-root.ts` 注入）。
> 工种子 Agent 通过 **pi-subagents** 派发（已 bundled）；agent 定义见本包 `agents/`。
> 脚本调用示例：`node "$PI_KB_ROOT/scripts/<name>.mjs"`。

## 用户输入

${@:-（未附带参数；结合当前对话上下文执行，缺信息时向用户澄清。）}

---
读取 03-tasks.md，按依赖图分组调度子 agent 并行执行实现任务。

**执行 Agent**：**kb-builder**（工种边界见 [kb-agent-roles.md](../skills/kb-workflow/references/kb-agent-roles.md)）

**子 Agent 编排（必遵）**：**必须**使用 Cursor **`Task` 工具**派发实现子 Agent（`subagent_type: generalPurpose`，prompt 声明 kb-builder 与本文）；**每一轮并行组内**每个 `T{n}` 对应一次独立 `Task`，主 Agent **不写业务代码或文档状态**，只做调度、验收、失败重试与执行报告；需要写回任务状态时另派子 Agent 执行。细则见 `skills/kb-workflow/SKILL.md`「编排与子 Agent」。

**chain 独立（必遵）**：本命令**禁止**被 orchestrator/kb-admin 串进 design/plan 同 chain；`/kb-apply` 须**单独** `subagent`/`Task` 链派发（见 [`kb-orchestrator.md`](kb-orchestrator.md)「subagent chain 口径」）。子 Agent 门禁命令**必须**带 `--target "$(pwd)"`（bootstrap、codegraph 等），禁止省略 target。

**与需求变更的关系**：若当前是 **PRD 变更后的增量开发**，且 `07-prd-revisions.md` 已写明本轮「关联 03 任务」，优先使用 **`/kb-revise-apply`**，仅调度该子集，避免与「仅文档」阶段的 **`/kb-revise`** 混在同一轮会话里写代码。

**与评审修复的关系**：若 `04-review.md` 或 `00-manifest.json.reviews[]` 存在 `open` 问题，优先调度 `03-tasks.md` 中对应的 `T-FIX-{n}` 任务；没有修复任务时，先让子 Agent 根据评审问题追加修复任务，再执行实现。

**输入**: 变更名称（**必须为中文**，对应 `knowledge/变更/进行中/` 下的目录；必要时兼容 `knowledge/变更/归档/` 下同名目录）。

## Bootstrap 门禁（硬阻断）

本命令要求业务仓已完成 KB 初始化（`/kb-init` / `kb-bootstrap`）。开始前**必须**先跑机器门禁；失败则**立即停止**，禁止继续（含禁止用 `mkdir -p knowledge/...` 绕过建目录）。执行：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`

未通过时按脚本输出指引执行 `/kb-init`，或：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap.mjs" --target "$(pwd)"`

## CodeGraph 门禁（硬阻断）

本命令依赖 CodeGraph。开始前**必须**先跑机器门禁；失败则停止并输出脚本指引，禁止继续。执行：

`node "${PI_KB_ROOT}/scripts/kb-codegraph-check.mjs" --target "$(pwd)"`

门禁通过后，再按 [kb-codegraph.md](../skills/kb-workflow/references/kb-codegraph.md) §2.2 确认「CodeGraph 可用」——下列**任一**即可（索引可用 ≠ 工具名已暴露）：

1. 宿主 MCP：`codegraph_*`（至少 `codegraph_explore`；若已开放可再确认 `codegraph_status`）
2. Cursor + pi bridge：`pi__codegraph_*`（与 `codegraph_*` **等价**）
3. CLI 等价路径：本机 `codegraph` / `npx -y @colbymchenry/codegraph@…` 能查 status/explore

**降级顺序**（索引门禁已通过时）：MCP/bridge 工具名均未暴露 → **不得**空转 blocked，应尝试 CLI；CLI 也失败才硬阻断。仅用 CLI 时报告须声明「经 CLI，非 MCP」/「未完成 MCP CodeGraph 核对」，不得冒充已 MCP 核对。派发子 Agent 时 prompt **须写清**本会话实际暴露名（如 `pi__codegraph_explore`），勿只写裸名。

若 MCP/bridge/CLI **均**不可用：硬阻断，并按 [kb-codegraph.md](../skills/kb-workflow/references/kb-codegraph.md) §一，从 `${PI_KB_ROOT}/bootstrap/examples/mcp/` **只写当前宿主**对应文件（Claude/其他 → 根 `.mcp.json`；Cursor → `.cursor/mcp.json`；禁止无脑双写），配置后 Reload / 重启会话，再重试本命令。

## 约束

- **变更名称必须为中文**，如"红包功能"、"设备守卫-用户模糊搜索"
- 禁止使用 kebab-case、camelCase 或英文命名
- 目录格式：`<YYYYMMDDHHMMSS>-<中文名称>`
- 变更文档必须按 kb-flow 优先级使用两位数字前缀；读取任务文件时使用 `03-tasks.md`
- **自动链适用范围**：下文「全部通过后的强制链」（`applied` → validate → `/kb-review` → `/kb-test`）**仅适用于 `flow = standard`**；`flow = lite` 豁免本自动链（lite 流程见 `kb-lite.md`，本命令不改动其契约）

## 执行步骤

### 1. 读取任务文件

```bash
cat "knowledge/变更/进行中/*-<中文名称>/03-tasks.md"
# 必要时兼容读取 knowledge/变更/归档/*-<中文名称>/03-tasks.md
```

确认 03-tasks.md 存在且包含完整的依赖图和任务定义。读取 `00-manifest.json`，确认 `flow = standard` 且存在待执行任务；若缺失则先补建 manifest。

若存在 `reviews[].status = "open"`：
- 找到 `reviews[].task_id` 指向的 `T-FIX-{n}` 或 `T-Rev{n}-FIX-{m}`。
- 若缺少 `task_id`，先派发子 Agent 将评审问题转写为修复任务，追加到 `03-tasks.md` 并回写 manifest。
- 本轮默认只执行这些修复任务及其未完成前置依赖，避免重跑已完成主任务。

### 2. 解析依赖图

从 03-tasks.md 头部的依赖图和分组调度中提取执行顺序，并结合 `00-manifest.json.tasks[].files` 检查同轮文件冲突：

```
第一轮（并行）: T1, T2, T6    ← 无前置依赖，可同时执行
第二轮（并行）: T3, T4        ← 依赖第一轮
第三轮:        T5             ← 依赖第二轮
```

### 3. 按轮次调度子 agent

对每一轮任务：

**并行调度**：同一轮中「写入文件集合无交集」的任务同时启动子 agent；若多个任务写同一文件，拆成串行子轮次，或改用隔离工作区后由单一合并任务写回。`00-manifest.json` **始终**计入同文件冲突：并行组内 builder **禁止**各自写盘该文件。

每个子 agent 的 prompt 构造规则：

```
你是一个实现任务的子 agent。请严格按照以下任务描述执行实现。

## 任务定义

{从 03-tasks.md 复制该任务的完整内容，包括：
  背景、上下文文件、实现范围、接口契约、验收标准}

## 执行要求

1. 先使用 CodeGraph 查询任务中的关键符号、上下文文件和影响面，理解现有代码结构；若任务依赖第三方 API/SDK 的**当前**官方用法，可调用 `web_search`（带 Sources；不替代任务块与 CodeGraph）。无工具时引导 `/kb-deepseek-search-setup`，见 [kb-deepseek-search.md](../skills/kb-workflow/references/kb-deepseek-search.md)
2. 再读取所有「上下文文件」中必须确认的具体文件
3. 严格按照「实现范围」操作，不修改范围外的文件
4. 遵循「接口契约」中的签名和导出定义，确保与其他任务兼容
5. 完成后逐项检查「验收标准」
6. **AGENTS.md 沉淀（仅代码规范）**：验收通过后总结犯错经验，将**代码规范**（目录编码规矩：命名、分层、单文件行数、工具链命令等）写入最贴近改动文件的子目录 `AGENTS.md`（无则新建）；**禁止**将业务逻辑或 knowledge 级业务规格写入 AGENTS；业务知识在回报中列出「建议 knowledge 落点」（如 `knowledge/工程平台/Rust服务端/0N-*.md`），由 `/kb-archive` 合并，apply 阶段不得私自写入 knowledge；细则见 [kb-agents-precipitation.md](../skills/kb-workflow/references/kb-agents-precipitation.md)

## 约束

- 只创建/修改「实现范围」中列出的文件
- 遵循 AGENTS.md 中的项目规范（中文注释、conventional commits）
- 目录 `AGENTS.md` 只写**代码规范**（目录编码规矩），禁止业务逻辑、knowledge 级业务规格、单次变更流水账与「评审沉淀(日期)」式章节；尤其禁止写入各端根 `AGENTS.md`
- 不写测试脚手架（项目约定；验收分层由 `/kb-test` 在 `auto_test/` 按需补 Playwright/契约）
- 如果发现任务描述与实际代码矛盾，报告冲突而不是自行修改接口
- CodeGraph 发现额外影响面时，只报告并等待主 Agent/用户确认，不自行扩大实现范围

## 精简实现（Ponytail 口径，必遵）

细则见 [kb-ponytail.md](../skills/kb-workflow/references/kb-ponytail.md)：

1. 写代码前走**六阶决策梯**（YAGNI → stdlib → 平台原生 → 已有依赖 → 一行 → 最小实现）
2. 优先改现有文件；禁止在 `03` 实现范围外新建抽象层、helper、mixin/notifier 或新增 pub/crate/npm 依赖
3. 对有意接受的简化加 `// ponytail:` 或 `# ponytail:` 中文注释（已知上限 + 升级路径）
4. 不得为精简删减 `01`/`02`/`03` 要求的业务语义、信任边界校验、防数据丢失处理、安全与权限逻辑
5. `/kb-apply` 不写单元/集成测试脚手架；实现验证以 `03` 验收标准与 CodeGraph 影响面复核为准；Playwright/契约自动化在 review 后 `/kb-test` 阶段按需补写
```

### 4. 验收检查

每一轮完成后，验证：

- **状态回写（manifest 单写者）**：并行组内每个 builder **只在回报**中给出 `tasks` 状态变更建议（done/failed + 原因），**禁止**自行写盘 `00-manifest.json`；**每完成一批任务**须在回报中列出本轮 `T{n}` 状态表。**每一轮结束后**由主 Agent 另派**单一**子 Agent（优先 `kb-scribe`，或单一合并 Task）串行合并写回本轮全部 `done`/`failed`；进行中可先将 `stage` 写为 `"applying"`；**不得**在仍有失败任务时写 `"applied"`。禁止多个 builder 并发写同一 manifest。若 chain 可能被杀（超时/SIGTERM），scribe 单写者**被杀前尽量**回写 `stage="applying"` 与已完成的 `tasks[].status`，避免进度丢失。

- **评审问题回写**：若本轮执行的是 `T-FIX-{n}` 或 `T-Rev{n}-FIX-{m}`，由**上述单写者**子 Agent 将关联 `reviews[].status` 从 `"open"` 更新为 `"fixed"`，并写入修复文件、任务 ID 与简短说明；无法确认修复时保持 `"open"`。

- **验收标准逐项检查**：读取修改后的文件，确认每个 checkbox 条件满足

- **冲突检测**：如果多个任务修改了同一文件的不同部分，确认无遗漏合并

- **CodeGraph 影响面复核**：若任务修改公共符号、接口、服务方法或数据结构，使用 `codegraph_impact`（或 `pi__codegraph_impact` / CLI 等价）复核调用方是否已纳入实现范围；发现遗漏时停止并报告，不直接扩散修改。

- **验证口径**：默认不主动执行全量 `flutter analyze`、`dart analyze`、`cargo check`。只有用户明确要求，或任务验收标准指定了某个定向命令时，才执行该指定范围，并在报告中摘要结果。

### 5. 全部通过后的强制链（`flow = standard`）

**仅当本轮全部任务验收通过**时执行；若仍有失败任务：**不写** `stage = "applied"`、**不进入** review、**不串联** test。

在 `flow = standard` 下，须**同会话**按序完成（失败即阻断，不得跳步或仅「建议下一步」）：

1. **写 stage**：由子 Agent 将 `00-manifest.json` 的 `stage` 写为 `"applied"`（进行中可先写 `"applying"`，全部通过后必须为 `"applied"`）。
2. **校验 manifest**（失败即阻断，不得进入 review）：

```bash
node "${PI_KB_ROOT}/scripts/kb-manifest-validate.mjs" --file <变更目录>/00-manifest.json
```

3. **执行范围对账闸门**（`flow = standard` 必走；`flow = lite` 豁免）：
   - 由子 Agent 运行 `node "$PI_KB_ROOT/scripts/kb-audit-apply.mjs" --change-dir <变更目录> --json`
   - 脚本读取 `00-manifest.json.tasks[].files`（合并所有 `done` 任务）与 `git diff --name-only` 对比；脚本自动归一化路径并排除 bootstrap 产物（`.kb/`、`kb.project.json` 等）；缺失/多余均计入 drift。
   - `result=ok`：在 manifest 写入 `audit.{result:"ok", checked_at: ISO8601}`，stage 升级为 `"applied_audited"`，进入原步骤 4（review）。
   - `result=drift`：在 manifest 写入 `audit.{result:"drift", missing_files, extra_files, drift_report, checked_at}`，**回退** `stage` 为 `"applying"` 并在变更目录 `02-plan.md` 末尾追加 `## 对账漂移报告（自动）` 一节引用 audit 内容；**阻断**进入 review，由主 Agent 询问用户是修复 plan 还是补做改动。
   - 标准流豁免条件：用户明示「本轮跳过 audit」时按 `flow = lite` 同等豁免，但必须在执行报告注明。
4. **强制派发 `/kb-review`**：同会话执行 `/kb-review` 的完整步骤（产出评审结论；标准流 focused/full 须产出 `04-review.md`），**不是**「建议用户下一步再跑 review」。
5. **串联 `/kb-test`**：review **通过**后，同会话再执行可执行的 `/kb-test` 完整步骤（见 `prompts/kb-test.md（斜杠 `/kb-test`）` 契约）。review **未通过**时：不进入 test；按评审修复路径走 `/kb-apply` 或 `/kb-revise-apply` 后再 review。
6. **archive**：不得在本命令末尾跳过 review 直接 `/kb-archive`。test 通过或验收策略写完后，可提示用户（或后续步骤）运行 `/kb-archive`；archive 仍在 review/test 闭环之后触发。
7. **贡献分（可选同轮）**：若本轮实现**实际依赖**了 `manifest.files` 中 `kind=knowledge` 路径（或明确阅读的知识文件）且验收通过，由子 Agent shell `bump` 这些路径（`--delta 1`）；知识与代码冲突且确认知识误导时 `penalize`。细则 [kb-knowledge-evolve.md](../skills/kb-workflow/references/kb-knowledge-evolve.md)。无知识依赖可跳过。

`flow = lite`：**豁免**本强制链；勿套用上述自动串联（贡献分 bump 仍可在有知识依赖时执行）。

### 6. 失败处理

如果某个任务失败：
- 记录失败原因
- 不阻塞同轮其他任务
- 本轮结束后，尝试修复失败任务（再给子 agent 一次机会，附带错误信息）
- 如果二次失败，停止并报告，由主 agent 决定是否继续
- **不写** `stage = "applied"`，**不进入** `/kb-review` / `/kb-test` / `/kb-archive`

如果修复任务失败：
- 保持对应 `reviews[].status = "open"`，不要标记为 `fixed`
- 在执行报告中列出阻断的 review ID 和失败原因
- 不进入 `/kb-review` 强制链，也不进入 `/kb-archive`

### 7. 输出执行报告

```
## 执行报告

| 任务 | 轮次 | 状态 | 修改文件 |
|------|------|------|---------|
| T1   | 1    | ✅   | 新建 2 文件 |
| T2   | 1    | ✅   | 修改 1 文件 |
| T3   | 2    | ✅   | 修改 2 文件 |
| T4   | 2    | ❌   | 验收失败: xxx |
| T5   | 3    | ⏸️   | 被阻塞（T4 失败） |

### 下一步（强制链，非建议）
- 若有失败任务：修复后重新执行对应轮次；**不写 applied、不进入 review**
- **全部任务通过后**（仅 `flow = standard`）：同会话按序执行
  1. `stage = "applied"`
  2. `kb-manifest-validate.mjs`（失败即阻断）
  3. 强制执行 `/kb-review` 完整步骤
  4. review 通过后再同会话串联 `/kb-test`
- review/test 闭环完成后：可再运行 `/kb-archive <中文名称>`；**禁止**跳过 review 直接 archive
```

## 注意事项

- 子 agent 需要并行修改同一文件时，优先拆成串行；确需并行试验时使用隔离工作区，最后由一个合并任务写回主工作区
- `00-manifest.json` 始终单写者：并行 builder 只回报状态，轮末由单一 `kb-scribe`/合并 Task 写盘；禁止后写覆盖
- 主 agent 负责调度和验证，不参与具体编码或文件写入
- 如果 03-tasks.md 中没有依赖图，按顺序串行执行
- 每轮完成后检查任务验收标准与 manifest 状态，避免错误累积到后续轮次
- `flow = standard` 下，全部通过后的 review/test 为**同会话强制链**，不得改写成「建议下一步」