为 AI 代理的 Review 动作编写 Cedar 审批门控策略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本文面向需要为 Claude Code 等 AI 代理配置「审查面review-surface门控」的团队系统讲解如何基于 Cedar 授权语言编写、扩展与审计 review-governance 策略把 AI 代理发布 PR 评论、审批合并、编辑 CI 配置等高危动作牢牢关在人类审批这道门之后并借助 Ed25519 签名收据链实现可离线验证的审计证据。一、为什么需要「审查面门控」本文要解决的故障模式AI 代理一旦拥有对 GitHub CLI 或 GitHub API 的无限制访问权限就可能出现一系列严重后果发布幻觉式 review 评论、以虚构的理由审批 PR、错误地关闭 issue或悄悄改写 workflow 文件从而绕过其他安全控制。这类事故的特点是即时、可见且往往被归责到运行代理的那个账号头上——这正是 review-agent-governance 插件中review-policy-author代理定义于 agents/review-policy-author.md所针对的核心故障模式。review-policy-author是一个专门负责编写、审计和扩展 Cedar 审查面门控策略的专家代理。它的职责范围是决定 AI 代理在未经人类审批的情况下是否被允许发布 review、评论 issue、合并 PR、修改 CI 配置。审查面门控review-surface gating正是防止这一类事故的通用模式。二、审查面由哪些「命令模式与路径」构成要写出有效的门控策略必须先完整枚举各大平台的审查面命令模式。review-policy-author明确了以下几类必须被门控的路径GitHub通过ghCLIgh pr review、gh pr comment、gh pr merge、gh pr close、gh pr edit、gh pr ready、gh issue comment、gh issue close、gh issue edit、gh release create、gh release edit、gh api repos/.../comments、gh api repos/.../reviews、gh api repos/.../pulls/.../mergeGitLab通过glabglab mr comment、glab mr approve、glab mr merge、glab mr close、glab issue comment、glab issue close、glab release createBitbucket通过bbCLI 或直接 API 调用。必须人工门控的 CI/CD 路径.github/workflows/、.github/CODEOWNERS、.gitlab-ci.yml、.circleci/config.yml、buildkite/pipeline.yml、Jenkinsfile、azure-pipelines.yml必须门控的保护分支main、master、release、production、prod、stable通知面容易放大幻觉的传播渠道Slack webhookshooks.slack.com、Discord webhooks、Teams webhooks、PagerDuty 事件、任何邮件 API这些枚举不是空谈——插件自带的默认策略 review-agent-governance.cedar 就把其中的核心子集落成了可执行的forbid规则详见下文第四节。三、编写 review-governance 策略的六条原则review-policy-author给出了编写策略时的六条操作准则这也是把「审查面」落成 Cedar 策略的标准流程1. 从插件的默认策略起步。将plugins/review-agent-governance/policies/review-agent-governance.cedar复制到项目根目录的./review-governance.cedar再开始编辑。默认策略已覆盖 GitHub / GitLab、保护分支与 CI 路径是一个可靠的基线。2. 针对项目特有的审查面做扩展。如果团队使用 Linear、Jira、Notion 或自研 review 工具为这些工具用到的 CLI 命令模式或 WebFetch 主机补充forbid规则。3. 绝不门控只读操作。gh pr view、gh issue list、API GET 请求都允许代理无人值守地执行门控只针对 write / post / merge / close 这类写动作。4. 按分支名而非路径门控分支。使用context.target_branch in [main, ...]而不是context.resource_path starts with refs/heads/main——分支名才是人类推理的依据。5. 必须包含通知面。Slack 与 Discord webhook 是 review-bot 幻觉被放大的地方要门控对这些主机的 POST 请求。6. 不要动非 review 动作。该策略聚焦于审查面在末尾放一条宽松的permit (principal, action, resource);让其余一切放行。如需更广泛的策略强制与protect-mcp插件组合使用。四、默认策略逐条拆解审查面门控的落地实现默认策略 review-agent-governance.cedar 是理解这套门控体系的最佳入口它包含 5 条forbid规则与 1 条兜底permit。每条规则的作用域与实现要点如下规则 1门控ghCLI 的审查面动作forbid ( principal, action Action::Bash, resource ) when { [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].contains(context.command_pattern) };注意gh api repos是刻意保留的通配前缀它拦截任意 GitHub REST 调用防止代理用gh api repos/X/Y/pulls/42/reviews绕过基于命令模式command-pattern的规则。规则 2门控 GitLab / Bitbucket CLIforbid ( principal, action Action::Bash, resource ) when { [glab mr comment, glab mr approve, glab mr merge, glab issue comment].contains(context.command_pattern) };规则 3门控对保护分支的 git pushforbid ( principal, action Action::Bash, resource ) when { [git push, git push --force, git push -f].contains(context.command_pattern) context has target_branch [main, master, release, production].contains(context.target_branch) };注意context has target_branch这一存在性判断——只有命令上下文确实携带目标分支信息时才触发判断。规则 4门控对 CI/CD 配置文件的直接写入forbid ( principal, action in [Action::Write, Action::Edit], resource ) when { [.github/workflows/, .github/CODEOWNERS, .gitlab-ci.yml, .circleci/config.yml, buildkite/pipeline.yml].contains(context.path_starts_with) };修改这些文件等于让代理改变未来构建与 review 的运行方式从而绕过其他所有防护因此必须无条件要求人类审批。规则 5门控对已知 review / 聊天平台的 WebFetch POSTforbid ( principal, action Action::WebFetch, resource ) when { context.method POST [api.github.com, api.gitlab.com, api.bitbucket.org, hooks.slack.com, discord.com].contains(context.url_host) };兜底规则放行一切其他动作permit (principal, action, resource);这印证了review-policy-author的原则 6该插件聚焦审查面非 review 动作原样放行如需通用工具调用策略强制可并排安装 protect-mcp。策略的 Schema 契约与策略配套的 review-agent-governance.cedarschema 定义了策略引用的实体与动作上下文类型它决定了每条规则可用的context字段entity User; entity Resource; action Bash appliesTo { principal: [User], resource: [Resource], context: { command_pattern: String, target_branch?: String } }; action Write appliesTo { principal: [User], resource: [Resource], context: { path_starts_with: String } }; action Edit appliesTo { principal: [User], resource: [Resource], context: { path_starts_with: String } }; action WebFetch appliesTo { principal: [User], resource: [Resource], context: { method: String, url_host: String } };可以看到Bash动作携带command_pattern与可选的target_branchWrite/Edit携带path_starts_withWebFetch携带method与url_host。默认策略中的 5 条 forbid 规则正是精确消费这些上下文字段——这也是为什么审计策略时必须保证 schema 与实际使用的 context 属性一致。一个值得警惕的语言陷阱in-on-String 会被静默丢弃仓库的测试 test/README.md 与 run-tests.sh 专门防护了一个 Cedar 语言陷阱对应上游 issue #598在forbid规则里写context.attr in [ ... ]形式Cedar 会静默丢弃该规则导致门控悄悄失效。正确写法是[ ... ].contains(context.attr)。测试脚本的 Part A只需要grep任何环境都能跑做两件事一是断言策略中不存在context.attr in [的 bug 形态先扁平化空白防止跨行换行绕过检查二是断言策略确实使用了[ ... ].contains(context.attr)的修正写法。Part B 则仅在安装了cedarCLI 时运行cedar validate --policies ... --schema ...利用 schema 中 context 属性为String类型这一事实在加载期拒绝in-on-String 形式、接受.contains()形式。默认策略中大量.contains(context.command_pattern)写法正是这一防御的直接体现。五、三类典型扩展把默认策略适配到你的项目review-policy-author给出了三个可直接复制的扩展模板。5.1 使用 Linear 做 issue 分诊的团队禁止代理用 CLI 操作 Linear并禁止对api.linear.app发起写型 WebFetchforbid ( principal, action Action::Bash, resource ) when { context.command_pattern starts with linear }; forbid ( principal, action Action::WebFetch, resource ) when { context.method POST context.url_host api.linear.app };5.2 使用自研内部 review bot 的团队forbid ( principal, action Action::WebFetch, resource ) when { context.method in [POST, PUT, PATCH, DELETE] context.url_host in [ review-bot.internal.company.com, code-review.internal.company.com ] };5.3 允许专用 bot 账号、禁止个人账号当团队希望让运行在专属「automation」身份下的代理执行 review而不允许开发者个人账号执行时可用「精确permit 兜底forbid」的组合permit ( principal Principal::gh-bot-reviewer, action Action::Bash, resource ) when { context.command_pattern in [gh pr comment] }; forbid ( principal, action Action::Bash, resource ) unless { principal Principal::gh-bot-reviewer || context.human_approved true };注意这个forbid ... unless结构除 bot 账号外其余主体只有携带human_approved true上下文时才能通过。六、审计一份既有策略的五个检查点当需要审查一份review-governance.cedar时review-policy-author建议按以下顺序逐项核对命令覆盖确认团队使用的每一条审查面 CLI 命令都有对应的forbid规则。API 覆盖缺口检查gh api repos这类通配规则是否在。缺少它代理可以用gh api repos/X/Y/pulls/42/reviews绕过所有基于命令模式的规则。保护分支覆盖验证保护分支的git push规则覆盖了仓库设置中实际处于保护状态的所有分支。CI/CD 路径匹配确认 CI/CD 路径规则与本项目真正起门控作用的文件一致例如有些团队用deployment/而非.github/workflows/。默认放行规则不覆盖先前的 forbid检查末尾的默认放行规则不会覆盖更早的forbid。Cedar 中forbid是权威的后续的permit无法解除它。七、门控体系如何运转从策略到钩子到收据链策略本身只是一半另一半是运行时执行机制。该插件通过两个钩子定义于 hooks/hooks.json包住 Claude Code 的每一次工具调用PreToolUse 钩子门控决策if [ -f ${REVIEW_APPROVAL_FLAG:-./.review-approved} ]; then exit 0; fi; \ npx protect-mcp0.7.4 evaluate --policy ${REVIEW_GOVERNANCE_POLICY:-./review-governance.cedar} \ --tool $TOOL_NAME --input $TOOL_INPUT --fail-on-missing-policy false若存在./.review-approved审批标记文件或REVIEW_APPROVAL_FLAG指定的替代路径直接exit 0放行否则调用protect-mcp evaluate用 Cedar 策略评估该工具调用Cedar 判定 deny 时工具调用以退出码 2 结束Claude Code 随即阻止它。PostToolUse 钩子签名取证npx protect-mcp0.7.4 sign --tool $TOOL_NAME --input $TOOL_INPUT --output $TOOL_OUTPUT \ --receipts ${REVIEW_GOVERNANCE_RECEIPTS:-./review-receipts/} \ --key ${REVIEW_GOVERNANCE_KEY:-./review-governance.key}无论该次工具调用被批准、拒绝还是跳过都会产生一条 Ed25519 签名收据收据链精确记录了什么动作在何时被授权。审批窗口的打开与关闭审批窗口通过两种方式打开方式一标记文件最简touch ./.review-approved # 让代理执行被批准的动作 rm ./.review-approved方式二斜杠命令Claude Code 内/approve-review Posting the code review for #123/approve-review实现见 commands/approve-review.md创建./.review-approved并把审批理由写入文件与./review-receipts/approvals/下的时间戳 JSON 条目。关于审批日志的重要提醒./review-receipts/approvals/*.json是明文 JSON 记录不是签名收据。它们不经过protect-mcp sign因此veritasacta/verify不覆盖它们审批日志属于「操作者信任」——它记录人类意图批准什么但事后被编辑也无法被侦测。真正具备防篡改能力的是 PostToolUse 为每次动作无论放行还是拒绝生成的./review-receipts/*.json工具调用收据它们才是权威审计线索。对于受监管环境需要签名审批记录的场合可改用npx protect-mcplatest sign --tool approve-review --input ...直接签名。查看被拒动作/list-pending实现见 commands/list-pending.md遍历./review-receipts/收据链打印最近的decision: deny条目默认最近 10 条可用--last N调整展示工具名、命令模式与时间戳并提示可配合/approve-review人工放行后重试。一个完整的「拒绝 → 批准 → 放行」会话以代理想在 PR 上发布 review 评论为例。未批准时$ agent: gh pr review 42 --comment --body LGTM → PreToolUse hook 运行 → 无 ./.review-approved 文件策略被评估 → Cedar: 对 context.command_pattern gh pr review 判 forbid → 退出码 2Claude Code 阻止该工具调用 → PostToolUse 运行签名一条 decisiondeny 的收据批准后$ touch ./.review-approved $ agent: gh pr review 42 --comment --body LGTM → PreToolUse hook 运行 → 检测到 ./.review-approvedexit 0 → 工具调用执行 → PostToolUse 签名收据decisionallow, reasonhuman_approved $ rm ./.review-approved关于签名链的一个审计预期当审批标记存在时PreToolUse 钩子短路为exit 0不会调用protect-mcp evaluate。因此被批准动作对应的 PostToolUse 收据会是decision: allow但没有policy_digest字段因为没有评估任何 Cedar 策略。审计人员遍历收据链时应预期这一现象被批准的工具调用显示为带签名的收据、reason: human_approved、无策略引用而被拒绝的工具调用与非 review 动作它们确实经过 Cedar则照常携带policy_digest。八、收据链的离线验证与组合使用验证整条链npx veritasacta/verify ./review-receipts/*.json退出码语义0表示每条收据都真实且链完整1表示某条收据被篡改2表示收据格式损坏。任何持有公钥的一方都能离线验证不依赖操作者。与 protect-mcp 组合该插件聚焦审查面若要对所有 Claude Code 工具调用做通用策略强制可并排安装 protect-mcp。两个钩子都会运行、都会产出收据可配置不同的收据目录如./receipts/与./review-receipts/保持链条分离。任一策略判 deny工具调用即被阻止。九、技术选型依据为什么是 Cedar Ed25519 收据CedarAWS 的开源授权引擎以声明式、形式化的方式表达策略审查者阅读策略即可精确了解什么被门控无需读代码策略可通过cedar validate做类型检查策略变更可 diff。Ed25519 收据RFC 8032 签名、RFC 8785 JCS 确定性规范化、hash-chained提供不依赖操作者的防篡改证据。任何篡改都会导致验证退出码 1。涉及的完整标准栈Ed25519RFC 8032、JCSRFC 8785、CedarAWS、IETF 草案 draft-farley-acta-signed-receipts收据格式。十、参考资料与进一步阅读策略作者代理定义plugins/review-agent-governance/agents/review-policy-author.md插件默认策略plugins/review-agent-governance/policies/review-agent-governance.cedar策略 Schemaplugins/review-agent-governance/policies/review-agent-governance.cedarschema运行时钩子配置plugins/review-agent-governance/hooks/hooks.json插件完整说明含安装步骤、审批窗口、示例会话plugins/review-agent-governance/README.md一次性安装与每会话工作流plugins/review-agent-governance/skills/review-agent-setup/SKILL.md策略语言陷阱防护测试plugins/review-agent-governance/test/run-tests.sh通用策略强制插件可与本插件组合plugins/protect-mcp实际安装时可先执行claude plugin install wshobson/agents/review-agent-governance随后将默认策略复制到项目根目录./review-governance.cedar并按第四节、第五节的方法定制最后按第七节的方式投入运行。如需强制所有工具调用都走策略评估禁用审批旁路可设置REVIEW_APPROVAL_FLAG./.never-approve——这在 CI 或锁定的审计运行中尤为有用。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考