sjh9714/Agent-Gate

# Agent Gate [](https://github.com/sjh9714/Agent-Gate/releases/tag/v0.2.5) [](https://github.com/sjh9714/Agent-Gate/actions/workflows/ci.yml) [](https://github.com/sjh9714/Agent-Gate/actions/workflows/agent-gate.yml) [](LICENSE) Agent Gate 是一个无需 checkout 的 GitHub Action，当 AI 生成的 PR 触碰高风险策略边界时，它为维护者提供确定性证据。 它会检查 workflow 权限、PR 范围契约、agent 控制平面漂移、MCP 配置漂移、缺失的测试证据，以及 package 生命周期脚本漂移。 该 Action 不对 PR 代码进行 checkout，不进行运行时 LLM 调用，不执行仓库脚本，也不从不受信任的 PR head 加载策略。相同的分析器还为本地重放 fixture 提供支持，以进行确定性演示。 [30秒安装](#30-second-install) · [示例报告](#real-report-example) · [调整策略](#after-the-first-run-tune-policy) · [Action 参考](#action-reference) · [证据模型](docs/evidence-model.md) 由可重复的证据支持的 AI PR 策略边界。 ## 30秒安装 将 observe 模式的 workflow 模板下载到您的仓库中： macOS/Linux: ``` mkdir -p .github/workflows \ && curl -fsSL https://raw.githubusercontent.com/sjh9714/Agent-Gate/v0.2.5/templates/agent-gate-observe.yml \ -o .github/workflows/agent-gate.yml ``` Windows PowerShell: ``` New-Item -ItemType Directory -Force .github/workflows | Out-Null Invoke-WebRequest ` -Uri https://raw.githubusercontent.com/sjh9714/Agent-Gate/v0.2.5/templates/agent-gate-observe.yml ` -OutFile .github/workflows/agent-gate.yml ``` 这会下载一个固定 tag 版本的 workflow YAML 文件。它不会执行远程 脚本。提交该文件并打开一个 pull request；Agent Gate 将以 warn 模式运行，首次运行不需要 `agent-gate.yml`。 接下来： 1. 提交 `.github/workflows/agent-gate.yml`。 2. 打开一个 pull request。 3. 阅读 Agent Gate 的 job 总结。 ### 手动复制粘贴安装 希望在添加之前检查 workflow？使用以下内容创建 `.github/workflows/agent-gate.yml`： ``` name: Agent Gate on: pull_request: types: [opened, synchronize, reopened, edited, labeled, unlabeled, ready_for_review] permissions: contents: read pull-requests: read jobs: agent-gate: runs-on: ubuntu-latest steps: - uses: sjh9714/Agent-Gate@v0.2.5 with: github-token: ${{ secrets.GITHUB_TOKEN }} mode: warn fail-on-block: false ``` 为了实现更严格的供应链锁定，请将 `@v0.2.5` 替换为经过验证的 发布 commit SHA。 ## 真实报告示例 在没有 `agent-gate.yml` 的首次运行中，Agent Gate 仍然可以显示内置的 默认策略警告。例如，workflow 权限提升： ``` Agent Gate: NEEDS HUMAN DECISION Decision: warn Why: contents permission increased from read to write. Path: .github/workflows/demo-release.yml Recommended next step: review the workflow permission change before merging. Policy status: warning today; eligible to become a merge gate after tuning. Finding ID: agf_... Rule: workflow/permission-escalation Policy source: built-in default ``` 不熟悉该报告？请参阅 `docs/first-report.md` 了解如何阅读决策、 finding ID、证据快照和策略来源。 查看一个真实的首次运行沙箱冒烟测试 PR： [sandbox PR #12](https://github.com/sjh9714/agent-gate-install-smoke-20260617/pull/12)。 该 PR 将 `permissions.contents` 从 `read` 修改为 `write`，Agent Gate 在未进行 checkout 或缺少 `agent-gate.yml` 的情况下报告了 `workflow/permission-escalation`。 package 生命周期的首次运行证明仍可在 [sandbox PR #11](https://github.com/sjh9714/agent-gate-install-smoke-20260617/pull/11) 中查看。 更多示例列在 [docs/demo-prs.md](docs/demo-prs.md) 中。 ## 没有 `agent-gate.yml` 时会运行什么？ | 检查项目 | 无配置首次运行 | 有 `agent-gate.yml` | | ---------------------------------- | --------------------------- | --------------------- | | Workflow 权限提升 | 是 | 可配置 | | 危险的 workflow 模式 | 是 | 可配置 | | Agent 控制平面漂移 | 是 | 可配置 | | Package 生命周期脚本漂移 | 是，默认警告 | 可配置 | | Agent 检测 | 否 | 是 | | 必需的 PR 正文契约 | 否 | 是 | | 超出契约的修改 | 仅当存在契约时 | 是 | | 高风险路径和匹配的测试 | 否 | 是 | ## 首次运行后：调整策略 30秒安装足以在 warn 模式下启动。如果确认 PR base 分支上缺少默认的 `agent-gate.yml`，Agent Gate 将使用其内置的默认策略，并在报告元数据中记录 `configSource: default`。 在您看到首批报告后，可以通过一个小型的 `agent-gate.yml` 调整特定于仓库的检查： ``` version: 1 mode: warn contract: required_for: - agent allow_missing_in_observe_mode: true agent_detection: labels: - ai - agent - codex branch_patterns: - "codex/**" - "ai/**" high_risk_paths: workflows: paths: - ".github/workflows/**" severity: error ``` 对于 AI 生成的 PR，在 PR 正文中添加一个小型契约： ``` ``` 调整完成后，Agent Gate 还可以报告契约范围的证据： ``` Agent Gate: NEEDS HUMAN DECISION Decision: warn Why: .github/workflows/release.yml changed outside the allowed contract scope. Recommended next step: review the workflow change before merging. Policy status: warning today; eligible to become a merge gate after tuning. Finding ID: agf_... ``` 将首次运行视为观察，而不是语义正确性的证明： - `PASSED`：可安全观察 - `WARN`：需要人工决策 - `BLOCKED`：一旦策略强制执行，必须阻止 ## 它能捕获什么 - 超出契约的修改：agent PR 修改了其声明范围之外的文件。 - Workflow 权限提升：Actions workflow 获得了更广泛的写入权限。 - Agent 控制平面漂移 (`agent-control-plane/drift`)：影响未来 agent 的指令或工具配置更改。 - 缺失测试证据：高风险源码更改没有对应的测试文件更改。 - MCP 配置漂移：`.mcp.json` 的更改改变了 agent 可以调用的工具。 - Package 生命周期脚本漂移：添加或更改了高风险的 `package.json` 生命周期 脚本 ([规则指南](docs/rules/package-lifecycle-scripts.md))。 ## Agent Gate 不做什么 Agent Gate 不会： - 证明 PR 在语义上是正确的 - 取代人工代码审查 - 在 CI 阶段运行 LLM 审查器 - 执行受 PR 控制的代码 - 证明匹配的测试是有意义的 ## 何时使用 Agent Gate 在以下情况使用 Agent Gate： - AI agent 在您的仓库中发起 pull request - 您希望在合并前获得策略边界证据 - 您希望 CI 检查不执行受 PR 控制的代码 - 您希望在强制执行门控之前从 warn 模式开始 推荐的推广步骤： 1. 从 `mode: warn` 和 `fail-on-block: false` 开始。 2. 审查报告中的误报和嘈杂规则。 3. 调整 `agent-gate.yml`。 4. 将稳定的发现提升至 `mode: block`。 5. 当检查需要阻止合并时，设置 `fail-on-block: true`。 ## Agent Gate 与 LLM 审查器对比 LLM 审查器有助于提供判断。Agent Gate 则验证确定性的合并证据。 Agent Gate 不试图找出每一个语义错误或取代代码审查。它检查的是在 CI 中应该可解释且可重复的策略边界： - PR 是否停留在其声明的范围内？ - workflow 权限是否发生提升？ - agent 控制平面文件是否发生了漂移？ - 高风险代码是否在没有匹配测试文件证据的情况下进行了更改？ - MCP 配置更改是否被暴露出来？ - package 生命周期脚本是否发生了更改？ 使用您的 LLM 审查器进行判断。使用 Agent Gate 获取确定性的合并证据。 ## 为什么是确定性的？ AI agent 可以生成有用的 pull request，但测试和 LLM 审查并不总能暴露策略边界的更改： - 一个 workflow 悄悄获得了写入权限 - 一个 agent 修改了声明任务范围之外的文件 - `.mcp.json` 更改了未来 agent 可以调用的工具 - `AGENTS.md` 更改了未来的 agent 行为 - 高风险源码更改在没有匹配测试文件证据的情况下落地 - `package.json` 添加了 `preinstall`、`install`、`postinstall` 或 `prepare` 脚本 Agent Gate 专注于这些可重复的边界检查。 ## 重放演示 用于演示的易读输出： ``` pnpm --filter agent-gate build node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/workflow-permission-escalation ``` 示例输出： ``` Agent Gate: BLOCKED ERROR workflow/permission-escalation contents permission increased from read to write. Path: .github/workflows/release.yml ERROR workflow/dangerous-pattern .github/workflows/release.yml contains a dangerous GitHub Actions workflow pattern. Path: .github/workflows/release.yml ``` 机器可读的 JSON 报告： ``` node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/workflow-permission-escalation --format json ``` 预期结果：Agent Gate 报告一个被阻止的 PR，并带有 `workflow/permission-escalation` 和 `workflow/dangerous-pattern` 发现。 其他 unsafe-pr-zoo 演示： - `agent-control-plane-drift`：阻止 `AGENTS.md` 更改，因为它们可能会改变未来的 agent 行为。 - `out-of-scope-agent-edit`：阻止对 PR 契约中 `allowed_paths` 之外的支付 webhook 进行修改。 - `missing-test-evidence`：在没有匹配的 auth 测试更改的情况下阻止 auth 逻辑更改。 - `mcp-config-drift`：阻止 `.mcp.json` 更改，因为 MCP 配置可以更改 agent 可以调用的工具。 - `package-lifecycle-script-added`：针对新的高风险 package 生命周期 脚本发出警告。 ``` node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/agent-control-plane-drift node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/out-of-scope-agent-edit node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/missing-test-evidence node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/mcp-config-drift node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/package-lifecycle-script-added ``` ## Action 参考 通过 `sjh9714/Agent-Gate@v0.2.5` 使用根 Action。不需要 checkout 步骤。 ### 输入 | 输入 | 默认值 | 描述 | | ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `config` | `agent-gate.yml` | PR base 分支上的可选策略配置路径。在 `v0.2.3+` 版本中，当确认缺少默认路径时，将使用内置默认值。 | | `github-token` | `${{ github.token }}` | 用于仅限 API 的 pull request 读取的 token。 | | `mode` | 配置值 | 覆盖策略模式：`observe`、`warn` 或 `block`。 | | `comment` | `false` | 创建或更新带标记的 PR 报告评论。 | | `fail-on-block` | `true` | 当决策为 `block` 时以代码 1 退出。 | | `report-json` | `agent-gate-report.json` | 写入 JSON 报告的路径。 | | `report-markdown` | `agent-gate-report.md` | 写入 Markdown 报告的路径。 | ### 输出 | 输出 | 描述 | | ----------------- | ------------------------------------------- | | `decision` | 最终决策：`pass`、`warn` 或 `block`。 | | `risk-score` | 从 0 到 100 的风险分数。 | | `report-json` | JSON 报告的路径。 | | `report-markdown` | Markdown 报告的路径。 | `mode` 控制推广行为。`decision` 是分析器的结果。从 `mode: warn` 和 `fail-on-block: false` 开始，调整发现的规则，当规则信号足够精确时，再切换到 `mode: block`。 ### 权限和评论 最小权限为： ``` permissions: contents: read pull-requests: read ``` 为了让 Agent Gate 创建或更新 PR 报告评论，请添加 `issues: write` 并设置 `comment: true`。在 fork 的 pull request 上，GitHub 可能仍会提供只读 token，因此评论失败将被报告为警告，而不会导致 Action 失败。 ``` permissions: contents: read pull-requests: read issues: write with: comment: true ``` ### 策略配置 在仓库根目录创建 `agent-gate.yml`： ``` version: 1 mode: warn contract: required_for: - agent allow_missing_in_observe_mode: true agent_detection: authors: - github-copilot[bot] labels: - ai - agent - codex branch_patterns: - "codex/**" - "ai/**" high_risk_paths: workflows: paths: - ".github/workflows/**" severity: error ``` 团队可以随着策略的成熟，添加 auth、payment、infra 和 agent 控制平面的路径。 目前 `agent-gate.yml` 的支持范围被有意缩小：agent 检测、PR 正文契约、具有匹配测试文件证据的高风险路径、agent 控制平面路径、GitHub Actions workflow 规则以及 package 生命周期脚本检查。基于文件的契约、风险预算、依赖项添加、lockfile 不匹配、声明与 CI 证据的对比、审查者要求以及回滚计划要求都属于计划中的领域，目前会被拒绝，而不会作为空操作设置被接受。 从 `v0.2.4` 开始，package 生命周期脚本检查默认在 warn 模式下启用。它们会检查配置的 `package.json` 路径中是否添加或更改了 `preinstall`、`install`、`postinstall` 和 `prepare` 脚本。有关分类指南，请参阅 `docs/rules/package-lifecycle-scripts.md`。依赖项添加和 lockfile 不匹配检查仍是未来的工作。 ``` package_scripts: enabled: true severity: warn ``` 从 `v0.2.3` 开始，如果确认 PR base 分支上缺少默认的 `agent-gate.yml`，Agent Gate 可以使用其内置的默认策略，并在报告元数据中记录 `configSource: default`。该发布的默认策略为 GitHub Actions workflow 检查、agent 控制平面漂移和固定 Action 警告提供了与仓库无关的初始信号。 从 `v0.2.4` 开始，内置默认策略还包含警告模式下的 package 生命周期脚本漂移检查。特定于仓库的检查（例如 agent 检测、必需的 PR 契约、高风险源路径以及匹配的测试文件 证据）仍然需要 `agent-gate.yml`。 ## 状态和路线图 Agent Gate 处于预发布阶段。最新的预发布版本是 `v0.2.5`。 安装时请使用 `sjh9714/Agent-Gate@v0.2.5` 或固定的 commit SHA。`@main` 跟踪活跃的开发，可能会发生更改。 推荐的安装方式应使用 `sjh9714/Agent-Gatev0.2.5`。即使 发布已经发布并启用了 Marketplace，目前 GitHub Marketplace 在预发布版本的显示上可能会有延迟。 请参阅 `CHANGELOG.md` 了解发布历史，参阅 `docs/evidence-model.md` 了解当前的 证据模型。最新的外部安装冒烟测试证据记录在 `docs/external-install-smoke-v0.2.5.md` 中。 请参阅 `docs/repository-governance.md` 了解推荐的分支保护和发布安全设置。欢迎在 [#27](https://github.com/sjh9714/Agent-Gate/issues/27) 中提供有关 AI 生成的 PR 安全策略的反馈。 ## 包 - `packages/core`：纯分析引擎、内置的确定性规则以及 JSON/Markdown 报告渲染器。 - `packages/cli`：用于确定性本地 fixture 演示的 `agent-gate replay `。 - `packages/action`：Node 24 GitHub Action 包，它通过 GitHub API 读取 pull request 数据并调用核心分析器。 ## Action 包 外部用户应优先使用根 Action（即 `sjh9714/Agent-Gate@`）。包本地的 Action 仍位于 `packages/action/action.yml`，用于此仓库自身的开发工作流。两者都仅使用 REST API：它们在存在时从 PR base ref 加载 `agent-gate.yml`，仅在确认缺少默认文件时回退到内置默认值，从 API 读取更改的文件元数据和文件内容，运行 `@agent-gate/core`，写入 JSON/Markdown 报告，设置 Action 输出，写入 job 总结，并可选择性地插入一条带标记的 PR 报告评论。它们不会 checkout pull request 或执行仓库脚本。 ## 自我内部测试 Agent Gate 通过 `.github/workflows/agent-gate.yml` 在此仓库的 pull request 上运行。该 workflow 使用 `sjh9714/Agent-Gate/packages/action@main`，因此当 Action 本身处于开发阶段时，pull request 不会执行来自其自身分支的 Action 代码。在项目调整早期策略时，它以非阻塞的 `warn` 模式启动。 ## 本地开发 前置条件： - Node.js 20+ - pnpm 11.5.0 ``` pnpm install pnpm test pnpm typecheck pnpm lint pnpm build ``` ## 原则 Agent Gate 不得在运行时调用 LLM、执行受 PR 控制的代码或从不受信任的 PR head 加载策略。核心分析包必须保持独立于 GitHub API。

标签：AI 代码审查, GitHub Actions, MITM代理, SOC Prime, 开发工具, 自动化攻击, 自动笔记