dsh-tool-browser

English | 中文

这是一个面向 DeepSeek Harness（dsh）的 Playwright 浏览器自动化插件。Agent 可以打开允许访问的页面，在隔离会话中导航、读取可见文本、点击控件、填写表单、保存截图并关闭会话。

插件面向没有方便 API 的 Web 应用。每个浏览器上下文归创建它的 Agent 所有，导航和网络子资源都会经过来源白名单检查。

安装

npm install @libai168/dsh-tool-browser
npx playwright install chromium

第二条命令用于安装浏览器二进制文件；插件不会在 npm install 时自动下载浏览器。

插件需要由 dsh 运行时提供 @deepseek-ai/cordis (^4.0.1) 和 @deepseek-ai/dsh-tools (^0.1.0-rc.6)。

配置

- name: '@libai168/dsh-tool-browser'
  config:
    allowedOrigins:
      - 'https://example.com'
      - 'https://*.acme.example'
    browserType: chromium
    # Optional absolute path to a system browser.
    # executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
    headless: true
    timeoutMs: 30000
    maxSessions: 4
    maxTextBytes: 12000
    saveDir: '.dsh-browser'

来源条目可以是完整来源、https://.acme.example 这样的子域名规则，或 http://localhost: 这样的端口通配规则。allowedOrigins: ['*'] 会允许所有 HTTP(S) 来源，只应在可信且隔离的部署中使用。

完整示例见 examples/cordis.yml。

工具

| 工具 | 作用 | 外部副作用 | |---|---|---| | browser_open | 打开允许的 URL 并返回不透明会话 ID | 导航 | | browser_navigate | 在已有会话中导航 | 导航 | | browser_snapshot | 读取页面或 CSS 区域的有界可见文本 | 无 | | browser_click | 按 CSS 选择器或可访问角色/名称点击 | 有 | | browser_fill | 按 CSS 选择器填写输入框或文本域 | 有 | | browser_screenshot | 在 saveDir 下保存 PNG 或 JPEG | 写本地文件 | | browser_close | 关闭隔离浏览器上下文 | 释放资源 |

插件不会让模型参数携带 Cookie、凭据或任意请求头。截图文件名只能是简单文件名，不能逃出 saveDir。

行为约定

• 默认白名单是 http://localhost:* 和 http://127.0.0.1:*；访问外部网站必须显式加入配置。
• 每次 browser_open 都会创建隔离的 Playwright 上下文。会话 ID 不透明，只有所属 Agent 可以使用。
• 路由守卫会阻止不在白名单中的 HTTP(S) 子资源和重定向；不支持的 URL scheme 和 URL 中的嵌入凭据会被拒绝。
• 浏览器操作遵循 exec.signal；插件卸载时会关闭所有上下文和共享浏览器实例。
• 页面文本受 maxTextBytes 限制；截图只能写入配置目录。
• 工具结果是规范 JSON，展示回调是纯函数，因此调用和结果可以安全重放。

Model Experience

模型会看到七个小型浏览器工具。通常应先打开页面，再使用 browser_snapshot 查看可见文本，然后选择 CSS 选择器或可访问角色/名称执行操作。后续调用必须携带返回的会话 ID。

页面文本由 maxTextBytes 限制；截图结果只返回文件引用和字节数，不把图片字节塞入工具结果。配置和工具集合不变时，工具 schema 保持稳定。

已知限制和后续工作

• MVP 不提供 Cookie 或已保存存储状态导入；需要登录的流程要依赖外部浏览器准备，或等待后续的安全会话提供器。
• 一个会话只有一个活动页面，暂不暴露标签页、下载、文件上传和弹窗。
• 路由守卫按来源检查，网站使用 CDN 或独立身份服务时可能需要额外加入白名单。
• 浏览器二进制文件与平台相关，需要单独运行 Playwright 安装命令。
• 完整无障碍树快照、下拉选择、键盘快捷键和网络拦截暂未提供。

开发

npm install
npm run typecheck
npm test
npm run build

设计说明和发布检查见 DEVELOPMENT.md。

许可证

MIT