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 分钟），以防止运行超时。