前言¶

在 DSH 或智能体工作流里，常见问题不只是单个 Agent 能否完成任务，而是同一台机器上并行的 dsh、Codex、Claude Code、Hermes、OpenClaw 等本地 Agent 之间如何互发消息。dsh-agent-relay 是 Noelune 维护的一个 MIT 许可插件，提供本地多 Agent 协作中继：通过 loopback-first broker 与 HMAC 鉴权，在本地 Agent 间安全互发消息。

插件定位¶

一句话定位：dsh-agent-relay 是一个本地多 Agent 消息中继插件。

它提供本地消息中继 Broker，并把鉴权、轮询、租约、重试和持久化放在本机侧完成；同时提供 dsh Cordis 插件、CLI 客户端与 Python 客户端适配器，用于在本地 Agent 之间建立消息链路。

核心能力¶

• 提供本地消息中继 Broker，默认绑定 127.0.0.1:19121。
• 使用 HMAC-SHA256 签名鉴权，并内置时间戳重放防护、鉴权失败锁定与单 IP 速率限制。
• 支持 lease/ack 可靠投递、游标增量轮询、租约确认与幂等去重。
• 消息保留 7 天 TTL；默认使用 SQLite 持久化，Node 低版本或显式配置时回退 JSONL。
• 指数退避重试，示例为 2s/4s/8s。
• 提供 dsh Cordis 插件，注册 agent_relay_send、agent_relay_status、agent_relay_history、agent_relay_peers、agent_relay_retry 模型工具。
• 提供 CLI 客户端与 Python 客户端适配器。
• 支持 v1 兼容层，以及 v2/v3 线协议；v3 支持密钥轮换。
• README 声明零第三方运行依赖，package.json 显示 Node.js >= 20。

安装与启用¶

1、安装插件¶

官方安装命令如下：

dsh plugin --profile web add dsh-agent-relay

该命令将插件挂载到 web profile。

2、让 DSH 读取部署指南¶

安装后，可让 DSH 读取 docs/AGENT-DEPLOY.md，自动生成 HMAC 密钥、启动 Broker、装配 dsh、Codex、Claude Code、Python 客户端凭据，并执行 selfcheck。

典型用法¶

手动 CLI 验证¶

先克隆仓库，初始化并启动本地服务：

git clone https://github.com/Noelune/dsh-agent-relay.git && cd dsh-agent-relay
node setup/setup.js init
node setup/setup.js start

然后注册 Agent，并发送/接收消息：

node adapters/cli/relay.mjs register --agent alpha --secret $DSH_RELAY_SECRET
node adapters/cli/relay.mjs send beta "hello from alpha" --agent alpha --secret $DSH_RELAY_SECRET
node adapters/cli/relay.mjs recv --agent beta --secret $DSH_RELAY_SECRET

这里 $DSH_RELAY_SECRET 用于 HMAC 签名。send 命令把消息发往 beta，recv 命令用于在 beta 侧接收消息。

协议与请求头¶

v1 客户端请求头使用：

X-Relay-Agent
X-Relay-Timestamp
X-Relay-Signature

v2/v3 客户端请求头使用：

X-Agent-Relay-Agent
X-Agent-Relay-Timestamp
X-Agent-Relay-Signature

v3 可增加：

X-Agent-Relay-Key-Id

v1/v2/v3 协议格式不应混用；代际协议细节以 docs/PROTOCOL.md 与 docs/PROTOCOL-V2.md 为准。

适用场景与注意¶

适合需要在同一台宿主机上让多个本地 Agent 互发消息的 DSH 用户和智能体开发者。它适合用于本机 Agent 协作链路，而不是依赖外部消息服务完成本地消息路由。

使用前需要特别注意：

• 该插件在 dsh 进程中运行，会沿用当前 dsh 进程的权限。安装前应检查源码与许可证。
• 许可证为 MIT，README 声明允许商业化使用。
• 默认 Loopback 本地模式，README 警告切勿将未加密的明文 Broker 暴露在公网环境。
• 接收到的消息体应视为未校验数据输入，不应直接作为高权限指令执行。
• 运行要求为 Node.js >= 20；SQLite 默认持久化使用 Node 内置 node:sqlite，README 注明需 Node >= 22.5，22.13+/23.4+ 起无需 flag；Node 低版本或显式配置时回退 JSONL。
• Python 客户端适配器可选，需要 Python >= 3.10。
• README 标注基于 dsh 0.1.0-rc.6 进行测试与兼容性验证。
• package.json 的 peerDependencies 包含 @deepseek-ai/cordis ^4.0.1 与 @deepseek-ai/dsh-tools ^0.1.0-rc.6。

结尾¶

dsh-agent-relay 提供了一条可在本机运行的多 Agent 消息链路：默认 loopback 绑定、HMAC 鉴权、lease/ack 投递、轮询、重试和本地持久化。

• GitHub: https://github.com/Noelune/dsh-agent-relay
• 目录页（插件线索，请以目录站点实际展示为准）: https://www.skillhub.cn/plugins/Noelune/dsh-agent-relay