DSH 浏览器控制配置指南

August 13, 2026 · View on GitHub

本仓库发布 @deepseek-ai/dsh-tool-browser 的静态 Cordis overlay 和接入指南，不分发工具实现、DSH 运行时、浏览器二进制文件或凭据。

可用性

当前仅为静态配置候选。 使用获授权的 registry 只读访问探测显示 @deepseek-ai/dsh-tool-browser 返回 HTTP 404，也没有发现官方改名包。本仓库可以离线验证 overlay 语法和文档，但无法从 npm 产物安装工具或宣称运行时兼容性。

必须等官方工具包通过权威来源可用后，才能进行运行验收；不要用名称相似的第三方包代替。

后续运行验收要求

兼容的 DSH 安装，并且插件加载器已经能够解析 @deepseek-ai/dsh-tool-browser。
目标机器已安装 Chrome、Edge 或 Playwright Chromium，并能通过 channel 或可执行文件路径访问。
部署环境已经配置适合浏览器访问的权限与网络策略。

内容

examples/browser-control/         参考 overlay 与双语使用指南
scripts/verify-release.mjs        无外部依赖的静态发布门禁
README.md / README.zh.md          行为、配置与验收说明
SECURITY.md                       安全边界与报告方式
LICENSE                           BSD 3-Clause

工具

工具	行为
`browser_open`	打开调用代理的浏览器页面；应先于其他浏览器工具调用
`browser_navigate`	导航到绝对 HTTP(S) URL
`browser_click` / `browser_type`	操作匹配 CSS 选择器的第一个元素
`browser_extract`	提取选择器或整页正文中的可见文本
`browser_screenshot`	将 PNG 截图写入配置的目录
`browser_list` / `browser_close`	报告浏览器状态 / 关闭浏览器页面

浏览器页面归属于各自的调用代理。不要依赖一个代理能够观察或控制另一个代理的页面。

条件式配置

官方包可用后，可以使用 examples/browser-control/browser.cordis.yml 中的参考 overlay，也可以在装配中加入等价的插件行：

- insert:
    - id: tool-browser
      name: '@deepseek-ai/dsh-tool-browser'
      config:
        headless: true
        channel: chrome

仓库内的 overlay 不设置 channel 或 executablePath，由部署环境明确选择浏览器。下面的命令用于后续运行验收，目前尚未针对 npm 包完成验证：

dsh --config "$PWD/examples/browser-control/browser.cordis.yml"

浏览器选择

请根据目标机器选择一种受支持的方式：

channel: msedge 使用 Microsoft Edge；
channel: chrome 使用 Google Chrome；
executablePath 使用受管理的浏览器二进制文件；或
由部署管理员安装 Playwright Chromium 后使用其默认值。

配置项

键	默认值	含义
`channel` / `executablePath`	未设置	浏览器 channel / 可执行文件路径
`headless`	`true`	无头模式
`launchTimeoutMs`	`30000`	启动超时
`screenshotDir`	系统临时目录	截图输出目录
`actionTimeoutMs`	`15000`	DOM 操作超时
`maxExtractChars`	`100000`	单次提取字符上限

验证仓库

运行无外部依赖的静态门禁：

node scripts/verify-release.mjs

该门禁会严格解析 overlay 所使用的 YAML 子集并验证其结构，检查双语文档的 blob ID 与相对链接，确认仓库中没有运行时实现目录，并执行发布卫生扫描。它不会启动浏览器或访问网络。门禁通过不表示尚未发布的工具包能够安装，也不证明文档中的运行行为已经兼容公开版本。

运行验收

目标 DSH 安装已经具备官方工具包和浏览器后，启动 overlay，并在本地或其他获准的测试页面上依次验证八个工具。同时确认不同代理之间不共享页面，代理关闭后其浏览器页面得到释放。

安全

浏览器工具能够访问网络资源并写入截图。请阅读 SECURITY.md，使用部署环境现有的沙盒和权限控制限制工具，不要用高权限会话访问不受信任的目标。

许可证

本仓库的文档与配置使用 BSD 3-Clause。另行提供的工具包及其依赖保留各自的许可证。