运行时身份校验 fantasyce/agent-runtime-proof

Agent Runtime Proof

证明你启动的 agent 运行时就是你批准的产物。

Agent Runtime Proof (ARP) 是一个本地、只读的运行时身份验证器，适用于 AI agents 和 MCP servers。它能够检测陈旧、被替换、不匹配或无法验证的运行时，而无需上传代码、密钥、进程参数或进程数据。

ARP 所针对的故障很简单：你替换了 Agent 或 MCP 可执行文件，但昨天的进程仍在继续工作。磁盘上的文件是新的；已加载的运行时却不是。ARP 将实时进程身份绑定到明确的产物预期，并报告不确定性，而不是把磁盘上的文件当作正在运行内容的证据。

参见可复现的陈旧运行时演示，或从五分钟快速入门开始。

快速入门

当前版本是 v1.1.0，适用于 macOS arm64、Linux amd64 和 Windows amd64。从该 release 下载压缩包和 SHA256SUMS，验证字节，然后将单个二进制文件安装到用户拥有的目录中。各平台的完整命令见 docs/quickstart.md；生命周期和回滚细节见 docs/install.md。

安装后：

agent-runtime-proof --version
agent-runtime-proof doctor --format json
agent-runtime-proof inspect --all --limit 20

根据明确的预期验证进程：

agent-runtime-proof verify \
--expectation /absolute/path/to/expectation.json \
--pid 1234 \
--format json

只有当证据支持该结论时，ARP 才会返回 MATCHED。
UNKNOWN、STALE、LEAKED、CONFLICT 和 NOT_RUNNING 是领域判定，而不是传输错误。

本地 stdio MCP

ARP 可以作为本地 MCP server 运行：

{
"mcpServers": {
"agent-runtime-proof": {
"command": "/absolute/path/to/agent-runtime-proof",
"args": ["mcp"]
}
}
}

它恰好暴露三个只读工具：

- list_local_runtime_candidates
- inspect_local_runtimes
- verify_local_runtime

提供适用于 Codex、Claude Code、Cursor、OpenCode、DeepSeek Harness、VS Code/GitHub Copilot 以及通用主机的宿主配置。参见宿主配置指南。ARP 不会编辑宿主的配置。

v1.1.0 Release 还包含 agent-runtime-proof_1.1.0.mcpb，适用于兼容的 MCP 客户端。其 Registry 元数据将 bundle URL 绑定到其 SHA-256 摘要；同样的三个原生二进制文件仍作为普通平台压缩包提供。

同一 release 也发布在官方 MCP Registry 中，名称为 io.github.fantasyce/agent-runtime-proof。

ARP 证明了什么

这些控制手段回答不同的问题，并且最好配合使用：

| 证据 | 它回答的问题 |
| SBOM | 此构建中声明了哪些依赖项？ |
| 签名或构建证明 | 谁生成了这些产物字节，通过哪次构建？ |
| 校验和 | 下载的字节是否发生了变化？ |
| Agent 运行时证明 | 正在运行的本地进程是否与我批准的产物预期绑定？ |

ARP 不替代签名、来源追溯、SBOM、沙箱或主机策略。它弥合了已批准文件与实际执行工作的进程之间的缺口。

隐私与安全边界

ARP 有意保持范围狭窄：

- 仅限本地进程和本地文件；
- CLI、本地 stdio MCP，以及可选的启动 Witness；
- 对 Agent 和主机状态进行只读观察；
- 无守护进程、网络监听器、修复操作或配置写入；
- 不依赖 Across Agents Assistant、Across Context、Across Orchestrator 或 Across Autopilot。

MCP 响应会省略原始 argv、环境变量值、命令行、文件内容、凭据和会话记录。请在 docs/data-handling.md、docs/privacy-model.md 和 docs/threat-model.md 中阅读确切的保证和限制。

CLI 与 Witness

检查单个进程或有界的当前用户清单：

agent-runtime-proof inspect --pid 1234 --format json
agent-runtime-proof inspect --all --limit 100

通过字节透明的启动 Witness 运行本地命令：

agent-runtime-proof witness --expectation expectation.json -- command arg

Witness 记录进程身份和内容寻址的启动回执，然后代理 stdin/stdout，不重写协议字节。拥有进程创建权的主机可以通过 sdk/witness 嵌入相同的契约。

退出码：检查、doctor 或 MATCHED 为 0；确定的否定判定为 2；UNKNOWN 为 3；无效输入为 64；内部故障为 70。JSON 模式向 stdout 写入一个 JSON 值；经过净化的诊断信息使用 stderr。

支持的平台与限制

发布归档为 macOS 14+ arm64、Linux amd64 和 Windows 11 amd64 构建。当无法观察到活动入口点时，对解释器和声明树运行时的被动检查仍保持保守。仅凭磁盘上的摘要绝不会被报告为已加载运行时的匹配。

远程证明、守护进程、网络监听器、修复操作和 Agent 配置写入不在 v1 范围内。

架构与验收

相同的契约和应用层驱动 CLI、MCP 服务器、Witness 和纯数据 Host Profiles。技术设计记录在 architecture-development-acceptance.md 中。

验收记录：

- Phase 0 契约
- Phase 1 macOS 核心
- Phase 1 Windows 核心
- Phase 2 MCP
- Phase 3 Witness
- Phase 4 主机矩阵
- Phase 5 开源发布维护者可以使用以下命令运行完整的源码门禁：

bash scripts/check.sh

发布资产包括 CycloneDX SBOM、SHA-256 校验和以及 GitHub 工件证明。发布状态由公开的 GitHub Release 决定，而不是由本地验收记录决定。

Agent 可靠性工具包

ARP 是一个小型、本地优先的可靠性工具包中的一个独立部分：

- Agent Recall Trail 将私有 Agent 记忆与经过审查的共享知识分开保存。
- Agent Runtime Proof 验证运行中的 Agent 或 MCP 运行时是否与你批准的工件一致。
- Agent Residue Evidence 记录测试和构建留下的任务范围内的文件、进程和监听端口。

每个项目均可单独安装，并保持各自的信任边界。

社区

欢迎贡献以及独立的主机/运行时案例。对于经过脱敏处理的 Codex 或 DSH 集成，请在设计合作伙伴 issue中分享主机、版本、启动关系和观察到的证明边界。
DSH 用户还可以加入官方社区讨论。
请阅读 CONTRIBUTING.md、CODE_OF_CONDUCT.md 和 SUPPORT.md。按照 SECURITY.md 中所述私下报告漏洞；不要将机密或敏感进程数据放入公开 issue。

采用 Apache-2.0 许可。参见 LICENSE。