yu-tengguo/dsh-browser-tool

dsh-browser-tool

为 DeepSeek Harness (DSH) agent 打造的零依赖「内置浏览器」工具集。
注册一组原生 agent 工具（browser_navigate / browser_snapshot / browser_act / browser_screenshot / browser_close），
通过 Chrome DevTools Protocol (CDP) 驱动本机真实的 Chrome/Edge——打开网页、读取渲染后内容（中文 UTF-8 无乱码）、
点击、输入、提交表单、登录，不再需要任何 web-access 类 skill 或浏览器自动化工具。

A zero-dependency built-in browser toolset for DeepSeek Harness agents.
Native agent tools over CDP driving your local Chrome/Edge — no web-access skills, no npm installs, no browser downloads.

简体中文为主 · English version at the bottom / 英文版见文末

中文说明

为什么需要它

DSH 自带 web_search，但产品配置常把纯 HTTP 的 web_fetch 关掉；而需要 JavaScript 渲染、带反爬、
布局复杂的页面（百度百科、小红书、微博、Amazon…）必须用真实浏览器。每次都要先加载联网 skill 很绕。
本插件把真实浏览器直接放进挂载它的会话的默认工具目录里。

工作原理

- browser.mjs 是一个 cordis 插件文件，由 DSH agent 预设行（name: ./browser.mjs）挂载。
- 只依赖 Node 内置模块 + 全局 fetch/WebSocket（Node ≥ 22），无需 npm install、无需下载 Playwright。
- 首次调用时启动 headless Chrome/Edge（--remote-debugging-port 占用空闲端口），并用 CDP 驱动：
- Page.navigate / Runtime.evaluate / Page.captureScreenshot / 历史记录跳转
- 文本通过 document.body.innerText 读取，编码问题交给浏览器自己处理
- 输入走原生 value setter + input/change 事件；表单用 requestSubmit() 提交
- 每个 agent/会话独立标签页；cookie 持久化在 profile 目录，重启 GUI 后登录态仍在。

安装

完整分步指南见 docs/install.md（新建预设 / 挂已有预设 / 设为默认 / 卸载）。

一键安装（Node ≥ 22；自动定位 $DSH_HOME、创建 standard-browser 预设、复制插件、写入默认设置；幂等可重复执行）：

node install.mjs            # 安装 / 重复执行
node install.mjs --check    # 体检：报告产品 standard 组合能否找到、预设是否过时（不写文件）
node install.mjs --refresh  # 用当前产品 standard 组合重建 agent.cordis.yml（保留你的 builtin-browser 配置）

升级 DSH 后建议跑一次 --check。 产品 standard 组合的位置在 0.1.5 变了：
旧版在 /config/agent-presets/standard/，0.1.5 起在
@deepseek-ai/dsh-agent-presets/presets/standard/。脚本两处都会探测；若预设是基于旧版
standard 建的，--check 会列出缺失的行（如 0.1.5 新增的 dsh-command-goal、dsh-tool-present），
用 --refresh 一次补齐。

兼容性：插件本体（browser.mjs）只使用 Node 内置模块与 cordis 的工具注册 API，已在 DSH 0.1.5-rc.1 上验证；
安装脚本同时支持 0.1.5 之前与之后两种预设布局。

手动快速开始：

1. 把 browser.mjs 复制到你的用户预设目录，如 ~/.dsh/.agent-presets/standard-browser/；
2. 在该预设的 agent.cordis.yml 末尾追加：

- id: builtin-browser
name: ./browser.mjs
config:
chromePath: 'C:\Program Files\Google\Chrome\Application\chrome.exe'  # 可选，默认自动检测 Chrome/Edge
headless: true

3. 重启 dsh web 并用该预设新开会话。

提示：可在 DSH 用户设置里设为默认预设：
agent-presets: { default: standard-browser }

工具一览

| 工具 | 作用 |
| --- | --- |
| browser_navigate(url, waitMs?) | 打开 URL 并等待渲染；返回标题与开头文本 |
| browser_snapshot(mode?, maxChars?) | 读取当前页：text（渲染文本）\| interactives（可点击/输入元素索引）\| both |
| browser_act(action, selector?, match?, text?, js?, waitMs?) | click / type / submit / select / back / forward / refresh / eval |
| browser_screenshot(fullPage?, path?) | 截图存为 PNG 并返回路径（用 read_image 查看，需图像模型） |
| browser_close() | 关闭浏览器（下次调用自动重启） |
元素定位支持 CSS selector，也支持按可见文本 / placeholder / name 模糊匹配 match（取首个匹配）。
点击打开的新标签页会被自动接管。

配置项

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| chromePath | 自动检测 | Chrome/Edge 路径（也可设 CHROME_PATH） |
| headless | true | false 时显示窗口（便于人工配合验证码登录） |
| noSandbox | false | 追加 --no-sandbox（仅开发/CI） |
| timeoutMs | 25000 | 单次导航等待上限 |
| profileDir | $DSH_HOME/browser-profile | 持久化 cookie/登录态；删除目录即重置 |
| screenshotDir | $DSH_HOME/browser-shots | 截图输出目录 |

调试：设 DSH_BROWSER_DEBUG_BASE=http://127.0.0.1:9333 可附加到已运行的 Chrome 而非新启动。

开发与测试

- browser.mjs — 插件本体（单文件、无依赖）
- test/ — 冒烟测试：
- test-install.mjs 验证安装脚本（产品预设探测、幂等、--check、--refresh 保留自定义行配置），无需浏览器与网络
- test-plugin.mjs 用 mock 的 cordis ctx 直接执行真实工具函数
先手动启动调试 Chrome：chrome --headless --no-sandbox --remote-debugging-port=9333 about:blank

已知限制

- 严格反爬页（滑块、图形验证码）仍可能拦截 headless；复杂登录可 headless: false 有头运行、人工配合。
- 截图需要支持图像输入的模型用 read_image 查看；纯文本模型请用 browser_snapshot 读页面。

许可证

MIT

English / 英文版

一个面向 DeepSeek Harness (DSH)
智能体的零依赖内置浏览器工具集。它注册原生工具（browser_navigate、browser_snapshot、browser_act、browser_screenshot、
browser_close），通过 Chrome DevTools Protocol 驱动真实的本地 Chrome/Edge——因此智能体可以打开页面、
读取渲染后的内容（UTF-8 安全）、点击、输入、提交表单并登录，无需 web-access 技能或额外工具。

为什么

DSH 自带 web_search，但部署中通常会禁用纯 HTTP 的 web_fetch。JavaScript 渲染、反爬和
复杂页面（百度百科、小红书、微博、亚马逊……）需要真实浏览器。本插件将它放入挂载它的会话的智能体
默认工具目录中。

工作原理

- browser.mjs 是一个 cordis 插件文件，由 DSH 智能体预设行挂载（name: ./browser.mjs）。
- 仅导入 Node 内置模块以及全局 fetch/WebSocket（Node ≥ 22）——无需 npm install，无需下载 Playwright。
- 首次使用时，它会在空闲端口上启动无头 Chrome/Edge，并通过 CDP 与之通信
（Page.navigate、Runtime.evaluate、Page.captureScreenshot、历史记录条目）。
- 文本来自 document.body.innerText；输入使用原生 value setter + input/change 事件；
表单通过 requestSubmit() 提交。
- 每个智能体/会话拥有自己的标签页；cookie 持久化在 profile 目录中，因此登录状态在 GUI 重启后依然保留。

安装

分步指南：docs/install.md（新建预设 / 现有预设 / 默认预设 / 卸载）。

一键安装器（Node ≥ 22；定位 $DSH_HOME，创建 standard-browser 预设，
复制插件并将其设为默认；幂等）：

node install.mjs            # 安装 / 重新运行
node install.mjs --check    # 报告是否找到产品 standard 预设，以及
此预设是否已过期（不写入任何内容）markdown
node install.mjs --refresh  # 根据当前产品标准重建 agent.cordis.yml
（保留你自己的 builtin-browser 配置；备份旧文件）

升级 DSH 后请运行 --check。 产品 standard 组合在 0.1.5 中发生了变化：
它以前位于 /config/agent-presets/standard/，自 0.1.5 起位于
@deepseek-ai/dsh-agent-presets/presets/standard/。安装程序会探测这两个位置；当某个预设
是基于较旧的 standard 构建时，--check 会列出缺失的行（例如 0.1.5 新增的
dsh-command-goal、dsh-tool-present），而 --refresh 会将其补全。

兼容性：插件本身（browser.mjs）仅使用 Node 内置模块和 cordis 工具注册
API，并已在 DSH 0.1.5-rc.1 上验证；安装程序同时理解 0.1.5 之前和 0.1.5+ 的预设布局。

手动快速开始：

1. 将 browser.mjs 复制到用户代理预设目录，例如 ~/.dsh/.agent-presets/standard-browser/。
2. 向该预设的 agent.cordis.yml 追加：
yaml
- id: builtin-browser
name: ./browser.mjs
config:
chromePath: 'C:\Program Files\Google\Chrome\Application\chrome.exe'  # 可选；自动检测 Chrome/Edge
headless: true

3. 重启 DSH Web UI，并使用该预设启动一个新会话。

提示：通过 DSH 用户设置将其设为默认预设：
agent-presets: { default: standard-browser }

工具

| 工具 | 用途 |
| --- | --- |
| browser_navigate(url, waitMs?) | 打开 URL 并等待渲染；返回标题 + 开头文本 |
| browser_snapshot(mode?, maxChars?) | 读取页面：text \| interactives（可点击/输入索引）\| both |
| browser_act(action, selector?, match?, text?, js?, waitMs?) | click / type / submit / select / back / forward / refresh / eval |
| browser_screenshot(fullPage?, path?) | 保存 PNG 并返回其路径（在支持图像的模型上使用 read_image 查看） |
| browser_close() | 关闭浏览器（下次调用时自动重启） |

元素可以通过 CSS selector 或通过可见文本/占位符/name 模糊 match 来定位（首个匹配项生效）。
由点击打开的标签页会被自动接管。

配置

| 配置 | 默认值 | 含义 |
| --- | --- | --- |
| chromePath | 自动检测 | Chrome/Edge 的路径（或设置 CHROME_PATH） |
| headless | true | 设为 false 以显示可见窗口（人工辅助 CAPTCHA 登录） |
| noSandbox | false | 添加 --no-sandbox（仅限开发/CI） |
| timeoutMs | 25000 | 每次导航的超时时间 |
| profileDir | $DSH_HOME/browser-profile | 持久化 cookie/登录状态；删除以重置 |
| screenshotDir | $DSH_HOME/browser-shots | 截图写入位置 |

开发/测试：设置 DSH_BROWSER_DEBUG_BASE=http://127.0.0.1:9333 以附加到已运行的 Chrome，而不是启动一个新的。

开发

- browser.mjs — 插件（单文件，无依赖）
- test/ — 冒烟测试：
- test-install.mjs 覆盖安装器（产品预设发现、幂等性、--check，
以及 --refresh 保留自定义的行配置）；无需浏览器，也无需网络
- test-plugin.mjs 在带有模拟 cordis ctx 的调试 Chrome 上运行真实工具函数
首先以 --headless --no-sandbox --remote-debugging-port=9333 about:blank 启动 Chrome

限制

- 严格的防机器人页面（滑块、图片 CAPTCHA）仍可能对无头自动化发起挑战；请以有头模式运行
（headless: false）以便人工辅助登录。
- 截图需要具备图像能力的模型才能通过 read_image 查看；文本模型使用 browser_snapshot。

许可证

MIT