---
description: 基于业务 PRD（01-proposal）与知识库、CodeGraph，生成实现方案设计
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"`。

## 用户输入

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

---
基于 **`01-proposal.md` 业务 PRD** 与知识库，设计技术实现方案；知识库影响初评与更新计划在本阶段写入 `02-design.md`。

**输入**: 变更名称（**必须为中文**，对应 `knowledge/变更/进行中/` 下的目录）。

**内容结构**：`02-design.md` 章节标题、顺序以 [`knowledge/AGENTS.md`](../../knowledge/AGENTS.md) 为准--大标题统一用中文数字 `## 一、` … `## 十、`，段内小节用 `### （一）` … `### （三）`，**不得**自行增删或调换顺序；某段确无内容时写「无」。

## 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 / 重启会话，再重试本命令。

## 约束

- **变更名称必须为中文**
- 目录格式：`<YYYYMMDDHHMMSS>-<中文名称>`
- 读取 `01-proposal.md` 作为**业务真相**（产品口径、验收标准）；技术真相在本命令产出 `02-design.md`
- 变更文档前缀；本命令产出 `02-design.md`
- `02-design.md` **必须**包含 `## 一、业务流程与改动范围`（位于 `## 二、整体思路` 之前）
- 流程图 **必须**基于 `01-proposal.md` 的 `§业务流程`（主流程 + 关键分支 + 失败/回退），**不得**仅用技术分层图替代业务流
- **必须**用统一图例标注节点：`不改` / `改动` / `新增` / `删除`（写在节点 label 或紧邻 legend）
- **必须**附「流程步骤与改动对照表」，每行含：步骤 ID、业务含义、改动类型、涉及模块/文件、与 01 验收的对应关系
- 纯知识库同步类变更若无用户可见业务流，允许用「数据/配置流转图」替代，但须在表中说明「无用户交互主流程」的原因
- 缺业务流程图或改动对照表视为 **design 阶段未完成**，不得将 `stage` 设为 `designed`

## 子 Agent 编排（必遵）

- 检索类似实现、分层模式、接口惯例、**代码影响面**时**并行**派发 `Task`（`generalPurpose` 只读）；必须优先 CodeGraph。
- **仓外/时效信息**（官方 API、SDK changelog、协议版本）：派发 **kb-scribe** 或只读子 Agent 时须允许并要求使用 `web_search`；query 具体、优先 `allowed_domains` 官方站、落盘写入「外部依赖/假设」并带 Sources。无工具则引导 `/kb-deepseek-search-setup`，声明「未完成外网核对」。细则：[kb-deepseek-search.md](../skills/kb-workflow/references/kb-deepseek-search.md)。
- 子 Agent 写入 `02-design.md` 与更新 `00-manifest.json.stage = designed`。

## 执行步骤

### 1. 读取业务 PRD

```bash
cat "knowledge/变更/进行中/*-<中文名称>/01-proposal.md"
```

确认 `01` 为业务 PRD（含验收标准），非旧版工程提案。读取 `00-manifest.json`，确认 `flow = standard`；缺失则先补建。

**提取流程节点清单**：列出 `01` 中 `§业务流程` 下所有小节标题与步骤编号，作为后续 Mermaid 节点与对照表行项（子 Agent 交付物之一）。

### 2. 深入检索知识库

按两级索引读 `index.md` → 领域/平台 index → 相关叶子文件（架构、接口、数据、流程等），对照 PRD 涉及的业务域。

### 3. CodeGraph 与代码影响（并行 `Task`，自 propose 迁入）

并行子 Agent 示例：

- **Rust**：`rust_server/` 相关入口、服务、数据层
- **Flutter**：`vkk_client_flutter/lib/` 用户可见链路
- **Quasar / proto**：若 PRD 涉及后台或契约

每个子 Agent prompt 须包含：

- `codegraph_explore` 定位入口、相关符号与源码
- 必要时 `codegraph_impact` / `codegraph_callers` / `codegraph_callees`
- 交付物：
  - **可能修改的文件路径**、依赖与风险、与知识库文件对应关系
  - **每个流程节点的现网实现符号**（caller/callee）
  - **该节点是否落在 PRD 改动范围内**（是/否/待定）

主 Agent 汇总时：**先**合流业务图与改动表，**再**写接口/数据结构/实现步骤；实现步骤编号应能回溯到流程步骤 ID（如「步骤 2-B 对应 saveTokens 防御 scrub」）。

### 4. 编写设计文件

子 Agent 写入 `02-design.md`（**固定十段 + 段内 `（一）（二）（三）` 小节，顺序不可变**；编号规则见 AGENTS §六）：

```markdown
---
type: ChangeDesign
title: <需求名称> - 实现设计
description: <一句话设计摘要>
timestamp: <ISO8601>
---

# <需求名称> - 实现设计

> **业务 PRD**：见同目录 `01-proposal.md`（验收标准以 01 为准）

## 一、业务流程与改动范围

> 业务口径以 `01-proposal.md` §业务流程 为准；下图覆盖主流程与关键分支。

### （一）业务流程图

\`\`\`mermaid
flowchart TD
  startNode[用户触发] --> stepA[步骤A 不改]
  stepA --> stepB[步骤B 改动]
  stepB --> stepC[步骤C 新增]
\`\`\`

**图例**：`不改` 行为与现网一致；`改动` 需改代码/配置；`新增` 新节点或新分支；`删除` 移除路径。

### （二）流程步骤与改动对照

| 步骤 ID | 业务含义 | 改动 | 落点（模块/文件） | 01 验收关联 |
|---------|----------|------|-------------------|-------------|
| ... | ... | 不改/改动/新增/删除 | `path/to/file` | 01 §... |

### （三）改动汇总

- **改动**：…
- **新增**：…
- **不改（显式列出）**：… - 避免 implement 阶段误改

## 二、整体思路

<!-- 可追溯 01 的章节（如「见 01 §…」）；说明根因、方案要点与边界 -->

**最小方案三问（必答，细则见 [kb-ponytail.md](../skills/kb-workflow/references/kb-ponytail.md)）**：

1. 能否复用 CodeGraph 已定位的现有模块/符号，而非新建文件或抽象层？
2. 拟新增的抽象、trait/mixin/notifier 层或第三方依赖，是否被 `01` 验收或 PRD 明确要求？若否，说明 YAGNI 依据或改为 inline/复用。
3. 能否合并到已有文件完成改动，而非「预建通用层」？若必须新建，在 §二 写一句理由。

## 三、分层设计

<!-- 可选：架构 Mermaid 侧重模块边界，不能替代「（一）业务流程图」 -->
- **端点层**：
- **服务层**：
- **数据层**：

## 四、接口设计

<!-- 无新增接口时写「无」并说明沿用契约 -->

## 五、数据结构

<!-- 表/字段/模型扩展；无变更时写「无」 -->

## 六、实现步骤

<!-- 按顺序编号；每步应能回溯到「（二）」对照表中的步骤 ID -->
1. ...

## 七、参考实现

<!-- CodeGraph 命中的关键符号与路径；无命中时说明检索方式 -->

## 八、技术影响

### （一）影响范围

- 涉及模块：
- 接口/proto 变更：
- 数据变更：
- 风险：

### （二）工程补充验收项

<!-- 01 未覆盖但实现需核对的工程向验收；无则写「无」 -->
- [ ] …

## 九、知识库影响

<!-- 初评：archive 前由「（一）」细化 -->
- `knowledge/业务域/...` — 原因
- `knowledge/工程平台/...` — 原因
- 两级索引：是否需更新 `index.md` / 领域 index（说明原因）

## 十、知识库更新计划

<!-- archive 主消费清单 -->

### （一）必须更新

- ...

### （二）可能更新（视实现结果）

- ...

### （三）不需要更新

- ...
```

### 5. 高内聚低耦合检查

模块边界、依赖是否合理。

### 6. 输出总结

阶段完成前自检：

- [ ] `## 一`～`## 十` 大段齐全；「一 / 八 / 十」段内 `### （一）…（三）` 小节齐全（规则见 AGENTS §六编号规则）
- [ ] 至少 1 张 Mermaid **业务流程**图（位于「（一）」，非仅「三、分层设计」图）
- [ ] 对照表覆盖 01 全部主流程与分支
- [ ] 所有 `改动`/`新增` 行有文件路径
- [ ] `不改` 节点已显式列出（或表中标注）
- [ ] `## 二、整体思路` 已回答 Ponytail **最小方案三问**（见 [kb-ponytail.md](../skills/kb-workflow/references/kb-ponytail.md)）；新增抽象/依赖有 YAGNI 依据

通过后：

- `00-manifest.json.stage` → `designed`
- 下一步：`/kb-plan <中文名称>`