dsh-agent-relay

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

<div align="center">

⚡ dsh-agent-relay

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

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






[产品定位与设计动机](#-产品定位与设计动机) • [核心技术特性](#-核心技术特性) • [系统架构与流程](#-系统架构与工作流) • [Agent 全流程自动部署](#-agent-全流程自动部署流程) • [Wire Protocol 规范](#-wire-protocol-v10-规范)

</div>

---

📌 产品定位与设计动机

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

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

---

🚀 核心技术特性

• 通信与编排解耦 (Decoupled Transport)

区别于强侵入性的工作流编排引擎（Orchestration Frameworks），Relay 仅专注于消息路由与可靠投递，保持 Agent 内部推理与决策逻辑的完整解耦。

• Loopback 优先的安全架构 (Loopback-First Architecture)

Broker 默认仅绑定本地回环地址 127.0.0.1:19121，免去云端部署成本与外部网络攻击面风险。

• HMAC-SHA256 严密鉴权体系 (Cryptographic Verification)

所有 HTTP 接口调用均经由 HMAC-SHA256 签名校验，内置 300 秒时间戳重放防护、连续 5 次鉴权失败引发的 5 分钟安全锁定机制及单 IP 速率限制。

• 高可靠投递与容错机制 (Reliable Delivery & Idempotency)

采用基于游标的增量轮询与租约确认机制，支持消息 7 天 TTL、SQLite 默认持久化（Node 20 自动回退 JSONL）、指数退避重试 (2s/4s/8s) 与基于 UUID 的幂等去重。

• 隐私保护设计 (Privacy-by-Design)

消息体只为可靠投递保存在本机 TTL 队列中，Broker 与参考客户端不会把消息体写入应用日志或遥测；默认回环部署时数据不离开本机。

• dsh 一级工具无缝集成 (First-Class Cordis Plugin)

针对 DeepSeek Harness 提供原生 Cordis 插件，注册 relay_send、relay_recv、relay_peers、relay_history 模型工具，并提供图形化侧边栏状态面板。

---

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

维度对比 · ⚡ dsh-agent-relay · ❌ 工作流编排引擎 (AutoGPT/LangGraph) · ❌ 传统消息服务 (Slack/Discord API)

架构定位 · 纯粹消息路由总线，保持 Agent 推理独立 · 强依赖 DAG 图逻辑，侵入式驱动控制流 · 人类社交 UI 框架，包含复杂的 Presence 状态

部署与网络依赖 · 零第三方依赖，Loopback 本地极速运行 · 需复杂的中间件环境与 Redis/数据库支持 · 需公网访问、OAuth 鉴权与 WebSocket 长连接

状态持久化与容错 · 本地 SQLite（JSONL 兼容）+ 7 天 TTL + 租约投递 · 依赖外部集中式数据库管理状态 · 依赖第三方云端服务器消息留存

数据隐私保护 · 默认纯本地，消息体不进入日志或遥测 · 常见云端日志留存与 Embedding 上传 · 消息明文通过第三方服务器中转

---

🏗️ 系统架构与工作流

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 /messages (HMAC Signed) <br> { to: "claude", body: { task: "code_review" } }
    Note over B: 1. 校验 Timestamp < 300s<br>2. 验证 HMAC-SHA256 签名<br>3. 写入本地持久化队列 (TTL 7d)
    B-->>D: 201 Created (Message ID: UUID)

    C->>B: GET /messages?since=cursor (HMAC Signed)
    B-->>C: 200 OK [Unread Messages Array]
    Note over C: Agent 接收消息并执行相关任务
    C->>B: POST /messages (Reply with ack=true)
    B-->>D: 确认投递，推送至 dsh 侧边栏状态栏

---

🤖 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[自动校验自检并输出部署报告]

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

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

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

在接下来的 DSH 会话中，DSH 将自动执行如下全流程步骤：

1. 自动配置生成：生成安全 HMAC 密钥并写入 ~/.dsh/relay.json。

2. 后台服务拉起：启动 Broker 进程并绑定 127.0.0.1:19121 端口。

3. 多 Agent 凭据装配：自动为 dsh、Codex (AGENTS.md)、Claude Code (CLAUDE.md) 与 Python 客户端配置环境变量 DSH_RELAY_AGENT 与 DSH_RELAY_SECRET。

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 register --agent alpha --secret $DSH_RELAY_SECRET
node adapters/cli/relay.mjs register --agent beta  --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

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

---

📜 Wire Protocol v1.0 规范

所有语言客户端适配器（JS Plugin / JS CLI / Python Client）必须严格遵循 Wire Protocol v1.0 标准规范。

请求头鉴权规范

任何非 GET / 请求均须包含以下 HTTP 请求头：

X-Relay-Agent: <agent_name>
X-Relay-Timestamp: <unix_epoch_seconds>
X-Relay-Signature: <hex_hmac_sha256>

签名推导公式：

SigningString = Method + "\n" + PathnameWithQuery + "\n" + TimestampSeconds + "\n" + RawBody
Signature     = HMAC-SHA256(secretKey, SigningString).hex()

---

📂 仓库目录结构 (Repository Layout)

路径 · 功能说明

broker/ · Relay 中继核心服务（零 npm 运行依赖，包含配置、HMAC 鉴权、SQLite/JSONL 持久化与 HTTP 服务）+ Dockerfile

lib/ · dsh 插件核心：提供模型工具接口 (relay_send / relay_recv / relay_peers / relay_history) 与客户端库

adapters/cli/ · 零第三方依赖 Node.js CLI 客户端适配器

adapters/hermes/ · 纯 Python 标准库客户端适配器 + Hermes 风格 Agent 集成示例

adapters/openclaw/ · OpenClaw 框架集成适配说明文档

setup/ · 环境初始化脚本 setup.js (init/start/selfcheck) 与 Docker Compose 演示环境

docs/ · PROTOCOL (规范说明), ARCHITE

…(truncated)