dsh-plugin-chrome
DeepSeek Harness 浏览器可视化插件：为每个会话打开一个真实可见的 Chrome 窗口，Agent 通过 chrome_* 工具集操作浏览器，你在 Web GUI 的「Chrome」标签页里实时观看画面流，随时可以手动接管。
特性
- 独立可见窗口：每个 DSH 会话拥有一个独立 Chrome 窗口（真实窗口、非 headless），用户在旁边就能看到 Agent 的每一步操作；窗口使用隔离的 user-data-dir，与你的日常浏览器互不干扰。
- 实时画面流：Web GUI「Chrome」标签页通过 Chrome screencast 实时显示页面画面（秒级帧率），无需反复截图。
- 完整的 Agent 工具集（16 个工具）：
chrome_open / chrome_status / chrome_close / chrome_navigate / chrome_tabs / chrome_snapshot / chrome_screenshot / chrome_click / chrome_click_at / chrome_fill / chrome_type / chrome_press_key / chrome_hover / chrome_scroll / chrome_evaluate / chrome_wait。
- 无障碍树快照：
chrome_snapshot 输出紧凑的 a11y 树 + 稳定元素 uid，点击/填充直接按 uid 定位，比裸 DOM 省 token、抗脆弱选择器。
- 截图双通道：
chrome_screenshot 的图片既进模型上下文（图片块），也保存到会话截图目录并展示在面板里。
- 安全设计：CDP 不暴露固定端口；Web API 同源校验 + sessionId 白名单；浏览器数据按会话隔离。
- 资源治理：空闲自动关闭（默认 10 分钟，可配置），
chrome_close 显式关闭，插件卸载/宿主退出时全部收尾。
安装
前置：已安装 DeepSeek Harness（DSH），本机装有 Chrome 或 Edge。
# 方式一：从 GitHub 安装（推荐）
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:jiaererw/dsh-plugin-chrome
# 方式二：本地路径（开发调试）
npx -p @deepseek-ai/dsh dsh plugin --profile web add D:/harness/dsh-plugin-chrome
安装后重启 DSH，Web GUI 的会话顶部会出现「Chrome」标签页。
使用
给 Agent 用（工具）
安装后 Agent 自动获得 chrome_* 工具集。直接对 Agent 说：
打开 Chrome，访问 https://example.com，截个图，然后点页面里的「登录」按钮并填写用户名。
Agent 会：chrome_open → chrome_navigate → chrome_screenshot（看图）→ chrome_snapshot（拿 uid）→ chrome_click / chrome_fill。
给你看（可视化）
- 打开会话顶部的「Chrome」标签页：
- 实时画面：Live 视图持续显示 Chrome 窗口画面。页面有活动时走 Chrome 原生 screencast 帧流（秒级流畅）；页面静止时由心跳兜底强制截帧（约 3 秒一帧），画面不会冻结。
- 标签页管理：右侧列表切换/关闭标签页，与窗口同步。
- 手动接管：你随时可以在 Chrome 窗口里自己点几下——Agent 的下一次工具调用会看到你的改动。
- 截图历史：每次
chrome_screenshot 的产物都在「截图历史」里，点击缩略图放大。
窗口生命周期与容错
- 惰性启动：首次调用任意
chrome_* 工具（或点击面板「打开窗口」）时才拉起 Chrome。
- 接管遗留实例：若 DSH 进程异常退出留下了孤儿 Chrome（profile 被锁），插件下次启动会通过
DevToolsActivePort 自动连接并接管该窗口（借鉴 chrome-devtools-mcp 的 autoConnect 机制），而不是报错。
- 空闲回收：窗口空闲超过
idleTimeoutMs（默认 10 分钟）自动关闭；有 Web UI 观看实时画面时不回收。
- 无可用标签页时自动补页：所有操作都会先确保存在一个可用的普通标签页，避免「窗口开着但全是 chrome:// 内部页」时的死锁。
配置
在 profile 的 cordis.patch.yml 中覆盖插件行配置（整段 config 替换）：
- id: dsh-plugin-chrome
config:
headless: false # 保持 false：可见窗口是本插件的核心
executablePath: '' # 留空自动探测 Chrome/Edge；也可指定绝对路径
idleTimeoutMs: 600000 # 空闲自动关闭（0=禁用）
windowWidth: 1280
windowHeight: 900
screencastFrameSkip: 4 # 实时画面抽帧（1=最流畅）
screencastQuality: 70 # JPEG 质量 1-100
maxSnapshotText: 60000 # 单次快照最大字符数
maxTabs: 16
autoScreenshot: false # 每次操作后自动截图
extraArgs: '' # 追加的 Chrome 启动参数
数据目录（浏览器配置与截图）：~/.dsh/data/dsh-plugin-chrome/sessions/<sessionId>/（可用 dataRoot 覆盖）。
常见问题
- 点开 Chrome 标签页没画面：确认窗口已运行（面板顶部状态点）；首次打开可能需数秒启动 Chrome。静止页面约 3 秒一帧（心跳兜底），有内容变化时帧率自动提升。
- Agent 报"未知元素 uid"：页面已变化，让它重新
chrome_snapshot。
- 窗口被我自己关了：面板状态会显示"窗口未打开"，下次任意
chrome_* 工具调用或点击「打开窗口」即可重启。
- 登录态问题：每个会话的浏览器是独立 profile，登录态不复用日常浏览器；这是隔离设计，如需登录某网站请让 Agent 完成一次登录（session 期间保持）。
- 杀 DSH 后 Chrome 还开着：孤儿窗口会在下次会话调用时被自动接管，或手动关闭即可；正常关闭 DSH（插件卸载）会连带关闭窗口。
开发
npm install
npm run typecheck # host + client 两个 program
npm test # vitest 单测
npm run test:e2e # 真实 Chrome 端到端冒烟（会弹出可见窗口）
npm run build # lib/index.js（host）+ lib/client.js（client bundle）
npm run watch # 开发时持续构建；client 变更经 HMR 热更，host 变更需重启 DSH
架构：host 半（cordis 插件）用 puppeteer-core 驱动本机 Chrome，注册 chrome_* 工具与 /dsh-chrome/* HTTP/WS API；client 半（浏览器 bundle）注册 conversation.view 的「Chrome」标签页，消费 API 与帧流。画面流 = Chrome 原生 screencast（活动页）+ 截图心跳（静止页兜底）。控制层借鉴 chrome-devtools-mcp（CDP 控制、a11y 快照+uid 反查、等待机制、autoConnect 接管）与 mcp-chrome（截图压缩、CDP 坐标输入、会话引用计数）的成熟设计。
License
MIT
