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

🤖 Codex Guard

Awesome · DSH plugin

文档站点： <https://akimiya-z.github.io/codex-guard>

给 AI 生成的 pull request 自动把关的质量门禁。 拦住残留的 TODO、泄露的密钥、潦草的提交记录和飘红的 CI，别让它们进 main —— 不用再为这些明摆着的问题浪费评审精力。

支持 OpenAI Codex（云端和命令行）、Claude Code、Copilot，以及任何会向你的仓库提 PR 的智能体。

🐕 自己吃自己的狗粮： 本仓库用自己给自家 AI 生成的 PR 把关。想看真实的失败案例，见 PR #6，背后的工作流在 .github/workflows/codex-guard.yml。

为什么需要它

AI 编程智能体写代码很在行，收拾自己的烂摊子却很糟糕。实际用下来，智能体写的 PR 往往都带着那么几个老毛病：

- // TODO: handle this 这类注释，本来就没打算留下
- 从聊天记录里抄来的硬编码 API key 和连接字符串
- WIP、fix stuff、more changes 这种提交记录 —— 一团乱麻的会话压扁之后的样子
- 看着挺绿，其实 head commit 上 CI 是挂的

这些不该每次都靠人去抓。Codex Guard 自动检查那些无聊的、确定性的问题，而且只查看起来像 AI 生成的 PR —— 人的注意力要花在刀刃上。

工作原理

Codex Guard 在 pull_request 上运行，先判断这个 PR 是不是智能体生成的（看 label、分支前缀或标题），然后：

| 检查项 | 会标记什么 |
| 🧹 TODO 扫描 | 只查新增行上的 TODO / FIXME / XXX / HACK / WIP 标记 |
| 🔐 密钥扫描 | AWS（access key + secret key）、GitHub、Google、OpenAI、Anthropic、Slack、Stripe、npm、SendGrid、Telegram、Azure 连接字符串、JWT、硬编码凭据、连接字符串（报告里会把值打码） |
| 💬 提交规范 | 不符合 conventional commits 的标题、空标题 |
| 🧪 CI 状态 | PR head commit 上失败的 status check 或 check run |

每条发现都会以 GitHub check-run annotation 的形式，精确标注到文件和行，同时在 PR 上留一条人能看懂的汇总评论。

内容扫描覆盖范围，实话实说

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

下面的输出来自在本仓库上的一次真实运行（PR #6）——一个从 codex/ 分支发出的刻意测试 PR，留下了 TODO、形似凭据的 fixture 和两个潦草的提交。形似密钥的值在这里已做脱敏，与当前报告中的处理一致：

🤖 Codex Guard

❌ Checks failed — review the findings before merging.

| Check | Result |
| TODO / FIXME scan | ⚠️ 2 |
| Secret scan | ⚠️ 3 |
| Commit hygiene | ⚠️ 2 |
| CI status | ✅ |

Unfinished work
- 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. Potential leaked secrets
- 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 Commit hygiene
- 7c84ae1 — _WIP stuff_ (by Akimiya-z)
- 1affcf8 — _tmp_ (by Akimiya-z)

Detected as an AI-generated PR (branch prefix "codex/").

快速开始

在 Git 仓库根目录下执行：

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

安装程序以观察模式启动：发现问题会加注解，但在你调整策略期间不会让工作流失败。三个设置预设让上线过程清晰可控：

| 预设 | 命令 | 行为 |
| Observe | npx --yes codex-guard init | 报告所有问题，但不阻塞。 |
| Balanced | npx --yes codex-guard init --preset balanced | 阻塞密钥、提交卫生和红色 CI；对未完成标记发出警告。 |
| Strict | 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 已包含 check run 的读取权限。没有 status 访问权限时，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 就会直接放行，不跑任何检查。当人类已经审查并接受了改动时，这很有用。

输入项

| Input | Default | Description |
| preset | _(empty)_ | 策略基线：observe、balanced 或 strict。留空则保持 preset 之前的行为。仓库策略可以覆盖它。 |
| github-token | ${{ github.token }} | 对 checks 和 PR 有写权限的 token。 |
| 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 | _(empty)_ | 要跳过的文件路径子串（例如 README,test/fixtures）。 |
| check-commits | true | 校验提交主题。 |
| commit-pattern | conventional commit regex | 主题必须匹配的正则。 |
| check-ci | true | head commit 的 CI 失败时是否失败。 |
| ignore-check-run-names | _(empty)_ | 评估 CI 时要忽略的 check/context 名称。 |
| 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 | 扫描所有打开的智能体 PR，而不是只扫一个（配合 workflow_dispatch 使用）。 |
| sweep-label | _（空）_ | 只扫描带此标签的 PR。 |
| sweep-base | main | 只扫描以该分支为基底的 PR。 |

CI 结果从不靠猜

Codex Guard 同时读取 commit status 和 check run，逐页跟进所有结果页，直到 GitHub 的 3,000 条结果安全上限，并把每个已完成且结论非成功的检查都当作失败。检查仍在进行时给出中性结果，不会提前亮绿灯。如果某个 GitHub CI API 不可用，报告为中性，并明确说明可见性不完整；如果两个都不可用，CI 检查按失败处理（fail closed）。之前 Codex Guard 自己的 check run 会被忽略，所以重跑不会继承自己旧的失败。

配置文件

感知 AGENTS.md： 如果仓库的 AGENTS.md 或 CLAUDE.md 用反引号正则写明了提交约定（例如「commits must match ^JIRA-[0-9]+: .+$」），那么在没有设置 commit-pattern 输入或配置键时，Codex Guard 会把它当作最后的兜底默认值——action 和命令行都是如此。

上面每个输入都能用默认分支上的 .github/codex-guard.yml 文件按仓库覆盖——这样智能体就没法在自己的 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
它会检查 pull-request 触发器、Action 步骤、生效的 workflow/job 权限、setup preset、policy YAML、未知键、布尔值、comment-mode 和 fail-on。配置出错时退出码为 1，只剩警告或全部通过时退出码为 0。这是本地文件诊断；GitHub 分支保护和组织策略仍然位于仓库设置中。

本地 dry-run（命令行）

命令行会安装 workflow，并在 CI 之前本地预览同样的检查——不需要 token，也不用等待：

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 <(git diff origin/main)

from this repo's source
git diff origin/main > /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 进程替换（<(...)）。请把 diff 保存到临时 UTF-8 文件：

$patch = New-TemporaryFile
try {
git diff origin/main | Set-Content -LiteralPath $patch -Encoding utf8
npx --yes codex-guard --diff $patch
} finally {
Remove-Item -LiteralPath $patch
}

退出码：0 = 没有阻断性问题，1 = 有阻断性问题，2 = 用法错误。--json 会打印原始报告（结构与 findings-json 输出相同），供脚本使用。在 --git 模式下，命令行会自动加载 .github/codex-guard.yml，因此本地内容检查使用的 preset、patterns、exclusions 和阻断规则与 Action 完全一致。想显式覆盖本地配置，可以用 --preset 或单独的标志；想换用别的策略文件，用 --config <path>；想绕过仓库策略，用 --no-config。显式的命令行标志优先于加载的文件。只有传入 --commits 时才会检查提交规范。被 Git 忽略的文件仍然忽略；普通的未跟踪文件会当作全部新增的补丁处理，所以新文件在第一次 git add 之前就会被扫描。二进制文件或超过 8 MiB 的未跟踪文件会被明确列为未扫描，而不是悄悄当作干净处理。

智能体技能（提交前自检）

同样的检查，再往上提一层：打包成技能，让 Codex 或 Claude Code 在开 PR 之前_自己_先跑一遍——这样 CI 关卡就不会再看到智能体本地没发现的脏 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/

技能会告诉智能体在提交前运行 node src/cli.js --git --commits，修掉 TODO/secret/commit 类问题，只有检查通过（或在描述里记录了例外）才开 PR。

Codex 插件

同一个技能也打包成官方 Codex 插件（仅技能形式， schema 遵循 openai/plugins）：plugins/codex-guard/.codex-plugin/plugin.json 外加一份 marketplace 清单，位于 .agents/plugins/marketplace.json。Codex 用户可以在 Codex 应用或命令行里，把这个仓库添加为插件 marketplace —— 安装步骤见 OpenAI 的插件文档： <https://developers.openai.com/codex/plugins/build>。

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)

这个工具会在当前工作目录里调用已发布的命令行（npx --yes codex-guard --git），所以它拿到的报告和 CI 门禁用的那份一样，结果确定。Node API 兼容性针对真实的 @deepseek-ai/dsh-tools registry 包做了测试（见 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-run。
用 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'

接入一个自动打上智能体标签的工具：

如果你的智能体有 GitHub App 或机器人给 PR 打标签，当前 Codex Guard 会尊重你配置的任何标签——而且当 PR 完全没有信号时，它会失败开放（即通过）。

继续拦截来自 fork 的智能体 PR：

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

对比

| 工具 | 做什么 | 为什么你还需要 Codex Guard |
| 分支保护 | 阻止缺少必需审查/检查的合并 | 它是_策略_；Codex Guard 是_检查_，在 PR 上执行智能体卫生规则。 |
| 密钥扫描器（gitleaks、TruffleHog） | 跨历史深度检测密钥 | 配合使用——我们的是廉价的、按 diff 范围的正则扫描，不是替代品。 |
| Linter / 格式化工具 | 风格与静态分析门禁 | 我们抓的是智能体留下的_工作流_问题（TODO、密钥、提交卫生、CI 变红），这些 linter 不管。 |
| AI 审查机器人（CodeRabbit 等） | LLM 驱动的 PR 审查 | 很好——但慢、主观，且每次审查都有 token 成本。Codex Guard 是确定性的、快的、在 CI 里免费运行，而且能无争议地作为门禁。 |
| 智能体自审钩子 | 智能体检查自己的输出 | 默认会通过；中立的确定性门禁不会跟着点头。 |

社区

- 提问与讨论——问题、配置方案和路线图投票都在 GitHub Discussions； bug 报告和功能请求走 issue 模板。
- 适合新手的 issue 打有 good first issue 和 help wanted 标签——贡献指南在 CONTRIBUTING.md。
- 路线图由反馈驱动：影响下个版本最快的方式，是提一个功能请求并在 Discussions 里投票。
- 每一份外部贡献都会在发布说明里点名致谢。谢谢你——这个项目靠用户的反馈活着。

开发

npm install
npm test # node:test — no framework required
npm run check # syntax-check every source file
npm run build # rebuild the checked-in Action bundle
开 PR 之前先看 CONTRIBUTING.md —— 里面写了发布流程（重新构建 dist/、打 v1.x 标签）。发布历史见 CHANGELOG.md。可以直接复制粘贴的工作流放在 examples/，docs/ 里说明了怎么录制演示 GIF、怎么在本地做冒烟测试。

限制

- 密钥检测刻意采用正则 —— 它能低成本地抓住明显的错误，但替代不了真正的密钥扫描器（另外用 gitleaks 或 zizmor）。
- TODO 扫描只看本 PR 新增的行 —— 不会拿已有的注释来烦你。
- 二进制文件或超大文件，GitHub 可能不提供文本补丁。这类文件无法做内容扫描。Codex Guard 会报告它们的路径，并用中立的检查结论，而不是悄悄声称已全覆盖；但仓库级的密钥扫描器仍应是权威控制手段。
- GitHub 的 pull-request files endpoint 最多返回 3,000 个文件。达到这个上限会报告为覆盖不完整，因为可能有文件缺失。
- 提交状态和检查运行同样有保守的 3,000 条结果安全上限，按 API 计算。达到上限会报告为 CI 可见性不完整，而不是悄悄忽略后面的结果。
- 本地命令行会扫描普通的未跟踪文件，但二进制文件和超过 8 MiB 的未跟踪文件会报告为未扫描。Git 忽略的文件按设计直接略过。
- 智能体检测刻意采用启发式。当覆盖比区分人类和智能体 PR 更重要时，把 gate-agents-only: false 设上。
- 在 pull_request 事件上运行；fork 贡献请用 pull_request_target（见 examples/forks.yml），并提供作用域正确的 token。

路线图

- [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