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

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

[English](README_EN.md) · 中文

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

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 和截断状态；
- 把警告、盲区、供应商降级和最终报告保存在本地台账中。

## 为什么不能只用一个 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 等宿主的同等级安装器与集成测试；
- 自动修复、修复者自证和独立验证闭环；
- 企业多租户、中央控制平台、远程数据库和权限系统；
- 对所有语言、构建系统和静态分析格式的覆盖；
- 大规模真实用户、准确率、性能或节省时间数据。

## 总体架构

```mermaid
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 台账"]
```

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

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

详见 [架构说明](docs/architecture.zh-CN.md)。

## 一次完整审查流程

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` 读取结果。

完整命令和失败处理见 [审查工作流](docs/review-workflow.md)。

## 四种 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](docs/protocol.md)。

## 确定性检查与 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。

```bash
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 配置见 [快速开始](docs/quick-start.md)。

## 脱敏示例

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

- Requirement：重试必须复用调用者提供的幂等键；
- Finding：重试路径生成新键，可能导致重复扣款；
- Evidence：允许列表内的幂等测试返回 `FAIL`；
- Report：Finding 为 `SUPPORTED`，同时保留未验证问题和 Basic/CRG warning。

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

JSON 报告片段：

```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 报告片段：

```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 辅助审查，不替代项目所有者的最终责任。

完整威胁模型、路径边界、秘密脱敏保证和残余风险见 [安全模型](docs/security.zh-CN.md)。

## 已知限制

- 本地存储不承诺数据库级多写者、NFS/SMB 或任意断电恢复语义。
- Evidence 脱敏覆盖常见字面量与环境变量名称；编码、拆分、重排后的秘密可能逃逸。
- 自动降级到 Basic 会降低关系图覆盖，但会写入 warning，不会静默宣称完整。
- Reviewer 是概率模型；结构化输出和角色隔离不能消除错误判断。
- 候选执行可访问网络、启动子进程或修改 Diff 之外的数据，除非外部环境限制它。
- 当前仅 Codex 集成具备仓库内契约测试，其他宿主不作兼容承诺。

## 路线图

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

1. 扩充经过真实 Fixture 验证的 Pack 与 Parser；
2. 改善安全的 Evidence 目录发现与审查体验；
3. 为其他宿主增加同等级安装、隔离和契约测试；
4. 在单独威胁模型下研究远程控制面与更强执行隔离；
5. 只有在真实、可复查数据存在后才发布性能或准确率结果。

## 开发与验证

```bash
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](CONTRIBUTING.md)。

## 许可证

Copyright © 2026 yibei-wz.

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

## 文档

- [快速开始](docs/quick-start.md)
- [审查工作流](docs/review-workflow.md)
- [架构](docs/architecture.zh-CN.md)
- [协议与 JSON Schema](docs/protocol.md)
- [安全模型](docs/security.zh-CN.md)
- [Apache License 2.0](LICENSE)
- [Mechanical Check Packs](docs/mechanical-check-packs.md)
- [代码智能 Provider 契约](docs/provider-contract.md)
- [Codex 集成](integrations/codex/README.md)
- [双语文档索引](docs/README.md)
- [英文版 README](README_EN.md)

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