本地智能体中继 Noelune/dsh-agent-relay

⚡ dsh-agent-relay

Local Multi-Agent Collaboration Relay for DeepSeek Harness & Local Fleets

DeepSeek Harness 本地多智能体轻量级通信中继总线 — 基于 HMAC-SHA256 鉴权与 Loopback 优先架构的安全消息路由组件

产品定位与设计动机 • 核心技术特性 • 系统架构与流程 • Agent 全流程自动部署 • Wire Protocol 规范

📌 产品定位与设计动机

现有的智能体框架多数专注于单体智能体内部的推理链条与工具调用（Task Execution），但缺乏标准化的智能体间对等通信机制（Peer-to-Peer Inter-Agent Communication）。当在同一宿主机上并行运行 dsh、Codex、Claude Code 与 Hermes 等多个独立智能体时，代理之间无法直接发起代码评审（Code Review）、事实交叉验证或协作任务分发。

dsh-agent-relay 旨在填补这一架构空白：它是一个完全解耦、轻量且自建的智能体通信总线（Communication Bus），包含 HTTP Broker、dsh Cordis 插件、JS/Python 客户端与命令行辅助工具，助力开发者构建智能体舰队协同链路。

🚀 核心技术特性

- 通信与编排解耦 (Decoupled Transport) 区别于强侵入性的工作流编排引擎（Orchestration Frameworks），Relay 仅专注于消息路由与可靠投递，保持智能体内部推理与决策逻辑的完整解耦。
- Loopback 优先的安全架构 (Loopback-First Architecture) Broker 默认仅绑定本地回环地址 127.0.0.1:19121，免去云端部署成本与外部网络攻击面风险。
- HMAC-SHA256 鉴权体系 (Cryptographic Verification) 所有接口调用均经由 HMAC-SHA256 签名校验，内置 300 秒时间戳重放防护与常量时间比较；投递层再以「每次认领一枚租约令牌」约束确认与续租。速率限制与鉴权失败锁定属于已删除的 v1 世代，现在没有这两道闸，所以边界由「只绑回环」承担。
- 高可靠投递与容错机制 (Reliable Delivery & Idempotency) 请求默认留存 7 天、SQLite 单一路径持久化、租约投递 + 令牌化确认、服务端长轮询唤醒（落库即达）、失败/过期由服务端定时扫描自动回发未送达通知，并以幂等键去重。
- 隐私保护设计 (Privacy-by-Design) 消息体只为可靠投递保存在本机 TTL 队列中，Broker 与参考客户端不会把消息体写入应用日志或遥测；默认回环部署时数据不离开本机。
- dsh 一级工具无缝集成 (First-Class Cordis Plugin) 针对 DeepSeek Harness 提供原生 Cordis 插件，注册 agent_relay_send / agent_relay_status / agent_relay_history / agent_relay_peers / agent_relay_retry 模型工具，自适应退避轮询 + per-root relay 会话 + read/write 权限预设，并提供图形化侧边栏状态面板。
- v2/v3 线协议（与自用版 Python 客户端字节兼容） canonical-JSON 签名、snake_case 信封、execution mode、per-mode ACL、租约令牌、undelivered 通知；v1 世代已于 2026-09-19 移除。

⚖️ 系统设计对比 (Architecture Comparison)

| 维度对比 | ⚡ dsh-agent-relay | ❌ 工作流编排引擎 (AutoGPT/LangGraph) | ❌ 传统消息服务 (Slack/Discord API) |
| 架构定位 | 纯粹消息路由总线，保持智能体推理独立 | 强依赖 DAG 图逻辑，侵入式驱动控制流 | 人类社交 UI 框架，包含复杂的 Presence 状态 |
| 部署与网络依赖 | 零第三方依赖，Loopback 本地极速运行 | 需复杂的中间件环境与 Redis/数据库支持 | 需公网访问、OAuth 鉴权与 WebSocket 长连接 |
| 状态持久化与容错 | 本地 SQLite + 7 天留存 + 租约投递 + 长轮询唤醒 | 依赖外部集中式数据库管理状态 | 依赖第三方云端服务器消息留存 |
| 数据隐私保护 | 默认纯本地，消息体不进入日志或遥测 | 常见云端日志留存与 Embedding 上传 | 消息明文通过第三方服务器中转 |

🏗️ 系统架构与工作流

全部路由都在 /v1/ 之下，说同一套 v2/v3 线协议（规范见 docs/PROTOCOL-V2.md）：签名有两种形态——不带 keyId 头走 v2 串，带 X-Agent-Relay-Key-Id 走 v3 串——但共用同一个密钥环与同一套租约/ack 投递。v1 世代（X-Relay- 头、/register、/peers、游标轮询）已整代删除，不带 v2/v3 头的请求会收到 400 并附协议指引。

sequenceDiagram
autonumber
participant D as dsh (Agent A)
participant B as Relay Broker (127.0.0.1:19121)
participant C as Claude Code (Agent B)

Note over D,C: Loopback 架构下基于 HMAC-SHA256 的通信流程 D->>B: POST /v1/messages (v2/v3 HMAC Signed) Note over B: 校验时间戳/签名/ACL写入 SQLite 队列
B-->>D: 200 {message_id, root_id, protocol_version}
C->>B: POST /v1/pull (lease)
B-->>C: 200 {messages, lease_token}
Note over C: Agent 接收消息并执行相关任务 C->>B: POST /v1/lease/renew (长任务可选) C->>B: POST /v1/ack (completed 或 retry)
B-->>D: 状态可由 /v1/status 查询，回复通过 parent_id 关联

🤖 Agent 全流程自动部署流程 (Agent-Driven Automated Deployment)

本项目原生支持由 AI Agent 主导的全流程自主部署与链路装配。开发者无需手动执行繁琐的环境配置，只需将部署任务交由 DSH (DeepSeek Harness) 或通用 AI Agent，系统即可自动完成终态构建。

flowchart LR
A[开发者执行插件挂载] --> B[DSH 读取 docs/AGENT-DEPLOY.md]
B --> C[自主生成 HMAC 密钥与 Broker 配置]
C --> D[启动 Broker 进程与健康检查 selfcheck]
D --> E[装配 CLI / Python / Agent 通信凭据]
E --> F[自动校验自检并输出部署报告]

🚪 推荐接入方式：MCP（Codex / Claude Code / Qoder / 任意 MCP 宿主）

mcp/relay-mcp.mjs 是协作圈的 MCP 入口。宿主在会话启动时自己拉起它、结束时回收，所以接入一个 Agent 是 3 行配置，而不是一个常驻轮询进程。工具面只有 5 个：

| 工具 | 作用 |
| relay_ask | 交给对方并直接等到回答（对方不在线时立刻返回 peer_offline，请求仍留存数天等自动投递） |
| relay_send | 异步投递，不等 |
| relay_inbox | 取别人发给我的请求（默认读完即确认） |
| relay_reply | 把答案回到某条收到的请求上（同一条会话线） |
| relay_status | 我发的请求到哪一步了 |
| relay_agents | 谁在圈里、谁此刻在线、队列积压 |

Codex（~/.codex/config.toml）与 Claude Code（~/.claude.json）示例：

[mcp_servers.relay_codex]
command = "node"
args = ["<repo>/mcp/relay-mcp.mjs"] # 本仓库的绝对路径
[mcp_servers.relay_codex.env]
AGENT_RELAY_AGENT = "codex"
AGENT_RELAY_BROKER_URL = "http://127.0.0.1:19121"
指向部署里已有的 dotenv，别让宿主配置变成密钥的第二个明文副本：
AGENT_RELAY_SECRET_ENV_FILE = "D:/path/to/bot/.env" # 读取 AGENT_RELAY_CODEX_SECRET
或者用 DPAPI 保管库：AGENT_RELAY_SECRET_REF + AGENT_RELAY_VAULT_MODULE

Claude Code 同理，写进 ~/.claude.json 顶层 mcpServers。凭据优先级：secret → secret_env → secret_env_file → secret_ref+vault_module。

接入后一句"让 claude 审一下这个函数"就是一次 relay_ask 工具调用。

让"没在跑的成员"也能被投递：wake_command

轮询模型要求接收方一直有进程活着，这在个人机器上经常不成立。给成员声明 wake_command 后，消息落库时若它 90 秒内没取过件，broker 会按需启动一次工作进程（凭据走子进程环境变量，不进命令行）；它真的会跑一次该成员的 CLI 并产生 API 费用，所以开关单独成一条命令，默认只预演：

node setup/enable-wake.mjs --agent codex # 预演：打印将写入的行
node setup/enable-wake.mjs --all-clients --apply # 确认后写入（自动备份），再重启 broker

唤醒是兜底而非竞争：成员只要 90 秒内取过件（比如它的常驻代理正在跑），broker 就不会另起工作进程，避免同一消息被处理两次。

一条命令自检

node setup/doctor.mjs # 或 node adapters/cli/relay.mjs doctor

输出：broker 是否可达、谁真的能收消息、队列积压、两处凭据是否漂移、明文密钥、WAL 是否膨胀、线上 adapter 与仓库基线是否一致。退出码 0/2/1。

1. DSH 自主部署指令 (推荐)

在终端中安装插件后，直接让 DSH 读取任务指南 docs/AGENT-DEPLOY.md 即可完成端到端自主部署：

安装中继插件
dsh plugin --profile web add dsh-agent-relay

在接下来的 DSH 会话中，DSH 将自动执行如下全流程步骤：
1. 自动配置生成：生成随机 HMAC 密钥并写入 broker 的 config.yaml；成员的运行时配置是 ~/.dsh/agent-relay.json（只记 vault 条目名，不记明文密钥）。
2. 后台服务拉起：启动 Broker 进程并绑定 127.0.0.1:19121 端口。
3. 多 Agent 凭据装配：为 dsh、Codex、Claude Code 与 Python 客户端各自落地身份与凭据来源（环境变量 AGENT_RELAY_／DSH_RELAY_、指向已有 dotenv、或 DPAPI 保管库条目），不新造明文密钥副本。成员身份由取件行为体现，没有注册这一步。
4. 链路自检与验证：自动运行 selfcheck 验证收发链路，并向用户汇报部署结果。

2. 命令行手动部署流程 (单机快速验证)

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 名）
export DSH_RELAY_SECRET=<secret_printed_in_config>
node adapters/cli/relay.mjs v2 send beta "hello from alpha" --agent alpha --secret $DSH_RELAY_SECRET
node adapters/cli/relay.mjs v2 pull --wait 10 --agent beta --secret $DSH_RELAY_SECRET
node adapters/cli/relay.mjs doctor

完整指南详见：docs/DEPLOY.md · Wire Protocol 规范：docs/PROTOCOL-V2.md · 系统架构：docs/ARCHITECTURE.md · 安全规范：docs/SECURITY.md

📜 Wire Protocol 规范

唯一在用的协议是 v2/v3，规范见 docs/PROTOCOL-V2.md； v1 世代（X-Relay- 头、/register、/messages 游标轮询）已于 2026-09-19 移除——审计显示 v1 队列表自 2026-08-15 起再无任何消息，且没有任何现役客户端注册过。

鉴权头：X-Agent-Relay-Agent、X-Agent-Relay-Timestamp、X-Agent-Relay-Signature； v3 另带 X-Agent-Relay-Key-Id（现役飞书 bot 与 Hermes 适配器都走 v3 的 legacy 键）。

签名串（canonical JSON + HMAC-SHA256，v3 在第二段插入 keyId）的字节级定义只在 docs/PROTOCOL-V2.md 维护，此处不再复制一份等着漂移。
跨语言字节级一致性由 test/protocol_v2_golden.py 与 test/protocol-v2-python.test.mjs 锁定；不要自行改写签名规则，改协议请同步更新这两个测试。

📂 仓库目录结构 (Repository Layout)

| 路径 | 功能说明 |
| broker/ | Relay 中继核心服务（零 npm 运行依赖：配置、v2/v3 签名鉴权、SQLite 持久化、长轮询唤醒与按需拉起）+ Dockerfile |
| lib/ | 可发布的客户端层：v2/v3 客户端 (client-v2.js)、协议单一来源 (protocol.js)、配置分层 (relay-config.mjs)、凭据解析 (credentials.mjs)、DSH 的五个 agent_relay_ 工具、workspace 租约/隔离 |
| mcp/ | MCP stdio 入口 relay-mcp.mjs：6 个工具，宿主按会话拉起，不需要常驻轮询进程 |
| adapters/cli/ | 零第三方依赖 Node.js CLI 客户端适配器 |
| adapters/hermes/ | 纯 Python 标准库客户端适配器 + Hermes 风格 Agent 集成示例 |
| adapters/openclaw/ | OpenClaw 框架集成适配说明文档 |
| adapters/relay-agent.mjs | 短生命周期工作进程：认领→交给 --backend-cmd→ack→队列空即退出（wake_command 的默认目标） |
| setup/ | setup.js (init/start/selfcheck)、add-member.mjs、sync-secrets.mjs、doctor.mjs（一条命令体检）、enable-wake.mjs（按需唤醒开关，默认预演）、migrate-v2.mjs、capture-adapter.mjs、Docker Compose 演示 |
| docs/ | PROTOCOL-V2（线协议规范，唯一权威）、ARCHITECTURE（系统结构与取舍）、DEPLOY（部署）、SECURITY（威胁模型）、AGENT-DEPLOY（给 Agent 的部署任务书） |

🔧 环境要求 (Requirements)

- Node.js ≥ 22.13（Broker 服务、CLI 客户端、dsh 插件）。持久化只有 SQLite 一条路径（零外部依赖，用 Node 内置 node:sqlite，需 Node ≥ 22.13）；JSONL 回退已随 v1 世代一起移除。
- Python ≥ 3.10 (仅 Python 客户端适配器需要，可选)
- dsh 0.1.0-rc.6（推荐测试版本）

📌 维护状态 (Maintenance Status)

- 维护者：Noelune
- 社区维护 —— 欢迎提交 Issue 与 Pull Request。缺陷修复通常在 1–2 周内处理，安全相关问题将优先响应。
- 兼容性：基于 dsh 0.1.0-rc.6 进行测试与兼容性验证。上游 API 变更说明同步记录于 CHANGELOG.md。
- 许可证：MIT License —— 允许商业化使用。

🛡️ 安全规范 (Security)

详细说明请参阅 docs/SECURITY.md。

* 鉴权与传输：通过 HMAC 实施身份验证，网络级加密依赖 TLS。默认强制推荐使用 Loopback 本地回环模式，切勿将未加密的明文 Broker 暴露在公网环境。
* 威胁模型防护：对于从 Relay 接收到的任何消息体，接收端 Agent 必须将其视为未校验的数据输入（Untrusted Data），严禁直接作为高权限指令执行。

🤝 贡献指南 (Contributing)

欢迎提交 Pull Request。提交前请确保运行单元测试（node --test）。项目的 CI 流程会在每次 Push 时自动执行单元测试、代码密钥扫描（gitleaks）与开源许可证合规检查。