dsh-event-relay: 主機向瀏覽器推送通知的共享 SSE 渠道

前言¶

在 DeepSeek Harness (DSH) 插件開發中，主機端的狀態變化（如設置變更、構建完成）需要實時通知瀏覽器界面。現有的輪詢方式有延遲，RPC 模式依賴用戶交互，而瀏覽器端的 WebSocket 有限制（通常每個域約 6 個連接）。dsh-event-relay 提供了一個共享的 SSE 端點，用於解決這一通信問題。

安裝¶

安裝命令如下：

pnpm dsh plugin --profile web add /path/to/dsh-event-relay

安裝完成後，重啓 Harness，主機端會在啓動時加載該插件。瀏覽器端插件通過 ctx.get('eventRelay') 消費該服務。

核心功能¶

共享 SSE 路由：使用單一的 /relay/events 路由，爲所有訂閱者保持連接並推送 JSON 消息。
服務器端過濾：瀏覽器端通過 URL 參數指定訂閱的主題前綴，服務器只發送匹配的消息。
重連信號：連接建立或重連時，會發送 __relay/open 信號，幫助客戶端判斷連接狀態。
無依賴：純原生實現，無額外依賴。

用法示例¶

主機端（生產者）¶

主機插件通過 relay.publish 發送事件。

const relay = ctx.get('eventRelay') // 可選，如果缺失則降級處理

// 直接發送
relay.publish('my-topic', payload)

// 映射 Cordis 事件
ctx.on('my/event', (data) => relay.publish('my/event', data))

瀏覽器端（消費者）¶

瀏覽器端通過 relay.subscribe 訂閱主題，或直接使用 EventSource。

const relay = ctx.get('eventRelay')

// 使用客戶端服務訂閱
const unsubscribe = relay.subscribe('kanban', (topic, payload) => {
  // 處理消息
})

// 或使用原生 EventSource，配合主題過濾
// new EventSource('/relay/events?topics=kanban,notifications')

設計說明¶

單向通信：該插件設計爲單向通信，僅支持主機向瀏覽器推送。瀏覽器發起請求，主機響應。
負載可選：消息中的 payload 是可選的。有些插件只將其作爲“門鈴”信號，觸發自身數據刷新；有些則直接消費消息內容。
生存能力優先：插件可能不存在，消費者應具備回退機制（如在 __relay/open 時發起 Pull 請求），不應完全依賴該流進行狀態同步。
路由契約：/relay/events 是組合層面的約定，其他組合根（如 /api、/plugins、/workspace-history、/notifications、/granular-settings）也是此類契約的一部分。

調試¶

在終端中監聽 SSE 端點，可以驗證主機端是否正常發送消息：

curl -N 'http://127.0.0.1:3080/relay/events'

總結¶

dsh-event-relay 解決了在瀏覽器端爲多個插件建立共享事件流的需求，避免了連接數限制，並提供了可靠的連接狀態信號。開發者可根據需要選擇直接消費負載或僅作爲觸發器。