---
description: 从设计文档分解出原子任务，每个任务足够详细以供子 agent 独立执行，含依赖关系支持并行调度
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"`。

## 用户输入

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

---
从 02-design.md 分解出可独立执行的原子任务。每个任务包含完整上下文，子 agent 无需额外推理即可开始工作。

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

**内容结构**：`03-tasks.md` 文件级章节以 [`knowledge/AGENTS.md`](../../knowledge/AGENTS.md) 为准--大标题用中文数字 `## 一、` / `## 二、` 固定顺序；执行计划段内用 `### （一）依赖图` / `### （二）分组调度`；单条任务内仍用 `## T{n}` + `### 背景` 等字段，**不得**省略任务模板字段。

## 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)"`

门禁通过后，再确认 MCP 工具 `codegraph_*`（至少能调用 `codegraph_explore`（或 `codegraph_status`））可用。若工具不可用：阻断，并指引用户从插件示例复制项目级 MCP 配置：

按 [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`
- **仅产出/更新 `03-tasks.md`（及变更目录内说明）**，不修改各端业务源码；需求变更场景下常接在 **`/kb-revise`** 之后。

## 子 Agent 编排（必遵）

- **依赖与引用关系**、**按层拆分任务草案**：用 `Task` 并行 `generalPurpose` 只读模式完成；子 Agent 必须先用 CodeGraph 识别候选文件、调用链和影响面。
- 每个子任务交付物为「文件依赖边列表」或「单条 `T{n}` 完整 Markdown 草案」。
- 主 Agent 合并依赖图、消除循环依赖、统一编号与分组调度说明；`03-tasks.md` 的实际写入由子 Agent 执行。

## 执行步骤

### 1. 读取设计文档

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

同时读取业务 PRD 作为验收追溯来源：
```bash
cat "knowledge/变更/进行中/*-<中文名称>/01-proposal.md"
# 必要时兼容读取 knowledge/变更/归档/*-<中文名称>/01-proposal.md
```

**验收追溯**：每条 `03` 任务的验收标准须能覆盖 `01` 的「验收标准」与 `02` 中的工程验收项（若有「工程补充」须标明）；`01` 为业务真相，`02` 为实现真相。

读取 `00-manifest.json`，确认阶段不晚于 `planned`；若缺失则先补建 manifest。

### 2. 分析代码依赖图（并行 `Task`）

使用 **`Task` + `generalPurpose` 只读模式** 并行分析设计涉及的依赖（可按仓库拆分）：

- 列出需要新建/修改的文件候选
- 文件间 import/引用关系、共享类型/mod
- 与设计中的「6、实现步骤」逐条对齐，标出可并行边界
- 每个候选任务的可能冲突文件，供调度时避免并行写同一文件

CodeGraph 使用要求：
- 先用 `codegraph_explore` 按设计目标定位入口和相关符号。
- 用 `codegraph_impact` 识别修改公共类型、服务方法、接口定义可能波及的调用方。
- 用 `codegraph_callers` / `codegraph_callees` 补齐依赖边；只在 CodeGraph 未覆盖时读取具体文件确认 import/mod 细节。

主 Agent 合并各子 Agent 输出后再进入分解。

### 3. 分解原子任务（可并行草案）

**分解原则**：
- 每个任务只涉及 1-3 个文件的修改/创建
- 任务之间通过明确的接口契约耦合（函数签名、struct 定义、mod 导出）
- 被多个任务依赖的公共定义（如 struct、enum、trait）拆为独立任务
- 数据层（repository）优先于服务层，服务层优先于端点层
- **Ponytail 口径**（细则 [kb-ponytail.md](../skills/kb-workflow/references/kb-ponytail.md)）：禁止「预建通用层」任务，除非 `02` §2 已写明 YAGNI 依据；优先合并到已有文件的任务划分

若任务数较多：可对每一批「同层或同文件簇」**并行**派发 `Task`（`generalPurpose`），prompt 要求**仅返回一条 `T{n}` 的完整 Markdown 块**（含背景、上下文文件、实现范围、接口契约、验收标准、依赖），主 Agent 统一改 ID、校对依赖图后，派发子 Agent 写入 `03-tasks.md`。

**每个任务必须包含以下全部字段**：

```markdown
## T{n}: {任务名称}

### 背景
<!-- 这个任务为什么存在，它在整体设计中的位置。2-3句话。 -->

### 上下文文件
<!-- 子 agent 必须读取的文件，按优先级排列 -->
- CodeGraph: {查询关键词或关键符号} — {用于定位调用链/影响面}
- 必读: {精确文件路径} — {读取目的}
- 必读: {精确文件路径} — {读取目的}
- 参考: {精确文件路径} — {可选，辅助理解}

### 实现范围
<!-- 精确到文件和方法级别 -->
- 新建: {文件路径} — {包含什么内容}
- 修改: {文件路径} — {改什么，从什么改为什么}
- 删除: {文件路径} — {为什么删除}

### 接口契约
<!-- 本任务对外暴露的接口，其他任务依赖这些定义 -->
- `{函数签名或 struct 定义}` — {用途}
- `{mod 导出}` — {用途}

### 验收标准
- [ ] {具体可检查的条件}
- [ ] {具体可检查的条件}
- [ ] 无 `02`/`03` 未要求的抽象层、trait/mixin 中间层或未批准的新依赖（Ponytail 口径，见 [kb-ponytail.md](../skills/kb-workflow/references/kb-ponytail.md)）

### 依赖
- 前置任务: {T{n} 或 "无"}
- 后续任务: {T{n} 或 "无"}
```

### 4. 生成依赖图

在 `03-tasks.md` 头部写入固定结构（**顺序不可变**），主 agent 据此判断并行度：

```markdown
# <需求名称> - 任务分解

> **来源**：`/kb-plan`（基于 `01-proposal.md`、`02-design.md`）

## 一、执行计划

### （一）依赖图

T1 ──→ T3 ──→ T5
T2 ──→ T4 ──→ T5
T6（独立）

### （二）分组调度

- **第一轮（并行）**: T1, T2, T6
- **第二轮（并行）**: T3, T4
- **第三轮**: T5

## 二、任务清单

<!-- 以下每条任务自包含；子 agent 执行时只读单条 T{n} + 上下文文件 -->
```

### 5. 写入任务文件

由子 Agent 将完整任务写入 `knowledge/变更/进行中/*-<中文名称>/03-tasks.md`；若用户明确选择归档目录中的变更继续修订，则写入对应 `knowledge/变更/归档/*-<中文名称>/03-tasks.md`。

同时更新 `00-manifest.json`：
- `stage`: `"planned"`
- `tasks`: 写入每个任务的 `id`、`title`、`status: "pending"`、`files`（**相对业务仓根**路径，正斜杠，如 `knowledge/变更/进行中/<变更>/01-proposal.md`；允许字符串或 `{path,kind,source,status}` 对象，audit 取 `.path`）、`depends_on`
- `updated_at`: 当前时间

### 6. 输出总结

阶段完成前自检：

- [ ] `## 一、执行计划` 与 `## 二、任务清单` 齐全，符合 AGENTS §七「变更任务文档结构」
- [ ] 每条 `T{n}` 含背景、上下文文件、实现范围、接口契约、验收标准、依赖六字段
- [ ] 每条 `T{n}` 验收标准含 Ponytail 口径项（无未批准抽象/新依赖）；无「预建通用层」任务，除非 `02` §二 已说明

展示调度计划和总任务数，建议下一步：

- "任务已分解。运行 `/kb-apply <中文名称>` 按依赖图调度子 agent 执行。"
- "实现完成后，运行 `/kb-archive <中文名称>` 归档"

## 注意事项

- 任务描述必须自包含：子 agent 只读 03-tasks.md 中的单个任务 + 上下文文件，不应需要读 02-design.md
- 如果设计步骤超过 8 个，考虑合并相关步骤减少任务数（目标 3-8 个任务）
- 修改同一文件的不同部分可以并行（在验收标准中标注冲突区域）
- 若多个任务写同一文件，默认拆成串行轮次；只有使用隔离工作区并指定单一合并任务时才允许并行
- 优先按层级分解：数据层任务 → 服务层任务 → 端点层任务