前言¶

在 DeepSeek Harness（DSH）裏跑 agent，常見需求是跨 session、跨機器協作：一臺機器上的 agent 需要給另一臺機器上的 session 發消息，或者探測對端是否在線、列出可投遞的目標。單靠本機 API 或手工拼 HTTP 請求，既要維護地址映射，又要處理連接保活和失敗重試，成本不低。

dsh-interconnect 是社區維護者 Chinesezjc 發佈的工作流類插件，當前在 GitHub 上有 34 stars。它把跨實例消息投遞、活性探測、事件推流和模型側工具封裝成一套 host 服務，讓多個 DSH 實例通過持久 WebSocket 鏈路互相通信。

這是什麼¶

dsh-interconnect（npm 包名 dsh-interconnect，當前版本 0.10.0，MIT 許可）是面向 DeepSeek Harness 的跨實例消息互通與事件通知插件。一句話定位：讓一個 DSH 實例能向本機、另一臺機器、或另一臺機器上的其他 DSH 實例發送消息、探測活性，並在實例之間雙向推送事件。

插件以 bundle 形式提供三個組件：

核心功能¶

下面按傳輸層、工具層和配套 skill 分開說明。

持久 WebSocket 鏈路¶

從 0.9 起，傳輸只走 WebSocket 持久鏈接，不再有 HTTP 端點。send、reply、ping、list 全部經 /interconnect/link 上的 msg / query 幀完成。激活時插件會按 peers 映射自動對每個對端建鏈，帶心跳與指數退避重連。

尋址參數是 instanceId，不再是 baseUrl。instanceId 是配置裏 peers 映射的鍵；真正用來撥號的 origin 由映射值給出（例如隧道端點 http://127.0.0.1:13080）。到未配置或未聯通的對端，send / ping / list 返回 unreachable，沒有 HTTP 回退。

鑑權使用共享密鑰 DSH_INTERCONNECT_TOKEN（bearer，fail-closed，timing-safe 比較），配置在憑據源而非插件 config 裏。

模型可見工具¶

tool-interconnect 暴露四個工具：

1. interconnect_send：向對端實例的指定 session 投遞消息；可選 delivery 選投遞模式、resume 喚醒離線 session。發送時會自動注入本機 instanceId 和 sessionId。
2. interconnect_list：列出對端當前 live 的 session（id、標題、狀態），用於不知道 session id 時尋址。
3. interconnect_ping：探測對端實例活性與身份。
4. interconnect_reply：向記錄過的發送方回傳消息，只需本機 session id 和文本，無需再次尋址。

interconnect_list 只返回當前有運行中 agent 的 session——send 能到達的正是這些。subagent 擁有的 session 不會出現在列表裏，也不能直接投遞。

雙向回覆¶

收到帶 sender（instanceId + sessionId）的 send 後，接收方會記下「本地 session id → sender」的映射。之後該 session 可用 interconnect_reply 回信，目標從記錄的 sender 解析，走本機到對端的持久鏈接。sender 用於 reply 歸因，不是路由或鑑權依據；也不進模型上下文。

投遞模式與喚醒¶

delivery 有三個取值，發送方可按消息覆蓋接收方默認值：

resume 默認關閉。設爲 true 可喚醒已持久化但沒有運行 agent 的 session，但會觸發完整 agent 回合（含模型調用），發送方需顯式請求，接收方可用 allowResume: false 拒絕。

投遞失敗時，SendResult.reason 會指明原因，例如 session-not-live、unreachable、resume-refused、session-owned-by-subagent、no-sender-known 等，便於調用方決定重試還是換目標。

配套 skill¶

skill-interconnect 向模型註冊 dsh-interconnect skill，說明 list / ping / send / reply 的完整用法、投遞模式、resume 喚醒語義與失敗處理。它依賴 interconnect 服務，只有傳輸層存在時才註冊進 ctx.skills。

安裝與啓用¶

本包已發佈到 npm。倉庫是一個 DSH profile bundle，根 package.json 聲明 dsh.bundle.patch 指向 cordis.patch.yml，後者會插入三個插件行。

從 npm 安裝：

dsh plugin --profile <name> add dsh-interconnect

或從本地路徑安裝（開發調試時）：

dsh plugin --profile <name> add file:/path/to/dsh-interconnect

dsh plugin add 會把倉庫識別爲 bundle 並追加進 profile 的 dsh.profile.bundles。重啓 web 服務使 host 側生效。兩端實例的 .credentials.yaml（或等價憑據源）需設置相同的 DSH_INTERCONNECT_TOKEN 作爲共享密鑰。

配置示例（interconnect 行的 config，字段均可選）：

- id: interconnect
  config:
    instanceId: my-box
    peers:
      peer-a: http://127.0.0.1:13080
      peer-b: http://127.0.0.1:13081
    delivery: followup
    allowResume: false

典型用法¶

尋址與投遞¶

先用 interconnect_list 查看對端 live session，再向指定 session 發消息：

interconnect_list(instanceId="peer")
interconnect_send(instanceId="peer", sessionId="session-264d37b0-…", text="…")
interconnect_ping(instanceId="peer")

interconnect_list 返回示例：

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

雙向回覆¶

實例 A 向實例 B 的 session 發消息，B 憑本地 session id 回信，無需再次給出對端地址：

# A 發往 B
interconnect_send(instanceId="b", sessionId=B-sess, text="…")

# B 回傳
interconnect_reply(sessionId=B-sess, text="reply")

喚醒離線 session¶

喚醒並讓對方實際處理（會起一個計費回合）：

interconnect_send(instanceId="peer", sessionId, text, resume=true, delivery="followup")

喚醒但不起回合，只寫入上下文：

interconnect_send(instanceId="peer", sessionId, text, resume=true, delivery="inject")

適用場景與注意¶

適合誰：

• 需要在多臺機器或多個 DSH 實例之間做 agent 協作的開發者
• 希望模型能通過工具主動發現對端 session、投遞消息、收回復的場景
• 需要跨實例事件推流（生命週期事件經 interconnect/event 發出）的集成

使用前注意：

1. 插件以當前 DSH 進程的權限運行，安裝前應檢查 源碼 與 MIT 許可證。
2. 0.9 起傳輸只走 WebSocket，到未聯通對端無 HTTP 回退；部署時需保證 peers 映射中的 origin 可達，且兩端 DSH_INTERCONNECT_TOKEN 一致。
3. resume 會觸發完整 agent 回合併產生模型調用費用，默認關閉；接收方可設 allowResume: false 拒絕。
4. 不能直接投遞 subagent 擁有的 session，需通過父 agent 觸達。
5. 沒有 Host agent lookup 的部署（headless、無 api-proxy）無法喚醒離線 session，會降級爲 session-not-live。

結尾¶

dsh-interconnect 把跨實例消息投遞、活性探測、事件推流和模型工具收進一個 bundle，用 instanceId + 持久 WebSocket 鏈路替代手工維護 HTTP 端點。如果你需要在多個 DSH 實例之間讓 agent 互相發消息、列 session、探測在線狀態，dsh-interconnect 是目前社區裏較完整的工作流方案。

• 社區目錄頁：https://www.skillhub.cn/plugins/Chinesezjc/dsh-interconnect
• GitHub：https://github.com/Chinesezjc/dsh-interconnect
• npm：https://www.npmjs.com/package/dsh-interconnect