agentgate

English · 中文

agentgate

为 Agent 运行的工具提供控制平面。它盘点正在使用的内容，记录每项声明背后的证据，明确公司拒绝什么，并在 CI 和运行时执行该决策。

整个项目遵循一条规则：

只有在每项检查都已运行时，才会发出 clean。无法测量的内容会标记为 unmeasured，而包含未测量部分的产物会标记为 incomplete——绝不会是 clean。

制定这条规则，是因为安全扫描器常见的问题是：没人做过的工作却让构建显示为绿色。在这里，检查崩溃会导致结果变为不完整，因此不会悄无声息地发生。

四个部分

部分	功能	软件包
盘点	枚举注册表、解析软件包、获取仓库	packages/collect
证据	将内容汇总为每个服务的一条记录，并附上每项声明背后的字节数据	packages/collect
策略	扫描配置、钩子、清单和源代码，找出公司会拒绝的内容	packages/guard
验证	使用声明之外的内容核验声明	packages/verify

运行

服务端设置请参阅部署操作手册。 首次部署于 2026-09-16，相关记录见docs/verification.md，其中列出了已检查的内容以及尚未检查的内容。

docs/capabilities.md逐条列出本项目能做和不能声称能做的事情，每条都附带一条可运行的命令。之所以编写这份文档，是因为有位顾问曾替我们整理过项目能力，其中列出了四项我们并不具备的能力。

无需安装即可试用

服务运行于 https://xn--5kvo87g.com/：同一主机提供首页、定价、证据索引（每日重建）和 API。

https://ciceroyang.github.io/agentgate/ 是 GitHub Pages 上的首页。索引是一个可浏览的单页，网址为 https://ciceroyang.github.io/agentgate/evidence.html，每天从实时注册表重建——记录直接嵌入页面，筛选在本地进行，无需注册。定价和十分钟演示。

快速开始

升级到 0.6.0： 在替换现有的准入门禁或监控安装前，请阅读升级指南。0.5.0 软件包在缺少证据时，可能会错误地通过必需证据门禁；请勿将其用于新门禁。请确认已安装的版本，并参阅发布记录，了解公开软件包的验证情况。源代码检出版本和托管服务可能运行不同的版本。

Node 20 或更高版本，无需依赖项。克隆的仓库已附带示例索引，因此服务可立即响应；refresh 会将其替换为最新索引。

node bin/agentgate.mjs serve
# agentgate serving http://127.0.0.1:8080

curl -s localhost:8080/health
curl -s localhost:8080/v1/index/summary
curl -s localhost:8080/v1/servers/<name>
curl -s localhost:8080/badge/<name>.svg

该软件包已发布到 npm，名称为 @zhiliangtech/agentgate。推送 v* 标签后，CI 会通过来源证明发布软件包；publish-checklist.md列出了设置步骤以及已验证内容的记录。

npx --yes --ignore-scripts @zhiliangtech/[email protected] check --root .
npx --yes --ignore-scripts @zhiliangtech/[email protected] serve

不指定版本的 npx 命令会跟随 latest dist-tag，而不是当前检出的版本。请固定使用已接受的版本；修改本地版本号不会改变公开软件包。

未提供策略文件时，check 使用内置默认策略，不会额外拒绝任何内容；serve 则使用软件包随附的快照响应。refresh 会将数据写入当前目录下的 ./data，绝不会写入已安装的软件包。

Docker 也能运行，且执行相同的命令：

docker compose up                            # the service on :8080
docker compose --profile collect run --rm refresh   # rebuild data/index.json and seed the first snapshot

工具清单

运行 node bin/agentgate.mjs serve，并在它显示的地址打开 /inventory.html。粘贴工具名称列表或选择文本／JSON 文件，解决含糊的匹配项，填写你实际使用的版本，然后下载独立的 HTML 报告。比对在浏览器内存中针对嵌入的索引快照进行：列表不会上传或存储，不会扫描你的机器，也不会执行任何工具。如果记录包含覆盖情况区块，报告还会列出哪些扫描器已运行、哪些未运行，以及原因；如果记录自身的覆盖情况区块表明某个必需扫描器未完成，无论其余证据看起来多么完整，都不会将该记录显示为匹配。

不使用浏览器也能完成同样的操作：

node bin/agentgate.mjs inventory --input examples/inventory/tools.json --out my-tools.html
node bin/agentgate.mjs inventory --input tools.json --index data/index.json --format json

输入可以是每行一个名称、JSON 数组，或 { "tools": [...] }。每个对象可以包含 name、server、package、registry 和 version，不能包含其他内容。我们有意拒绝完整的客户端配置和凭据。清单指南中有详细说明。

未匹配、匹配含糊、缺少版本、版本不匹配和证据不完整的项目都会保留在报告中。版本匹配并不能证明实际安装了什么。已提交的示例数据是历史数据，无法产生已确认的匹配；没有精确内容绑定的旧证据也一样。即使是已确认的匹配，也不是安全认证，更不代表进行了新的扫描。依赖结果之前，请查看范围、发现项、快照日期和缺口。

退出代码 0 表示已生成报告，并不表示所有工具都通过了检查。输入格式错误或数据无法读取时，退出代码为 2；--out 不会覆盖已有文件。如果你希望 CI 拒绝某些情况，请使用 check，而不是 inventory。

首先如何获取清单

没人会手动整理这份清单。discover 会读取机器上已有的 MCP 配置文件，并生成 inventory --input 可接受的输入。当所有导出的身份信息都已知时，它会按行输出软件包坐标；如果有任何条目只有别名，则会使用 JSON，以免将 [email protected] 之类的别名误认为经过验证的软件包和版本：

node bin/agentgate.mjs discover --out tools.txt          # home directory + current directory
node bin/agentgate.mjs discover --roots ~/code/a,~/code/b --format json

它绝不会输出 env 值、标头或参数；远程地址会被截断为主机，因为路径和查询字符串可能包含令牌。它会读取 Codex 的 .codex/config.toml MCP 表格，但不会启动已配置的服务。在 --format json 中，明确禁用的条目仍会显示，但不会包含在文本和清单导出中。不受支持的 MCP TOML 格式、格式错误的文件和无法读取的文件都会列出原因，并使命令以退出代码 2 结束。软件包名称和版本仅取自可识别的已声明运行器参数；自定义命令或远程主机不会被视为经过验证的软件包或运行时版本。

多个仓库

node bin/agentgate.mjs audit --roots ~/code/a,~/code/b,~/code/c --index data/index.json

每个目录扫描一次，对整个集合给出一个判定。任何目录不完整都会使审计不完整；不存在的目录计为未测量，而非跳过。

自上次以来的变更

node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive
node bin/agentgate.mjs watch --verify --archive ./archive
node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive \
  --webhook https://example.invalid/hook --webhook-format wecom

每次运行都会向链式归档追加一行（prev 是上一行的哈希），并将所见内容存储在 snapshots/<sha256>.json 下。--verify 会重新计算哈希链和每个保留的快照；任何内容不匹配时，退出代码为 1。除非 --webhook 指定了地址，否则不会向任何地方发送内容；归档会在推送前写入，因此聊天服务不可用也不会导致采集结果丢失。

问卷映射

node bin/agentgate.mjs framework                       # who answers which AI-CAIQ item
node bin/agentgate.mjs inventory --input tools.json --framework aicaiq --out report.html

对于每个 AI-CAIQ 项目，映射会说明我们能够提供什么、我们的覆盖范围止于何处，以及答案应由我们、客户还是独立评估方提供。它描述的是证据，不是合规结论，也不会复现官方文本。评审方会向供应商询问的四个领域共 58 个项目均已分类：13 项由我们回答，41 项由客户回答，4 项需要独立评估方。

证据包

映射说明了我们能提供什么。pack 会生成实际交付物：一个供应商交给审核人员的目录，其中我们声称的每个答案都指向同一目录中的证据，而所有无法测量的内容都会在顶部统计。

node bin/agentgate.mjs pack --input tools.json --archive ./agentgate-archive --out agentgate-pack
node bin/agentgate.mjs pack --verify agentgate-pack     # recompute every hash and the seal

它会写入 pack.json（机器可读）、pack.html（供审核人员查看）、answers.aicaiq.md（全部 58 项，每项都经过分类）、manifest.txt（每个文件对应一个 sha256）和 manifest.sha256（清单的封条）。缺少证据的答案会标记为 unmeasured，命令会以 2 而不是 0 退出。以下示例基于实时索引生成： docs/samples/evidence-pack-example — 可使用 pack --verify 验证。规范：docs/spec/evidence-pack-v1.md。

MCP 服务

任何支持 MCP 的工具都可以直接查询索引。将以下内容添加到 claude_desktop_config.json、仓库的 .mcp.json，或客户端读取的其他配置文件中：

{
  "mcpServers": {
    "agentgate": { "command": "npx", "args": ["--yes", "@zhiliangtech/agentgate@next", "mcp"] }
  }
}

四个只读工具：lookup_server（单条记录及其覆盖情况区块）、inventory_tools（匹配你实际使用的工具）、coverage_report（索引中有多少内容经过测量）和 check_project（扫描本地目录）。它会读取本地索引，不会写入或上传任何内容，也不会运行扫描到的工具。不完整的记录会报告为不完整，索引中不存在的记录会报告为缺失，而不是安全。详情见： docs/spec/mcp-server-v1.md。

策略

策略声明公司拒绝什么。它是数据，而非代码，并且有相应规范： docs/spec/policy-v1.md。

{
  "version": "agentgate.policy/v1",
  "threshold": "high",
  "required": { "pinnedPackages": true, "measuredEvidence": ["packageManifest"] },
  "forbidden": { "rules": ["AG-INSTALL-001"], "servers": ["internal/*"] }
}

node bin/agentgate.mjs check --policy agentgate.policy.json --root . --index data/index.json

上述策略要求提供索引证据。请提供与本地 npm 包名称和版本完全匹配的真实索引：缺少证据时以 2 退出；索引明确标记为缺失、格式错误或示例索引时以 3 退出。本地源代码扫描不能替代所需的包证据。

如果没有策略文件，也没有使用 --policy，检查仍会运行。它会报告检查结果，并说明使用的是内置默认策略，该策略不会额外拒绝任何内容；替你凭空添加义务只会降低结果的意义，而不会提高。如果明确指定的策略无法读取，就会报错，因为这说明指定有误。

同一评估结果也可以提供给他人查看，而不只是输出到终端：

node bin/agentgate.mjs check --policy agentgate.policy.json --root . --index data/index.json --format html --out report.html

这是一个静态、可打印且不包含脚本的文件。所有无法测量的内容都会在检查结果上方单独列出：如果报告掩盖了未检查的内容，就会让结果看起来比实际更完整。免费检查服务交付的就是这个文件。

检查结果有三种状态，incomplete 的优先级高于 findings。如果某项检查未能运行，或者策略要求的证据区块为 unmeasured，退出代码就是 2，无论检查结果看起来多么干净。没有任何阈值能把不完整的答案变成通过。

退出代码	含义
0	无问题
1	发现问题
2	不完整

强制执行

如果拉取请求添加了策略所拒绝的内容，就不会被合并；拒绝原因会直接发布在拉取请求上，而不是留在无人查看的日志里。

- uses: ciceroyang/agentgate@main
  with:
    policy: agentgate.policy.json
    index: data/index.json

参见 examples/github-actions/policy.yml。该操作会运行检查、为代码扫描生成 SARIF、在拉取请求上评论报告，并以检查本身的退出代码退出——因此，不完整的扫描仍会以 2 使构建失败。

运行时

如果在 MCP 服务前面放置网关，而不是让客户端直接连接 MCP 服务，同一策略也能应用于已经部署的内容：

node bin/agentgate.mjs proxy --policy agentgate.policy.json --log calls.jsonl -- \
  npx -y @modelcontextprotocol/server-filesystem /data

策略拒绝的调用会在本地收到一条说明原因的响应，且不会到达 MCP 服务。被禁止的工具会从公布的列表中移除，因此客户端根本无法请求该工具。每项决策，无论允许还是拒绝，都会追加到日志中。

历史

索引会一直保留，因此可以比较两次构建。最值得关注的是最后一列： 本该由某个版本发布说明解释、却没有解释的变更。

node bin/agentgate.mjs diff --from previous-index.json --to data/index.json

  added:           0
  removed:         0
  verdict changed: 1
  package changed: 0
  silent (no version move, different evidence): 1

版本未变却出现新的发现，通常意味着软件包未经发布便被替换、仓库被直接修改，或者扫描器开始检测到某些内容。这条记录无法事后补录，只有当时有人在查看时，它才会存在。

索引背后的流水线

node packages/collect/mcp-audit.mjs --max 6000 --out data/census.json
node packages/collect/scripts/guard-scan.mjs --census data/census.json --out data/guard-scan.json
node packages/collect/scripts/build-index.mjs --census data/census.json --guard data/guard-scan.json --out data/index.json
node scripts/coverage-stats.mjs --index data/index.json   # how much of it was actually measured

以及在本地项目中运行的扫描器：

node packages/guard/bin/agent-guard.mjs . --fail-on high
node packages/collect/bin/agent-add.mjs --index data/index.json <server-name>

文章

• 我们为 11,605 条 MCP 记录建立了索引，并审计了其中 258 条（中文）——实际测量了收集到的服务中有多少，以及其余服务为何未能测量。文中的数字对应文章撰写时的 2026-09-19 构建；索引每天重建数次，内容会不断变化。
• 最响亮的规则九次全错
• “干净”是对已完成工作的断言
• 一条读起来像发现的原因——五个覆盖缺口的描述写的是对象本身，而不是扫描器；其中四个是我造成的。

测试

npm test                              # the whole suite; it prints how many ran
node scripts/bench.mjs 50000 200      # lookups must stay under 10 ms p50
node scripts/measure-verify.mjs       # claim extraction, against a small labelled set
node packages/guard/scripts/regression.mjs   # benign must stay silent, positives must fire

布局

packages/guard     the scanner: engine, nine checks, CLI, corpus, GitHub Action
packages/collect   census, package and repository scanning, the evidence index
packages/policy    policy evaluation and human-readable reports
packages/gateway   runtime policy enforcement for MCP servers over stdio
packages/history   index snapshots and change comparisons
packages/service   the read-only evidence API
packages/verify    cross-model claim checking
docs/              architecture and product notes

验证

测试由编写代码的同一批人编写。 docs/verification.md 记录了尚未进行的检查：通过网关连接真实 MCP 服务，以及仍未验证的事项清单。

node scripts/verify-real-server.mjs

如需确认索引中的 high 和 critical 发现是否仍与已记录的人工审查相符，请运行 node scripts/review-criticals.mjs。审查必须将发现及其证据关联到确切的软件包版本和完整的扫描内容溯源信息，包括 SHA-256 摘要和范围。关联信息缺失或发生变化时，需要再次进行人工审查；旧版批准不会自动升级。--accept 用于记录已完成的审查，并会拒绝不完整的溯源信息；它不会执行审查，也不会为第三方代码背书。

运维

• docs/operations/deployment-runbook.md — 阿里云和智量.com 域名的部署手册，包括 ICP 备案相关注意事项。
• docs/operations/plan-b-no-icp.md — 中国大陆服务器没有 ICP 备案时的应对方案。
• deploy/ — Caddyfile 和 systemd 单元文件，可直接复制到服务器。
• docs/operations/pilot-package.md — 试点项目单页说明：交付内容、时间安排、我们需要什么，以及我们不需要什么。
• site/index.html 和 site/pricing.html — 着陆页和定价页，独立完整，不依赖外部资源。
• scripts/onboard-server.sh — 将部署步骤写成脚本；脚本会打印将要执行的操作，只有使用 --apply 才会实际执行。
• scripts/smoke.mjs — 部署后的检查：确认服务可访问、索引存在且为最新，并且记录是真实记录而非示例记录。

状态

这是一个早期的开源核心。它涵盖采集、证据索引、扫描、CI 中的策略检查、通过 stdio 接入 MCP 服务的运行时网关、历史差异和只读服务。仓库中包含部署脚本和运行手册，首次部署及其检查记录在 docs/verification.md 中。该文档不代表托管服务当前的运行状况。容器路径尚未得到断言，但已构建：CI 会运行 docker compose up --build，然后对运行中的容器执行健康检查。

版本标识所承诺的内容以及支持哪些版本，已记录在 docs/spec/compatibility.md 中；SECURITY.md 说明了如何报告漏洞以及可以期待什么。这两份文档都不能替代上述第 3 和第 4 道关卡——企业级功能仍然缺失，仓库外目前也没有人依赖它。

定价方案中描述的企业功能——SSO/SAML、RBAC、多租户和签名审计导出——尚未实现。Team 和 Enterprise 价格是尚未验证的假设；我们通过免费试点来测试是否有人需要它。请参阅试点范围和许可证。

测试套件中有一项不变量：检查崩溃时绝不会产生 clean。运行 npm test 查看当前数据；本页不重复列出测试数量。

许可证

AGPL-3.0-only。如果你想将修改后的 agentgate 作为闭源服务提供，却不公开你的更改（这是 AGPL 不允许的情况），可以申请商业许可证。请参阅 docs/product/licensing.md。