Chrome 浏览器 Aurora-Lucas/dsh-chrome-browser

chrome-browser

DeepSeek Harness 插件，给模型提供 chrome 工具：它通过 Chrome DevTools Protocol 驱动机器上安装的 Google Chrome，做前端时可以导航、截图、检查、与真实渲染的页面交互。

这个工具跑在 Harness Host 进程里，由此带来两点值得注意：

- 每次调用无需审批。 chrome 调用就是普通工具调用，从不申请 shell 或沙箱权限。
- 不受 bash 文件沙箱影响。 Chrome 在 Landlock 限制的 shell 下无法启动（会以 chrome_crashpad_handler: --database is required 中止），所以在加固过的 Host 上，直接跑 google-chrome --headless … 这样的 bash 命令会失败。Host 进程不受限制，插件就跑在那里。

截图会作为真实图片放进工具结果（当模型路由接受图片输入时）并且写入文件，这样模型能看到渲染后的 UI，人也能在事后打开那张一模一样的 PNG。

下面这张真实渲染图就是工具自己截的 —— astro.build，1280×800：

astro.build rendered in headless Chrome by the chrome tool

工具参考

只有一个工具 chrome，带一个 action 参数。页面 id（p1、p2……）由 open 生成；之后每个 action 都可以带一个可选的 page，不带就用最近的那个。

| Action | 关键参数 | 结果 |
| open | url、width、height、deviceScaleFactor、mobile | 需要时启动 Chrome，打开一个页面。 |
| goto | url、page | 导航到已打开的页面并等待加载完成。 |
| screenshot | path、fullPage、selector、width、height、scale | PNG 图片 + 保存路径；默认截视口。 |
| viewport | width、height、deviceScaleFactor、mobile | 调整模拟视口大小（做响应式检查）。 |
| dom | selector、maxChars | 整个文档或某个元素的 outerHTML。 |
| text | selector、maxChars | body 或某个元素的 innerText。 |
| eval | expression、maxChars | 在页面里执行 JavaScript，返回 JSON 值。 |
| click | selector 或 x/y、button、clickCount | 在元素中心触发真实鼠标事件。 |
| type | selector、text、clear、submit、delayMs | 聚焦、清空、插入真实输入事件。 |
| press | key | Enter、Tab、Escape、方向键、Home、End、PageUp、PageDown、Backspace、Delete、Space。 |
| wait_for | selector 或 text、timeoutMs | 轮询直到选择器匹配或文本出现。 |
| console | clear、limit | 收集到的 console.* 调用、未捕获异常、浏览器日志条目。 |
| network | clear、limit | 附加期间看到的失败请求和 HTTP 4xx/5xx 响应。 |
| pdf | path | 把页面打印成 PDF 文件。 |
| tabs | – | 列出已打开的页面。 |
| close | page | 关闭一个页面。 |
| stop | – | 关闭 Chrome，并删除它的临时配置档。 |

环境要求

- Google Chrome 或 Chromium（任意较新版本；开发时用的是 Chrome 155）。
- Node.js 22+（用到全局 WebSocket）。
- 无 npm 依赖：插件只导入同级的兄弟模块和 Node.js 内置模块。
- 页面含中日韩文字时，装一款中日韩字体（Debian/Ubuntu 上执行 apt-get install fonts-noto-cjk）；不装的话，截图里这些字形会渲染成空方块。

安装到 Harness 配置档

Host 只从自己的模块根目录导入插件（配置档和 dsh 安装目录），所以必须把打包产物真正复制到配置档里，不能用软链接指向某个检出目录：

npm pack # -> local-dsh-chrome-browser-<version>.tgz

然后通过 Harness 插件管理器安装这个 tarball（plugin_manager，action: install_bundle，target = tarball 的绝对路径）。如果替换掉已安装的包，Host 会返回 restart-required；重启 dsh web 以加载新的模块代际。版本号一升，依赖规格就变了，更新才能被检测到。

配置

bundle 补丁会设置下面这些项；apply 把它们合并到自己的默认值之上，并做校验。

| 键 | 默认值 | 含义 |
| chromePath | ''（自动检测） | Chrome 可执行文件。 |
| headless | true | 无窗口运行。 |
| noSandbox | true | 传入 --no-sandbox（Host 以 root 运行时必需）。 |
| defaultWidth / defaultHeight | 1280 / 900 | 默认视口。 |
| maxOutputChars | 100000 | dom/text/eval 输出的默认上限。 |
| navigationTimeoutMs | 30000 | 导航和 wait_for 的时间预算。 |
| artifactDir | ''（系统临时目录） | 未给 path 时，截图和 PDF 的存放位置。 |

Chrome 是怎么定位的

工具 schema 里没有路径参数：模型不需要知道浏览器装在哪。resolveChromePath 按下面的顺序解析，全都不匹配就报错，错误信息里会点名对应的配置键，方便你直接改：

1. 当前行的 chromePath 配置；
2. DSH_CHROME_PATH 环境变量；
3. 一份探测列表 —— /usr/bin/google-chrome、google-chrome-stable、google-chrome-beta、 /usr/bin/chromium、chromium-browser、/opt/google/chrome/chrome、/snap/bin/chromium，再加上 macOS 和 Windows 的常见位置。

安装位置比较特殊的话，给 Host 设 DSH_CHROME_PATH，或者改当前行的 chromePath —— 不用改代码。

测试

两套无依赖的测试套件会驱动真实的 Chrome（不需要测试框架）：

node test/engine.test.mjs # CDP engine: navigation, capture, input, console, network, multi-page, teardown
node test/tool.test.mjs # the real tool definition: schema validation, every action, error paths

在仓库根目录运行；tool.test.mjs 会把用完即弃的截图写到 .tmp/ 下。

运维说明

- Chrome 在第一次操作时才会惰性启动，运行时使用全新的临时配置档；stop（或插件销毁）会终止它并删除该配置档。
- 所有页面共用一个 Chrome 进程，所有会话也共用它。
- 页面高度超过 12000 CSS px 的截图会被截断，如果裁剪截图超出部署的图片限制，会以一半比例重试一次。
- 如果没有可用的附件服务或支持图片的路由，screenshot 仍会保存 PNG 并报告路径，而不是附加图片。

License

MIT — 见 LICENSE。