---
description: 代码评审，嵌入 KB 工作流。按风险选择 lite-review、focused-review 或 full-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"`。

## 用户输入

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

---
基于 KB 工作流上下文的代码评审。利用 01-proposal.md、02-design.md、03-tasks.md 或 lite summary 提供评审上下文，按风险分级产出问题清单；标准流通过后进入 `/kb-test`，再由 archive 消费。

**输入**: 变更名称（**必须为中文**，对应 `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)"`

门禁通过后，再确认 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 优先级使用两位数字前缀；读取与新增产物均使用 `04-review.md`

## 评审分级

先基于 `00-manifest.json`、`manifest.files`、`05-summary.md`、实际 diff 做风险判定：

| 等级 | 适用场景 | 执行方式 |
|---|---|---|
| lite-review | `flow = lite` 或记录型低风险文案/样式/局部修正，未触发契约/数据/权限/资金/事务 | 对 `flow = lite` 可豁免：可不生成 `04-review.md`；若用户要求评审，单个只读子 Agent 检查范围和明显 bug |
| focused-review | 普通局部实现、知识同步型 lite、单端小功能，风险可收敛 | 1～2 个只读子 Agent，聚焦设计偏差、明显 bug、知识库清单 |
| full-review | 高风险标准流程、跨端联动、proto/HTTP/gRPC 契约、数据库、资金、权限、事务、审计、安全敏感路径 | 默认六角并行评审（#1～#5 + Ponytail #6） |

风险等级必须写入 `04-review.md` 的 `§1 审查范围` 或 `05-summary.md` 的评审说明。低风险不因“走了 KB 流程”自动升级 full-review。

**产物约束**：`flow = standard` 下 focused-review / full-review **必须**产出 `04-review.md`；lite-review 对 `flow = lite` 的既有豁免可保留（可不写 `04-review.md`，结论可记入 `05-summary.md`）。

## 子 Agent 编排（必遵）

- full-review 默认 **6 次并行 `Task`**（`generalPurpose` 只读）：Agent **#1～#5** 各一次 + **#6 Ponytail 精简轴** 一次；#1～#5 交付物为「问题条列 + 位置 + 分数建议」。
- focused-review 按风险选择 1～2 个只读 `Task`；**Agent #3 须含 Ponytail 精简检查**（至少 3 条 shrink/yagni/stdlib/native/delete 视角，无则写「Lean already. Ship.」）；lite-review 最多 1 个只读 `Task`，也可只记录“低风险跳过评审”的原因。
- 每个评审子 Agent 必须先用 CodeGraph 理解改动文件相关的调用链和影响面；评审公共符号、接口、数据结构时必须使用 `codegraph_impact`，避免只看 diff 孤立判断。
- 主 Agent 只做去重、评分过滤与报告结构审核；需要写入 `04-review.md` 或更新 manifest 时由子 Agent 执行。

## 执行步骤

### 1. 确定审查范围

```bash
# 查看未提交变更（apply 产出的代码）
git diff --name-only
git diff --cached --name-only
git status --short

# 如果没有未提交变更，审查最近一次提交
git log --oneline -3
git diff HEAD~1 --name-only
```

如果没有任何变更，提示用户先运行 `/kb-apply <中文名称>`。

### 2. 加载 KB 上下文

读取变更目录下的设计文档，获取评审基准：

```bash
# 提案 — 了解需求范围
cat "knowledge/变更/进行中/*-<中文名称>/01-proposal.md"

# 设计 — 实现方案，包含知识库更新计划
cat "knowledge/变更/进行中/*-<中文名称>/02-design.md"

# 任务 — 原子任务清单和验收标准
cat "knowledge/变更/进行中/*-<中文名称>/03-tasks.md"

# 必要时读取 knowledge/变更/归档/*-<中文名称>/ 下的同名文件
```

读取 `00-manifest.json`，确认待评审任务范围；若变更目录缺失该文件，先由子 Agent 补建最小 manifest，再继续评审。评审发现的问题须回写到 `reviews` 数组中，状态初始为 `open`。

若 manifest 中已有 `reviews[]`，本次评审必须先区分：
- 已关闭问题：`fixed`、`accepted_debt`、`false_positive`，只复核是否仍成立，不重复创建同类问题。
- 未关闭问题：`open`，必须继续出现在报告中，或说明已修复并回写为 `fixed`。

### 3. 收集规范上下文

读取以下规范文件（如存在）：
- `AGENTS.md`（根目录）
- `rust_server/AGENTS.md`（后端变更时）
- `quasar/AGENTS.md`（前端变更时）
- `vkk_client_flutter/AGENTS.md`（客户端变更时）

### 4. 按分级启动子 Agent 评审（`Task`）

full-review 必须通过 `Task` 工具并行启动 **6** 个子 Agent（`generalPurpose` 只读模式，同一轮同时发出）：Agent #1～#5 + Agent #6（Ponytail 精简轴）。每个子 Agent 独立评审，返回问题清单。

focused-review 从下列 Agent 中选择最相关的 1～2 个；lite-review 通常只选 Agent #2 或 Agent #3，并可把结论写入 `05-summary.md` 而不补 `04-review.md`。

评审 prompt 必须包含：
- 先对改动文件或关键符号运行 `codegraph_explore`。
- 涉及被复用函数、组件、服务、proto、数据结构时运行 `codegraph_impact`。
- 问题描述需说明是 diff 直接发现，还是 CodeGraph 调用链/影响面发现。

**Agent #1 — 规范合规**：
- 对照 AGENTS.md 检查变更
- 重点：范围控制、枚举规范、中文注释/日志、SQL 分层、文件行数、软删除、时间类型
- 排除不适用于评审的规则（如"不写测试"是约束行为的）

**Agent #2 — Bug 扫描**：
- 只读 diff，聚焦明显 bug
- 空指针/unwrap、逻辑错误、资源泄漏、并发问题、错误处理
- 忽略编译器/linter 会捕获的问题

**Agent #3 — 设计偏差检测**：
- 对比 02-design.md 中的实现方案与实际代码
- 检查 03-tasks.md 中每个任务的验收标准是否满足
- 识别实现中新增了 design 未涵盖的变更
- 检查是否有被意外删除的重要逻辑
- **Ponytail 精简（focused/full 必做）**：对照 [kb-ponytail.md](../skills/kb-workflow/references/kb-ponytail.md) 检查 `02` §2 最小方案三问是否被违反（未批准的新抽象/依赖）；列出最多 3 条可删/可 shrink 项，无则写「Lean already. Ship.」

**Agent #4 — 多端一致性**：
- 如果修改了 proto 或接口，检查 Rust/Flutter/Quasar 三端同步
- 如果修改了枚举值，检查各端映射一致
- 检查客户端调用是否与后端接口契约一致

**Agent #5 — 性能与安全**：
- 热路径多余分配/克隆、阻塞异步运行时
- 数据库 N+1、全表扫、缺少分页
- 密钥/令牌硬编码、错误信息泄露
- 事务一致性（关键多步操作是否在同一事务中）

**Agent #6 — Ponytail 精简轴（仅 full-review 并行）**：
- 只读 diff + CodeGraph；**只** hunt 过度工程，不重复 Agent #2/#5 的正确性/安全职责
- 标签：`delete:` / `stdlib:` / `native:` / `yagni:` / `shrink:`（定义见 [kb-ponytail.md](../skills/kb-workflow/references/kb-ponytail.md) §7）
- 每条一行：`位置 → 删什么 → 用什么替代`；结尾 `net: -N lines possible` 或 `Lean already. Ship.`
- **禁止**将 AGENTS「不写测试」、manifest 白名单、中文注释/日志要求标为 bloat
- 产出并入 `04-review.md` **§3 警告**；默认评分 50～74（建议处理，**不阻断 archive**）；仅当 over-engineering 直接违背 `02`/`03` 范围或引入未批准依赖时可达 ≥75

### 5. 问题去重与评分

对每个子 Agent 发现的问题，独立评分（0-100）：

| 分数 | 含义 |
|------|------|
| 0 | 误报 |
| 25 | 可能有问题但无法确认，未被 AGENTS.md 明确要求 |
| 50 | 确实有问题但不严重 |
| 75 | 很可能是真实问题，会影响功能或违反 AGENTS.md |
| 100 | 确定是真实问题，会频繁触发 |

评分时排除：
- AGENTS.md 中不存在的规则
- 编译器/linter 会捕获的问题
- 未被本次变更触及的已有问题
- 有意为之的功能变更
- 既有代码原样搬运且不在本次 design 范围内的问题

### 6. 输出评审报告

过滤掉评分 < 75 的问题后，派发子 Agent 写入 `knowledge/变更/进行中/*-<中文名称>/04-review.md`；若用户明确选择归档目录中的变更继续评审，则写入对应 `knowledge/变更/归档/*-<中文名称>/04-review.md`：

同时由子 Agent 更新 `00-manifest.json`：
- `stage`: `"reviewed"` 或 `"review_failed"`
- `reviews`: 写入问题 `id`、`severity`、`status`、`file`、`summary`、`task_id`（如已转修复任务）、`resolution`（关闭原因）
- `files`: 追加或确认 `04-review.md`、被评审代码文件、评审修复文件
- 无阻断问题时写入空数组并标记阶段为 `"reviewed"`
- 禁止只在 Markdown 中写“有条件通过/有条件归档”而不更新 manifest；若存在需团队接受的债务，仍写 `review_failed`，由 `/kb-archive` 在用户明确接受后改为 `archived_with_debt`

`reviews[].status` 只能使用：
- `open`：真实问题未处理。
- `fixed`：已修复，必须有修复文件或关联任务 ID。
- `accepted_debt`：用户/团队明确接受债务，只能归档为 `archived_with_debt`。
- `false_positive`：复核后确认误报，必须写明原因。

结构以 [`knowledge/AGENTS.md`](../../knowledge/AGENTS.md)「8」为准；大段须 `## N、` 阿拉伯数字编号，禁止语义或中文序号大段。

```markdown
# <中文变更名称> - 代码评审报告

## 1、审查范围
- **变更类型**: apply 产出的未提交变更
- **评审等级**: lite-review / focused-review / full-review
- **涉及文件**: X 个文件
- **设计文档**: 02-design.md（对照基准）

## 2、严重（必须处理）
<!-- 评分 >= 90；无则写「无」 -->

1. **<简要描述>**
   - 位置: `<文件路径>:<行号>`
   - AGENTS.md: "<引用的具体规则>"
   - 说明: <问题描述与修改方向>

## 3、警告（建议处理）
<!-- 评分 >= 75；无则写「无」 -->

1. **<简要描述>**
   - 位置: `<文件路径>:<行号>`
   - 说明: <问题描述与修改方向>

## 4、设计偏差
<!-- 实现与 02-design.md 不一致之处；无则写「无」 -->

1. **<偏差描述>**
   - 设计预期: ...
   - 实际实现: ...
   - 影响: ...

## 5、验收标准检查
<!-- 从 03-tasks.md 逐项检查 -->

| 任务 | 验收条件 | 状态 |
|------|---------|------|
| T1   | 条件 1  | ✅   |
| T1   | 条件 2  | ❌ 未满足 |

## 6、调用链与回归风险
<!-- mermaid/表格；无则写「无」 -->

## 7、遗留债务
<!-- 不阻断 archive；无则写「无」 -->

## 8、修复任务建议
<!-- 对 open 问题给出可执行闭环方式 -->
| 问题 ID | 建议动作 | 关联任务 |
|---------|----------|----------|
| R1 | 追加 `T-FIX-01` 修复边界判断 | T-FIX-01 |

## 9、结论
<!-- 一句话：通过 → 进入 /kb-test；未通过 → 修复后再 review -->
```

如果没有评分 >= 75 的问题且验收标准全部满足，结论写"**通过**，同会话进入 `/kb-test`"。

否则写"**未通过**，需修复后再评审"，并列出必须处理的问题。需要保留为债务的问题也必须列入“未通过”清单，不能在评审阶段自行放行。

### 7. 生成修复任务（按需）

当存在 `open` 问题时，必须给出闭环建议：
- 局部修复：在 `04-review.md` 的「修复任务建议」中写清楚改动点，并在 manifest 的对应 review 写入建议 `task_id`。
- 需要实际落盘到 `03-tasks.md` 的修复：派发子 Agent 追加 `T-FIX-{n}`，字段格式与 `/kb-plan` 的普通任务一致，`depends_on` 指向被影响任务。
- PRD 变更轮次中的修复：使用 `T-Rev{n}-FIX-{m}`，并写入 `07-prd-revisions.md` 当前轮关联任务。

修复完成后重新运行 `/kb-review <中文名称>`。复评时必须关闭已解决的 review，而不是创建重复问题。

## 在工作流中的位置

```
propose → design → plan → apply → review → test → archive（含 commit+push+可选外部 sync）
  提案      设计    分解    实现    评审     验收     归档
```

- **输入**: apply / revise-apply 产出的代码变更 + 02-design.md/03-tasks.md（且 manifest 已为 `applied` 并通过 validate）
- **输出**: `04-review.md`（标准流 focused/full 必产；archive 会读取此文件）
- **通过**: **同会话串联** `/kb-test <中文名称>`（可执行验收）；**不要**写「直接 `/kb-archive`」
- **未通过**: 按「修复任务建议」运行 `/kb-apply <中文名称>` 或 `/kb-revise-apply <中文名称>`，修复后再运行 `/kb-review <中文名称>`
- **archive**: 在 review 通过且 `/kb-test` 闭环之后，由用户或后续步骤触发；不得跳过 review/test

## 注意事项

- 所有输出使用简体中文
- 评审聚焦本次 design 范围内的变更，不扩散
- 不在 review 阶段补写 Playwright/契约/unit 测试；验收分层由 `/kb-test` 负责
- 不建议执行部署、迁移 SQL 等操作
- 04-review.md 是 archive 的输入之一，归档后随变更目录保留
- 标准流结论模板：**通过 → 进入 `/kb-test`**；**未通过 → 修复后再 review**