前言¶
让 Agent 干浏览器里的活，常见的做法是起一个 headless 浏览器：Agent 在里面点按钮、填表单，把截图和日志回传给你。整个过程接近黑盒——页面没加载出来、选择器失效、被登录框挡住，你只能看日志猜，想插手也没有入口。
dsh-plugin-chrome 走的是另一条路：每个 DSH 会话开一个真实的、可见的 Chrome 窗口，画面实时串流到 Web GUI，你在旁边看着 Agent 操作，随时可以自己点几下接管。下面介绍它的功能、安装和用法。
这是什么¶
dsh-plugin-chrome 是 DeepSeek Harness（DSH）的浏览器可视化插件，由 jiaererw 维护，MIT 许可证，代码在 GitHub 开源。它解决的问题是：Agent 操作浏览器时，你既能实时看到它在做什么，也能随时手动介入。
DSH 的理念是一切皆插件。这个插件装进 profile 后，会话顶部会多出一个 Chrome 标签页，Agent 则自动获得一套浏览器工具。
核心功能¶
每个会话一个可见窗口¶
每个 DSH 会话拥有一个可见的真实 Chrome 窗口（非 headless），使用隔离的 user-data-dir，不与日常浏览器混用。Agent 的每一步操作都能直接看到。
实时画面串流¶
Web GUI 的 Chrome 标签页通过 Chrome screencast 实时串流窗口画面，页面活跃时帧流顺畅。空闲页面由心跳兜底强制截帧——静默 3 秒后约每 2 秒一帧，画面不会冻结。
16 个 chrome_* 工具¶
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_tabs 覆盖列表 / 新建 / 关闭 / 选择四种操作；快照、截图与点击始终作用于当前选中的标签页。
快照与截图¶
chrome_snapshot 返回带稳定元素 uid 的紧凑可访问性树，点击与填写直接以 uid 为目标，比倾倒整个 DOM 轻得多，也不容易因页面结构变动而失效。
chrome_screenshot 是双通道设计：图片块送入模型上下文，让模型“看到”页面；同时保存到面板的会话截图历史，历史条目保留标题、URL、尺寸元数据，跨重启保留。
安全设计¶
- CDP 不暴露固定端口；
- Web API 拒绝跨站请求（基于 Sec-Fetch-Site），并对 sessionId 做白名单校验；
- 浏览器数据按会话隔离。
资源治理与生命周期¶
- 空闲窗口自动关闭，默认 10 分钟，可配置；
- chrome_close 显式关闭；插件卸载或宿主关闭时，会关闭它打开的所有窗口；
- 懒启动：只在首次 chrome_* 调用或面板 Open 按钮时才启动 Chrome；
- 孤儿收养：DSH 异常退出遗留的 Chrome，插件通过 DevToolsActivePort 重连接管，而不是报错失败；
- 自动标签页恢复：每次操作确保存在可用标签页，避免窗口全是 chrome:// 内部页时无法工作。
安装与启用¶
前置条件：已安装 DeepSeek Harness (DSH)，机器上有 Chrome 或 Edge；插件要求 Node >= 20。
官方安装命令：
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，每个会话顶部会出现 Chrome 标签页。
两个可能遇到的问题：
1、如果 profile 的 cordis.patch.yml 里还保留着旧的 dsh-plugin-chrome 手动挂载行（本地开发时加的），先移除再用 CLI 安装，避免双重挂载；
2、pnpm 的 strict-dep-builds 可能阻止安装：在 profile 的 pnpm-workspace.yaml 的 allowBuilds 中加入 dsh-plugin-chrome: true 后重试。
配置¶
配置通过 profile 的 cordis.patch.yml 覆盖插件行（整体替换）：
- 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
extraArgs: '' # 额外的 Chrome 启动参数
浏览器数据与截图存放在 ~/.dsh/data/dsh-plugin-chrome/sessions/<sessionId>/，可用 dataRoot 覆盖。
典型用法¶
让 Agent 执行一句自然语言指令：
Open Chrome, go to https://example.com, take a screenshot, then click the “Login” button and fill in the username.
对应的工具流程是：chrome_open → chrome_navigate → chrome_screenshot（模型看到图片）→ chrome_snapshot（拿到 uid）→ chrome_click / chrome_fill。
面板侧的操作：
1、打开会话顶部的 Chrome 标签页，Live view 持续显示窗口画面；
2、侧栏可以创建、切换、关闭标签页，与真实窗口同步；
3、随时手动点击真实窗口接管，Agent 下一次工具调用就能看到你的变更；
4、每次 chrome_screenshot 都存入面板截图历史，点击缩略图可放大查看。
几个常见情况的处置：
- 自行关闭窗口后不用重装，任意下一次 chrome_* 调用或面板 Open 按钮会重新启动；
- Agent 报 “unknown uid” 说明页面已经变了，让它重跑一次 chrome_snapshot；
- 面板黑屏时先检查窗口是否在运行（顶部状态点），首次启动需要几秒。
适用场景与注意事项¶
适合的人：
- 想实时盯着 Agent 浏览器操作、不放心纯日志回传的；
- 调试浏览器自动化流程，需要看现场而不是猜日志的；
- 有登录态需求的任务——每个会话使用隔离 profile，登录态不与日常浏览器互通（设计如此）。如需登录，让 Agent 在会话内完成，登录态在会话内持久。
注意事项：
1、纯文本模型慎用截图。chrome_screenshot 会把图片块写入会话历史，若模型不接受图片，后续每轮都会被拒绝（UNSUPPORTED_CONTENT: does not accept image input）且会话不再响应，重试无效。需要截图的会话请使用支持视觉的模型，或在该会话中避免 chrome_screenshot；
2、headless 配置应保持 false，可见窗口是这个插件的核心；
3、安全提醒：插件以当前 dsh 进程的权限运行，安装前请自行检查源码与许可证（本项目为 MIT）。文中提到的社区目录 skillhub.cn 是独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-plugin-chrome 把 Agent 的浏览器操作从黑盒变成现场：窗口可见、画面实时、随时接管，16 个工具加生命周期兜底让它能在会话里长期稳定跑。如果你在用 DSH 做浏览器相关任务，值得一装。
- 目录页：https://www.skillhub.cn/plugins/jiaererw/dsh-plugin-chrome
- GitHub：https://github.com/jiaererw/dsh-plugin-chrome
