dsh-interconnect

跨实例消息互通与事件通知插件，用于 DeepSeek Harness (DSH)。 让一个 DSH 实例能向同一个实例、另一台机器、或另一台机器上的别的 DSH 实例发送消息、探测活性，并在实例之间双向推送事件。

项目状态（2026-09-16）：本仓库是该插件的树外（out-of-tree）主源。并入 DSH monorepo 的计划（PR #3243）已按「保持树外」的评审意见关闭；插件继续经 npm 分发（dsh-interconnect），并由团队内部的插件集合仓以 git submodule 引用本仓库。

包含三个插件

interconnect —— host 服务（ctx.interconnect）：

• 全走持久 WebSocket 链接：跨实例、跨机器投递消息、枚举 live session、探测活性（send/reply/ping/list 经 /interconnect/link 的 msg/query 帧）
• /interconnect/link WebSocket 端点：双向实时事件推流，含心跳与指数退避重连；也承载 send/reply 消息（msg/msg-result 帧，WS 优先 + HTTP 回退）
• 事件 fan-out（HTTP + WebSocket），入站事件以 interconnect/event 发出
• 共享密钥鉴权（DSH_INTERCONNECT_TOKEN，bearer，fail-closed，timing-safe 比较）

tool-interconnect —— 模型可见工具：

• interconnect_send：向对端实例的指定 session 投递消息；可选 delivery 选投递模式、resume 唤醒离线 session
• interconnect_list：列出对端实例的 live session（id + 标题 + 状态），用于在不预先知道 session id 时寻址
• interconnect_ping：探测对端实例活性与身份
• interconnect_reply：向记录过的发送方回传消息，只需文本；回信 session 是本 agent 自己的，无需再次寻址

skill-interconnect —— 配套 skill：

• 向模型注册 dsh-interconnect skill，说明 list/ping/send/reply 的完整用法、 投递模式、resume 唤醒语义与失败处理。
• 明确告知模型：interconnect_send 会自动注入发送方的 instanceId 和 sessionId， 接收方凭记录的 sender 即可用 interconnect_reply 回信，不需要手工传地址。
• 依赖 interconnect 服务，只有传输层存在时才注册进 ctx.skills。

用法

寻址（0.9 起用 instanceId，全走持久链接）

从 0.9 起，传输只走 WebSocket 持久链接，不再有 HTTP 端点，寻址参数从 baseUrl 改为 instanceId：

• interconnect_send(instanceId="peer", sessionId=..., text=...)
• interconnect_ping(instanceId="peer")
• interconnect_list(instanceId="peer")
• interconnect_reply(text=...)（只需文本；回信 session 是本 agent 自己的，目标从记录的 sender 解析）

instanceId 是 interconnect 行 peers 映射里的键；真正用来拨号的 origin 由该映射的值给出（例如隧道端点 http://127.0.0.1:13080），instanceId 本身从不出现在线上，也不参与路由——origin 才是唯一的拨号依据。到未配置 / 未联通的对端 send/ping/list 返回 unreachable（无 HTTP 回退）。

interconnect_list 返回对端当前 live 的 session，每一行的 sessionId 在调用时刻都是合法的投递目标：

session-264d37b0-…  重构 interconnect 插件  [idle]
session-b07326da-…                          [running]

title 与 status 是尽力而为的：标题来自可选的 title projection 服务，对端没装该服务、或 该 session 还没有标题时，整个键不出现（而不是空字符串），所以「无标题」与「该对端不提供 标题」可以区分。projection 抛错只会让那一行降级成只有 id，不会让整个列表失败。

只列 live session 是有意的：send 能到达的正好是这些。对端存在但没有运行 agent 的 session 不会出现在列表里，也收不到消息。

答案有双重上限：行数（MAX_LISTED_SESSIONS，100 行）与字节预算（MAX_LIST_ROWS_BYTES，等于链路 帧上限减去 4 KiB 的 query-result 信封）。整帧必须待在链路的帧上限内，ws 对超限帧会直接关闭 链路，所以 live session 极多、或标题很长时，对端只回答能装下的前若干行，而不是把传输打断。 对端不上报截断标志，所以 interconnect_list 只在收到的行数正好等于该上限时追加一行提示 （100 of possibly more live sessions）——满页可能被截断，缺失的目标仍可能 live。 ping 与 list 的答复还会按调用方问的 kind 校验形状，形状不符按「无答复」处理（对应 unreachable）。

回复（reply）

send 的线负载带一个 sender 身份（无地址：instanceId + sessionId），收到消息的 instance 会按「本地 session id → 该 sender」记下这份身份。之后那个 session 回信只需要文本： 回信 session 就是执行 interconnect_reply 的 agent 自己的 session，工具据此查出记录的 sender， 不用再次给出本地 session id、对端 instanceId 或远程 session id——回信走的是本机到那个 instance 的持久链接。

# 源实例 A 指定目标 B 的 session，并带上自己的身份（无 baseUrl）
interconnect_send(instanceId="b", sessionId=B-sess, text="…", sender={instanceId:A, sessionId:A-sess})

# B 回传：只给文本，回信 session 即执行该工具的 agent 自己的 session
interconnect_reply(text="reply")

…