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 解决了在浏览器端为多个插件建立共享事件流的需求，避免了连接数限制，并提供了可靠的连接状态信号。开发者可根据需要选择直接消费负载或仅作为触发器。