界面容器 CH4ACKO3/dsh-ui-container

dsh-ui-container

用于 DeepSeek Harness 浏览器插件的可复用视觉与服务容器。它拥有具名 UI 表面、文档提供者、递归 React 宿主，以及连接另一个前端所需的小型远程协议，而无需传输 DOM 或组件树。

将该插件安装到 DeepSeek Harness 配置文件中：

dsh plugin --profile web add github:CH4ACKO3/dsh-ui-container

此命令作用于配置文件范围，可从任意目录运行。

Git 依赖会运行此包的 prepare 构建。使用 pnpm 10 或更新版本时，请在配置文件的 pnpm-workspace.yaml 中批准首次安装所报告的确切包键，然后重复该命令。注册表发布版本和打包产物不需要该批准。

其他浏览器插件从 @ch4acko3/dsh-ui-container/client 导入其公共 API，并注入 uiContainer Cordis 服务。

远程传输

@ch4acko3/dsh-ui-container 可以跨进程或网络边界投射容器。远程契约传输文档快照和变更通知；它从不传输 React 元素、DOM 节点或 Cordis 服务对象。

能力

协议版本 1 在强制握手期间协商以下能力：

- documents 解析基于 URI 的文档投射。
- subscriptions 订阅一个 URI，并在其投射可能已更改时发送一个小型失效通知。
- surface_commands 将打开、显示和关闭命令路由到已挂载的表面会话。服务器必须选择启用此能力；默认情况下它处于禁用状态。

文档解析包含一个可选的 known_revision。当它与当前服务器修订版本匹配时，响应为 not_modified，且不包含文档负载。变更通知仅包含订阅 id 和 URI。随后客户端会再次解析文档，因此网络使用量取决于实际数据变更，而非所渲染组件树的大小或嵌套深度。

所有远程文档内容和元数据必须与 JSON 兼容。渲染器保留在接收方前端内部，并在本地渲染投射。

跨进程连接

将 MessagePort 用于 Worker、iframe 桥接或宿主 IPC 适配器：

const hostChannel = createMessagePortUiRemoteChannel(hostPort)
const clientChannel = createMessagePortUiRemoteChannel(clientPort)

const stopServing = exposeUiContainerRemote(ctx.uiContainer, hostChannel, {
server: {
name: 'patchouli-host',
version: '0.1.0',
instance_id: crypto.randomUUID(),
},
})

const remote = await UiContainerRemoteClient.connect(clientChannel, {
client: {
name: 'patchouli-window',
version: '0.1.0',
instance_id: crypto.randomUUID(),
},
protocol_versions: [UI_REMOTE_PROTOCOL_VERSION],
capabilities: ['documents', 'subscriptions'],
})

const unregister = ctx.uiContainer.documents.registerProvider(
remote.createDocumentProvider('memory'),
)

将 unregister、remote 和 stopServing 与拥有这些端口的生命周期一起释放。
网络连接

网络所有者首先接受并认证 WebSocket，然后通过该套接字暴露容器：

webSocketServer.on('connection', (socket, request) => {
const principal = authenticate(request)
if (!principal) return socket.close(1008, 'Unauthorized')

const channel = createWebSocketUiRemoteChannel(socket)
exposeUiContainerRemote(ctx.uiContainer, channel, {
server: {
name: 'patchouli-host',
version: '0.1.0',
instance_id: processInstanceId,
},
capabilities: ['documents', 'subscriptions'],
})
})

浏览器客户端可以直接连接：

const remote = await connectUiContainerWebSocket('wss://host.example/ui', {
client: {
name: 'patchouli-web',
version: '0.1.0',
instance_id: crypto.randomUUID(),
},
protocol_versions: [UI_REMOTE_PROTOCOL_VERSION],
capabilities: ['documents', 'subscriptions'],
})

该传输层有意不定义认证。拥有 WebSocket 端点的应用程序必须在调用 exposeUiContainerRemote 之前强制执行认证、授权、TLS 和来源策略。服务器应仅对允许控制所寻址前端会话的主体启用 surface_commands。

线路契约

消息采用 JSON-RPC 2.0。方法名携带其主版本号：

ui.container.handshake@1
ui.container.document.resolve@1
ui.container.document.subscribe@1
ui.container.document.unsubscribe@1
ui.container.document.changed@1 # server notification
ui.container.surface.open@1
ui.container.surface.reveal@1
ui.container.surface.close@1

src/client/remote-protocol.ts 中的 TypeScript 定义是规范性的线路模式。一个连接只允许一次握手，并且之后的每个方法都必须属于已协商的能力。