前言¶
DeepSeek Harness (DSH) 采用了“一切皆插件”的架构，支持在运行时动态加载工具。dsh-playwright 是一个为此场景设计的插件，它给智能体提供了一套 browser_* 工具集，底层通过 Playwright 驱动 Chromium 进行真实的网页操作。
这个插件解决了智能体需要与外部 Web 界面交互的需求，例如打开页面、点击元素、抓取数据或截图。它不依赖外部的桥接服务，直接在宿主进程中运行。
核心功能¶
该插件提供以下工具能力：
- browser_open: 打开指定 URL，返回最终地址与页面标题。
- browser_status: 查询浏览器或当前页面的状态（是否挂载、端点、URL、标题等）。
- browser_attach: 运行时挂载或切换到一个已存在的浏览器实例。
- browser_tabs: 列出、切换或关闭已打开的标签页。
- browser_click: 点击元素（支持 CSS 或
text=选择器）。 - browser_type: 逐字输入文本（支持设置
delay模拟打字节奏）。 - browser_fill: 快速填充表单。
- browser_press: 模拟按键（如 Enter、Tab、Escape 等）。
- browser_wait: 等待指定毫秒数。
- browser_extract: 抓取页面或指定元素的文本内容。
- browser_html: 抓取页面或指定元素的 HTML 结构。
- browser_eval: 在页面上下文中执行 JavaScript 表达式。
- browser_screenshot: 截图并保存为 PNG，支持图片输入的模型直接查看画面。
- browser_close: 关闭浏览器或断开连接。
安装与启用¶
在任意目录执行一条命令，DSH 会自动定位 profile 目录。首次使用会自动初始化：
dsh plugin --profile web add git+https://github.com/whklwhkl/dsh-playwright.git
安装完成后需要重启 DSH，browser_* 工具才会对 profile 下的所有会话生效。
环境准备¶
该插件依赖 playwright-core，但它不会自动下载浏览器二进制文件。在首次使用前，需要手动安装 Chromium：
npx playwright-core install chromium
安装的浏览器文件会进入系统缓存目录（如 ~/Library/Caches/ms-playwright），插件启动时会自动发现。
使用方式¶
插件支持两种主要模式：
- 自建模式：插件内部启动一个干净的浏览器实例。
- 挂载模式：通过 CDP (Chrome DevTools Protocol) 接管用户当前正在使用的浏览器，保留登录态、Cookie 和扩展。
挂载模式通常需要先设置环境变量：
export PW_CDP_ENDPOINT=chrome
然后在对话或代码中调用：
browser_attach({ endpoint: 'chrome' })
特性说明¶
- 版本兼容：对
dsh 0.2.0-rc.2实测通过。自该版本起，DSH 增加了插件兼容闸门，会检查插件的peerDependencies。本插件声明了@deepseek-ai/dsh: ^0.2.0-rc.2。若升级 DSH 到 0.3 及以上，需同步更新插件版本。 - 进程内运行：宿主进程内直接
require('playwright-core')，自建模式下无需额外的桥服务或端口。 - 中断即取消：支持转发
exec.signal，在途操作（如click、fill）会被中止，未完成的调用也会快速结算。 - 失败即抛：出错时直接抛出错误，不会拼接成“看起来成功”的字符串，便于策略和日志进行错误处理。
- 截图可见：
browser_screenshot返回的 PNG 会作为附件内联，支持图片输入的模型直接看到画面。 - 中英双语：通过设置
PW_LANG=en可以切换工具描述、参数文档和输出文案为英文（默认中文）。
短结尾¶
dsh-playwright 是一个轻量级的浏览器自动化工具集，适合需要让 DSH 智能体进行网页操作的场景。它通过 Playwright 提供了从基础点击到复杂数据提取的完整能力。更多细节和源码，请访问 GitHub 仓库。
