前言¶

在 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