brett-buskirk/agent-gate
GitHub: brett-buskirk/agent-gate
一款在 CI 流水线中对 AI Agent 生成的 Pull Request 提供自动化护栏检查与风险拦截的代码审查工具。
Stars: 0 | Forks: 0
# AgentGate
[](https://github.com/brett-buskirk/agent-gate/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@brett.buskirk/agent-gate)
[](LICENSE)
[](https://github.com/marketplace/actions/agentgate-ai-pr-guardrails)
**为 AI agent 生成的 pull request 提供护栏检查。**
AgentGate 在 CI 中对每个 PR 运行，检查 diff 中是否存在 AI agent 常见引入的风险信号——泄露的 secrets、超出范围的更改、缺失的测试、意外的 dependencies——发布结构化的审查评论，并设置通过/失败检查状态。您的团队无需盲目批准即可审查 agent 的工作。
## 状态
**v1.1.0 — 稳定版。** 包含六条确定性规则以及可选的 LLM 意图检查，经过测试（99%+ 覆盖率，在 CI 中强制执行）。Action 已打包（`dist/index.js`）并已在 [GitHub Marketplace](https://github.com/marketplace/actions/agentgate-ai-pr-guardrails) 上架。内部测试 CI 在自身的 PR 上运行 AgentGate。CLI 会自动检测您的默认分支，并附带一个 `init` 脚手架工具。已作为 [`@brett.buskirk/agent-gate`](https://www.npmjs.com/package/@brett.buskirk/agent-gate) 发布到 npm。
## 查看实际运行效果
当 agent 打开一个泄露了密钥、编辑了不该触碰的 workflow、悄悄加入 dependency 且跳过测试的 PR 时，AgentGate 会阻止合并，并准确解释原因：
在 CI 中，它会将相同的判定结果作为单条 PR 评论发布——这里有一个[评论示例](docs/assets/sample-pr-comment.md)。
## 快速开始
### GitHub Action
```
# .github/workflows/agentgate.yml
name: AgentGate
on: [pull_request]
jobs:
agentgate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: brett-buskirk/agent-gate@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
```
在您的仓库中添加一个 `.agentgate.yml` 进行配置（或者直接跳过——默认配置非常合理）。
### CLI
```
# 自动检测您的默认分支 (main、master 或 origin/HEAD)
npx @brett.buskirk/agent-gate check
```
或者全局安装：
```
npm install -g @brett.buskirk/agent-gate
agent-gate check # diff against the auto-detected default branch
agent-gate check --base develop # or pick a base explicitly
agent-gate check --json # machine-readable output
agent-gate init # scaffold a .agentgate.yml
```
## 配置说明
在您的仓库根目录放置一个 `.agentgate.yml`。所有配置都有默认值——该文件是可选的。
```
version: 1
fail_on: error # error | warning | never
comment: true # post/update a PR comment
rules:
secrets:
enabled: true
severity: error
scope:
enabled: true
severity: error
allow: # if set, only these paths are permitted
- "src/**"
- "test/**"
- "docs/**"
deny: # always blocked regardless of allow
- ".github/workflows/**"
- "infra/**"
- "**/*.lock"
- "package-lock.json"
diff_size:
enabled: true
severity: warning
max_files: 30
max_lines: 800
tests_required:
enabled: true
severity: warning
src_globs: ["src/**"]
test_globs: ["**/*.test.*", "**/*.spec.*", "tests/**"]
dependencies:
enabled: true
severity: warning
manifests: ["package.json", "requirements.txt", "go.mod", "Gemfile", "Cargo.toml"]
dangerous_patterns:
enabled: true
severity: error
patterns:
- "eval\\("
- "--no-verify"
- "child_process\\.exec\\("
intent: # opt-in — needs ANTHROPIC_API_KEY
enabled: false
severity: warning
model: claude-haiku-4-5-20251001
max_diff_bytes: 60000
```
### `fail_on`
| 值 | 行为 |
|-------|----------|
| `error` | 只有 error 级别的发现会导致检查失败（默认） |
| `warning` | warning 级别也会导致检查失败 |
| `never` | 检查始终通过；发现的问题仍然会被报告 |
## 规则
| 规则 | 默认严重程度 | 捕获内容 |
|------|-----------------|-----------------|
| `secrets` | error | AWS 密钥、GitHub token、私钥块、高熵赋值 |
| `scope` | error | 白名单之外或黑名单之内的文件 |
| `diff_size` | warning | 超过 `max_files` (30) 或 `max_lines` (800) 的 PR |
| `tests_required` | warning | 源代码更改而没有相应的测试文件更改 |
| `dependencies` | warning | 修改了 dependency 清单（供应链风险） |
| `dangerous_patterns` | error | 应用于新增行的用户自定义正则表达式黑名单 |
| `intent` *(可选)* | warning | 使用 LLM 标记超出 PR 描述范围的更改 |
## LLM 意图检查（可选）
`intent` 规则是唯一非确定性的检查：它会询问 Claude 您的 diff 是否真正执行了 PR 所述的操作——从而捕获那些实际执行了比描述*更多*，或*不同*操作的 agent。*用 AI 检查 AI。*
以下是它捕获一个标题为*“修复 README 中的拼写错误”*，但实际上添加了整个新模块的 PR 的示例：
它**默认关闭**。在 `.agentgate.yml` 中启用它：
```
rules:
intent:
enabled: true
```
并为其提供一个 Anthropic API key——`ANTHROPIC_API_KEY` 环境变量，或 `anthropic-api-key` Action 输入：
```
- uses: brett-buskirk/agent-gate@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```
在本地运行时，请自行提供意图：
```
agent-gate check --intent "Add a refund flow to the payment processor"
agent-gate check --intent-file PR_DESCRIPTION.md
```
注意事项：
- **绝不会因基础设施问题而阻止**——缺少 key 或 API 调用失败将被报告为 info，而不是失败；您的确定性检查门仍会运行。
- **有界成本**——diff 会被总结并截断至 `max_diff_bytes`；默认模型（`claude-haiku-4-5-20251001`）快速且便宜。
- **默认严重程度为 `warning`**——LLM 的判断仅供参考；如果您希望阻止合并，可以将其提升为 `error`。
## PR 评论
AgentGate 会在 PR 上发布一条评论，并在重新运行时直接更新该评论——绝不发送垃圾信息。它会显示整体判定结果、按规则划分的汇总表，以及包含文件、行号和修复建议的可展开发现项。
当一个 PR 触发多条规则时，每个发现项都会与其建议归组在一起：
干净的 PR 会静默通过：
## 工作原理
1. 在 `pull_request` 事件中，Action 会从 GitHub API 获取 PR diff
2. diff 被解析为结构化模型（文件、块、新增/删除的行）
3. 每个启用的规则都会在模型上运行并返回发现项
4. 引擎聚合发现项并根据 `fail_on` 计算判定结果
5. 报告器发布 PR 评论、设置检查状态，并编写 Step Summary
6. 如果判定结果为 `fail`，则检查失败——在 agent 的工作被审查之前阻止合并
CLI（`agent-gate check`）使用 `git diff` 而不是 GitHub API，使其能够在本地和 pre-commit hooks 中使用。
## 项目结构
```
agent-gate/
action.yml # GitHub Action metadata
src/
cli.ts # CLI entry (commander)
action.ts # Action entry
engine.ts # Aggregates rules → verdict
diff/ # Diff providers + parser
rules/ # Rule implementations
report/ # Reporters (comment, check, summary, CLI)
config/ # Schema (zod) + loader
utils/ # Glob matching
test/
fixtures/ # Sample diffs (clean + dirty per rule)
rules/ # Rule unit tests
engine.test.ts
docs/
ABOUT.md # plain-language overview (non-technical)
DESIGN.md # architecture & internals
RELEASING.md # release + Marketplace runbook
SPRINTS.md # sprint plan
```
## 技术栈
| 层级 | 技术 |
|-------|-----------|
| 语言 | TypeScript 5, 严格模式 |
| 运行时 | Node 20+ |
| Action 打包工具 | @vercel/ncc |
| 配置校验 | zod |
| 配置格式 | js-yaml |
| CLI | commander |
| GitHub API | @actions/github (Octokit) |
| 测试 | Vitest |
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。我们最欢迎新增规则作为贡献——这里有一个专门的 issue 模板和清晰的模式供您遵循。
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
标签：AIOps, GitHub Action, MITM代理, SOC Prime, 代码审查, 开发工具, 自动化攻击