ThreeMoonsLab/agents-shipgate
GitHub: ThreeMoonsLab/agents-shipgate
Shipgate代理：AI代理能力更改的确定性合并门审查工具。
Stars: 3 | Forks: 1
## 为什么存在
一旦一个AI代理能够退款、发邮件、取消、部署或修改记录，每个工具更改都变成一个发布事件。代码审查捕获代码；评估套件捕获行为；可观察性捕获运行时。它们都没有回答发布问题：*给定这个PR中声明的工具表面，我们是否对每个操作都有明确的批准策略、范围覆盖、幂等证据和审查准备？*
Shipgate代理生成一个在提升之前对该问题的确定性答案。
当前产品的承诺是故意狭窄的：一个确定性、本地优先、静态合并门，用于AI生成代理能力更改——在PR时间运行的工具使用就绪审查。更广泛的生命周期想法是未来路线图的工作，而不是这个扫描器今天所声称的。
## 发现画廊
捆绑的支持退款组件演示了Shipgate代理旨在揭示的发布风险：
```
## 发布决策
Decision: blocked
Reason: 2 active findings block release.
Blockers: 2
Review items: 16
Fail policy: would_fail_ci=false (exit 0)
Top findings:
1. stripe.create_refund lacks a declared approval policy
2. stripe.create_refund lacks idempotency evidence
3. Manifest declares broad permission scopes
```
- `stripe.create_refund` 缺少声明的批准策略，因此财务操作可能会在没有明确的人类审查门的情况下发货。
- `stripe.create_refund.amount` 缺少最大界限，削弱了爆炸半径控制。
- `stripe.create_refund` 在重试行为已知的情况下缺少幂等证据，存在重复退款的风险。
- `wildcard_mcp_tools.*` 暴露了一个通配符工具表面，使得审查不完整。
- `gmail.send_customer_email` 在没有匹配的确认策略的情况下与禁止的外部通信操作重叠。
## 看它阻止PR
理解审查者需要了解的变化最快的方法：通过一个黄金PR进行操作。每个黄金PR都发送一个样本清单、生成的报告、发布决策和代理应发布的推荐PR评论摘要。
- [openai-agents-sdk-refund-agent](examples/golden-prs/openai-agents-sdk-refund-agent/README.md) — 退款代理添加 `stripe.create_refund`。Shipgate决定 `blocked`，因为缺少批准策略和幂等证据。包括推荐的Markdown PR评论模板。
- [golden-pr-from-coding-agent.md](examples/golden-prs/golden-pr-from-coding-agent.md) — 编码代理在运行验证首先流程后应生成的 *工件*：PR评论、`merge_verdict`、`capability_review` 和人类/编码代理的下一步行动。
- [mcp-only-tool-server](examples/golden-prs/mcp-only-tool-server/README.md) — 没有Python框架导入的MCP服务器；演示了仅MCP的采用路径。
- [openapi-support-agent](examples/golden-prs/openapi-support-agent/README.md) — OpenAPI描述的工具表面；显示范围覆盖发现。
## 为什么不直接...
| 替代方案 | Shipgate代理覆盖的差距 |
| --- | --- |
| 单元测试 | 测试通常验证代码路径，而不是发布的工具表面和声明的策略。 |
| 代码审查 | 审查者错过了生成的规范、MCP导出、广泛的范围和缺少的批准策略。 |
| 运行时跟踪 | 有用，但它们在行为存在之后到达。Agents Shipgate在提升之前运行。 |
| 什么都没有 | 工具表面漂移成为生产惊喜。 |
有关与特定评估者和平台的命名比较，请参阅营销网站与页面：
[vs evals](https://threemoonslab.com/vs/evals/),
[vs promptfoo](https://threemoonslab.com/vs/promptfoo/),
[vs Braintrust](https://threemoonslab.com/vs/braintrust/),
[vs LangSmith](https://threemoonslab.com/vs/langsmith/), 和
[vs 可观察性平台](https://threemoonslab.com/vs/observability/).
## CI行为
CI默认为咨询：
```
agents-shipgate scan --config shipgate.yaml --ci-mode advisory
```
严格模式仅在存在未抑制的关键发现时退出代码 `20`。
配置、输入解析和内部工具错误分别使用 `2`、`3` 和 `4`：
```
agents-shipgate scan --config shipgate.yaml --ci-mode strict
```
对于现有项目，将当前审查的发现保存为本地基线，并且仅在出现新的未抑制发现时才失败严格CI：
```
agents-shipgate baseline save --config shipgate.yaml --out .agents-shipgate/baseline.json
agents-shipgate scan --config shipgate.yaml --baseline .agents-shipgate/baseline.json --ci-mode strict
```
团队可以覆盖严重性和CI失败阈值：
```
checks:
severity_overrides:
SHIP-AUTH-MISSING-SCOPE: critical
ci:
fail_on:
- critical
- high
```
## Google ADK
Agents Shipgate支持静态Google ADK提取Python入口点和代理配置YAML。适配器检测 `LlmAgent`/`Agent` 定义、函数工具、`OpenAPIToolset`、`McpToolset`、回调、插件、子代理、评估引用和显式本地工具库存，而无需导入ADK代码。
```
version: "0.1"
project:
name: adk-support-agent
agent:
name: support-agent
declared_purpose:
- handle support cases
environment:
target: production_like
tool_sources:
- id: adk
type: google_adk
path: agent.py
google_adk:
eval_sets:
- evals/support.eval.json
tool_inventories:
- inventories/adk-mcp-tools.json
```
动态ADK工具集会产生警告或发现，除非您提供显式的MCP、OpenAPI或本地工具库存输入。
## LangChain 和 CrewAI
Agents Shipgate包括LangChain/LangGraph和CrewAI的静态Python提取。适配器仅解析Python AST；它们不导入框架包或用户模块。支持的LangChain/LangGraph模式针对LangChain Core 0.3+、LangChain 1.x `create_agent` 和 LangGraph 0.2+源形状。
```
tool_sources:
- id: langchain_agent
type: langchain
path: agent.py
- id: crewai_agent
type: crewai
path: crew.py
```
对于动态或预构建的工具表面，提供显式的本地库存文件：
```
langchain:
tool_inventories:
- inventories/langchain-tools.json
crewai:
tool_inventories:
- inventories/crewai-tools.json
```
## 策略包
v0.4添加了本地声明式YAML策略包，用于组织特定的发布规则。策略包是静态数据，运行时无需导入代码。
```
checks:
policy_packs:
- path: policies/org-release.yaml
```
```
agents-shipgate scan --config shipgate.yaml --policy-pack policies/org-release.yaml
```
## 它是为谁准备的
| 买家 | 痛点 | 投资回报 | 下一步 |
| --- | --- | --- | --- |
| 平台工程师发布第一个生产代理 | "我不知道我不知道什么。" | 审查清单和工具模式以发现代码审查遗漏的发布风险。 | 运行 `agents-shipgate init --workspace . --write`。 |
| 安全或GRC审查员 | "代理绕过了现有的控制。" | 创建一个静态工具表面审计跟踪以供审查。 | 审查 [检查目录](docs/checks.md)。 |
| 有发布截止日期的AI PM | "安全审查阻碍了我们。" | 在正式批准之前为团队提供自助预审查。 | 扫描 [支持退款组件](samples/support_refund_agent/shipgate.yaml)。 |
## 局限性
Agents Shipgate是一个静态、清单优先的扫描器。它是故意狭窄的：
- 它默认不运行代理、调用工具、调用LLM或通过导入ADK代码来验证模型可用性（默认静态；请参阅 [信任模型](#trust-model) 和 [`ALLOWED_EXCEPTIONS`](tests/test_adapter_static_only.py)）。
- 它不验证运行时行为、延迟、提示质量或路由决策。
- 它不取代动态安全测试或对底层系统的人类安全审查。
- 它仅检查 `shipgate.yaml` 中声明的、本地的OpenAPI规范、MCP导出、Anthropic/OpenAI API工件、可选SDK AST元数据、静态Google ADK/LangChain/CrewAI/n8n输入和静态Codex插件包元数据中声明的工具；未声明或无法静态发现的工具不进行扫描。
- 清单保持 `version: "0.1"`，因此现有配置仍然有效。当前报告携带 `report_schema_version: "0.23"`（在v0.22的验证周期块上添加，向 `capability_change` 成员添加语义元数据）同时保留报告模式文档中记录的稳定有效负载合同。
请参阅 [ROADMAP.md](ROADMAP.md) 了解计划中的内容。
## 信任模型
**Agents Shipgate默认不导入用户代码、运行代理、调用工具、调用LLM、连接到MCP服务器、进行网络调用或收集遥测数据。**
请参阅 [信任模型](docs/trust-model.md) 和 [安全策略](SECURITY.md) 了解默认的本地唯一保证和披露过程。
## GitHub Action
将此完整的咨询工作流程放入 `.github/workflows/agents-shipgate.yml`。它在每个PR上运行，发布摘要评论，上传报告和包作为工作流程工件，并且永远不会失败作业。这是在 `examples/github-actions/01-advisory-pr-comment.yml`(examples/github-actions/01-advisory-pr-comment.yml) 中发送的相同文件。
```
name: Agents Shipgate (advisory)
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
shipgate:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
with:
fetch-depth: 0
- uses: ThreeMoonsLab/agents-shipgate@v0.11.0
with:
ci_mode: advisory
diff_base: target
pr_comment: 'true'
shipgate_version: '0.11.0'
```
采用后，选择显式合并策略。`examples/github-actions/07-block-on-blocked-verdict.yml`(examples/github-actions/07-block-on-blocked-verdict.yml) 仅在 `merge_verdict == blocked` 时阻止；`examples/github-actions/08-require-mergeable.yml`(examples/github-actions/08-require-mergeable.yml) 需要 `can_merge_without_human == true`。请参阅 `examples/github-actions/`(examples/github-actions/) 了解严格/基线/SARIF/多配置/更改路径配方。
输入：`config`、`ci_mode` (`advisory` 或 `strict`)、`fail_on`、`baseline`、`baseline_mode`、`diff_from`、`diff_base`、`base_ref`、`head_ref`、`policy_packs`、`no_plugins`、`output_dir`、`upload_artifact`、`pr_comment`、`github_token`、`shipgate_version`。将 `diff_base: target` 设置为PR基/头差异丰富。操作委托给 `agents-shipgate verify` 并永不获取；在检出时使用 `fetch-depth: 0`，或在早期步骤中获取基线引用。如果设置了 `head_ref`，则验证扫描该引用的隔离存档；否则，它扫描检出的工作区。如果无法检查显式基线引用或PR差异，则验证跳过仅头扫描，将 `merge_verdict: "unknown"` 写入 `verifier.json` 并退出2。
输出：`decision`、`merge_verdict`、`can_merge_without_human`、`blocker_count`、`review_item_count`、`ci_would_fail`、`diff_enabled`、`status`、`critical_count`、`high_count`、`medium_count`、`baseline_new_count`、`baseline_matched_count`、`baseline_resolved_count`、`adk_agent_count`、`adk_dynamic_toolset_count`、`trust_root_touched`、`policy_weakened`、`capability_changes_added`、`capability_changes_modified`、`capability_changes_removed`、`report_json`、`report_markdown`、`report_sarif`、`verifier_json`、`pr_comment_markdown`、`exit_code`。使用 `decision` / `ci_would_fail` 进行CI门控，使用 `merge_verdict` / `can_merge_without_human` 进行PR控制器路由，并避免使用 `status` 进行新门控。
将 `shipgate_version` 设置为安装固定的PyPI发布版本，而不是操作源，当您的流程需要包/版本对齐时。
对于设计合作伙伴审查，导出小型红acted验证器反馈工件，而不是发送原始报告证据：
```
agents-shipgate feedback export \
--from agents-shipgate-reports/verifier.json \
--redact \
--out shipgate-feedback.json
```
## 定价和开源立场
Agents Shipgate现在是，并将继续是免费的开源软件，供个人和在自己的基础设施上运行它的团队使用。核心清单优先扫描器、内置检查、Markdown报告和JSON报告旨在保持开源。我们不收集遥测数据，也不需要账户。
如果托管仪表板、SSO、组织范围内的基线、批准工作流程或基于跟踪的证据出现，它们应该存在于一个单独的可选产品中，而不是将核心开源功能移至付费墙后面。
发布类似工具使用的代理的团队可以申请 [Three Moons Lab设计合作伙伴计划](https://threemoonslab.com/design-partners/)
— 营销页面与存储库中的 `docs/design-partners.md`(docs/design-partners.md) 相对应，并包括一个
预填充的电子邮件CTA，用于审查标准和联系。当前的试点运行手册是 `docs/design-partner-verifier-pilot.md`(docs/design-partner-verifier-pilot.md)
：带来一个AI生成的代理PR，运行验证器循环，并导出红acted
反馈。
## 文档
在 [threemoonslab.com](https://threemoonslab.com/) 的营销网站以人类可读、搜索优化的形式承载了相同的标准概念：
[快速入门](https://threemoonslab.com/quickstart/),
[检查目录](https://threemoonslab.com/checks/),
[术语表](https://threemoonslab.com/glossary/),
[博客](https://threemoonslab.com/blog/), 和
[设计合作伙伴](https://threemoonslab.com/design-partners/)。存储库中的文档
以下是标准合同；营销页面是为首次读者和AI搜索摄取而设计的。
- [工具使用就绪发布门类别](docs/category.md)
- [清单 v0.1](docs/manifest-v0.1.md)
- [检查目录](docs/checks.md)
- [策略包](docs/policy-packs.md)
- [基线工作流程](docs/baseline.md)
- [JSON报告模式 v0.23](docs/report-schema.v0.23.json)
- [反馈导出模式 v0.1](docs/feedback-schema.v0.1.json)
- [隐私和编辑](docs/privacy.md)
- [条款](docs/terms.md)
- [信任模型](docs/trust-model.md)
- [AI搜索摘要](docs/ai-search-summary.md)
- [设计合作伙伴](docs/design-partners.md)
- [设计合作伙伴验证器试点](docs/design-partner-verifier-pilot.md)
- [运行时库存设计说明](docs/runtime-inventory.md)
- [故障排除](docs/troubleshooting.md)
- [集成配方](docs/integrations.md)
- [分发计划](docs/distribution.md)
- [JSON报告模式 v0.2](docs/report-schema.v0.2.json)
- [JSON报告模式 v0.1](docs/report-schema.v0.1.json)
标签：AI, API 开发, GitHub Action, SDK 开发, 二进制发布, 人工智能, 代码安全, 代码审查流程, 安全策略, 工具使用准备度, 开源工具, 开源框架, 持续集成, 提示词设计, 日志审计, 权限控制, 漏洞枚举, 用户模式Hook绕过, 自动化代码审查, 软件发布流程, 软件生命周期管理, 逆向工具, 重复操作检测, 金融安全, 风险检测