前言¶
在 DeepSeek Harness（DSH）桌面端里，右侧边栏可以嵌入真实网页，但模型侧若直接对接 Chromium 的标签索引，往往会因为索引易变、开页路径与 Electron CDP 限制而失败。社区插件 dsh-browser-automation（维护者 damijun）在 Windows 版 DSH 桌面端上，用稳定的 pageId 契约和 playwright-cli 桥接，把 @deepseek-ai/dsh-client-ui-sidebar-browser 变成一组模型工具可调用的自动化目标。下面介绍其定位、能力与在 Windows 上的安装启用方式。
这是什么¶
dsh-browser-automation 归类为联网工具，当前 npm 版本为 0.3.0，许可证 MIT。插件为模型暴露 12 个以 pageId 为参数的 browser_* 工具；内部通过 CDP 附着 DSH 进程，经 playwright-cli 完成选页与操作，并通过页面桥调用 ctx.sidebarRight.openTab 开新标签。README 明确：仅支持 Windows 版 DSH 桌面端；Web 版无可附加 CDP，macOS/Linux 桌面端未验证。
核心设计¶
插件分三层：browser_* 工具层只认 pageId；SessionManager 负责登记与会话归属；CliBridge / PageDriver 连接 playwright-cli -s=dsh 并执行 tab-select、eval、click 等。三条不变量值得记住：
- 标签索引每次调用重新解析，不缓存；
pageId才是稳定契约。 - 新开页必须走 DSH UI（
browser_open），不能依赖 CDPTarget.createTarget或tab-new。 - 结束自动化用
browser_status { action: "detach" }，只 detach，不 close DSH 进程。
并发上，PageDriver.withCli() 用全局 CLI 互斥串行化「选页 + 命令」，不同会话操作不同页面时互不踩踏。
核心工具能力¶
启动只有两种方式：browser_open（新建侧边栏标签）或 browser_claim（接管用户当前可见页）。其余工具均在已登记的 pageId 上操作。
| 能力类别 | 工具示例 |
|---|---|
| 页面生命周期 | browser_open、browser_claim、browser_list、browser_status |
| 导航 | browser_navigate（url / reload / back / forward，不增 tab） |
| 感知 | browser_snapshot（可访问性快照）、browser_screenshot |
| 交互 | browser_click、browser_fill、browser_press |
| 扩展 | browser_run_code（函数体传入，勿 JSON.stringify 返回值）、browser_console |
文档建议：同一时刻侧栏只显示一个 tab，若当前页状态可丢弃，优先 browser_navigate 换址，而非多开 tab。配置项 disabledTools 可逗号分隔屏蔽部分工具，减少上下文体积。
侧栏「浏览器自动化」面板供人只读查看 CDP、CLI、桥与会话页面列表；browser_status 返回的 JSON 含 cdp.diagnosis（如 serving、absent、stale、no-record）等诊断字段，连不上时按 diagnosis 查原因。
安装与启用¶
安装（任选其一）：
- DSH 桌面端：Settings → Plugins，搜索并安装
dsh-browser-automation。 - CLI：
dsh plugin add dsh-browser-automation
- npm 包名：
dsh-browser-automation（见 npm）。
引擎要求（package.json）：node >= 22，dsh >= 0.2.1-rc.2 < 0.3.0-0。
必做前置（Windows）：
- 远程调试端口：完全退出 DSH 后，在快捷方式「目标」中于
.exe路径后追加--remote-debugging-port=0，再启动。插件从%APPDATA%\@deepseek-ai\dsh-desktop\DevToolsActivePort读取端口，无单独配置项。 - 全局安装 playwright-cli：
npm install -g @playwright/cli@latest
playwright-cli --version
验证： 侧栏打开「浏览器自动化」面板，CDP 显示已连接；模型调用 browser_status，cdp.diagnosis 应为 serving，cli.resolved 有值。若 CDP 或 CLI 未就绪，面板顶部会显示「一次性设置」引导卡片。
典型用法思路¶
- 模型调用
browser_open { url: "https://example.com" }或browser_claim取得pageId。 browser_snapshot { pageId }获取含[ref=…]的快照，再browser_click/browser_fill操作。- 需要读 DOM 数据时，用
browser_run_code，例如文档所示：return await page.evaluate(() => document.title)（只传函数体）。 - 会话结束调用
browser_status { action: "detach" }。
用户也可在侧栏自行打开状态面板，使用「断开 CLI」「重新连接」；detach 会使已有 pageId 失效。
适用场景与注意¶
适合在 Windows DSH 桌面端 上让智能体完成侧边栏内的查资料、填表、截图、控制台排查等步骤，且希望模型侧接口稳定（pageId）而非死记 tab 序号。
使用前注意：
- 插件以当前 DSH 进程权限运行，安装前宜查阅 GitHub 源码 与 MIT 许可证。
- 固定调试端口（如
9222）可能因残留实例导致ECONNREFUSED；默认推荐--remote-debugging-port=0。 browser_navigate的reloaddeliberately 不用playwright-cli reload，以免刷新整个 DSH 外壳；browser_run_code中不宜page.reload()。
结尾¶
dsh-browser-automation 把 DSH 右侧边栏浏览器整理成以 pageId 为契约的 playwright-cli 自动化面，适合 Windows 桌面端智能体联网操作。更多细节见项目 README 与 CHANGELOG。
