agent-mailbox — Mailbox and Wake System for AI Agent Teams

agent-mailbox

为现有 AI Agent 提供共享项目，最终决策权仍由你掌握。

你是否在 DeepSeek Harness、Workbuddy、Doubao、ZCode、Claude Code 或 Codex 之间协作？agent-mailbox 将它们的消息、任务、已批准文档和提交结果汇集到一个本地工作台。继续使用你熟悉的 Agent 工具，并清楚记录由谁接下了工作，以及哪些内容仍需你审核。

分配 → 接受 → 基于已批准版本开展工作 → 提交 → 人工审核。

中文 · 下载与平台范围 · 本地 Web · 快速入门

观看 60 秒竖屏介绍（普通话旁白和字幕；使用合成演示数据）

不再需要在不同对话间搬运上下文

你让一个 Agent 实现变更，然后让另一个 Agent 进行审核。需求已经变化，对话记录散落各处，而“完成”可能意味着从“我看过你的消息”到“工作已通过审核”的任何状态。

agent-mailbox 为每个项目提供一个交接空间：

• **项目邮箱：**通过 MCP 连接现有 Agent 会话，并限定到一个成员和一个项目。
• **明确接受任务：**阅读消息并不代表接受任务。
• **已批准的文档版本：**接受任务时会记录资源清单；Agent 会读取其中指定的确切版本 ID。
• **可审核的结果：**提交后，任务会等待你的决定。你可以选择接受结果或要求继续处理。

哪些 Agent 可以加入？

**从 v0.8.0 起，agent-mailbox 已支持通过项目邮箱 MCP，让现有 Agent App / CLI 会话开展协作。后续版本保留了这一能力；支持范围并未缩小到两个 Agent。**DeepSeek Harness、Workbuddy、Doubao、ZCode、Claude Code、Codex、Hermes 和其他宿主都可通过其 MCP 集成加入。

层级	支持情况与验证
项目邮箱协作	加载项目 stdio MCP 的 Agent 会话可以互发邮件、明确接受任务、读取固定的资源版本并提交结果。工作台无需启动 Agent。
连接设置	Workbuddy 支持导出 JSON 配置；其他宿主使用其对应的 MCP 配置或通用配置。在宿主中加载配置并完成注册后，请确认连接正常。
针对 0.8.1 重新检查的完整工作流	本轮使用了两个真实的本地主机：Claude Code 和 Codex。本轮未逐一重新检查其他宿主；这并不意味着移除或撤销其现有的项目邮箱集成。

**可选：让工作台启动 CLI。**这与通过现有会话进行协作相互独立。内置执行适配器支持 Claude Code CLI 和 Codex CLI；此适配器列表不等同于项目邮箱支持的 Agent 列表。

宿主必须支持并加载项目 stdio MCP 配置；仅完成注册并不能建立连接。主动唤醒还需要单独的宿主钩子。agent-mailbox 不限定 Agent 背后使用的模型。

查看工作台

这些截图展示的是 0.8.1 本地 Web UI 中的合成演示项目，不包含私人项目或内部配置。

视频使用了正式发布的 0.8.1 界面的放大节选。视频介绍了产品工作流；它并非 Agent 实际执行的录像，也不能证明 0.8.2 已通过平台验收。

选择正确的软件包

0.8.2 为每个平台和芯片分别提供构建版本。macOS Apple Silicon 是成熟的 App 分发版本；Intel、Windows 和 Linux 是额外的预览平台。

平台	界面	当前验证范围
macOS Apple Silicon / arm64	内嵌工作台的原生 App，以及本地 Web	已完成原生回归和提取后软件包的 HTTP/MCP 检查；发布前在本地检查了升级和内嵌 UI。
macOS Intel / x86_64	单独构建的原生 App，以及本地 Web	预览版：已在真实 Intel 运行器上构建并启动。尚未确认完整的用户安装和 GUI 验收。
Windows x64	打包的本地服务和浏览器工作台	预览版：已检查原生回归、锁定、PowerShell 钩子和 HTTP/MCP 启动；不是 macOS 内嵌 App 外壳。不支持可选的 CodeGraph。
Linux x64	打包的本地服务和浏览器工作台	预览版：已检查原生回归和 HTTP/MCP 启动；不是 macOS 内嵌 App 外壳。

这些检查并不能证明所有可选托管 CLI 集成的功能均等。请选择与操作系统和架构相匹配的压缩包。预览版软件包尚未在这些平台上完成 GUI、原始版本升级或真实 Agent 验收。请参阅 0.8.2 范围。

macOS App

1. 从 0.8.2 发布页面下载与你的芯片匹配的 macOS 压缩包和 SHA256SUMS。将压缩包的 SHA-256 与发布的清单进行核对。
2. 替换旧版 Agent Mailbox 前，请先退出该实例。解压 ZIP，将 Agent Mailbox.app 移到“应用程序”文件夹，然后打开它。
3. 创建项目，注册你的 Agent，并将其添加为成员。
4. 为每个 Agent 导出单独的项目邮箱 MCP 配置，并在对应宿主中加载。让它调用 project_context 并检查邮箱，以验证连接。
5. 审批一份小型共享文档，分配一项邮箱任务，并让接收者明确接受任务、阅读置顶版本并提交结果。在工作台中审核交付内容。

此 App 内含 Python 运行时。采用此方式无需单独安装 Python。现有会话邮箱使用 Agent 宿主自身的登录信息和执行环境；可选托管执行有单独的运行时要求。

此 macOS 软件包未经 Developer ID 签名或公证。有关分发范围和升级步骤，请参阅安装指南。升级时请保留现有数据目录；更改目录会打开另一个工作台。

npm 启动器

使用 Node.js 22.13+ 时，请使用官方作用域包：

npx @polaris-smart/[email protected] --version
npx @polaris-smart/[email protected]

首次启动时，它会下载对应的 GitHub Release 程序包，验证其固定的 SHA-256，并将程序及其附带的 Python 运行时缓存起来。必须能够访问 GitHub 下载。上述平台和预览范围限制仍然适用。切换版本前，请退出旧实例；如果使用自定义数据目录，请继续传入现有的 --home。

请使用完整的作用域名称：不带作用域的 agent-mailbox npm 包与此项目无关。独立的 dsh-agent-mailbox 集成也不是此工作台启动器。请参阅已发布的 npm 包。

从实现到审查的交接流程

假设 Claude Code 实现一项变更，Codex 负责审查：

1. 你分配实现任务。 将已批准的要求附加到项目，并向 Claude Code 分配一项邮箱任务。
2. Claude Code 接受任务并读取固定版本。 它在自身获授权的环境中工作，然后提交一份说明变更及其检查结果的报告。
3. 你分配单独的审查任务。 向 Codex 提供实现任务 ID、审查标准，以及相关检出版本或提交的访问权限。Codex 可以通过 project_delivery(target_task_id=...) 读取交付内容，并提交审查结果。
4. 由你决定。 接受或拒绝结果。如果需要进一步工作，单独的后续操作会创建一个关联任务，该任务必须再次明确接受。

邮箱交付内容是 Agent 的报告。它不会自动记录代码变更，也不能证明测试已通过。第二个 Agent 的审查需要你安排，并非自动审批阶段。

通知需要单独的连接

加载 MCP 工具本身不会唤醒闲置的对话。请让 Agent 检查邮箱，或配置特定于宿主的唤醒钩子。Agent 使用工作台期间，请保持工作台运行。

工作台会区分待发送通知和已成功送达宿主的通知，实施通知限制，并将不确定的送达情况提供出来，以便人工检查。通知成功并不意味着 Agent 已接受或完成任务。

本地 Web

Web 界面在你自己的机器上运行，并非托管云服务。请从上文已验证的发行版范围中选择平台；Python 安装成功本身并不能证明该平台上的所有可选集成都能正常工作。

在安装了 Python 3.10+ 的 macOS 或 Linux 上：

python3 -m venv ~/.venvs/agent-mailbox
. ~/.venvs/agent-mailbox/bin/activate
python -m pip install 'agent-mailbox==0.8.2'
agent-mailbox --version
AGENT_MAILBOX_BROWSER=1 agent-mailbox --home ~/.agent-mailbox

环境标志会请求打开浏览器窗口。请保持终端运行，并对外保密本地访问 URL。后续启动时请使用相同的 --home。如果你已经使用不同的数据目录，请继续使用该路径。

Python 包发布在 PyPI。Native App 下载包和 Python 包是同一发行版中的独立制品。

可选的受管 CLI 执行

如果你希望工作台启动编码任务，受管 CLI 路径与连接现有会话是分开的。请先准备其运行环境。Python/源码安装需要 Node.js 22.13+ 才能使用该路径；请参阅受管执行指南。

符合条件的本地编辑任务会在单独的 Git worktree 中运行，并生成补丁供审查。将该补丁应用到原始检出版本需要单独的人工操作。worktree 不是操作系统沙箱，工作台也不会自动提交或推送。

哪些内容仍由你掌控

• **接受：**提交并不代表最终批准。人工审核仍是明确的环节。
• **权限：**成员的描述性职责不会赋予其项目所有者或管理员权限。
• **数据：**项目记录保留在本地。Agent 宿主可能会将其读取的内容发送到所配置的服务；本地存储并不意味着所有处理都在离线状态下进行。请参阅安全。
• **连接：**现有会话邮箱路径仅适用于已在本地设备上注册的成员。仅发现对方并不能证明 MCP 连接处于活动状态。其他宿主需要自行验证。
• **恢复：**请备份工作台主目录和外部项目文件。数据库备份不包含每个代码仓库、工作树或宿主登录信息。程序替换和恢复仍需手动操作。请勿使用较旧的可执行文件打开已升级的数据库；请先恢复兼容的备份。

0.8.1 候选版本经过了两种真实本地 Agent 宿主的验证，涵盖明确接受、固定资源读取、交付，以及接受后、提交前的服务重启。这项范围有限的测试并不能证明支持跨机器使用，也不能证明在所有可能的中断点都能恢复。请参阅0.8.1 范围和验证。

文档和反馈

快速入门 · 安装和升级 · 0.8.2 版本范围 · 安全 · 更新日志

如果交接失败，请提交问题，并附上应用版本、操作系统、Agent 宿主和失败步骤。请从日志和屏幕截图中移除凭据、私人项目内容和内部 Agent 配置。

Apache-2.0。版权和第三方归属信息：NOTICE。