前言¶
给智能体接浏览器时，常见的两种做法各有代价：让模型跑一个无头浏览器，用户看不到它到底点了什么；或者用户自己浏览，再把内容复制给模型。dsh-playwright 走的是第三条路——在 DeepSeek Harness（DSH）里开一个 Browser Use 面板，你和模型看到并操作同一个 Playwright 页面。下面介绍这个插件的定位、功能、安装与用法。
这是什么¶
dsh-playwright 是一个 DSH 插件，由 JeremyGuo 维护，MIT 许可。一句话定位：使用一个共享的 Playwright 浏览器，配合你的 DeepSeek Harness AI。DSH 的理念是一切皆插件，浏览器能力就以插件形式接入：每个 DSH 会话拥有独立的 BrowserContext 与 Page，模型通过一组 browser_* 工具导航、读取、点击、输入、截图，你在面板里看到的是同一份实时画面。
核心功能¶
Browser Use 面板¶
Chrome CDP 把重绘帧通过仅回环的二进制 WebSocket 推送到稳定画布。面板与对话共享宽度，左分隔条可拖动，占比范围 10%–80%。超过 55% 时插件会折叠 DSH 左侧的 Workspace/session 选择器，低于 48% 时只恢复它自己折叠过的选择器。
导航与页面读取¶
导航能力覆盖打开 HTTP(S) URL 和刷新当前页面。browser_navigate 打开 URL 并返回语义快照；browser_snapshot 返回有界页面文本，以及可见链接、按钮、输入框等可交互元素的临时 id（如 e1）。注意这些 id 仅对当次快照有效，导航或动态 UI 变化后需要重新获取。
指针与键盘¶
browser_click 默认左键，可按元素 id 或截图坐标定位，支持 left、right、middle 三键，动作有 click、down、move、up。拖拽是 down → 一次或多次 move → up，使用同一鼠标键。browser_type 替换可见可编辑元素的值并可选回车提交；browser_keyboard 支持 type、press、down、up，组合键如 Control+A、Meta+K，down/up 可长按游戏键。
截图与点击标记¶
browser_screenshot 通过 DSH 原生附件与图片块管线返回 PNG，仅限声明了图片输入的模型路由。它可以在截图上标记上次成功点击的位置：绘制的是后处理 RGB 方块，不修改页面 DOM，面板里有独立的「显示上次点击」开关。
会话隔离与恢复¶
Chrome 惰性启动，teardown 时排队的操作先完成再关闭。如果 Chrome 意外退出，下次操作会启动替换浏览器，并把受影响会话恢复到上次顶层 URL。
安装与启用¶
先确认环境满足要求：
- DeepSeek Harness
0.1.0-rc.6 - Node.js
^22.19.0或>=24.0.0 - 主机安装 Google Chrome 或 Chromium
- 使用
browser_screenshot需要支持图片输入的模型路由
README 中给出的安装命令如下（标注为「After publication」，即正式发布后的安装方式）：
dsh plugin --profile web add dsh-playwright
dsh web --port 3081
本地开发可以用 link 方式挂载本地目录，先拉依赖并跑一遍类型检查、测试与构建：
pnpm install
pnpm run verify
dsh plugin --profile web add link:/absolute/path/to/dsh-playwright
dsh web --port 3081
启用后，用界面右缘的 Browser Use 按钮开关面板，拖动左侧分隔条调整占比。
典型用法¶
打开页面并拿到语义快照：
{"url":"https://example.com"}
点击可以用快照里的元素 id，也可以用坐标：
{"element_id":"e1"}
{"action":"click","button":"right","x":640,"y":400}
只移动指针不点击，steps 控制中间步数：
{"action":"move","x":640,"y":400,"steps":20}
拖拽分三步发送，up 与 down 用同一鼠标键：
{"action":"down","button":"left","x":200,"y":200}
{"action":"move","x":600,"y":400,"steps":30}
{"action":"up","button":"left","x":600,"y":400}
输入文本并回车提交：
{"element_id":"e3","text":"DeepSeek Harness","submit":true}
键盘操作支持打字、组合键与长按：
{"action":"type","value":"hello","element_id":"e3","delay_ms":50}
{"action":"press","value":"Control+A"}
{"action":"down","value":"ArrowRight"}
{"action":"up","value":"ArrowRight"}
截图时可选标记上次成功点击，方便确认点击是否落在预期位置：
{
"show_last_click": true,
"marker_r": 0,
"marker_g": 255,
"marker_b": 0,
"marker_size": 60
}
RGB 三个通道是 0–255 的整数，show_last_click 默认 false。README 提到插件会在提示层面引导模型主动刷新失效的元素 id、在画布类页面上改用截图坐标、释放长按中的鼠标与键盘输入，以及在需要验证点击时请求带标记的截图。
要用截图功能，需要为模型路由声明图片输入。以 llm-pi-ai 路由为例：
llm-pi-ai:
providers:
my-provider:
models:
- id: my-vision-model
name: My Vision Model
input:
- text
- image
声明图片输入是对端点能力的声明；如果端点实际不接受图片，provider 会拒绝请求。
配置项¶
browserExecutablePath：显式指定 Chrome/Chromium 可执行文件；省略时使用常见的 macOS/Linux 路径viewportWidth/viewportHeight：共享页面视口navigationTimeoutMs：Playwright 操作超时actionSettleMs：返回操作后状态前的延迟screencastQuality：CDP 截屏 JPEG 质量，取值 30–90，默认 60maxSnapshotChars/maxSnapshotElements：语义快照的体积上限allowPrivateHosts：设为 true 时允许 localhost 与私有网络目标，默认 false
安全边界¶
几条值得先了解的设计：
1、RPC 与 screencast 端点仅接受回环同源客户端。
2、默认拦截对 localhost、字面私有地址以及解析为私有地址的主机名的 HTTP(S) 请求，包括子资源。仅对可信任务开启 allowPrivateHosts。
3、私有地址拦截是网络防护，不是针对不可信网站的完整沙箱。
4、浏览器会话不复用用户 Chrome 的 profile、Cookie 或登录态，弹窗与下载不对外暴露。
适用场景与注意¶
适合的场合：需要模型在 DSH 中操作真实网页——能看、能点、能输入——同时希望用户全程旁观并可随时接管的任务，例如调试智能体的网页交互流程。
使用前注意：
1、插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（本项目为 MIT）。
2、快照中的元素 id 仅对当次快照有效，导航或页面动态变化后要让模型重新获取。
3、browser_screenshot 只有在模型路由声明了 image 输入时才可用。
4、如前所述，allowPrivateHosts 只应对可信任务开启。
结尾¶
dsh-playwright 把「用户看得到」和「模型操作得了」放进同一个页面，省去了在无头浏览器与手工复制粘贴之间来回倒腾的成本。如果你在用 DSH 做智能体开发，值得一试。
- GitHub：https://github.com/JeremyGuo/dsh-playwright
- 社区目录：https://www.skillhub.cn/plugins/JeremyGuo/dsh-playwright （社区独立站点，与 DeepSeek / 幻方无官方从属关系）
