dsh-ultron-browser-relay

面向鸿蒙 PC（HarmonyOS）上海泰浏览器（Haitai Browser）内置的 OpenClaw Ultron Browser Relay 扩展的中继服务与 DeepSeek Harness 插件。

让 DeepSeek Harness（DSH）直接控制真实浏览器里已 attach 的标签页：读取/总结网页、导航、点击、填表、截图、开关标签页。无需安装 OpenClaw。

背景

鸿蒙 PC 的海泰浏览器（com.haitai.htbrowser）内置了 OpenClaw Ultron Browser Relay 扩展（v0.1.0，ID jpnjfphggjeblcocmlkmnkngokpicgna）。该扩展：

• 在标签页上点图标即可 attach（chrome.debugger，图标变 ON），再点一次 detach；
• 把标签页的 CDP 流量经 WebSocket 中继到本机：ws://127.0.0.1:18792/extension?token=<HMAC派生token>；
• token 派生规则：HMAC_SHA256_HEX(gatewayToken, "openclaw-extension-relay-v1:{port}")，默认 gatewayToken 为 harmony_openclaw（扩展 Options 里可改）；
• 同时还有一个面向鸿蒙侧的 augmented-bridge 连接（默认端口 18888，本服务不依赖它）。

本仓库实现该扩展的服务端：接收中继、转发 CDP 命令、提供 agent 可用的控制 API，并以 DSH 插件形式交付。

架构

浏览器标签页（用户在扩展图标上点一下 attach，badge ON）
    ↕ chrome.debugger
海泰浏览器内置 OpenClaw Ultron Browser Relay 扩展
    ↕ WebSocket ws://127.0.0.1:18792/extension?token=<hex>
本服务（standalone server.js 或 DSH 插件，均监听 127.0.0.1）
    ↕ 控制 API http://127.0.0.1:18793
DeepSeek Harness agent（bash/curl 调用）

组件

路径	说明
package.json	DSH 插件包根（仓库根即 npm 包，声明 dsh.bundle.patch）
lib/index.js	插件体：启动中继 + 注册 browser-relay 技能
lib/relay.js	中继核心（startRelay()）
cordis.patch.yml	插件树条目与默认配置（端口/token）
server.js	独立版中继服务（不装插件时调试用；不进 npm 发布包）
relayctl	控制 API 的 bash 助手
mock-extension-test.js	模拟扩展客户端（离线自测协议）

快速开始

浏览器侧

1. 打开海泰浏览器，确认 Ultron Browser Relay 扩展已启用。
2. 扩展 Options：Relay 端口 18792（默认即可）。
3. 在要控制的标签页上点扩展图标 attach（图标变 ON）。

服务侧（二选一）

方式 A：DSH 插件（推荐）

# 从 GitCode 仓库直接安装（HTTPS，仓库根即插件包，无需子目录）
dsh plugin --profile web add "git+https://gitcode.com/hu60cn/dsh-ultron-browser-relay.git" --config.minimumReleaseAge=0
# 或本地路径安装
dsh plugin --profile web add /path/to/relay-server --config.minimumReleaseAge=0
# 或发布到 npm 后
dsh plugin --profile web add dsh-ultron-browser-relay --config.minimumReleaseAge=0

重启 dsh web 生效。插件会：启动中继（18792/18793）、自动注册 browser-relay 技能。之后任何会话只需说"用浏览器打开 xxx / 总结这个网页"，agent 会自动加载技能操作浏览器。

方式 B：独立服务

cd <仓库目录>
npm install        # 只需 ws
node server.js     # RELAY_TOKEN=any 接受任意 token（仅回环）

配置（可选）

编辑 ~/.dsh/profiles/web/cordis.patch.yml 里 browser-relay 条目的 config（改完重启 dsh web 生效）：

- insert:
    - id: browser-relay
      name: 'dsh-ultron-browser-relay'
      config:
        relayPort: 18792   # 扩展连接的端口（对应扩展 Options 的 Relay port）
        controlPort: 18793 # agent 控制 API 端口（仅 127.0.0.1）
        token: ''          # 留空 = 接受任意 token；可设固定值校验

DSH 技能（新会话怎么用）

插件启动时自动注册一个 browser-relay 技能到 DSH 技能目录，任何新会话的 agent 都能发现并加载：

• 直接说"用浏览器打开 xxx" / "读取并总结这个网页" / "控制我的浏览器"——agent 会自动加载该技能，按说明用 curl 调控制 API 操作已 attach 的标签页。
• 也可显式说"加载 browser-relay 技能"，或先问"你有哪些技能？"确认它在目录里。
• 前提：目标标签页上扩展图标是 ON（已 attach）。

控制 API（127.0.0.1:18793）

GET  /status   中继与扩展状态、已 attach 的 session（sessionId/targetId）
GET  /tabs     已 attach 的 session 列表
GET  /events?after=N   CDP 事件流（Page.loadEventFired 等）
GET  /log?tail=N       中继日志
POST /cdp      {"sessionId"?, "method": "<CDP方法>", "params": {...}}
POST /eval     {"sessionId"?, "expression": "..."}         # Runtime.evaluate
POST /nav      {"sessionId"?, "url": "..."}                # Page.navigate
POST /shot     {"sessionId"?, "file"?: "/abs/path.png"}    # Page.captureScreenshot
POST /open     {"url": "..."}        # 新标签页（扩展自动 attach）
POST /close    {"targetId"?: "..."}  # 关标签页
POST /activate {"targetId"?: "..."}  # 激活标签页

sessionId（形如 cb-tab-1）可省略——扩展会回退到任意已 attach 的标签页；多标签页时建议显式指定。命令默认超时 30s（可传 timeoutMs）。

线协议要点（Ultron 扩展专用，与官方 OpenClaw 协议不同）

• 命令（服务端 → 扩展）：{"id":<n>,"method":"forwardCDPCommand","params":{"sessionId"?,"method":<CDP方法>,"params":{...}}}
• 响应（扩展 → 服务端）：{"id":<n>,"result":...} 或 {"id":<n>,"error":"..."}
• 事件（扩展 → 服务端）：{"method":"forwardCDPEvent","params":{"sessionId"?,"method":<CDP方法>,"params":{...}}}（含 Target.attachedToTarget / Target.detachedFromTarget）
• 心跳：服务端 {"method":"ping"} → 扩展 {"method":"pong"}；augmented-bridge 的 {"type":"PING"} 需回 {"type":"PONG"}
• 支持多连接并存（background relay 与 augmented bridge 可能同时连上来），CDP 命令只发给 relay 角色的连接
• attach 状态由扩展维护；导航后扩展自动重挂标签页（新 sessionId 出现在 /tabs）

开发与测试

# 协议自测（模拟扩展，不要对运行中的真实服务跑）
node mock-extension-test.js

发布到 npm

cd <仓库目录>        # 仓库根即插件包
npm publish --dry-run   # 检查 tarball 内容
npm publish

注意：pnpm 11 默认拒绝"发布未满 24 小时"的包，刚发布安装时加 --config.minimumReleaseAge=0。

常见问题

• 端口被占用：插件检测到 18792 被占会告警并跳过（不会崩溃）；standalone 与插件不要同时运行。
• Session with given id not found：session 已失效（标签页被 detach/关闭）。重新 attach 或看 /status 里的新 sessionId。
• badge 一直不 ON：扩展未连上中继——检查 Options 端口、服务是否在跑。
• 扩展断线：会自动重连并重新上报已 attach 的标签页，无需人工干预。

许可证

Apache-2.0（见 LICENSE）