前言¶
做浏览器自动化时，常见做法是让 Agent 在一个用户看不见的 headless 进程里跑。问题是：页面发生了什么、Agent 点了哪里，用户都无从确认；遇到需要登录或人工判断的环节，也没有自然的交接手段。
dsh-browser-plus 针对的就是这个问题。它把浏览器窗口留在用户眼前，同时给 Agent 提供可靠的 CDP 操作能力，用户可以在真实页面中直接操作，Agent 也能同步执行、接管和恢复任务。
这是什么¶
dsh-browser-plus 是专为 DeepSeek Harness（DSH）打造的 EGO 风格可视化 Agent 浏览器插件，由 ParticleLight 基于 MIT 许可的 dsh-browser 代码基础持续开发并独立维护，当前版本为 0.4.1。它是一个真实的 Electron 可视化窗口，不是 headless relay，支持多任务流并行管理与切换，并完整记录 Agent 的操作轨迹。
核心功能¶
真实可见的窗口¶
浏览器基于 Electron WebContentsView 呈现，用户能直接看到 Agent 正在操作的页面。输入、点击、滚动都发生在真实页面上。
任务隔离与玻璃工作区¶
所有 DSH session 共享一个可见窗口，但各自保留隔离的任务视图、标签与历史；browser_space 可以为浏览器任务命名。任务与操作轨迹是彼此独立的半透明玻璃面板，可同时打开，每项任务显示执行中、等待用户、用户接管、失败或空闲状态。缩略图仅在任务面板打开时为当前可见任务按需刷新，后台任务保留最后图像。
页面 chrome 和任务管理器通过 closed Shadow DOM 注入，不依赖第二个 Electron view。任务状态与轨迹以版本化增量消息同步，后台任务更新自己的隔离视图，不会抢走用户当前可见页面。
人机协作与交接¶
工具栏默认隐入页面上方，顶部中间悬停后展开。用户可以在工具栏最右侧接管任务，也可以显式把任务交还给 Agent，配合 browser_handoff 完成交接。
真实输入与工具集¶
键盘、鼠标、hover、双击和文件选择都走 CDP，而不是 element.click() 伪事件。插件提供的 browser_* 工具按场景分组：
| 场景 | 工具 |
|---|---|
| 打开与读取 | browser_open、browser_snapshot、browser_content、browser_screenshot |
| 语义导航 | browser_back、browser_forward、browser_reload、browser_stop、browser_scroll |
| 快照引用 | browser_click_ref、browser_scroll_into_view |
| 页面交互 | browser_click、browser_press_key、browser_double_click、browser_hover、browser_type |
| 表单与文件 | browser_fill、browser_upload_file、browser_wait_for |
| 任务与交接 | browser_tasks、browser_handoff、browser_list_tabs、browser_switch_tab、browser_close_tab、browser_space |
| 登录与恢复 | browser_auth、browser_reset_session、browser_history |
恢复能力与稳定基线¶
child 回收后会重新物化相同会话的视图，恢复后的首张截图等待 compositor 稳定。版本上固定 Electron 42.9.3；43.4.1 的 compositor 故障会被 resolver 拒绝，避免引入已知问题。可靠性规则包括：不 reparent 可见 WebContentsView，CDP capture 回退只临时处理同一窗口的 sibling 并保证恢复；对话框、截图、动态等待和 child recovery 均有回归测试与真实 SOAK 覆盖。
安装与启用¶
使用官方安装命令：
dsh plugin --profile web add github:ParticleLight/dsh-browser-plus
如果机器上已有浏览器 bundle，先阅读仓库中的 docs/MIGRATION.md 迁移指南，然后重启 DSH Web 完成启用。
环境要求：Node >= 22.19。插件固定 Electron 42.9.3，peerDependencies 包含 @deepseek-ai/cordis ^4.0.1。
典型用法¶
快照与引用操作¶
快照返回短生命周期的 snapshotId 与元素引用。推荐的操作顺序如下：
- 用
browser_open打开页面； - 用
browser_snapshot获取快照与元素引用； - 优先用
browser_click_ref或browser_scroll_into_view操作引用； - 页面发生变化后重新快照，再继续操作。
页面级脚本会自动过滤浏览器自身 chrome，不会误操作插件注入的工具栏。
对话框处理¶
alert、confirm、prompt 会自动接受，避免页面卡死；下一次页面操作会把详情记入 browser_history 的 dialog 条目，Agent 和用户都能追溯。
工作链路¶
从工具到窗口的调用链如下：
browser_* tools
-> BrowserRuntime (ctx.browser seam)
-> ElectronBrowserProvider (CDP)
-> RemoteElectronViewHost (loopback JSON-RPC)
-> host-main.js (BrowserWindow + WebContentsView)
开发与验证¶
需要参与开发时，按以下步骤构建和验证：
npm install
npm run build
npm test
npm run smoke:electron-host
其中 npm run smoke:electron-host 需要本地 DSH Web 已启动，用于验证真实 Electron Host 的导航与页面交接。完整运行时检查清单见 docs/SOAK-CHECKLIST.md，贡献方式见 CONTRIBUTING.md，更完整的使用说明在 docs/README.md。
适用场景与注意事项¶
适合需要在 DSH 中做网页操作、又希望全程可见、可人工介入的场景，例如需要登录态的页面任务、多任务流并行浏览、以及用户与 Agent 交替操作页面的工作流。
安装前请注意：
- 插件以当前 dsh 进程的权限运行，安装前建议检查仓库源码；
- 许可证为 MIT，详见仓库中的
LICENSE与NOTICE.md； - 如果从旧版浏览器 bundle 迁移，务必先阅读
docs/MIGRATION.md。
小结¶
dsh-browser-plus 解决的是 Agent 浏览器自动化里「看不见、管不了、断线难恢复」三个问题：真实可见的 Electron 窗口、任务隔离与显式交接、以及 child 回收后的会话恢复。经过上面的步骤即可完成安装和验证，更多细节见插件目录页与 GitHub 仓库：
- 目录页：https://www.skillhub.cn/plugins/ParticleLight/dsh-browser-plus
- GitHub：https://github.com/ParticleLight/dsh-browser-plus
