浏览器控制工具omdsh-dev/dsh-tool-browser

DSH 浏览器控制配置指南

本仓库发布 @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。另行提供的工具包及其依赖保留各自的
许可证。