review-agent-setup

review-agent-governance — 设置

将 AI Agent 的审查操作（PR 审查、评论、合并、CI 编辑）置于明确的人工审批之后。每一次尝试，无论批准还是拒绝，都会生成一份 Ed25519 签名的凭据。

何时使用此插件

在 Claude Code Agent 会执行以下操作的项目中安装它：

• 审查、评论或合并拉取请求（gh pr review、gh pr merge）
• 分诊 issue（gh issue comment、gh issue close）
• 发布 release（gh release create）
• 修改 CI 配置（.github/workflows/、.gitlab-ci.yml）
• 推送到受保护分支（main、master、release、production）
• 发布到外部通知渠道（Slack webhook、Discord），前提是你为执行发布的命令添加了规则（默认策略不会拦截它们）

如果 Agent 只做本地文件编辑和运行测试，此插件就大材小用了。请使用 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

你可以编辑此文件以匹配项目的具体规则。关于编写审查策略的指导，请参见 ../agents/review-policy-author.md。

3. 创建凭据目录和签名密钥

mkdir -p ./review-receipts
echo "/review-receipts/" >> .gitignore
echo "/review-governance.key" >> .gitignore
echo "/.review-approved" >> .gitignore
if [ ! -e ./review-governance.key ]; then
  d=$(mktemp -d) && npx [email protected] init --dir "$d" && mv "$d/keys/gateway.json" ./review-governance.key
fi

protect-mcp 0.7.4 的 sign 不会创建密钥，最后一条命令会创建它，并且它绝不会替换已有的密钥。没有密钥时，凭据是未签名的。要轮换密钥，请归档 ./review-governance.key 和 ./review-receipts/receipts.jsonl，然后再次运行该命令。将 ./review-governance.key 中的 publicKey 值提供给审计人员。不要提交该文件，因为它同时也保存着私钥。

每会话工作流

Cedar 策略会无条件拒绝审查面上的操作。要批准某个具体操作，请在其之前打开审批窗口，并在其后关闭。

标志文件（最简单）

# Before the action you want to approve
touch ./.review-approved

# Let Claude Code run the review / comment / merge

# Immediately after
rm ./.review-approved

斜杠命令（在 Claude Code 内）

/approve-review "Reviewing PR #123 authored by contributor X"

这会创建 ./.review-approved，并将给定的原因作为备注嵌入其中，同时将该原因记录到 ./review-receipts/approvals/ 下的未签名审批日志中。仍需随后执行一次 rm 来关闭窗口。

全部试运行（强制执行完整策略评估）

如果你希望每一次工具调用都经过 Cedar，且没有审批绕过：

export REVIEW_APPROVAL_FLAG=./.never-approve

任何匹配 forbid 规则的工具调用都会被拒绝；已批准的窗口不会生效。适用于 CI 或锁定式的审计运行。

验证凭据

列出所有凭据：

ls -la ./review-receipts/

使用公钥离线验证每一份凭据：

PUB=$(node -p 'JSON.parse(require("fs").readFileSync("./review-governance.key")).publicKey')
npx @veritasacta/[email protected] --replay-chain ./review-receipts/receipts.jsonl --key "$PUB"

退出码 0 表示每份凭据均验证通过。退出码 1 表示某份凭据验证失败，原因是它被篡改、密钥错误或某行格式不正确。退出码 2 表示无法读取凭据文件。

被拒绝的调用永远不会运行，因此没有凭据。要查看策略拦截了什么，请在 Claude Code 内运行：

/list-pending

它会列出当前会话中被 PreToolUse 钩子拦截的工具调用，并附上工具名称以及命令或路径。

示例：批准一次 PR 审查

# 1. Human reviews the agent's proposed comment
$ /list-pending
  Blocked in this session:
  - Bash "gh pr review 42 --approve --body 'LGTM'"
  - Bash "gh pr comment 42 --body 'Looking good'"

# 2. Human decides the first one is appropriate, approves it
$ /approve-review "Approving LGTM on PR 42 after visual inspection"
  ./.review-approved created

# 3. Agent retries the action; this time it succeeds
$ agent: gh pr review 42 --approve --body "LGTM"
  [receipt appended to ./review-receipts/receipts.jsonl, decision=allow]

# 4. Human closes the window
$ rm ./.review-approved

被允许的调用有一份签名凭据，任何持有公钥的人都可以离线验证。被拒绝的尝试没有凭据，而且审批日志是未签名的，所以向审计人员展示轨迹时请把这两点都考虑在内。

与 protect-mcp 组合使用

如果两个插件都已安装，每个插件的 hooks/hooks.json 都会注册自己的 PreToolUse 钩子，Claude Code 会在每次工具调用时同时运行两者：

{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/evaluate.sh" }

每个 evaluate.sh 都从 stdin 上的钩子负载中读取 tool_name 和 tool_input（Claude Code 不设置 TOOL_NAME 变量），并评估各自的策略：protect-mcp 使用 ./protect.cedar，此处使用 ./review-governance.cedar。

两个钩子都必须通过，工具调用才能继续。任一策略中的 Cedar deny 都会阻止它。

标准

• Ed25519 — RFC 8032（数字签名）
• JCS — RFC 8785（确定性 JSON 规范化）
• Cedar — AWS 的开放授权策略语言
• IETF 草案 — draft-farley-acta-signed-receipts