前言¶
DeepSeek Harness (DSH) 代理在与网页交互时，通常缺乏直观的反馈机制和深度调试能力。开发者需要代理能像人类一样操作页面、查看细节，并携带上下文与对话。
dsh-browser-annotate 插件解决了这个问题。它通过一个 Electron 桌面应用提供真实的 Chromium 浏览器环境，并集成了 Chrome DevTools Protocol (CDP) 访问权限。插件与桌面应用通过本地 HTTP 循环回环通信（127.0.0.1:7391），为代理提供了一套完整的浏览器操作工具，同时支持用户通过右键注释直接向对话注入前端事实。
核心功能¶
插件提供十二种浏览器操作工具，覆盖从基础导航到复杂交互的全链路：
openBrowserPage：在浏览器中打开新标签页，若目标不可达会返回真实的 Chromium 错误。navigatePage：支持 URL 导航、刷新、前进和后退。readPage：获取页面可访问性树快照，支持通过选择器范围限定。screenshotPage：支持视口或元素截图，并作为图片附件返回。clickElement/hoverElement/typeInPage：基于元素引用或选择器进行点击、悬停和输入，支持回车提交。dragElement：通过引擎执行拖拽，若引擎不支持则回退到 Playwright 的dragAndDrop。handleDialog：处理alert/confirm/prompt对话框，不再自动回答。runPlaywrightCode：通过 CDP 在应用 Chromium 上执行自定义 Playwright 函数。cdp：支持调用任何 Chrome DevTools Protocol 方法（如 Input、DOM、Runtime、Network 等）。annotations：读取和管理用户创建的注释队列。
此外，插件具备以下特性：
- 右键注释与检查：在浏览器中右键点击元素，可快速添加注释或进入开发者模式检查 DOM。
- 注释队列机制：支持将选中的元素信息（包括 CSS 选择器、DOM 路径、截图、计算样式等）加入队列，最后统一注入到对话中。
- 双栏布局：左侧为 DSH Web UI，右侧为真实 Chromium 浏览器，互不干扰。
安装与启用¶
安装该插件需使用 DSH 的插件命令，该仓库不作为 npm 包发布。
# 安装插件
dsh plugin --profile web add github:iimaguest/dsh-browser-annotate
# 更新到最新提交
dsh plugin --profile web update dsh-browser-annotate
# 卸载插件
dsh plugin --profile web remove dsh-browser-annotate
安装后，DSH 启动时会加载该插件。若未启动桌面应用，代理调用浏览器工具时会收到“桌面浏览器未连接”的提示，而不会导致程序崩溃。
使用示例¶
- 启动桌面应用：在终端运行以下命令启动 Electron 应用，并传入 DSH Web UI 的 token 地址。
./dev.sh 'http://127.0.0.1:3090/?token=…'
后续启动可省略 URL，应用会读取 `.dev-url` 文件。
- 操作浏览器：代理可以使用上述十二种工具对页面进行操作。
- 管理注释：用户可以在浏览器中右键添加注释，或使用插件提供的命令管理队列。
# 列出当前队列中的注释（结果附带截图）
annotations list
# 将注释队列注入到对话输入框中
annotations inject
# 清除已注入或未处理的注释
annotations clear
架构与限制¶
插件与桌面应用各司其职：
- 插件端：提供 DSH 侧的 HTTP 路由和工具定义，不加载任何 DSH 服务。
- 桌面端：运行真实 Chromium，处理页面渲染和用户交互。
已知限制：
- 标签页关闭：Electron 应用中的标签页关闭需手动操作（快捷键
⌘W），代理工具尚未实现自动关闭标签页。 - CDP 限制：Electron 不支持
Target.createTarget和Target.createBrowserContextAPI，因此无法通过代理直接创建新的浏览器上下文，只能通过openBrowserPage打开新标签页。 - 启动安全：首次启动 macOS 的 DMG 安装包时，由于系统安全限制，通常需要右键打开或手动在“隐私与安全性”中允许运行。
结尾¶
dsh-browser-annotate 通过将真实的浏览器环境、CDP 访问权限与注释队列机制结合，填补了 DSH 在网页交互和深度调试方面的空白。它既能让代理像操作员一样使用浏览器，也能让人类通过直观的注释将前端事实直接反馈给智能体。
