# Code Review

> 面向 ZeroLaunch-rs 的项目专属代码审查技能。对当前工作区、staged 变更、当前分支全量变更、指定 git range 或最近 N 次 commit 的聚合变更进行多 agent 并行审查，重点验证逻辑正确性、确认是否引入新回归、检查架构边界耦合、以及验证与 .omp/rules/ 规则的一致性。

- Skill: `ghost-him/code-review` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add ghost-him/code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ghost-him/code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ghost-him (https://skillmd.com/u/ghost-him)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ghost-him/code-review

---


## 用途

对 ZeroLaunch-rs 的代码变更执行**项目专属**代码审查。默认只读，不直接修改代码。6 个并行子 agent 分别覆盖：

1. **变更建模** — 建立风险地图，为后续 agent 提供聚焦点
2. **逻辑正确性** — 控制流、状态流、数据契约、异步时序、错误路径
3. **新回归** — 严格只计"变更前没有、变更后出现"的问题
4. **架构结构（4a）** — 代码放置、类型边界、依赖方向（P1/P2/P3，P2/P3 有脚本兜底）
5. **架构行为（4b）** — 职责域解耦、通信方式、接口复用、**过度设计检测**（P4/P5/P6 + 设计债，纯人工判断）
6. **规则一致性** — 与 `.omp/rules/` 的规定是否一致（不一致可能是代码违反规则，也可能是规则已过时需更新）

## 触发方式

```text
/code-review                                    # 默认: 审查工作区变更 (git diff HEAD)
/code-review --staged                           # 仅审查暂存区
/code-review 审查本分支中的所有更改               # 审查当前分支相对默认分支的全量变更
/code-review <git range>                        # 审查指定范围，如 main..HEAD、HEAD~3..HEAD
/code-review 对过去5次commit做审核               # 最近 N 次 commit 聚合审查
/code-review 审核最近3个 commit                  # 同上
```

**范围解析优先级**：明确 git range > "最近 N 次 commit" 描述 > "本分支" 描述 > 默认 working-tree。

当 `N > 1` 或范围为多 commit 时，进入**跨 commit 审核模式**：先聚合审查，再对大 commit 单独下钻。

## 执行流程

### 第一阶段：确定范围并收集上下文（脚本驱动）

1. 根据用户参数运行上下文收集脚本：

```bash
# mode 取值: working-tree | staged | branch | range | commits
bash .omp/skills/code-review/scripts/collect-context.sh <mode> [range_or_n]
```

脚本一次性输出：变更统计、按子系统分组的文件清单、子系统交叉数、需加载的规则文件、**依赖方向检查（确定性，workspace + src-tauri 内部模块层级）**、**边界类型泄漏检查（确定性）**、构建/lint 建议、**IPC 命令三方一致性检查（确定性）**、大 commit 分类表。

2. 若脚本建议执行构建检查（任意 `.rs` 变更），执行 `cd src-tauri && cargo check`；并优先运行 `cargo clippy`——其中 `clippy::await_holding_lock` 可**确定性**检出「RwLock/Mutex 守卫跨 `.await`」这一核心规则违规，胜过肉眼看 diff。
3. 若变更涉及前端或 IPC 契约，必要时执行 `bun run build`。
4. 命令不存在或成本过高时，回退到静态分析并在结论中说明。

### 第二阶段：并行发现（6 个子 agent）

同时启动 6 个只读审查 agent。各 agent 的提示词模板见 `references/agent-prompts.md`。

所有 agent 共享前置约束：

- **只读**，不修改文件
- 先读 `references/project-review-checklist.md`
- 阅读第一阶段脚本输出的上下文报告
- 按变更路径加载 `.omp/rules/` 中最相关的规则文件
- 若存在 `.codegraph/`，优先使用 CodeGraph

| Agent          | 职责                         | 严重程度上限     |
| -------------- | ---------------------------- | ---------------- |
| 1 — 变更建模   | 建立风险地图                 | 不评级（信息性） |
| 2 — 逻辑正确性 | 控制流/状态流/契约/异步/错误 | 阻塞             |
| 3 — 新回归     | 仅计本次引入的回归           | 阻塞             |
| 4a — 架构结构  | P1 放置/P2 类型边界/P3 层级  | 阻塞             |
| 4b — 架构行为  | P4 职责域解耦/P5 通信/P6 复用 + 过度设计检测 | 阻塞（设计债定级中/低） |
| 5 — 规则一致性 | 与 `.omp/rules/` 的一致性    | 阻塞（A 类违规） |

Agent 5 的核心区分：不一致发现分为 **A 类**（代码违反规则，需改代码）和 **B 类**（规则已过时，需更新规则）。A 类问题使用阻塞级提示。

### 第三阶段：大 commit 下钻

仅在多 commit 范围审查时执行。第二阶段的 `collect-context.sh` 已通过 `classify-commits.sh` 输出大 commit 分类表。

大 commit 判定标准（满足任一）：

- 变更文件数 ≥ 8
- 插入 + 删除总行数 ≥ 300
- 跨越 ≥ 2 个核心子系统

对每个大 commit 启动独立审查 agent（提示词模板见 `references/agent-prompts.md` 末尾）。只有在聚合审查完成后才决定是否下钻，不机械逐个重审。

### 第四阶段：主 Agent 汇总

阅读 6 份聚合审查报告（及大 commit 报告如有），执行以下步骤：

#### 4.1 冲突检测与复核

**若不同子 agent 对同一代码位置的结论相互冲突**（例如 Agent 2 认为某处有逻辑错误，Agent 4a/4b 认为该设计合理），主 agent **必须**：

1. 自行阅读相关代码与 diff，独立确认实际情况
2. 在对应问题条目下追加一行 `[冲突复核：<来源 agent> 认为 <结论>，复核后确认 <最终判定>]`，说明采纳哪方结论，或两方都不完全正确

不跳过这一步，不简单"少数服从多数"。冲突复核行内化，不设独立章节。

#### 4.2 报告生成

按 `references/report-template.md` 规定的结构与输出风格生成最终报告。模板只保留四要素问题条目：**等级 / 现象 / 位置 / 修复建议**（外加来源标注与冲突复核行）。

**如实全量呈现纪律（必须遵守）**：

- 最终报告必须覆盖**每个子 agent 报告中的每一条发现**——包括疑点、既有问题、B 类规则更新建议
- 同一位置的多 agent 同质问题可以合并为一条，但必须标注全部来源（如 `来源：Agent 2、Agent 4a`）；**不得**因报告已长、问题已多、或与其他 agent 重复而省略任何子 agent 的问题
- 报告生成完毕后，对照各子 agent 报告逐一核对覆盖情况（每条发现都出现在最终报告中），核对结果写入报告文件末尾（`覆盖核对：Agent 1 (N) / Agent 2 (N) / ... / Agent 5 (N) 全部纳入`）
- Agent 1（变更建模）不产出问题条目，其风险地图压缩为总览表中的「变更概要」一句话

#### 4.3 结果持久化到文件

结构化审查结论生成后，**必须**将完整审查报告写入文件：

- **目录**: `.omp/skills/code-review/reports/`（若不存在，使用 `mkdir -p` 创建）
- **文件名格式**: `code-review-YYYY-MM-DD-简短摘要.md`
  - `YYYY-MM-DD` 为审查执行当天的日期
  - `简短摘要` 描述审查范围，如 `working-tree`、`main-to-HEAD`、`staged`、`last-3-commits`、`review-plugin-system` 等（使用英文 kebab-case）
- **文件内容**: 包含完整的结构化审查结论（`references/report-template.md` 的所有章节），从"总体结论"到"覆盖核对"，各子 agent 的报告摘要可精简纳入而不丢失关键信息。文件开头加一行元数据（格式见 `references/report-template.md` 末尾）
- **写入方式**: 使用 `Write` 工具写入。若同日期同范围的文件已存在，则追加或覆盖均可（新文件头部注明"覆盖前次报告"）
- **时机**: 在向用户输出审查结论的同时或之后立即执行，确保结果不丢失

## 判定准则

最终判断以以下项目约束为审查锚点：

- **架构原则 P1-P6**（详见 `references/architecture-principles.md`）：职责驱动放置、类型职责边界、编译期层级、运行时职责域解耦、通信方式契约、接口复用优先
- 前端是薄展示层；业务逻辑、文件/进程/平台操作必须留在后端 IPC 之后
- IPC 类型契约必须 Rust / TypeScript 双端同步，字段名使用明确的 serde rename
- `commands/` 是命令入口，不是业务逻辑容器
- 插件系统优先沿用既有抽象：`PluginHandle`、`ExecutorRegistry`、`CandidatePipeline`、`SearchPipeline`、`Configurable` 生命周期
- 过度设计检测（Agent 4b）：为「可能到来的未来」提前支付的抽象成本——零调用者接口、可推导冗余字段、恒值预留字段、状态空间虚胖（合法组合远小于声明组合且靠纪律维持）、单实现者抽象。此类定级「中/低」（设计债），不得因"为未来好"升为阻塞；若抽象实际破坏了现有功能，归 Agent 2/3 的阻塞/高问题
- `PluginManager` 与配置/路由系统通过事件解耦，不重新拉回直接依赖
- 同步锁守卫不得跨 `await`（`parking_lot`/`std::sync`/`DashMap` 等；`tokio::sync` 异步锁豁免）
- workspace 依赖方向 + src-tauri 内部模块层级不可反转（`check-deps-direction.sh` 确定性检查）
- 类型职责边界（P2）：类型定义位置编码职责，职责决定使用范围（`check-type-scope.sh` 确定性检测已知边界类型；LLM 按方法论判断所有类型含新增）
- 代码必须与 `.omp/rules/` 中的规定一致；不一致时区分"代码违反规则"与"规则已过时"

## 脚本清单

| 脚本                              | 用途                                                                                                                                          |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `scripts/lib.sh`                  | 共享库：子系统分类、核心子系统判定、路径→规则文件映射（`collect-context.sh` 与 `classify-commits.sh` 共同 source，避免分类逻辑漂移）          |
| `scripts/collect-context.sh`      | 收集审查上下文（diff stat、子系统分类、规则映射、架构检查、IPC 命令检查、大 commit 分类）                                                     |
| `scripts/classify-commits.sh`     | 对多 commit 范围中的每个 commit 做大 commit 分类                                                                                              |
| `scripts/check-deps-direction.sh` | 确定性检查依赖方向：workspace crate 层级 + **src-tauri 内部模块层级（P3）**，检出反向依赖                                                      |
| `scripts/check-ipc-commands.sh`   | 确定性交叉校验 IPC 命令：`#[tauri::command]` 定义 ↔ `generate_handler!` 注册 ↔ 前端 `invoke` 调用，检出未注册/未定义/前端调用不存在命令等漂移 |
| `scripts/check-type-scope.sh`     | 确定性检查边界类型泄漏（P2）：IPC DTO（`commands/` 内 struct）与 `BridgeError` 是否被内部模块（core/plugin_framework/builtin_plugin/state）引用  |

脚本输出进入上下文，脚本代码本身不消耗上下文 token。能用脚本确定性判断的检查项一律用脚本，不交给 LLM 推断，当前覆盖：

- 依赖方向合规性（workspace + 内部模块层级，`check-deps-direction.sh`，对应 P3）
- 边界类型泄漏（`check-type-scope.sh`，对应 P2）
- 文件分类 / 规则映射 / 核心子系统交叉 / 大 commit 判定（`lib.sh` + `collect-context.sh` + `classify-commits.sh`）
- IPC 命令定义/注册/前端调用三方一致性（`check-ipc-commands.sh`）
- RwLock/Mutex 守卫跨 await（交由 `cargo clippy` 的 `await_holding_lock` 而非 LLM）

> 架构原则的详细定义（P1-P6、层级表、职责域、类型范围表）见 `references/architecture-principles.md`，是 Agent 4a/4b 的核心审查依据。

## 注意事项

你只可以一步一步的按照该步骤处理。不可以做其他更多的事。不要在没有明确指令的情况下修改代码。

由于脚本执行或 cargo check 的时间会比较长，所以你必须将超时时间设置为至少 5 分钟（推荐 10 分钟），以防止运行超时。