review-agent-governance：用 Cedar 策略与 Ed25519 回执为 AI 代码审查代理加上人类审批闸门

review-agent-governance：用 Cedar 策略与 Ed25519 回执为 AI 代码审查代理加上人类审批闸门

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents

导读

review-agent-governance是 agents24 仓库中一个专注于"审查面（review surface）"治理的 Claude Code 插件：在 AI 代理执行 PR 审查、评论、合并、Issue 操作、发布 Release、改写 CI 配置等高风险动作之前，强制要求一次明确的人类批准信号；同时通过 protect-mcp + Cedar 策略评估与 Ed25519 签名回执链，为每次放行或拦截留下可离线验证的防篡改审计证据。读完本文，你将掌握该插件的策略文件结构、双钩子执行链路、批准窗口的两种开启方式（flag 文件与/approve-review斜杠命令）、回执链的验证方法，以及如何与protect-mcp组合实现"通用策略 + 审查面专项闸门"的分层治理。

它要解决的失败模式：无人类闸门的审查面事故

AI 代理如果能够直接面向审查面发帖（PR 评论、批准、合并、CI 工作流修改），就可能影响其他贡献者、受监管系统以及代码库本身的完整性。当代理产生幻觉、误读上下文或被诱导错误执行时，损害是即时且可见的：在真实账号下出现虚假审查评论、发生本不该发生的合并、工作流文件被悄悄改写。

正如插件 README 所指出，这并非假设性风险——审查机器人曾批量发布幻觉式审查评论、批准了本不该批准的 PR、以破坏其他安全控制的方式编辑工作流文件。问题的根源在于：自动化代理被赋予了审查面动作权限，而在动作发生的那一刻缺少人类闸门，这会把一个局部 bug 放大为公开事故。review-agent-governance正是针对这一具体失败模式设计的：它不试图限制代理的一切行为，而是精确地在"后果重大、影响他人的动作"前面加一道人工确认。

插件工作机制：两个钩子包围每一次工具调用

插件的全部逻辑集中在 Claude Code 的 Hook 配置中。其核心机制由两个钩子构成（见 hooks/hooks.json）：

1. PreToolUse：先检查人类批准 flag。若 flag 存在，直接exit 0放行；若不存在，则调用npx protect-mcp@0.7.4 evaluate对 Cedar 策略文件求值。Cedar 返回 deny 时工具调用以退出码 2 结束，Claude Code 随即阻止该调用。

2. PostToolUse：无论工具调用是被放行、被拒绝还是被跳过，都通过npx protect-mcp@0.7.4 sign对本次尝试生成一份 Ed25519 签名回执，记录"哪些动作被授权、何时被授权"。

实际配置中，钩子通过以下环境变量保持可配置性：

注意PreToolUse钩子带有--fail-on-missing-policy false，策略文件缺失时不会硬性失败，避免误伤普通会话。批准窗口通过创建./.review-approvedflag 文件开启，窗口一直保持开放直到 flag 被删除。

默认策略：审查面上哪些动作被闸住

默认策略位于 policies/review-agent-governance.cedar，全部采用"无批准则 forbid"的声明式规则。核心拦截面如下：

• GitHubghCLI 发帖类动作：gh pr review、gh pr comment、gh pr close、gh pr merge、gh pr edit、gh issue comment、gh issue close、gh issue edit、gh release create、gh release edit，以及兜底的gh api repos（捕获任意 GitHub REST 调用，防止绕过命令模式匹配直接调 API）。
• GitLab / Bitbucket 等效命令：glab mr comment、glab mr approve、glab mr merge、glab issue comment等。
• 向受保护分支的git push：当context.target_branch命中main、master、release、production时禁止git push、git push --force、git push -f。
• 对 CI/CD 配置文件的直接写入：Write/Edit动作命中.github/workflows/、.github/CODEOWNERS、.gitlab-ci.yml、.circleci/config.yml、buildkite/pipeline.yml时禁止——因为改写这些文件等于让代理改变未来所有构建与审查的运行方式，绕过其他一切防护。
• WebFetch的 POST 请求：当context.method == "POST"且目标主机为api.github.com、api.gitlab.com、api.bitbucket.org、hooks.slack.com、discord.com时禁止。

策略末尾保留一条宽松的兜底规则permit (principal, action, resource);——除了上述审查面动作，其余一切照常放行。插件刻意保持聚焦，如需通用工具调用策略治理，应与 protect-mcp 配合使用。

与之配套的 policies/review-agent-governance.cedarschema 定义了四类动作的上下文结构：Bash动作带command_pattern: String与可选的target_branch；Write/Edit动作带path_starts_with: String；WebFetch动作带method: String与url_host: String。这些类型约束正是cedar validate能够静态校验策略的依据。

一处值得注意的写法：用.contains()而非in

从策略源码可以看出，所有列表匹配都写成["gh pr review", ...].contains(context.command_pattern)这种形式，而不是context.command_pattern in [...]。这不是风格偏好，而是踩坑后的修正：test/run-tests.sh 明确说明这是为了抵御"#598in-on-String forbid bug"——Cedar 会静默丢弃context.<attr> in [ ... ]形式的 forbid 规则，导致闸门形同虚设。

该测试脚本分两部分：Part A（仅依赖grep，总是运行）扁平化策略文本后断言不存在context.<attr> in [的 forbid 模式，并确认已改用].contains(context.<attr>)惯用法；Part B（仅当本机安装了cedarCLI 时运行）用cedar validate --policies ... --schema ...校验策略类型正确性，若cedar缺失则 SKIP 而不失败。需要说明的是，插件运行时是protect-mcp serve（Cedar 经 WASM 执行），该测试直接校验策略源文件，不依赖 protect-mcp。

安装与一次性配置

1. 安装插件

claude plugin install wshobson/agents/review-agent-governance

2. 将默认策略复制到项目根目录

cp .claude/plugins/review-agent-governance/policies/review-agent-governance.cedar \ ./review-governance.cedar

策略文件可以按项目实际规则自由编辑（例如调整受保护分支列表、补充自研审查工具的 CLI 模式），编写与审计策略的专项指导见 agents/review-policy-author.md。

3. 初始化回执目录并忽略敏感文件

mkdir -p ./review-receipts echo "./review-receipts/" >> .gitignore echo "./review-governance.key" >> .gitignore echo "./.review-approved" >> .gitignore

protect-mcp sign首次调用时会自动生成签名私钥；建议从第一份回执中提取并提交公钥，供日后审计方离线验证。一次性安装的完整步骤还可参考 skills/review-agent-setup/SKILL.md。

完成配置后，有两种使用模式任选其一：

• （推荐）保持钩子每个会话都生效，在审查动作前显式打开批准窗口；
• 设置REVIEW_APPROVAL_FLAG=./never-approve，等于彻底禁用批准旁路，强制每一个审查面动作都经过 Cedar 求值——适合 CI 或锁定的审计运行。

打开批准窗口的两种方式

方式一：flag 文件（最简）

touch ./.review-approved # 让代理执行被批准的动作 rm ./.review-approved

方式二：Claude Code 内的斜杠命令

/approve-review "Posting the code review for #123"

该命令（实现见 commands/approve-review.md）会创建./.review-approved文件、将批准原因写入文件并追加一条 JSON 记录到./review-receipts/approvals/，随后输出确认信息并提醒尽快rm ./.review-approved关闭窗口。命令内部用$ARGUMENTS完整捕获带空格的批准原因，并通过python3 -c 'import json...'做 JSON 转义，防止引号、反斜杠、换行破坏审批记录的结构。

关于批准日志的重要澄清：./review-receipts/approvals/*.json是纯 JSON 记录，而非签名回执。它们不经过protect-mcp sign，因此@veritasacta/verify不覆盖它们。批准日志属于"操作者信任"范畴——它记录人类打算批准什么，但事后可被编辑而不被发现。真正签名且防篡改的，是PostToolUse为每个动作（无论放行还是拒绝）生成的./review-receipts/*.json工具调用回执，它们才是权威审计链，可用npx @veritasacta/verify ./review-receipts/*.json验证。若受监管环境需要同样签名的批准记录，可将其单独通过npx protect-mcp@latest sign --tool approve-review --input ...走一遍签名流程。

查看待审批或被拒动作

/list-pending

该命令（实现见 commands/list-pending.md）遍历./review-receipts/回执链，按event_time倒序打印最近的decision: deny条目（默认最近 10 条，支持--last N），展示工具名、命令模式/路径与时间戳，并提示可用/approve-review "<reason>"批准后重试。它只读不改，且会跳过approvals/子目录——因为那里不是工具调用回执。

签名链覆盖范围的边界

当批准 flag 存在时，PreToolUse钩子短路为exit 0，不会调用protect-mcp evaluate。因此该被批准动作的PostToolUse回执会带有decision: allow但没有policy_digest字段（因为未求值任何 Cedar 策略）。审计人员遍历回执链时应预期：被批准的工具调用显示为带reason: human_approved、无策略引用的签名回执；而被拒绝的动作和普通非审查动作（确实经过 Cedar）则照常携带policy_digest。

端到端示例会话

一个处理 PR 的代理想发布审查评论。无批准时：

$ agent: gh pr review 42 --comment --body "LGTM" → PreToolUse hook runs → No ./.review-approved file, policy evaluates → Cedar: forbid on context.command_pattern == "gh pr review" → Exit 2: Claude Code blocks the tool call → PostToolUse runs, signs a receipt with decision=deny

有批准时：

$ touch ./.review-approved $ agent: gh pr review 42 --comment --body "LGTM" → PreToolUse hook runs → ./.review-approved present, exit 0 → Tool call proceeds → PostToolUse signs a receipt (decision=allow, reason=human_approved) $ rm ./.review-approved

./review-receipts/中的回执链会同时记录这两次尝试：先是被拒的 deny，后是批准后的 allow。审计人员日后翻阅回执链，可以精确还原哪些动作经过人类闸门、发生在何时。

验证回执链

# 列出所有回执 ls -la ./review-receipts/ # 离线验证整条链 npx @veritasacta/verify ./review-receipts/*.json

@veritasacta/verify的退出码语义：退出 0表示每份回执都真实、链完整；退出 1表示有回执在签名后被篡改；退出 2表示回执格式损坏。验证不依赖操作者——任何持有公钥的一方都可以独立完成。

与 protect-mcp 组合：分层策略治理

review-agent-governance只关注审查面动作；若需要对所有 Claude Code 工具调用做通用策略治理，应同时安装 protect-mcp。两者天然互补：

• protect-mcp对每次工具调用求值通用策略（例如禁止rm -rf、限制Write到项目根目录内）；
• review-agent-governance在之上叠加审查面闸门。

两个钩子都会执行、都会产生回执。可将回执目录分别配置为./receipts/与./review-receipts/以保持两条审计链独立，便于审计工作流。在 Claude Code 侧，二者的PreToolUse钩子按顺序配置（见 skills/review-agent-setup/SKILL.md 中的组合示例），任一策略 deny 都会阻止工具调用。

为什么选择 Cedar + 签名回执

Cedar（AWS 开源授权引擎）让策略以声明式、形式化方式表达。审查者无需阅读代码即可理解被闸住的动作集合；策略可经cedar validate做类型检查；策略改动可 diff、可评审。

Ed25519 回执（RFC 8032 签名、RFC 8785 JCS 确定性规范化、哈希链式链接）提供不依赖操作者的防篡改证据。任何持有公钥的第三方都能运行npx @veritasacta/verify ./review-receipts/*.json，用退出码证明每份回执的真实性与整条链的完整性；任何回执在签名后被改动，验证即以退出 1 失败。

延伸：如何扩展与审计自定义策略

若团队使用 Linear、Jira、Notion 或自研审查工具，可参考 agents/review-policy-author.md 中给出的扩展模式：为对应 CLI 命令模式或 WebFetch 主机追加forbid规则（例如context.command_pattern starts with "linear"、context.url_host == "api.linear.app"且method == "POST"）；为专属审查机器人账号追加受限permit。审计既有策略时重点关注五点：每个审查面命令是否有对应 forbid 规则、gh api repos兜底是否覆盖任意 REST 调用、受保护分支git push规则是否与仓库设置一致、CI/CD 路径规则是否匹配项目实际使用的文件、结尾的默认放行规则是否覆盖了更早的 forbid（Cedar 中forbid具有权威性，后置permit不会解除它）。

标准与依赖

插件基于的标准与运行时依赖：Ed25519（RFC 8032，回执签名）、JCS（RFC 8785，签名前确定性规范化）、Cedar（AWS，声明式策略求值）、IETF 草案 draft-farley-acta-signed-receipts（回执格式）、protect-mcp（npm 运行时，本插件依赖其 evaluate/sign 子命令）。所有源码、策略、测试与文档均位于仓库 plugins/review-agent-governance/ 目录下，可供进一步深入研读。

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents