Agent Review｜面向编码智能体的可审计代码审查系统

A local-first, auditable code review system for coding agents.

English · 中文

Agent Review 是一个独立于宿主模型的本地审查执行内核。它冻结 Git 变更，生成不可变 ReviewBundle（审查包），为四类独立 Reviewer 投影不同上下文，校验结构化 Finding（审查发现），运行允许列表内的确定性 Evidence（证据），并保存可追踪的 JSON 与 Markdown 报告。

当前版本：0.1.0。核心流程与可选 Mechanical Check Packs 已实现并有自动化测试。本仓库是个人公开项目，用于作品展示、技术交流和招聘评估，并采用 Apache License 2.0 开源许可证。

它解决什么问题

编码智能体可以快速生成或修改代码，但普通对话式 Review 容易出现四个问题：审查对象在过程中变化、不同 Reviewer 互相污染判断、结论缺少可复查证据、报告无法在另一台机器复现。

Agent Review 把这些问题拆成可验证的系统边界：

• 用内容哈希冻结一次审查的输入和来源；

• 让正确性、安全性、架构和测试 Reviewer 只看到各自所需的只读投影；

• 用跨语言 JSON Schema 约束 Finding、Evidence 和报告；

• 只执行仓库预先允许的命令 ID，并记录退出码、耗时、stdout/stderr 和截断状态；

• 把警告、盲区、供应商降级和最终报告保存在本地台账中。

Related MCP server: @shareworker/code-review-mcp

为什么不能只用一个 Skill

Skill 是宿主智能体中的技能与编排说明，适合告诉 Codex“按什么顺序调用工具”。它本身不能提供不可变快照、Schema 校验、角色隔离、本地持久化、Evidence 状态转换或确定性报告。

Agent Review 与 Skill 的关系是“执行内核 + 宿主编排”：Skill 可以驱动流程，但审查协议、数据验证、命令边界和审计记录由独立的 TypeScript CLI/MCP 内核负责。更换宿主模型不会改变这些核心契约。

当前能力与边界

已完成

• 本地 TypeScript CLI 和 stdio MCP（模型上下文协议）服务；

• working-tree、staged、branch、commit 四种 Git 范围；

• 不可变 ReviewBundle、内容派生的 snapshotHash 和本地审查台账；

• 正确性、安全性、架构、测试四类角色上下文；

• Zod 运行时校验与语言无关的 JSON Schema；

• Basic、CRG、Auto 三种代码智能模式；

• 允许列表 Evidence 与确定性 JSON/Markdown 报告；

• 可选 Mechanical Check Packs，内置 generic、TypeScript、Java Pack；

• 经过契约测试的 Codex Skill 和四个只读 Reviewer 配置。

兼容性术语：Mechanical 扩展仍是 opt-in Mechanical Check Packs；未启用或不存在时，unchanged V1 workflow 仍是默认路径。

可选或降级能力

• CRG（代码关系图工具）是可选增强。auto 在 CRG 不可用时显式降级到 Basic 并写入 warning；crg 模式则直接失败。

• Mechanical Checks 默认不自动启用。配置必须先提交到可信 Git 基线，后续 Review 才能使用；候选配置只能被校验，不能为自身授权。

• Basic 模式保证最低可用流程，但只提供变更文件级上下文，不宣称图关系覆盖。

尚未完成

• 操作系统级进程、网络或文件系统沙箱；

• Claude Code、OpenClaw 等宿主的同等级安装器与集成测试；

• 自动修复、修复者自证和独立验证闭环；

• 企业多租户、中央控制平台、远程数据库和权限系统；

• 对所有语言、构建系统和静态分析格式的覆盖；

• 大规模真实用户、准确率、性能或节省时间数据。

总体架构

flowchart LR
    A["Git 变更 + Requirement"] --> B["prepare / prepare_review"]
    T["可信 Git 基线中的可选 Mechanical Plan"] --> B
    B --> C["不可变 ReviewBundle"]
    C --> D1["正确性上下文"]
    C --> D2["安全性上下文"]
    C --> D3["架构上下文"]
    C --> D4["测试上下文"]
    D1 --> E["结构化 Findings"]
    D2 --> E
    D3 --> E
    D4 --> E
    C --> F["允许列表 Evidence"]
    E --> G["确定性报告"]
    F --> G
    G --> H["本地 JSON + Markdown 台账"]

代码依赖方向由自动化架构检查强制执行：

protocol <- domain <- application <- adapters/report <- delivery/composition

详见 架构说明。

一次完整审查流程

1. prepare 解析 Requirement、验收标准和 Git 范围，冻结 ReviewBundle。

2. 宿主分别读取 correctness、security、architecture、test 上下文。

3. 四个独立 Reviewer 返回符合 Schema 的 Finding；上下文不包含 Author 的对话、隐藏推理、自评或身份。

4. 协调者用同一个 snapshotHash 提交四类 Finding。

5. 如需验证，协调者选择 .agent-review/config.yaml 中稳定的 commandId 运行 Evidence；Reviewer 不能直接提供命令。

6. finalize 生成确定性 JSON/Markdown，report 读取结果。

完整命令和失败处理见 审查工作流。

四种 Git 审查范围

四类产品审查角色

不可变审查包

ReviewBundle 记录请求、Git 基线、变更文件与符号、适用 Policy、代码智能来源、Evidence、warning 和 provenance。snapshotHash 由内容派生；后续提交若使用不同哈希会被拒绝。

它不会包含 Author 的完整聊天记录、隐藏思维链、自我评价、模型名、资历或原始环境变量。角色上下文是同一 Bundle 的只读投影，不是四个 Reviewer 共享的可变记忆。

代码智能模式

核心协议不依赖 CRG 类型，CRG 只是可替换 Provider（供应商适配器）。

七个 MCP 工具

输入输出、错误信封和版本兼容规则见 协议与 MCP。

确定性检查与 Evidence

普通 Evidence 命令定义在 .agent-review/config.yaml。Mechanical Check Packs 则从 scope 对应的可信 Git 对象解析 Pack、命令模板、模式、Parser 和角色，然后在候选工作区运行预先允许的命令。内置 Pack 不会自动安装工具或从远程下载规则。

Evidence 只能支持一个 Finding，不能把运行过的检查自动标记为 VERIFIED；没有运行的命令也不能被写成已通过。Mechanical Diagnostic 是候选观察，不会自动变成产品 Finding。

快速开始

要求：Node.js 24–26、Git。CRG 非必需；只有从源码开发时才需要 pnpm 10.34.5。

npm install --global @yibei-wz/agent-review@latest
agent-review --version
agent-review --repository /path/to/target setup
agent-review --repository /path/to/target prepare \
  --scope working-tree \
  --provider basic \
  --requirement "描述本次变更必须满足的行为" \
  --acceptance-criterion "写出一条可验证的验收标准"

setup 用一次确认完成基础配置、Codex MCP、Review Skill、四个只读 Reviewer，以及按仓库语言自动选择的 Mechanical Check Packs。它不会运行目标仓库代码，也不会提交文件；Mechanical 配置在人工审查并提交前保持 PENDING_TRUSTED_BASELINE。自动化环境可显式传入 --yes。公开 npm 包会安装 agent-review 命令；启动或重启 Codex 前，请在同一环境确认 agent-review --version 可用且 npm 全局可执行目录位于 Codex 可见的 PATH。后续升级可重新运行上述 npm 安装命令。

prepare 返回 reviewId 和 snapshotHash。继续读取四类上下文、提交 Finding、可选执行 Evidence，再 finalization。可复制的完整流程、安装 tarball 和 Codex MCP 配置见 快速开始。

脱敏示例

仓库提供一个虚构 Java 支付重试场景，仅用于展示协议，不来自真实公司或客户：

• Requirement：重试必须复用调用者提供的幂等键；

• Finding：重试路径生成新键，可能导致重复扣款；

• Evidence：允许列表内的幂等测试返回 FAIL；

• Report：Finding 为 SUPPORTED，同时保留未验证问题和 Basic/CRG warning。

完整 Markdown 示例见 examples/review-report.md。示例中的仓库、路径、人员、标识和数据均为合成值。

JSON 报告片段：

{
  "schemaVersion": "1.0",
  "reviewId": "review-example",
  "snapshotHash": "sha256:example-snapshot",
  "findings": [
    {
      "findingId": "payment-retry-idempotency",
      "role": "correctness",
      "severity": "HIGH",
      "status": "SUPPORTED"
    }
  ],
  "conclusion": "This report is bounded evidence; no findings does not mean the change is absolutely safe."
}

Markdown 报告片段：

## Findings

| Severity | Status    | Role        | Location                       | Title                        |
| -------- | --------- | ----------- | ------------------------------ | ---------------------------- |
| HIGH     | SUPPORTED | correctness | `src/.../OrderService.java:12` | Retry can duplicate a charge |

安全模型和信任边界

必须先理解这些边界：

1. 当前本地命令执行器 not an OS sandbox，不是操作系统级沙箱。

2. 构建、测试和包管理脚本可能执行候选代码。候选 package scripts、Maven/Gradle plugins、wrappers、tests、build hooks 和 runtime code 都可能以当前用户权限运行。

3. EvidenceCommandRunner、参数数组、shell: false、offline flags、timeout、output limits、cancellation 和 redaction 是受控调用措施，不证明候选代码安全。

4. Trusted execution configuration controls Plan authority only. 可信配置只决定哪些命令可以进入 Plan，不改变 candidate workspace 中代码的可信度。

5. Keep Mechanical Checks disabled for untrusted code，或在外部容器、虚拟机、沙箱、隔离 CI Runner 中运行完整流程。

6. warning MECHANICAL_CHECKS_EXECUTE_UNSANDBOXED_CANDIDATE_CODE 会显式暴露未隔离执行边界。

7. 没有发现问题不代表代码绝对安全；Agent Review 辅助审查，不替代项目所有者的最终责任。

完整威胁模型、路径边界、秘密脱敏保证和残余风险见 安全模型。

已知限制

• 本地存储不承诺数据库级多写者、NFS/SMB 或任意断电恢复语义。

• Evidence 脱敏覆盖常见字面量与环境变量名称；编码、拆分、重排后的秘密可能逃逸。

• 自动降级到 Basic 会降低关系图覆盖，但会写入 warning，不会静默宣称完整。

• Reviewer 是概率模型；结构化输出和角色隔离不能消除错误判断。

• 候选执行可访问网络、启动子进程或修改 Diff 之外的数据，除非外部环境限制它。

• 当前仅 Codex 集成具备仓库内契约测试，其他宿主不作兼容承诺。

路线图

路线图表示方向，不是已承诺的交付时间：

1. 扩充经过真实 Fixture 验证的 Pack 与 Parser；

2. 改善安全的 Evidence 目录发现与审查体验；

3. 为其他宿主增加同等级安装、隔离和契约测试；

4. 在单独威胁模型下研究远程控制面与更强执行隔离；

5. 只有在真实、可复查数据存在后才发布性能或准确率结果。

开发与验证

pnpm format:check
pnpm lint
pnpm typecheck
pnpm arch
pnpm test
pnpm test:contract
pnpm build
pnpm verify

CI 使用 Node 24、pnpm 10.34.5、锁文件安装、只读 contents 权限，不读取 Secret、不发布包、不上传 Artifact。贡献流程见 CONTRIBUTING.md。

许可证

Copyright © 2026 yibei-wz.

本项目采用 Apache License 2.0。你可以在遵守许可证条款的前提下使用、修改和分发本项目，包括商业用途。许可证包含明确的专利授权，不授予商标权，也不提供任何担保。

文档

• 快速开始

• 审查工作流

• 架构

• 协议与 JSON Schema

• 安全模型

• Apache License 2.0

• Mechanical Check Packs

• 代码智能 Provider 契约

• Codex 集成

• 双语文档索引

• 英文版 README

设计规格用于解释产品边界，不是新用户的上手入口；当前可用能力以上述 README、用户文档、实现和测试为准。