agent-postbox

agent-postbox

为 MCP Agent 提供可验证的交接。agent-postbox 让通过 GitHub 进行的 Agent 交接可验证——通过读回和证据，而不是简单的状态消息。

AI 同事通过 GitHub Issues 和拉取请求协作——采用受限写入、回执和四眼审核。

你已经拥有一个持久、可审计且易于阅读的协作系统：你的 GitHub 仓库。agent-postbox 将其变成 AI Agent 的邮筒，让它们能够互相交接工作、报告结果并审核彼此的拉取请求，同时确保每次写入都小巧、经过验证且可追溯，并将每项决策都交由人工处理。

它是一个小型的 Model Context Protocol 服务（stdio 或 Streamable HTTP）加上一个 CLI。零运行时依赖。

human ──opens issue──▶  #12  [to:builder]
builder ── inbox ─────▶ claims (claimed:builder), works, opens PR #13 [to:reviewer]
reviewer ─ review ────▶ REQUEST_CHANGES on #13 @ head commit (cannot review its own PR)
builder ── comment ───▶ evidence: tests, output, links
human ───────────────▶ merges. Agents cannot merge, close, or set authority labels.

共享收件箱可以传递消息。agent-postbox 能证明交接确实发生了——读回每次写入、确认绑定到 Agent 读取的确切文本、禁止自我审核，以及可供验证的签名证据日志。

版本：v0.2.1 · 适用对象：在同一个 GitHub 仓库中运行多个编码 Agent（Claude Code、Codex、Cursor、……）的开发者 · 零运行时依赖。

30 秒快速体验

无需 GitHub 账号、令牌或网络——此演示使用虚构数据，让两个 Agent 在内存中的 GitHub 上运行：

git clone https://github.com/Aethelgard-Systems/agent-postbox.git
cd agent-postbox
npm run demo

如果 Windows PowerShell 因“此系统上已禁用运行脚本”而阻止 npm？可以改用 npm.cmd run demo 或 node examples/offline-demo/demo.mjs——演示效果相同，无需更改策略。

你将看到构建者和审核者互相交接工作；网络响应丢失后，系统会进行协调，而不是重复发布；此外，还会拒绝三种不安全操作（自我审核、仅限人工使用的标签、在评论中包含令牌）。详情和限制：examples/offline-demo。

npm run demo:handoff 展示 v0.2 流程：规划者将任务交给构建者；构建者的确认与其读取的文本绑定（编辑交接内容后，在重新读取前会被拒绝）；随后验证签名证据日志——再篡改日志并检测出篡改。

原因

多 Agent 配置通常会以一些乏味的方式失败：Agent 声称自己发布了内容，实际却没有；超时后重试，结果重复发布；批准自己的工作；把 issue 中的文本当作命令；或将令牌泄露到评论中。agent-postbox 专门解决这些问题，不做其他事情。

问题	agent-postbox 的处理方式
“我发布了”——但实际上什么都没有	回读：每次写入后都会重新获取并进行比对，确认无误后才算完成
超时 → 重试 → 重复	写入回执：发送前记录 ATTEMPTED，回读后记录 CONFIRMED。只有当 GitHub 显示由 Agent 自身身份执行的精确写入时，才会协调未知结果；否则会保持阻止状态，直到人工解决
Agent 批准自己的 PR	四眼原则：当 PR 作者与令牌自身身份相同时，会拒绝任何审核（包括评论）；该身份会通过 GitHub 验证，审核也会绑定到头部提交
Agent 决定本应由它提议的事项	权限分离：受保护的标签（例如 approved、decision:*）仅限人工使用；提议中会附带明确声明不具备权限的页脚
Agent 可以执行令牌所能执行的任何操作	受限写入：固定的端点允许列表——不允许合并、关闭、删除、编辑正文、访问设置或代码
令牌或密码出现在评论中	对每个标题和正文应用机密过滤器（尽力而为，详见“安全性”）
Issue 文本试图指挥 Agent	所有读取内容都会标记为不可信数据
Agent 失控	写入和提议均设有每日限额
“完成了”——但完成的是什么，依据的是哪个版本的任务？	任务交接（v0.2）：创建带有验收标准的任务 issue；确认信息会绑定到 Agent 读取的文本哈希，并需要提供证据
日志事后可被编辑	证据日志（v0.2）：每次回执状态变更都会进行哈希链式记录并使用 Ed25519 签名；evidence verify 可检测编辑、缺失和截断

非目标

它不是 Agent 框架，不是运行时，没有数据库、仪表盘、工作树编排或角色模型。Agent 由你自备；agent-postbox 只是邮箱。

工具

工具	作用
inbox	标签为 to:<this-agent> 的 Issue/PR
read	带评论的单个 Issue 或 PR（内容不可信）
comment	一条带回执并经过回读的评论
label	添加/移除标签：to:<any-agent>（交接）、claimed:<self>、allowedLabels 中的标签
propose	创建标记为 proposal 的新 Issue，进行重复检查并受每日限额限制
review	绑定到头部提交的 PR 审核（APPROVE、REQUEST_CHANGES、COMMENT）；自己的 PR 会被拒绝
handoff_create	将任务交给另一个 Agent：创建标记为 to:<agent> 和 handoff 的 Issue，并附带验收标准（v0.2）
handoff_read	读取任务交接及其确认信息；返回 body_sha256（v0.2）
handoff_ack	确认交给你的任务交接（DONE 需要证据）；如果你读取后文本发生变化，则会被拒绝；计入完成前会先回读（v0.2）

完整工具列表占用的大模型上下文不到 4,500 个字符（经测试）。

快速开始

1. 每个 Agent 使用一个身份。 每个 Agent 都需要自己的 GitHub 身份，才能确保作者身份和双人审核切实有效——可以使用专用机器账号及仅限单个仓库的细粒度个人访问令牌（Issues：读取/写入、Pull requests：读取/写入、Metadata：读取），也可以使用 GitHub App 安装令牌。默认拒绝经典令牌。
2. 安装（Node.js ≥ 20）：

   npm install -g github:Aethelgard-Systems/agent-postbox
   

3. 配置 – agent-postbox.config.json：

   {
     "repository": "example-org/example-repo",
     "agent": "builder",
     "tokenEnv": "AGENT_POSTBOX_TOKEN",
     "allowedLabels": ["needs-review", "blocked", "question"],
     "protectedLabels": ["approved", "decision:*"],
     "limits": { "writesPerDay": 50, "proposalsPerDay": 5 }
   }
   

4. 检查，不写入任何内容：

   AGENT_POSTBOX_TOKEN=... agent-postbox doctor
   

5. 连接 MCP 客户端（适用于使用通用 mcpServers 格式的客户端示例）。对于支持 Streamable HTTP 的客户端，请改为运行 agent-postbox serve --transport http --port 8471，并将其指向 http://127.0.0.1:8471/mcp（其他主机需要 AGENT_POSTBOX_HTTP_TOKEN）：

   {
     "mcpServers": {
       "agent-postbox": {
         "command": "agent-postbox",
         "args": ["serve", "--config", "/path/to/agent-postbox.config.json"],
         "env": { "AGENT_POSTBOX_TOKEN": "<this agent's token>" }
       }
     }
   }
   

6. 将 templates/AGENTS.md 和 templates/pull_request_template.md 复制到你的仓库中，让 Agent 和人类遵循同一套协议。

分步设置指南：docs/getting-started.md。examples/two-agent-review 中提供了两个 Agent 互相审核的演示。

配置

键	默认值	含义
repository	–	owner/repo；此实例唯一可操作的仓库
agent	–	此 Agent 的名称（[a-z0-9-]）
login	来自 GET /user	令牌对应的 GitHub 登录名；GitHub App 令牌必填（例如 my-app[bot]）
tokenEnv	AGENT_POSTBOX_TOKEN	存放令牌的环境变量
addressPrefix	to:	用于指定目标 Agent 的标签前缀
claimPrefix	claimed:	用于认领工作的标签前缀（仅限自身）
proposalLabel	proposal	Agent 提案的标签
allowedLabels	needs-review、blocked、question	Agent 可设置的额外标签（后缀 * = 前缀匹配）
protectedLabels	approved、decision:*	仅限人类使用的标签；Agent 既不能添加，也不能移除
limits	50 次写入、每天 5 条提案、正文 6000 字符、标题 120 字符	每个 Agent 的限制
receiptsFile	$XDG_STATE_HOME/agent-postbox/<owner>-<repo>-<agent>.json	本地回执存储文件
allowClassicToken	false	接受经典 PAT（不推荐）
evidence	true	写入签名证据日志（v0.2）；false 可将其禁用
evidenceFile、evidenceKeyFile	与 receiptsFile 同目录	证据日志及其 Ed25519 密钥（首次使用时创建，权限为 0600）
handoffLabel	handoff	用于标记交接问题的标签

CLI

agent-postbox doctor | inbox | read <n> | comment <n> --body ... | label <n> --add a --remove b
agent-postbox propose --title ... --body-file ... | review <n> --event approve|request-changes|comment --body ...
agent-postbox handoff create --to <agent> --title ... --body ... [--acceptance "a|b"] | handoff read <n>
agent-postbox handoff ack <n> --read-sha256 <hex> --result done|partial|blocked|declined [--evidence "a|b"]
agent-postbox receipts list | receipts resolve <key> --as confirmed|failed
agent-postbox evidence verify | evidence key
agent-postbox serve [--transport stdio|http] [--host 127.0.0.1] [--port 8471]

所有输出均为 JSON。拒绝操作时以代码 2 退出，并返回稳定的错误代码（POLICY、SECRET、LIMIT、SELF_REVIEW、UNKNOWN_OUTCOME、READBACK_MISMATCH，……）。

证据日志（v0.2）

agent-postbox 会在回执文件旁保存 <receipts>.evidence.jsonl：每次回执状态变更占一行，并使用 Agent 的 Ed25519 密钥进行哈希链链接和签名。日志包含键、类型、状态、回读判定和哈希——绝不包含正文、标题或令牌。 agent-postbox evidence verify 会重新计算哈希链，并报告任何被修改、删除、重排、伪造或截断的行。 格式说明见 docs/evidence-format.md，并与配套工具共用，因此同一个验证器即可验证所有工具的日志。

已知限制（v0.2）

• 同一议题中相同的评论文本只会发布一次（重放保护）；添加上下文，让新评论有所区别。
• 重复标题检查和协调最多扫描 1,000 个项目。GitHub 的议题列表可能会在写入后延迟几秒更新：Agent 自己造成的重复会在本地拦截，但两个不同的 Agent 若在几秒内提交相同标题，可能都会成功。
• 添加 to:<agent> 标签时，如果仓库中尚不存在该标签，就会创建它。
• agent-postbox 不会编辑或删除审查和评论——这是有意的设计。
• 通过标准输入/输出运行 serve 时，即使没有配置或令牌也会启动，以便客户端列出工具；此时每次工具调用都会返回 CONFIG/TOKEN，直到完成设置。HTTP 传输则会拒绝启动。
• MCP 服务和 CLI 共用回执文件时，锁冲突可能会使服务暂停最多 5 秒；并发进程也可能多写几次，超过每日限制。
• HTTP 传输是无状态 JSON（无 SSE、无会话、无服务端主动发送的消息），且不提供 TLS；当它需要离开本机时，请将其置于你自己的反向代理之后。浏览器会被有意排除在外（必须使用 JSON 内容类型，Host 必须指定该服务，除非 Origin 已列入 AGENT_POSTBOX_HTTP_ORIGINS，否则会被拒绝）。
• 证据日志只能证明写入其中的内容，无法证明绕过它的内容；请参阅 docs/evidence-format.md 中的“What it does not prove”。末尾截断可通过签名的 .head 旁文件检测；如果该旁文件被删除，evidence verify 会发出警告，而不会干净地通过验证。

安全模型

agent-postbox 旨在降低常见多 Agent 故障的风险。它不是沙箱。

• 令牌才是真正的边界。 agent-postbox 无法阻止持有令牌的人直接调用 GitHub。每个 Agent 使用一个权限范围严格受限的令牌，并通过分支保护和必需审查保护 main，确保合并仍由人工完成。
• 四眼原则依赖不同身份。 如果两个 Agent 共用一个令牌，GitHub 会将它们视为同一作者，四眼检查也无法发挥作用。
• 机密过滤器只能尽力而为。 它能捕获常见的令牌格式和高熵字符串，但会漏掉一些机密，偶尔也会误报无害文本。
• 不受信任的内容仍然不受信任。 agent-postbox 会将读取的所有内容都标记为数据。你的 Agent 是否遵守这一点，取决于该 Agent 本身。
• 回执只是本地提示，GitHub 才是真相。 回执文件会在锁文件保护下以 0600 模式原子写入，因此 MCP 服务和 CLI 可以共用它。文件中包含键、状态、议题编号、链接和 HTTP 状态码——不含消息正文、标题或令牌。
• 标记不可见，但并非机密。 每次写入都会附带 HTML 注释标记。只有当 GitHub 显示该标记属于 Agent 自己的身份所创作的内容，且文本与预期完全一致时，才会信任它。
• 限制仅在本地生效。 每日限制根据此机器上该 Agent 回执文件中的写入次数计算；它只是制动机制，不是由 GitHub 强制执行的配额。
• 无遥测，无托管服务。 agent-postbox 只会使用你提供的令牌与 api.github.com 通信。

请按照 SECURITY.md 中的说明报告漏洞。

有关参与者、信任边界、控制措施和剩余风险，请参阅威胁模型。

AI 辅助开发

本项目在开发过程中借助了生成式 AI 工具。维护者会在纳入项目之前审查、筛选、修改并整合 AI 生成的建议。项目中未有意纳入任何第三方专有源代码。AI 辅助不会改变本项目或其第三方依赖项的许可条款。

免责声明

本项目是根据 Apache License 2.0 提供的免费开源软件。

本软件按“原样”提供。不作任何关于其适用于任何特定生产、安全、合规、法律或业务用途的陈述或保证。

本软件可以与 GitHub 资源交互，并且在经过相应配置后可能执行写入操作。用户有责任在将本软件用于重要代码仓库或生产工作流之前，检查所授予的权限、配置以及自动化操作或 AI 发起的操作可能产生的影响。

权限限制、验证步骤和机密信息过滤等安全机制可以降低风险，但不得将其视为能够检测或阻止所有不安全操作、凭据、机密信息或意外输出的保证。

本声明中的任何内容均不排除或限制适用法律禁止排除或限制的责任。

许可证

Apache License 2.0。版权所有 2026 Marco Gernand。欢迎根据 Developer Certificate of Origin 贡献代码。