浏览器助手 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 test # 发布门禁：typecheck + 全部离线校验（scripts/run-tests.mjs）
pnpm test:e2e # 两条实机 e2e 一条命令跑完；需要运行中的 dsh
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 # 24 项离线断言：sessionWorkspace 契约 + 诊断轨迹 + 插件接线
pnpm check:permission # 43 项离线断言：权限档位规则 + spec 场景覆盖分类
pnpm check:grouping:status # 只读排查（不连 dsh）：注册表成员 vs 目录下真实会话文件
pnpm check:selection:e2e # 实机端到端：对运行中的 dsh 验证会话选择
pnpm check:grouping:e2e # 实机端到端：经真实桥发起 session.create,并从 Workspace 注册表断言

离线脚本不需要 dsh、不需要 Chrome、不需要网络——它们用 esbuild 打包真实源码后在 Node 里断言 spec 场景；pnpm test 经 scripts/run-tests.mjs 一口气跑完它们（外加 typecheck），是每次发布必须通过的门禁。桥接自身的 typecheck 需要 dsh 宿主框架类型（@deepseek-ai/），它们随 dsh 安装在本机：首次 checkout 后跑一次 bash scripts/link-dsh-types.sh 把类型软链进包内。check:grouping:status 只读磁盘上的注册表与会话目录，用来回答「会话为什么没进分组」；两个 :e2e 脚本需要运行中的 dsh（check:grouping:e2e 还需配置 sessionWorkspace）；它们会短暂顶替 Chrome 面板的桥连接（桥同一时刻只服务一个，扩展会自行重连），且每次运行都会创建一个真实会话。

发布版本

两半独立发布：

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

打 tag 必须走发布门禁脚本——离线套件不通过就拒绝打 tag：

bash scripts/tag-release.sh bridge-dsh 0.3.0 # typecheck + pnpm test 通过后才打 tag 并推送 bash scripts/tag-release.sh bridge-browser 0.3.0 --e2e # 另加实机 e2e（需要运行中的 dsh）

脚本先核对版本号与对应包的 package.json（扩展还要核对 manifest.json）一致，再跑门禁，全部通过才创建并推送 tag；任何一步失败都不会产生 tag。推送后的 tag 触发下方流水线，流水线在构建前会再跑一遍同一套离线套件。

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

- bridge-dsh —— 从 npm 安装：dsh plugin --profile web add -w "bridge-dsh@0.3.0" --config.minimumReleaseAge=0（其 release 也附了 bridge-dsh-0.3.0.tgz）
- bridge-browser-0.3.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