dsh-frontend-tools-bridge

English | 中文

前端工具桥的 dsh 侧：一个仅监听回环地址的 WebSocket 服务，让任意数量的已连接应用把自己私有的工具镜像注册到 ctx.tools 上，每个应用占据独立的命名空间。工具的真实实现只存在于应用（浏览器渲染进程、Web 应用、Node 进程）——本桥接插件不含任何业务知识；它把模型调用转发给持有的应用并返回其结果。应用侧的对应件是 dsh-frontend-tools-client。

功能

插件启动一个绑定 127.0.0.1 的 WebSocketServer（绑定非回环地址会把模型的工具访问暴露给本地网络；握手 KEY 是客户端身份，不是网络边界）。认证依托客户端名单：应用自行生成 DSH KEY（客户端 SDK 产出 64 位十六进制），用户在对话中把它登记到某个命名空间——KEY 因此兼任客户端身份，凭证的生命周期归应用自己掌管。连接先完成 hello 握手（协议版本、key）；服务端以 welcome 应答并回显绑定的命名空间。每个命名空间同一时刻只允许一个会话——第二个连接呈交已被占据的命名空间时收到 duplicate_connection 拒绝；持有者断开后，其镜像工具被注销、在途调用被拒绝，该命名空间立即接受替代连接。不同命名空间的客户端并发连接，互相看不见对方的工具。

注册以 register 批次为单位、整批生效或整批拒绝：批次内任一工具校验失败或名称冲突，整批以非致命的 invalid_tool 错误拒绝，客户端可修正定义后再次发送 register。每个被接受的工具以公开名 __（沿用 mcp-client 契约）出现在 ctx.tools 上：名称被规范化到模型函数名字母表 [A-Za-z0-9_-] 与 64 字符预算内；凡规范化造成损失的名称都会追加 12 个十六进制字符的 SHA-256 身份哈希，确保不同的客户端名称永不合并。会使整桥超过 maxTools 上限的批次以非致命的 too_many_tools 错误拒绝。unregister 批次按原始名移除工具，并以实际移除的原始名应答（未知名被忽略），释放的公开名可在同一连接上再次注册。

模型调用以 call 帧转发给持有会话的连接，帧携带客户端的原始工具名（公开名绝不回传）；promise 在收到匹配的 callResult 时落定，在调用方通过 exec.signal 中止时拒绝，连接断开或 callTimeoutMs 期限内无应答时同样拒绝。被放弃或已超时调用的迟到 callResult 会被丢弃，不影响会话。结果渲染为格式化 JSON 文本；客户端未声明输出 schema 时默认为任意 JSON。

存活探测每 15 秒发送一个 ping 帧；下一个探测到期时仍未应答的探测会终止会话（close 路径负责完整的清理链：注销工具、拒绝在途调用、接受替代连接）。

管理工具

接入一个应用的日常方式是对话，而不是改配置。凭证归应用所有：应用生成 DSH KEY（客户端 SDK 的 generateClientKey）并展示给用户，用户把它交给模型，模型通过 ctx.tools 上的管理工具完成登记。

• frontend_tools_register_client(namespace, key) — 把应用提供的 DSH KEY 登记到该命名空间并持久化，返回 { namespace, url, replaced }；输出绝不回显 KEY（用户消息里已有，多一份副本只会扩大会话日志的暴露面）。对同一命名空间重复登记会立即替换旧凭证（旧 KEY 随即失效）；已绑定其他命名空间的 KEY 会被视为身份冲突而拒绝，不符合 64 位十六进制格式的 KEY 同样被拒绝。