dsh-plugin-chrome-driverless

把 Docker 里的有头 Chrome 接进 DeepSeek Harness：Agent 能像人一样打开网页、看截图、点按输入、切 Tab、切 Profile，并把登录态持久化下来。

底座是 friddle/chrome-driverless——Playwright 驱动的持久化 Chrome（Xvfb 有头）+ 一套 MCP 风格的 HTTP 控制接口（POST /mcp）。本插件是这个服务在 DSH 里的那一层：

• lib/client.js —— 说服务的控制接口。它是 MCP 风格 的 JSON 信封（{method, params} → {result|error}），没有 initialize/tools/list，所以不走 @deepseek-ai/dsh-mcp-client：那个客户端说的是真 MCP。
• lib/docker.js —— 可选地由 DSH 管这个容器：建（挂上数据卷）、等 /health、按需停。也可以只连现成服务。
• lib/images.js —— 把服务返回的 base64 截图存进 DSH 附件服务，于是模型收到的是真的图片块，不是一坨 base64 文本。
• lib/tools.js —— 13 个工具：browser_open / screenshot / elements / click / type / press / scroll / evaluate / tabs / profile / save_auth / status / container。

为什么是插件而不是 MCP 客户端

服务自己的动词才是价值：多 Profile 隔离登录态、save_auth 导出、pw/ai_task、/devtools/* 调试反代。挂一个通用 MCP 桥会把这些压平成服务端碰巧发布的那几个方法，而且 chrome-driverless 目前也还不是合规 MCP server。要走 MCP，正确做法是给它加一层真 MCP 门面（见文末「可选路线」）。

安装

# GitHub 直装（不需要发 npm）
dsh plugin add github:friddle/dsh-plugin-chrome-driverless

# 或本地开发：repo 根就是包根
npm pack && dsh plugin add ./dsh-plugin-chrome-driverless-0.1.0.tgz

插件进 profile 后，dsh.bundle.patch（cordis.patch.yml）会插入一行 chrome-driverless：

- insert:
    - id: chrome-driverless
      name: 'dsh-plugin-chrome-driverless'

要覆盖配置就在自己 profile 的 cordis.patch.yml 里按这个 id 打补丁：

- id: chrome-driverless
  config:
    baseUrl: http://127.0.0.1:9223
    manageContainer: true
    dataDir: /srv/chrome-driverless
    profile: work
    proxy: http://10.0.0.2:7890

配置

字段	默认	说明
baseUrl	http://127.0.0.1:9223	服务地址；容器由本插件管时保持默认
manageContainer	false	由 DSH 启动/停止容器（需要 docker CLI）
autoStart	true	manageContainer 打开时，插件加载即确保容器在跑
stopOnDispose	false	插件卸载时停容器。默认关：登录态和数据卷应该活过 DSH 重启
containerName	chrome-driverless	容器名，已存在则复用
image	ghcr.io/friddle/chrome-driverless:latest	镜像，国内可换自建
port	9223	宿主端口，映射容器 9223；只绑 127.0.0.1
dataDir	~/.dsh/chrome-driverless	持久化目录（profiles / auth.json / 浏览器 profile）
profile	debug	容器启动时激活的 profile
proxy	空	浏览器代理；留空直连，不写死任何地址
requestTimeoutMs	60000	控制接口超时
actionTimeoutMs	90000	导航/点击/输入这类动作超时
startupTimeoutMs	120000	等 /health 就绪的超时

工具

工具	干什么
browser_open	打开 URL，返回截图。共享浏览器，登录态跨调用保留
browser_screenshot	截当前 Tab，不改变页面
browser_elements	列出可交互元素的 selector / 坐标 / 文本——定位登录框最省 token
browser_click	点：selector 优先，text 次之，x/y 兜底（覆盖层、hover 菜单、canvas）
browser_type	输入，可先点 selector 或 x/y；submit 顺手回车
browser_press	单键：Enter / Escape / Tab / PageDown / 单字符
browser_scroll	滚轮（dx/dy），可先移到 x/y
browser_evaluate	在页面里跑 JS 取结构化数据（页面上下文，不是 Node）
browser_tabs	list / new / select / close：其它工具都作用于当前 Tab
browser_profile	list / set：切换账号而不登出前一个（切换会重启 context）
browser_save_auth	把当前 profile 的 cookies/localStorage 导出成 auth.json
browser_status	服务是否可达 + 当前 URL/Profile + 容器状态；连不上时先查它
browser_container	start / stop / restart / logs（仅在 manageContainer 打开时可用）

安全

• 容器的 9223 只绑回环：这个控制接口自己没有鉴权，谁连上谁就能用你的登录态浏览器。
• 数据卷是宿主目录，装着真实登录态（cookie / localStorage）。别把 dataDir 放进会同步到云盘的目录。
• proxy 默认空：不预设任何代理，需要时用配置显式给。
• 插件不做任何网络暴露，也不改 DSH 自身文件。

和别的「Docker 里的 Chrome」比

方案	形态	有头/登录态	控制面	DSH 接入
chrome-driverless（本插件底座）	自建镜像 + GHCR	有头（Xvfb）+ 多 profile + auth.json 导出	POST /mcp（自有动词）+ /devtools/* CDP 反代 + /audio.mp3	本插件直连
Playwright MCP	npx 或 HTTP	有头可开；--user-data-dir 持久 profile；--cdp-endpoint 可连现成 Chrome	真 MCP（a11y 快照为主，少截图）	dsh-mcp-client（stdio/streamable-http）
chrome-devtools-mcp	npx	有头；可连现成 Chrome	真 MCP + puppeteer；性能 trace / 网络 / 控制台	dsh-mcp-client
browserless	Docker 商业授权	无头为主，多并发会话	CDP + REST（/content /screenshot /pdf /function）	需要自己包一层，或走它的 MCP
Steel Browser	Docker，Apache-2.0	无头为主，会话隔离	CDP + REST，面向 agent 的沙箱	同上
browser-use	Python + WebUI	有头可配	自带 agent 循环，不是平台	当作另一个 agent，不是工具层
Selenium Grid / neko / Kasm / BrowserBox	各家	有头（VNC 看真人操作）	WebDriver / VNC	需要 WebDriver 桥

结论：要「真 MCP + 生态最大」就挂 Playwright MCP / chrome-devtools-mcp（DSH 有 dsh-mcp-client，连插件都不用写）；要「我自己的有头、多 profile、登录态导出、音频/DevTools 都在一个服务里」就用本插件包 chrome-driverless。两者不冲突：chrome-devtools-mcp --browser-url 也能接到同一个容器的 CDP 上（走 /devtools 那条反代）。

可选路线：给 chrome-driverless 加真 MCP 门面

如果希望 DSH（以及 Claude Code / Cursor 等任何 MCP 客户端）不装插件也能用，最省事的是在 chrome-driverless 里加一个合规的 JSON-RPC /mcp：initialize / tools/list / tools/call，把现有 _dispatch 的 36 个方法映射成 tools。之后：

- id: mcp-chrome
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    transport: streamable-http
    url: http://127.0.0.1:9223/mcp

两条路可以同时在（本插件给 DSH 原生工具与图片块，MCP 门面给别的客户端）。

开发

npm install
npm test          # 38 个单测：配置归一化 / 客户端错误映射 / 容器生命周期 / 工具输出

测试全离线：fetch 与 spawn 都是注入的，不需要 Docker、不需要浏览器。

License

MIT