AI PR 质量门禁Akimiya-z/codex-guard

🤖 Codex Guard

GitHub release (latest by SemVer)
GitHub stars
License
CI
Docs
Marketplace
Awesome · DSH plugin

文档站点：

一个用于 AI 生成拉取请求的自动质量门禁。 阻止 TODO 遗留、泄露的密钥、草率的提交和失败的 CI 进入 main —— 无需在显而易见的问题上耗费任何评审精力。

适用于 OpenAI Codex（云端和 CLI）、Claude Code、Copilot，以及任何针对你的仓库创建 PR 的其他 agent。

🐕 自用实践（Dogfooding）： 本仓库对自己的 AI 生成 PR 进行门禁。可在 PR #6 查看一个真实的失败示例，其背后的工作流位于 .github/workflows/codex-guard.yml。

为什么需要它

AI 编码 agent 擅长写代码，却不擅长收拾自己的烂摊子。在实践中，agent 编写的 PR 往往带着同样几个老问题：

- // TODO: handle this 注释，本来就不该留下
- 从聊天记录里复制来的硬编码 API 密钥和连接字符串
- 类似 WIP、fix stuff、more changes 的提交记录 —— 一次混乱会话被压缩后的产物
- 看起来是绿色的 PR，但 head commit 上其实有失败的 CI

你不应该每次都需要人工评审来抓这些问题。Codex Guard 自动检查那些无聊、确定性的问题，而且只针对看起来是 AI 生成的 PR —— 这样人的注意力就能用在真正重要的地方。

工作原理

Codex Guard 在 pull_request 上运行，判断该 PR 是否看起来由 agent 生成（通过标签、分支前缀或标题），然后：

| 检查 | 标记内容 |
| --- | --- |
| 🧹 TODO 扫描 | 仅新增行上的 TODO / FIXME / XXX / HACK / WIP 标记 |
| 🔐 密钥扫描 | AWS（access + secret keys）、GitHub、Google、OpenAI、Anthropic、Slack、Stripe、npm、SendGrid、Telegram、Azure 连接字符串、JWT、硬编码凭据、连接字符串（报告中的值会被脱敏） |
| 💬 提交卫生 | 不符合 conventional commits 的主题、空主题 |
| 🧪 CI 状态 | PR head commit 上失败的状态检查或检查运行 |

每个发现都会以 GitHub check-run annotation 的形式发布在确切的文件和行上，并在 PR 上附上人类可读的摘要评论。

诚实的内容扫描覆盖范围
GitHub 有时会省略二进制文件或超大文件的文本补丁。Codex
Guard 现在会区分未发现问题和未扫描：每份报告都会显示实际检查过补丁的符合条件变更文件数量。缺失补丁会产生一条中性的、非阻塞的覆盖范围警告，并列出受影响的路径；JSON 和 Action 输出携带相同的信息。当 GitHub 的拉取请求文件 API 达到其文档所述的 3,000 个文件上限时，也会出现该警告。

下面的输出来自对本仓库的一次真实运行
（PR #6）——一个来自 codex/ 分支的刻意测试
PR，它留下了一个 TODO、形似凭据的测试夹具以及两次草率的提交。此处对形似密钥的值进行了脱敏，正如当前报告中所做的那样：

🤖 Codex Guard

❌ 检查失败——合并前请先审查发现的问题。

| 检查 | 结果 |
| --- | --- |
| TODO / FIXME 扫描 | ⚠️ 2 |
| 密钥扫描 | ⚠️ 3 |
| 提交卫生 | ⚠️ 2 |
| CI 状态 | ✅ |

未完成的工作
- scripts/sync.js:4 — FIXME: const aws = 'AKIA...MPLE'; // FIXME: move this to a secret store
- scripts/sync.js:2 — TODO: // TODO: wire up real retry with exponential backoff.
可能泄露的密钥
- scripts/sync.js:4 — AWS Access Key ID AKIA...MPLE
- scripts/sync.js:5 — Connection string post...prod
- scripts/sync.js:7 — OpenAI API Key sk-p...6789
提交卫生
- 7c84ae1 — _WIP stuff_ (by Akimiya-z)
- 1affcf8 — _tmp_ (by Akimiya-z)

检测为 AI 生成的 PR（分支前缀 "codex/"）。

快速开始

在你的 Git 仓库根目录下：

npx --yes codex-guard init
git add .github/workflows/codex-guard.yml
git commit -m "ci: add Codex Guard"

安装程序以观察模式启动：发现的问题会被标注，但在你调整策略期间不会使工作流失败。三种设置预设让上线过程保持明确：

| 预设 | 命令 | 行为 |
| --- | --- | --- |
| 观察 | npx --yes codex-guard init | 报告所有内容但不阻塞。 |
| 平衡 | npx --yes codex-guard init --preset balanced | 阻止密钥、提交卫生和红色 CI；对未完成标记发出警告。 |
| 严格 | npx --yes codex-guard init --preset strict | 阻止所有默认发现的问题。--strict 仍为别名。 |

更想手动添加？生成的工作流如下：

Generated by codex-guard init
name: Codex Guard
on:
pull_request:

permissions:
contents: read
statuses: read
pull-requests: write
checks: write

jobs:
codex-guard:
runs-on: ubuntu-latest
steps:
- uses: Akimiya-z/codex-guard@v1
with:
preset: 'observe'

就这样。Codex Guard 现在会对匹配的 PR 进行报告，但不会阻塞它们。

要升级现有工作流？请在其 permissions 块中添加 statuses: read。checks: write 已包含对检查运行的读取权限。如果没有状态访问权限，Codex Guard 会报告 CI 可见性不完整，并返回一个
中立的结果，而不是声称每项检查都是绿色的。

从 GitHub Actions Marketplace 一键安装。

开启强制执行

在几个有代表性的 PR 之后，选择强制执行的严格程度：

- uses: Akimiya-z/codex-guard@v1
with:
preset: 'balanced' # or 'strict'

balanced 会对未完成的标记发出警告，同时阻止密钥、提交卫生问题和红色 CI。strict 会阻止所有默认发现项。如需自定义组合，请使用 fail-on 和各个单独的输入项。然后在 Settings → Branches → Require status checks → Codex Guard 下要求状态检查。阻止性发现项会阻止 PR 合并，直到该问题被解决（或者 PR 被标记为 ignore 标签——参见“选择退出”）。

检测代理 PR

默认情况下，Codex Guard 只对它所认为由代理编写的 PR 进行门禁，因此人工编写的 PR 永远不会被拖慢：

- 标签 匹配 codex-generated、agentic、ai-generated 之一
- 分支 以 codex/、copilot/、claude-auto、gh-codex/ 开头
- 标题 包含 Generated by Codex、Generated by Claude、Generated by Copilot

所有这些都可配置——或者设置 gate-agents-only: false 来对所有 PR 进行门禁。

选择退出特定 PR

向 PR 添加名为 codex-guard-ignore（可配置）的标签，Codex Guard 将直接通过该 PR 而不运行检查。当人工已经审查并接受了更改时，这很有用。

输入项

| 输入项 | 默认值 | 描述 |
| --- | --- | --- |
| preset | _（空）_ | 策略基线：observe、balanced 或 strict。为空则保留预设前的行为。仓库策略可以覆盖它。 |
| github-token | ${{ github.token }} | 具有对检查和 PR 写入权限的令牌。 |
| gate-agents-only | true | 仅对检测为代理生成的 PR 进行门禁。 |
| agent-labels | codex-generated,agentic,ai-generated | 标记代理 PR 的标签。 |
| agent-branch-prefixes | codex/,copilot/,claude-auto,gh-codex/ | 标记代理 PR 的分支前缀。 |
| agent-keywords | Generated by Codex,Generated by Claude,Generated by Copilot | 标记代理 PR 的标题关键词。 |
| ignore-label | codex-guard-ignore | 跳过所有检查的 PR 标签。 |
| check-todos | true | 扫描新增行中的未完成工作标记。 |
| todo-patterns | TODO,FIXME,XXX,HACK,WIP | 要标记的标记。 |
| todo-blocking | true | 对 TODO 发现项失败（false = 仅警告）。 |
| check-secrets | true | 扫描新增行中的硬编码密钥。 |
| secret-exclude-paths | _（空）_ | 要跳过的文件路径子字符串（例如 README,test/fixtures）。 |
| check-commits | true | 验证提交主题。 |
| commit-pattern | 约定式提交正则表达式 | 主题必须匹配的正则表达式。 |
| check-ci | true | 对头部提交的失败 CI 失败。 |
| ignore-check-run-names | _（空）_ | 评估 CI 时要忽略的检查/上下文名称。 |
| post-comment | true | 在失败时发布报告评论。 |
| comment-mode | replace | replace 会就地更新之前的报告（每个 PR 一条评论），append 每次运行都会发布一条新评论，none 从不发布。 |
| request-changes | false | 对阻塞性发现同时提交正式的 REQUEST_CHANGES 审查（需选择启用；需要 pull-requests: write）。 |
| notify-users | _（空）_ | 在阻塞性发现的报告评论中要 @ 提及的用户名，以逗号分隔。 |
| soft-fail | false | 以中性 check-run 报告发现，但绝不使工作流失败。 |
| config-path | .github/codex-guard.yml | 可选的按仓库策略文件（位于默认分支上），用于覆盖工作流输入。 |
| fail-on | _（空）_ | 以逗号分隔的阻塞性检查：todos,secrets,commits,ci。为空 = 旧版行为；指定子集会使被排除的检查变为非阻塞。 |
| sweep | false | 扫描每个打开的 agent PR，而不是单个 PR（与 workflow_dispatch 一起使用）。 |
| sweep-label | _（空）_ | 仅扫描带有此标签的 PR。 |
| sweep-base | main | 仅扫描以此为基础分支的 PR。 |

CI 结果绝不猜测

Codex Guard 会读取提交状态和检查运行，跟随每个结果页直到 GitHub 的 3,000 条结果安全上限，并将每个已完成的非成功结论视为失败。待处理的检查会产生中性结果，而不是过早的绿色检查。如果某个 GitHub CI API 不可用，报告为中性，并明确说明可见性不完整；如果两者都不可用，CI 检查会失败关闭。之前的 Codex Guard 检查运行会被忽略，因此重新运行不会继承其自身的旧失败。

配置文件

感知 AGENTS.md： 如果仓库的 AGENTS.md 或 CLAUDE.md 以反引号正则表达式的形式声明了提交约定（例如“提交必须匹配 ^JIRA-[0-9]+: .+$”），当未设置 commit-pattern 输入或配置键时，Codex Guard 会将其作为最后手段的默认值应用——action 和 CLI 都是如此。

上述每个输入都可以通过默认分支上的 .github/codex-guard.yml 文件按仓库覆盖——这样 agents 就不能在自己的 PR 中随意放宽策略。未知键会被忽略（容忍拼写错误）。

.github/codex-guard.yml
preset: balanced
gate-agents-only: true
agent-labels:
- codex-generated
- agentic
todo-patterns:
- TODO
- FIXME
- XXX
secret-exclude-paths:
- README.md
- docs/
comment-mode: replace
request-changes: true

可复制粘贴的模板位于 examples/codex-guard.yml。策略解析是确定性的：工作流 preset 提供基线，仓库 preset 替换该基线，各个仓库键最后胜出。这保持了现有工作流的兼容性，因为空的工作流 preset 会保留旧版默认值。

诊断安装

在安装或更改策略后运行只读的本地 doctor：

npx --yes codex-guard doctor
npx --yes codex-guard doctor --json  # machine-readable output
它检查拉取请求触发器、Action 步骤、有效的工作流/作业权限、设置预设、策略 YAML、未知键、布尔值、comment-mode 和 fail-on。配置错误时退出码为 1，仅剩警告或通过时退出码为 0。这是本地文件诊断；GitHub 分支保护和组织策略仍位于仓库设置中。

本地试运行（CLI）

CLI 会安装工作流，并在 CI 之前在本地预览相同的检查——无需令牌或等待：

install the GitHub workflow (safe observe mode by default)
npx --yes codex-guard init

scan a diff from npm — no install needed (v1.7.0+)
npx --yes codex-guard --diff  /tmp/patch.diff
node src/cli.js --diff /tmp/patch.diff

or straight against a ref (bare --git scans tracked + untracked changes)
npx --yes codex-guard --git --commits
node src/cli.js --git origin/main --commits

PowerShell 不支持 Bash 进程替换（ 指定另一个策略文件，或使用 --no-config 绕过仓库策略。显式 CLI 标志优先于加载的文件。仅当传入 --commits 时才检查提交卫生。Git 忽略的文件保持忽略；普通未跟踪文件被视为全部新增的补丁，因此新文件在首次 git add 之前就会被扫描。大于 8 MiB 的二进制或未跟踪文件会被明确列为未扫描，而不是被静默视为干净。

Agent 技能（提交前自检）

相同的检查，再往上一个层级：打包为技能，因此 Codex 或 Claude Code 在打开 PR 之前会_自行_运行这些检查——CI 门禁就不会看到 agent 在本地尚未发现的脏 diff。本仓库将该技能放在 skills/codex-guard/SKILL.md；使用以下命令安装：

bash skills/install.sh              # installs for Codex and Claude Code
or copy skills/codex-guard/ into ~/.codex/skills/ or ~/.claude/skills/

该技能告诉 agent 在提交前运行 node src/cli.js --git --commits，修复 TODO/secret/commit 发现，并且只有在检查通过后才打开 PR（或在描述中记录例外情况）。

Codex 插件

相同的技能被打包为官方 Codex 插件（仅技能形式，
schema 遵循 openai/plugins）：plugins/codex-guard/.codex-plugin/plugin.json
外加一个位于 .agents/plugins/marketplace.json 的市场清单。Codex 用户
可以从 Codex 应用或 CLI 将此仓库添加为插件市场——
安装步骤见 OpenAI 的插件文档：
。

plugins/codex-guard/.codex-plugin/plugin.json
plugins/codex-guard/skills/codex-guard/SKILL.md
.agents/plugins/marketplace.json

安装后，Codex 会在打开或更新 PR 之前自行运行提交前检查——
行为与独立技能相同，只是离在 GitHub 上可被发现又近了一步打包步骤（参见 codex-plugin 主题）。

DeepSeek Harness 插件（dsh）

一个 DSH 捆绑包位于 dsh/：它声明了一个 dsh.bundle 清单，并注册了一个
codex_guard 工具，DeepSeek Harness 智能体可以调用它，在智能体编写的
diff 成为 PR 之前对其进行预检。

dsh/
├── package.json        # dsh.bundle manifest (name: dsh-codex-guard)
├── cordis.patch.yml    # the layer a profile applies
└── index.js            # registers the codex_guard tool (dsh-tools API)

该工具在当前工作目录中调用已发布的 CLI（npx --yes codex-guard --git），
因此它获得与 CI 门禁相同的确定性报告。Node API 兼容性针对真实的
@deepseek-ai/dsh-tools 注册表包进行了测试（参见 test/dsh.test.js），
包括在一个一次性 git 仓库中的端到端运行。

输出

| 输出 | 描述 |
| --- | --- |
| policy-preset | 选定的策略基线：observe、balanced、strict 或 custom。单个策略键仍可覆盖它。 |
| result | pass、fail 或 skipped。 |
| detected-agent | true / false —— PR 是否看起来由智能体生成。 |
| failed-checks | 失败检查的逗号分隔列表（todos,secrets,commits,ci）。 |
| todo-count / secret-count / commit-count | 各类别的发现数量。 |
| ci-failure-count | 失败的 CI 检查数量。 |
| content-scan-coverage | 已扫描的文本补丁 / 符合条件的文件，例如 12/13，或 disabled。 |
| unscanned-file-count | GitHub 未提供文本补丁的符合条件的文件。 |
| findings-json | 完整报告的 JSON —— 将其传入后续步骤以进行更多门禁或构建仪表板。 |
| sweep-scanned / sweep-failed | 扫描模式：已检查的智能体 PR / 存在阻塞性发现的 PR。 |
| sweep-report / sweep-json | 扫描模式：markdown 报告（也在运行摘要中）/ 每个 PR 的 JSON。 |

扫描现有 PR

采用 Codex Guard 不必是追溯性的——运行一次扫描即可一次性
检查当前所有打开的由智能体生成的 PR。添加一个 schedule
触发器（示例附带每周一运行）以实现零接触的每周
智能体 PR 健康检查：

on:
workflow_dispatch:
… uses: Akimiya-z/codex-guard@v1 with: { sweep: 'true' }

报告写入运行摘要和 sweep-report 输出（每个 PR
sweep-json 中的数字）。不会发布每个 PR 的评论或 check-runs。
使用 sweep-label 将运行限制为带有特定标签的 PR。
可在 examples/sweep.yml 中复制粘贴。

示例

拦截一切，并在文档上跳过密钥扫描：

steps:
- uses: Akimiya-z/codex-guard@v1
with:
gate-agents-only: 'false'
secret-exclude-paths: 'README.md,docs/'

先观察，后强制执行：

steps:
- uses: Akimiya-z/codex-guard@v1
with:
preset: 'observe'

与自动添加 agent 标签的工具集成：

如果你的 agent 有 GitHub App 或为 PR 打标签的 bot，当前的 Codex Guard 会
尊重你配置的任何标签——并且当 PR 完全没有信号时会失败开放（通过）。

继续拦截来自 fork 的 agent PR：

使用 pull_request_target，让检查以你仓库的写权限 token 运行。该
action 会从事件负载中读取 fork PR 的文件、commits 和 head SHA——
无需额外配置。可在 examples/forks.yml 中复制粘贴。

对比

| 工具 | 作用 | 为什么你还需要 Codex Guard |
| --- | --- | --- |
| 分支保护 | 阻止缺少必需审查/检查的合并 | 它是_策略_；Codex Guard 是_检查_，在 PR 上强制执行 agent 卫生规则。 |
| 密钥扫描器（gitleaks、TruffleHog） | 跨历史记录进行深度密钥检测 | 额外使用——我们的是廉价的、按 diff 范围的正则扫描，并非替代品。 |
| Linter / 格式化工具 | 风格和静态分析门禁 | 我们捕获 linter 不会发现的 agent 遗留的_工作流_问题（TODO、密钥、提交卫生、CI 失败）。 |
| AI 审查 bot（CodeRabbit 等） | LLM 驱动的 PR 审查 | 很好——但速度慢、主观，且每次审查都有 token 成本。Codex Guard 是确定性的、快速的、在 CI 中免费运行，并且无需争论即可作为门禁。 |
| Agent 自审查钩子 | Agent 检查自己的输出 | 默认会失败；中立的确定性门禁不会随声附和。 |

社区

- 提问与讨论——问题、配置和路线图投票都在
GitHub Discussions；
错误报告和功能请求请通过
issue 模板。
- 适合新手的问题被标记为 good first issue
和 help wanted——贡献指南在
CONTRIBUTING.md。
- 路线图由反馈驱动：影响下一个版本最快的方式
是提交功能请求并在 Discussions 中投票。
- 每个外部贡献都会在发布说明中被提及。谢谢你——
这个项目依靠用户的反馈而生存。

开发

npm install
npm test          # node:test — 无需框架
npm run check     # 对每个源文件进行语法检查
npm run build     # 重新构建已检入的 Action bundle
在打开 PR 之前，请先查阅 CONTRIBUTING.md —— 它涵盖了发布流程
（重新构建 dist/、打标签 v1.x）。发布历史请参见 CHANGELOG.md。
可复制粘贴的工作流位于 examples/，而 docs/ 解释了
如何录制演示 GIF 并在本地进行冒烟测试。

局限性

- 密钥检测有意基于正则表达式 —— 它能低成本地捕获明显的
错误，但它不能替代真正的密钥扫描器
（请额外使用 gitleaks 或
zizmor）。
- TODO 扫描只能看到本 PR 新增的行 —— 它不会对
已存在的注释唠叨。
- GitHub 可能会省略二进制文件或超大文件的文本补丁。这些文件
无法进行内容扫描。Codex Guard 会报告它们的路径，并使用中立的
检查结论，而不是默默声称完全覆盖，但
仓库范围的密钥扫描器仍应是权威控制手段。
- GitHub 的拉取请求文件端点
最多返回 3,000 个文件。达到该限制会被报告为覆盖不完整，
因为可能缺少其他文件。
- 提交状态和检查运行在每个 API 上也有保守的 3,000 条结果安全
上限。达到该上限会被报告为 CI 可见性不完整，而不是
默默忽略后续结果。
- 本地 CLI 会扫描普通的未跟踪文件，但会将二进制文件和
大于 8 MiB 的未跟踪文件报告为未扫描。被 Git 忽略的文件按设计
会被省略。
- 代理检测有意采用启发式方法。当覆盖范围比区分人类和代理 PR
更重要时，请设置 gate-agents-only: false。
- 在 pull_request 事件上运行；对于 fork 贡献，请使用
pull_request_target（参见 examples/forks.yml）并
提供具有正确权限范围的令牌。

路线图

- [x] 自动 request changes，而不仅仅是让检查失败（可选启用）
- [x] 在多次运行之间就地替换/更新报告评论
- [x] 支持配置文件（.github/codex-guard.yml）以实现按仓库策略
- [x] 用于提交前自检的代理技能（SKILL.md）
- [x] 通过 workflow_dispatch 扫描现有代理 PR
- [x] 已发布到 npm（npx codex-guard）
- [x] 一条命令的观察模式安装器（npx codex-guard init）
- [x] 观察/平衡/严格安装器预设和本地设置诊断
- [x] 本地扫描未被忽略的未跟踪文件
- [x] 共享 Action/CLI 预设，并自动加载本地仓库策略

_按设计放弃：AI 全 PR 摘要门禁 —— 按 token 计费的 LLM 成本与
该项目免费、确定性的定位相矛盾。Codex Guard 保持零成本。_

许可证

MIT