dragonTalon/dsh-browser-assistant

dsh 浏览器助手

让 DeepSeek Harness（dsh）读取、操作你正在使用的真实浏览器标签页：页面变成纯文本结构化快照，模型按编号寻址元素，登录态、会话、Cookie 全保留。

一个 pnpm workspace，两半由一条 WebSocket 连接：

- packages/bridge-dsh —— dsh Cordis 插件，发布为 bridge-dsh 0.2.0，挂载 /ext/bridge，注册 12 个 browser_ 工具。
- packages/extension —— Chrome MV3 扩展，发布为 bridge-browser 0.2.0（service worker + content script + side panel）。

模型工具链路纯文本——页面渲染为结构化文本快照，工具侧不截图。另外，面板提供用户主动框选，可把选区截图（裁剪）发给视觉模型。完整设计见 docs/zh/architecture.md。

能力

| 能力 | 实现 |
|---|---|
| 读页面 | browser_snapshot → 标题/URL/正文/编号控件/表单；delta:true 只返回变化 |
| 操作 | browser_click / browser_type / browser_press / browser_scroll 按稳定编号 |
| 导航 | browser_navigate / browser_open_tab / browser_back / browser_forward / browser_reload |
| 读区域/等待 | browser_get_text / browser_wait |
| 问用户 | dsh 的 ask_user_question 显示在面板，作答回传模型 |
| 页面感知 | 扩展追踪活动标签页，把 URL/标题注入每条消息作为上下文 |
| 框选截图 | 用户从面板框选页面区域 → 裁剪截图 + 选区内 DOM 元素清单 → 发给视觉模型 |
| 模型选择 | 面板连接后重拉 model.catalog；下拉框带能力标记（视觉/文本/未知）→ session.selectModel |
| 会话选择 | 下拉列出 session.list，默认「新会话」；会话在首次发送、首次为本会话选模型、或在「新会话」下唤出 / 菜单时创建。选中历史会话即绑定并重放其历史——不再产生孤儿会话，也不走 session.create |
| 斜杠命令与技能 | 输入 / 弹出可过滤、可键盘操作的菜单，列出所绑定会话的宿主命令与用户可调用技能：命令走 commands.execute（整行透传，含参数），技能作为普通消息发送；命令的 command/run/command/done 生命周期呈现在对话里 |
| 会话分组 | 配置 sessionWorkspace 后，扩展创建的会话自动归入该 dsh 工作区——在 dsh 侧边栏按目录分组，而不是堆在「未分组」桶里 |

安全模型：桥自带 bearer token；读默认放行，写操作 fail-closed 需面板审批；密码/卡号掩码、永不离开页面。远端连接必须提供 token，且不会放宽以上任何一条。

前置要求

- Node.js ^22 与 Corepack/pnpm
- dsh ≥ 0.1.2-rc.1 —— 最低支持版本（0.1.x 的 Typert Gateway + Connection 架构）；已在 0.1.3-alpha.1 上验证
- Chrome 116+

安装

桥插件发布在 npm；Chrome 扩展以打包好的 zip 放在 GitHub Releases。无需本地编译。

1. 从 npm 安装桥插件

dsh plugin --profile web add -w "bridge-dsh@0.2.0" --config.minimumReleaseAge=0

请固定版本，不要用 @latest。 pnpm 11 起 minimumReleaseAge 默认为 1440 分钟（1 天）：发布不满一天的版本会被挡下，而 @latest 这类 dist-tag 会静默装成上一个版本（不报错）。--config.minimumReleaseAge=0 用于本次安装取消这一等待。桥插件与扩展是版本配对的，请始终安装与你的 bridge-browser zip 相匹配的版本。

2. 下载 Chrome 扩展

gh release download bridge-browser@0.2.0 --repo dragonTalon/dsh-browser-assistant
→ bridge-browser-0.2.0.zip

3. 重启 dsh 并验证

cd ~/.dsh && dsh web
curl http://127.0.0.1:3080/ext/bridge-config
→ {"wsUrl":"ws://127.0.0.1:3080/ext/bridge"}

4. 加载扩展

解压 bridge-browser-0.2.0.zip，然后 chrome://extensions → 开启「开发者模式」→「加载已解压的扩展程序」→ 选解压出来的文件夹。打开任意 http(s) 页面，点扩展图标打开侧边栏，等「已连接 dsh」，即可对话。

5. 远端 dsh（可选）

dsh 跑在另一台机器上时，打开面板状态栏的齿轮按钮「系统配置」，填入地址（10.0.0.7:3080 或 wss://dsh.example.com）与那台机器上的 token（cat ~/.dsh/ext-bridge-token），保存前先点「测试连接」——它会做一次独立握手，并明确告诉你地址不可达还是 token 被拒绝。地址留空则维持零配置的本机自动发现。

被钉在回环上的方法（settings.、credentials.*、host.openPath、host.pickDirectory）在远端连接下始终不可用——这是桥自身的信任边界，不是配置弹窗的缺陷。

从源码构建（可选）

pnpm install --frozen-lockfile
pnpm build
→ packages/bridge-dsh/lib/index.js  与  packages/extension/dist/

本地开发时注意：dsh plugin add 安装的是打包快照（~/.dsh/profiles//node_modules/bridge-dsh/），重建 workspace 的 lib/index.js 不会影响正在运行的 dsh。每次改了 bridge 的源码后：

bash packages/bridge-dsh/build.sh       # 重建工作区产物
bash scripts/sync-profile.sh            # 拷贝进已安装的插件目录（自动备份）
然后重启 dsh（或重载该插件）让新 bundle 生效

上述拷贝替换的是 profile 里的文件，而正在运行的 dsh 仍持有它已经 import 的模块。热重载补丁只会用新配置重跑插件的 apply()，用的仍是旧模块，所以改了源码必须重启 dsh。

校验脚本

pnpm typecheck                  # 三个包的 tsc --noEmit
pnpm check:slash                # 28 项离线断言：斜杠词汇 + 目录生命周期
pnpm check:ordered-rpc          # 7 项断言：以真实 WebSocket 驱动真实 BridgeServer,
验证保序 RPC 的有界等待释放队列槽位而非挂死会话
pnpm check:grouping-lifecycle   # 6 项断言：连接替换后工作区分组仍能注册
pnpm check:selection            # 32 项离线断言：会话选择（缓冲、seq、历史重放）
pnpm check:grouping             # 16 项离线断言：sessionWorkspace 契约
pnpm check:selection:e2e        # 实机端到端：对运行中的 dsh 验证会话选择
pnpm check:grouping:e2e         # 实机端到端：经真实桥发起 session.create,并从 Workspace 注册表断言

五个离线脚本不需要 dsh、不需要 Chrome、不需要网络——它们用 esbuild 打包真实源码后在 Node 里断言 spec 场景。两个 :e2e 脚本需要运行中的 dsh（check:grouping:e2e 还需配置 sessionWorkspace）；它们会短暂顶替 Chrome 面板的桥连接（桥同一时刻只服务一个，扩展会自行重连），且每次运行都会创建一个真实会话。

发布版本

两半独立发布：

| 产物 | 包名 | 版本 | Git tag |
|---|---|---|---|
| dsh bridge 插件 | bridge-dsh | 0.2.0 | bridge-dsh@0.2.0 |
| Chrome 扩展 | bridge-browser | 0.2.0 | bridge-browser@0.2.0 |

桥插件已发布到 npm：bridge-dsh。每个 tag 也都有对应的 GitHub Release，附带构建产物，由打 tag 触发的流水线（.github/workflows/release.yml）自动生成：

- bridge-dsh —— 从 npm 安装：dsh plugin --profile web add -w "bridge-dsh@0.2.0" --config.minimumReleaseAge=0（其 release 也附了 bridge-dsh-0.2.0.tgz）
- bridge-browser-0.2.0.zip —— 扩展包；chrome://extensions → 「加载已解压的扩展程序」加载（或提交 Chrome 应用商店）

每次发布的说明都是中英双语，由对应包的变更日志生成，因此不会与真正发布的内容脱节：packages/bridge-dsh/CHANGELOG.md · packages/extension/CHANGELOG.md。

目录结构

packages/protocol/     共享零依赖帧协议（唯一真相源）
packages/bridge-dsh/   dsh bridge 插件（Cordis）
packages/extension/    Chrome MV3 扩展（background / content / panel）
docs/en/ docs/zh/       架构与功能文档（EN / 中文）

文档

文档为中英双语，每页都有 EN | 中文 切换：

- 整体架构 · English
- 线协议 · English
- bridge 插件 · English
- Chrome 扩展 · English