yibei-wz/agent-review

# Agent Review｜面向编码智能体的可审计代码审查系统 [English](README_EN.md) · 中文 [](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 等宿主的同等级安装器与集成测试； - 自动修复、修复者自证和独立验证闭环； - 企业多租户、中央控制平台、远程数据库和权限系统； - 对所有语言、构建系统和静态分析格式的覆盖； - 大规模真实用户、准确率、性能或节省时间数据。 ## 总体架构 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 详见 [架构说明](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、pnpm 10.34.5、Git。CRG 非必需。 pnpm install --frozen-lockfile pnpm build 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`。执行前须先让已构建或安装的 `agent-review` 命令位于 Codex 可见的 `PATH`；当前 npm registry 尚无正式发布包。 `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 报告片段： { "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 辅助审查，不替代项目所有者的最终责任。 完整威胁模型、路径边界、秘密脱敏保证和残余风险见 [安全模型](docs/security.zh-CN.md)。 ## 已知限制 - 本地存储不承诺数据库级多写者、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](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、用户文档、实现和测试为准。

标签：AI编程助手, MITM代理, SOC Prime, 云安全监控, 代码审查, 开发工具, 网络安全研究, 自动化审查, 自动化攻击, 静态分析