dsh-tool-playwright

English | 中文

一个给 DeepSeek Harness 用的插件：让 AI 能真的打开浏览器上网——打开网页、点按钮、填表单、翻页、看页面内容，就像人一样操作浏览器。

它移植自微软的 playwright-mcp 项目，但不需要单独开一个服务器进程，直接跑在 harness 内部。

它能做什么

想做的事	用的工具
打开网页、后退、前进、刷新、等页面加载	browser_navigate、browser_back、browser_forward、browser_reload、browser_wait_for
点击、输入文字、下拉选择、鼠标悬停、按键盘、拖拽、上传文件	browser_click、browser_type、browser_type_submit、browser_select_option、browser_hover、browser_focus、browser_press_key、browser_drag、browser_upload_file
查看当前页面长什么样	browser_snapshot
开新标签页、切换标签页、关标签页、列出标签页	browser_tab_new、browser_tab_switch、browser_tab_close、browser_tab_list
调整窗口大小、截图、存成 PDF	browser_resize、browser_screenshot、browser_pdf
看网页报错信息、看网页请求了哪些网址	browser_console_messages、browser_network_requests
高级功能（默认关闭，需要专门打开）	browser_evaluate、browser_storage_state、browser_init_script、browser_tracing_start、browser_tracing_stop

两个词先解释清楚：

• 快照（snapshot）：不是截图！是 AI 看网页的方式——一份"网页结构清单"，列出页面上有哪些按钮、链接、输入框，各自叫什么、编号（ref）是多少。
• ref：清单里的编号。AI 说"点 3 号"就能点 3 号元素。也可以直接给一个 CSS 选择器（比如 #search）代替编号。

怎么安装

第 1 步：认识你的"配置目录"（profile）

harness 的每套配置叫一个 profile，在硬盘上就是一个文件夹： C:\Users\<你的用户名>\.dsh\profiles\<档案名>\。网页版 GUI 用的那套叫 web。下面的命令都是装进 web 这套。

第 2 步：从 GitHub 克隆插件代码到本地

git clone https://github.com/cheng-nan01/dsh-tool-playwright.git

克隆完成后，你会得到一个插件文件夹（名字叫 dsh-tool-playwright），里面是插件的全部代码。这个文件夹之后别挪位置、别删。

第 3 步：用"本地文件夹"方式安装

dsh plugin --profile web add link:克隆下来的插件文件夹完整路径

把 link: 后面的路径换成你刚才克隆出来的文件夹路径（例如 link:D:\my-plugins\dsh-tool-playwright）。

这条命令内部做了 3 件事：

1. 登记：把插件写进配置目录里的 package.json（已安装清单）；
2. 建快捷方式：在配置目录的 node_modules 里生成一个指向你插件文件夹的快捷方式——代码不会被复制；
3. 加入启动清单：把插件名加进 dsh.profile.bundles，这是下次启动时"加载它"的依据。

link: 表示"建快捷方式、不复制代码"。也可以写 add ./相对路径（相对你当前所在的目录）。

第 4 步：重启 harness

"启动清单"只在 harness 启动时读取一次，所以装完必须重启才生效： 停掉 pnpm dsh web（按 Ctrl+C）→ 重新运行 pnpm dsh web。

第 5 步：验证

dsh --profile web --dump-config    # 看输出里有没有 "# == dsh-tool-playwright" 这一层

重启后在 http://127.0.0.1:3080 让 AI 用 browser_navigate 打开一个网页，能打开就说明装好了。

卸载

dsh plugin --profile web remove dsh-tool-playwright   # 删登记 + 删启动清单

如果你还在配置目录的 cordis.patch.yml 里写过覆盖配置，记得顺手删掉那段。

常见问题

• 找不到 dsh 命令：在 harness 源码目录（DeepSeek Harness 代码所在的文件夹）下改用 pnpm dsh ...。
• 装完没反应：几乎都是忘了重启。
• 插件文件夹挪了位置：快捷方式断了，重新执行一次 add。
• 安装时看到 "declares no dsh.bundle" 警告：表示这个包只是普通依赖、不会自动激活——本插件已声明为 bundle，不会有这个警告；第三方普通库出现属正常。

怎么改设置

插件自带一套默认设置（无头模式、chromium 等，见下表）。想改的话，编辑 harness 的 cordis.patch.yml 文件，把完整的设置重新写一遍（注意：它是整体替换，不是只改一行，漏掉的设置会回到默认值）：

# 在 $DSH_HOME/profiles/<档案名>/cordis.patch.yml 里追加：
- id: dsh-tool-playwright
  config:
    browser: chromium        # 用哪个浏览器：chromium / firefox / webkit / msedge
    headless: false          # false = 弹出可见的浏览器窗口；true = 后台默默运行
    executablePath: ''       # 可选：指定用哪个浏览器程序（不填就用 Playwright 自带的）
    viewport:
      width: 1280            # 窗口宽度（像素）
      height: 720            # 窗口高度（像素）
    timeoutMs: 30000         # 每个操作最多等多少毫秒
    capabilities:
      screenshot: true       # 允许截图
      pdf: true              # 允许存 PDF
      network: true          # 允许查看网络请求

常用设置一览：

设置项	作用	默认值
browser	用哪个浏览器	chromium
headless	false 显示窗口，true 后台运行	true
channel	用系统里装好的 Chrome/Edge（如 chrome、msedge）	不填
executablePath	指定用哪个浏览器程序文件	不填（用自带）
userDataDir	把登录状态（cookie）存到固定文件夹，重启不丢	不填（临时）
isolated	true = 每次操作都用全新浏览器（不留痕迹）	false
viewport	窗口大小	1280×720
outputDir	截图、PDF 存在哪	.dsh/playwright
timeoutMs	每个操作等待上限（毫秒）	30000
evaluate	是否允许 AI 在网页里执行任意代码（有风险，谨慎开启）	false

常见问题

1. 装好后 AI 打不开浏览器？ 先装一次浏览器本体：npx playwright install chromium。如果不想下载，也可以设置 executablePath 指向电脑上已有的浏览器。

2. 想亲眼看到 AI 操作浏览器？ 把 headless 设为 false，重启 harness。之后 AI 每次操作都会在可见窗口里实时演示。

3. 插件代码放在哪里都可以吗？ 可以。装的时候用 link: 加上完整路径就行；harness 通过快捷方式找到它。E 盘、D 盘、任意目录都行，路径对得上即可。

4. 和原来的 playwright-mcp 有什么不同？ 不用额外开服务器进程、工具名没有多余前缀、截图 PDF 等能力默认更保守（evaluate 默认关）。用法基本一样。

给开发者

pnpm typecheck   # 检查代码类型
pnpm smoke       # 用真实浏览器跑一遍自测

冒烟测试会真实打开浏览器，跑"打开页面 → 看结构 → 点按钮 → 输入文字"这一整套流程。如果本机没有 Playwright 自带的浏览器，可以用环境变量指到已有的浏览器：

$env:DSH_PLAYWRIGHT_EXECUTABLE = "C:\path\to\chrome.exe"; pnpm smoke

本机开发时依赖是通过 node_modules 里的快捷方式（junction）指向 harness 源码目录的，所以不用联网装依赖。

许可证

MIT。工具逻辑移植自 playwright-mcp（Apache-2.0），面向 harness 的实现为原创。