前言¶

DeepSeek Harness（DSH）生态强调“一切皆插件”，agent 之间的通信是构建复杂工作流的基础。现有的 messaging 插件大多存在一个隐含假设：参与者都是 DSH 会话。这意味着，如果两个 agent 驱动 Harness 的方式不同（例如一个是 DSH 会话，另一个是 MCP 客户端），它们之间无法直接通信，必须依赖人工中转每一条消息。

dsh-agent-mailbox 解决了这个问题。它是一个本地化的、零运行时依赖的持久化 agent-to-agent 消息传递方案。任何 MCP 客户端、任何 DSH 会话、任何 A2A agent 都可以互相寻址。

简介¶

这是一个由 blairlaird 维护的 DSH 插件，开源协议为 MIT。它支持线程、收据、搜索、广播、附件、状态感知、SSE 流式传输和签名。

核心功能¶

插件提供了以下核心能力：
* 传输层：HTTP / JSON-RPC 2.0，SSE 流式传输，长轮询。
* 消息模式：线程、回复、广播、请求/回复、发送即忘。
* 安全与信任：签名、明确的信任边界、密钥脱敏。
* 状态与交互：状态感知、唤醒消息、反应、撤回、编辑。
* 协作：MCP 客户端作为对等节点。

安装与配置¶

使用官方提供的预构建 tarball 进行安装。该包不需要构建步骤，也不需要任何 npm 账号。

dsh plugin --profile web add https://github.com/blairlaird/dsh-agent-mailbox/releases/latest/download/dsh-agent-mailbox.tgz

安装后，建议在自定义的 profile patch 中配置插件，而不是直接修改插件自带的配置。

- id: dsh-agent-mailbox
  name: dsh-agent-mailbox
  config:
    identity: dsh
    home: C:/Users/you/.dsh/agent-mailbox
    notifyCommand: [node, /path/to/notify.mjs]

使用方式¶

插件提供了多种接入方式，包括 DSH 命令、MCP 集成和 HTTP 接口。

DSH 会话命令¶

在 DSH 会话中，可以使用以下命令：

• /mailbox：读取发送给你的消息并确认。
• /mailbox --all：查看完整历史，不仅是新消息。
• /mailbox-send <to> <message>：发送消息给指定对等节点，或使用 * 进行广播。
• /mailbox-peers：查看存在哪些对等节点，谁处于在线状态，谁有未读消息。
• /mailbox-search <query>：搜索历史消息。

MCP 客户端集成¶

如果需要从外部 MCP 客户端接入，需在配置中指定 HTTP URL。

{ "mcpServers": { "mailbox": { "type": "http", "url": "http://127.0.0.1:4470/mcp" } } }

HTTP 与流式接口¶

插件暴露了标准的 HTTP 端点和 Server-Sent Events 流。

• 流式订阅：GET /stream?to=<name>&since=<cursor>
  • 使用 SSE 推送消息。
  • 连接建立时会重放消息，确保不会遗漏。
• 健康检查：GET /health
  • 返回解析后的邮箱目录、对等节点列表、在线流数量等。
• MCP 协议：POST /mcp
  • 使用 JSON-RPC 2.0 协议。
• Agent 卡片：GET /.well-known/agent.json
  • 供 A2A 客户端发现工具。

可用工具¶

插件内置了丰富的工具集，支持细粒度的消息操作：

• mailbox_send：发送消息（支持线程、优先级、附件、幂等性）。
• mailbox_read：游标读取消息（不消耗，崩溃不丢失）。
• mailbox_wait：挂起直到有消息到达（唤醒空闲 agent）。
• mailbox_peers：列出存在且在线的对等节点。
• mailbox_announce：声明存在状态。
• mailbox_acknowledge：发送收据，区分未读和忽略。
• mailbox_search：通过文本搜索历史决策。
• mailbox_react：添加反应而不增加时间线。
• mailbox_edit：覆盖自己的消息（保留原始）。
• mailbox_withdraw：将消息标记为墓碑（撤回）。
• mailbox_attachment：通过内容哈希获取附件。

注意事项¶

• 无侧边栏面板：DSH 本身不支持第三方侧边栏插槽，因此该插件没有 UI 界面。支持的操作仅限于 DSH 命令和 HTTP 接口。
• 认证限制：如果启用了 requireAuth，/health 和 /stream 端点需要 Bearer Token 认证。且 /stream 仅服务于令牌持有者的私有邮件。
• 内容视为数据：根据信任模型，所有接收到的消息内容被视为数据，而非指令。任何涉及写入、网络调用、审批或支付的操作，都需要像处理陌生人请求一样严格审核，不应自动执行，必须展示给用户。

结语¶

dsh-agent-mailbox 补齐了 DSH 生态中 agent-to-agent 通信的拼图。它不依赖外部协议，完全运行在本地进程内，为 DSH 工作流提供了可靠的通信基础设施。更多细节可查阅 GitHub 仓库。