事件中继 joao-paulo-santos/dsh-event-relay

dsh-event-relay

DeepSeek Harness（DSH）插件：把它和你的其他插件一起装进配置档。

从宿主推送到浏览器。 宿主可以主动发起会话；其他通道（fetch、RPC）都得等浏览器先问。如果你希望插件 UI 在宿主侧一有动静（配置变了、构建完成、通知到达）就立刻响应，那这条通道就是干这个的。

一条共享的 SSE 路由（/relay/events）把每个订阅者的响应挂住不关，事情一发生就推送 JSON 消息 {"topic","payload"}。每个浏览器标签页只占一条连接，不管有多少插件订阅。

架构

flowchart LR
subgraph HOST["🖥️ Host, dsh-event-relay (host half)"]
P["publish(topic, payload)"]
N["notifyClientsfilter per client"]
W[("/relay/eventsheld-open responses")]
end
subgraph WIRE["⇄ SSE"]
direction LR
M["data: {topic, payload}...one message per event..."]
end
subgraph BROWSER["🌐 Browser tab, dsh-event-relay (client half)"]
C["eventRelay servicesubscribe(topic, listener)"]
S["notifyListenersfan-out per topic"]
L1["plugin A listener"]
L2["plugin B listener"]
L3["plugin C listener"]
end
P --> N --> W
W --> M
M --> C
C --> S
S --> L1
S --> L2
S --> L3

插件价值

| 替代方案 | 差在哪 |
| 轮询 | 有延迟又浪费（为了确认「什么都没变」要发 N 次请求） |
| 聚焦/导航时重新拉取 | 免费又正确，但只有用户操作时才更新 |
| 每个插件自己开 EventSource/WebSocket | 浏览器对每个域名限制约 6 条连接（HTTP/1.1）；几个插件就把它们长期占满，其他所有请求都得排队。这条共享流整个标签页只占一条连接 |
| 宿主 RPC（/api） | 请求→响应：前端能问，但宿主没法打断 |

只做单向，是故意的。 浏览器→宿主是事务形态（命令→回复）：用普通 HTTP（宿主侧注册一条路由），有状态码、校验和错误处理，这些流都没有。宿主→浏览器是通知形态：时机不可预测，所有标签页同时收到。不同的活，走不同的路。

怎么安装

需要一份 DeepSeek Harness 检出和一个配置档（这里叫 web）：

from the harness checkout
pnpm dsh plugin --profile web add /path/to/dsh-event-relay

verify the profile still composes
pnpm dsh --profile web --dump-config

然后重启 harness；宿主侧在启动时加载。浏览器插件用 ctx.get('eventRelay') 消费客户端服务，除了装这个包，不用再接别的线。

生产者（宿主插件）

const relay = ctx.get('eventRelay') // optional, degrade if absent
relay.publish('my-topic', payload) // directjs
ctx.on('my/event', (data) => relay.publish('my/event', data)) // 镜像一个 Cordis 事件（在你的插件里做这件事）

消费端（浏览器打包产物） js const relay = ctx.get('eventRelay') // 由本包的客户端部分提供
const unsubscribe = relay.subscribe('kanban', (topic, payload) => { ... })
// 或者用原始方式：new EventSource('/relay/events?topics=kanban,notifications')

回调里的 payload 就是发布方传进来的内容。直接拿来用，或者忽略它、重新拉取你自己的真实数据，两种都是一等公民的用法。

主题过滤：订阅会匹配它的精确主题以及任意子主题（'kanban' 匹配 'kanban/change'）。浏览器的连接 URL 携带该标签页所有主题的并集，所以服务端只发送这个标签页监听的内容。当标签页最后一个监听者取消订阅时，连接关闭。

每次流（重新）打开时，合成主题 __relay 的订阅者都会收到 '__relay/open'。那些从消息里应用状态的消费端用它来重新同步：流断开期间错过的任何内容，都靠一次重新拉取补回来。

设计

是传输层，不是总线：Cordis 事件仍然是宿主侧的事件系统；这里只负责把消息送过平面边界。

payload 是可选的，不是只能当门铃。有些插件把中继纯粹当作变更信号，只发一条带主题的消息，告诉自己去重新拉取真实数据。另一些则直接消费 payload：notifications 演示推的是通知本身，看板推的是变更消息。publish(topic, payload)：有什么有用的就发什么。门铃只是一种用法，不是契约。

要的是存活，不是正确：中继可能不存在，消费端应该退回到聚焦时拉取（或者在 __relay/open 时拉取），而不是把状态寄托在流上。
路由根是组合层级的契约（/api、/plugins、/workspace-history、/notifications、/granular-settings 已被占用）。

调试

可以从终端监听这条链路。不用浏览器就能端到端验证发布，非常有用：

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

加上 ?topics=<prefixes> 就能镜像客户端的过滤条件；-N 让 curl 流式输出而不是先缓冲。

依赖

无

依赖本插件的插件

- dsh-granular-settings 为它的作用域设置平台发布仅作门铃的变更通知