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 已实现并有自动化测试。本仓库是个人公开项目，用于作品展示、技术交流和招聘评估，不提供开源授权。
它解决什么问题
编码智能体可以快速生成或修改代码，但普通对话式 Review 容易出现四个问题：审查对象在过程中变化、不同 Reviewer 互相污染判断、结论缺少可复查证据、报告无法在另一台机器复现。
Agent Review 把这些问题拆成可验证的系统边界：
- 用内容哈希冻结一次审查的输入和来源；
- 让正确性、安全性、架构和测试 Reviewer 只看到各自所需的只读投影；
- 用跨语言 JSON Schema 约束 Finding、Evidence 和报告；
- 只执行仓库预先允许的命令 ID，并记录退出码、耗时、stdout/stderr 和截断状态；
- 把警告、盲区、供应商降级和最终报告保存在本地台账中。
为什么不能只用一个 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
详见 架构说明。
一次完整审查流程
prepare解析 Requirement、验收标准和 Git 范围，冻结 ReviewBundle。- 宿主分别读取
correctness、security、architecture、test上下文。 - 四个独立 Reviewer 返回符合 Schema 的 Finding；上下文不包含 Author 的对话、隐藏推理、自评或身份。
- 协调者用同一个
snapshotHash提交四类 Finding。 - 如需验证，协调者选择
.agent-review/config.yaml中稳定的commandId运行 Evidence；Reviewer 不能直接提供命令。 finalize生成确定性 JSON/Markdown，report读取结果。
完整命令和失败处理见 审查工作流。
四种 Git 审查范围
| 范围 | 审查对象 | 典型用途 |
|---|---|---|
working-tree |
当前已跟踪与未跟踪工作区变更 | 提交前检查 |
staged |
Git index 中已暂存的变更 | commit 前门禁 |
branch |
指定 base ref 到当前 HEAD | Feature 分支里程碑 Review |
commit |
指定 commit 与其父提交 | 审查单个已提交变更 |
四类产品审查角色
| 角色 | 关注点 | 不替代什么 |
|---|---|---|
正确性 correctness |
Requirement、验收标准、状态与边界行为 | 产品所有者对需求的最终解释 |
安全性 security |
信任边界、输入验证、泄露和危险执行 | 专业渗透测试与运行环境隔离 |
架构 architecture |
依赖方向、模块职责、协议和演进成本 | 未获批准的新架构设计 |
测试 test |
回归覆盖、失败路径、契约与证据充分性 | 把“测试通过”直接等同于产品正确 |
不可变审查包
ReviewBundle 记录请求、Git 基线、变更文件与符号、适用 Policy、代码智能来源、Evidence、warning 和 provenance。snapshotHash 由内容派生；后续提交若使用不同哈希会被拒绝。
它不会包含 Author 的完整聊天记录、隐藏思维链、自我评价、模型名、资历或原始环境变量。角色上下文是同一 Bundle 的只读投影，不是四个 Reviewer 共享的可变记忆。
代码智能模式
| 模式 | 行为 |
|---|---|
basic |
始终可用；基于 Git 变更提供有限上下文并明确标记覆盖盲区。 |
crg |
强制使用 CRG；CRG 未安装、协议失败或结果无效时终止准备。 |
auto |
优先 CRG；失败时显式写入 CRG_UNAVAILABLE 或 CRG_FALLBACK 并使用 Basic。 |
核心协议不依赖 CRG 类型，CRG 只是可替换 Provider（供应商适配器）。
七个 MCP 工具
| 工具 | 作用 |
|---|---|
prepare_review |
冻结变更并创建 ReviewBundle。 |
get_review_bundle |
读取不可变 Bundle 与来源。 |
get_role_context |
读取一个角色的只读上下文。 |
submit_findings |
校验并保存一个角色的 Findings。 |
run_evidence_checks |
运行选定的允许列表命令 ID。 |
finalize_review |
生成并持久化确定性报告。 |
get_review_report |
读取 JSON 与 Markdown 报告。 |
输入输出、错误信封和版本兼容规则见 协议与 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、pnpm 10.34.5、Git。CRG 非必需。
pnpm install --frozen-lockfile
pnpm build
node dist/cli/program.js --repository /path/to/target init
node dist/cli/program.js --repository /path/to/target doctor --json
node dist/cli/program.js --repository /path/to/target prepare \
--scope working-tree \
--provider basic \
--requirement "描述本次变更必须满足的行为" \
--acceptance-criterion "写出一条可验证的验收标准"
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 |
安全模型和信任边界
必须先理解这些边界：
- 当前本地命令执行器 not an OS sandbox，不是操作系统级沙箱。
- 构建、测试和包管理脚本可能执行候选代码。候选
package scripts、Maven/Gradle plugins、wrappers、tests、build hooks和runtime code都可能以当前用户权限运行。 EvidenceCommandRunner、参数数组、shell: false、offline flags、timeout、output limits、cancellation和redaction是受控调用措施，不证明候选代码安全。- Trusted execution configuration controls Plan authority only. 可信配置只决定哪些命令可以进入 Plan，不改变
candidate workspace中代码的可信度。 - Keep Mechanical Checks disabled for untrusted code，或在外部容器、虚拟机、沙箱、隔离 CI Runner 中运行完整流程。
- warning
MECHANICAL_CHECKS_EXECUTE_UNSANDBOXED_CANDIDATE_CODE会显式暴露未隔离执行边界。 - 没有发现问题不代表代码绝对安全；Agent Review 辅助审查，不替代项目所有者的最终责任。
完整威胁模型、路径边界、秘密脱敏保证和残余风险见 安全模型。
已知限制
- 本地存储不承诺数据库级多写者、NFS/SMB 或任意断电恢复语义。
- Evidence 脱敏覆盖常见字面量与环境变量名称；编码、拆分、重排后的秘密可能逃逸。
- 自动降级到 Basic 会降低关系图覆盖，但会写入 warning，不会静默宣称完整。
- Reviewer 是概率模型；结构化输出和角色隔离不能消除错误判断。
- 候选执行可访问网络、启动子进程或修改 Diff 之外的数据，除非外部环境限制它。
- 当前仅 Codex 集成具备仓库内契约测试，其他宿主不作兼容承诺。
路线图
路线图表示方向，不是已承诺的交付时间：
- 扩充经过真实 Fixture 验证的 Pack 与 Parser；
- 改善安全的 Evidence 目录发现与审查体验；
- 为其他宿主增加同等级安装、隔离和契约测试；
- 在单独威胁模型下研究远程控制面与更强执行隔离；
- 只有在真实、可复查数据存在后才发布性能或准确率结果。
开发与验证
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. All rights reserved.
本仓库当前未采用开源许可证，因此不属于开源软件。除 GitHub 服务条款允许的查看和 Fork 外，未经作者书面许可，不得复制、修改、分发、再许可或将本项目用于商业用途。
文档
- 快速开始
- 审查工作流
- 架构
- 协议与 JSON Schema
- 安全模型
- Mechanical Check Packs
- 代码智能 Provider 契约
- Codex 集成
- 英文版 README
设计规格用于解释产品边界，不是新用户的上手入口；当前可用能力以上述 README、用户文档、实现和测试为准。
