dsh-browser-control: A CDP plugin that lets DSH agents reuse your daily Chrome login state

前言¶

给智能体接浏览器，常见做法是起一个干净的 headless 实例。问题在于登录态：很多页面需要已登录的 Cookie 才能看到真实内容，每次都要在隔离环境里重新登录，成本很高。而直接在日常使用的 Chrome 上开 --remote-debugging-port，新版 Chrome 已经明确禁止——默认 user-data-dir 不允许开调试端口。

下面介绍 dsh-browser-control，一个 DeepSeek Harness（DSH）插件，用 CDP（Chrome DevTools Protocol）驱动浏览器，核心卖点正是登录态复用：它能把你日常 Chrome 的登录状态搬进一个隔离的调试实例，让智能体直接以「已登录」的身份导航、截图、抓报错、执行 JS。

这是什么¶

dsh-browser-control 是由 PangYiMing 维护的 DSH 插件，当前版本 0.1.0，MIT 许可证。它通过 CDP 控制浏览器，提供：

复用日常 Chrome 登录态
页面导航与截图
抓取 console / pageError / networkError
在页面执行任意 JS
移动端视口与 UA 仿真

插件依赖 ws ^8.18.0，peerDependencies 为 @deepseek-ai/dsh-tools 与 @deepseek-ai/cordis，要求 Node >= 20.11。

核心能力¶

登录态复用启动器¶

scripts/launch.sh 负责起一个 :9222 端口的 CDP 调试实例。它的做法不是直接改日常 Chrome 的启动参数，而是：

把日常 Chrome 的登录态文件（Cookies / Login Data / Local Storage / IndexedDB 等）只读拷贝到隔离目录 /tmp/chrome-e2e-profile；
用这个隔离目录起调试实例。

几个设计细节：

单向不回写：调试实例不会污染日常 Chrome 的数据；
懒同步：只在首次或指定 --refresh 时才重新拷贝；
端口探测复用：实例已在跑就直接复用，不重复启动；
精确 pkill：关闭时只杀调试实例，不误伤日常浏览器。

原理与实现细节见仓库里的 docs/cdp-login-reuse.md。

CDP 驱动脚本¶

scripts/drive.mjs 负责具体的浏览器操作：导航 / 截图 / console / eval / mobile 仿真。导航完成后输出一段 JSON，包含 title、url（注意是 SPA 跳转后的最终地址）、bodyPreview、console、pageErrors、networkErrors 以及 screenshot 路径。也就是说，一次导航就能拿到页面文本预览和三类报错信息，方便智能体直接判断页面状态。

封装为 6 个 DSH 工具¶

安装插件后，以下 browser_* 工具会自动注册进 agent 的工具集：

工具	说明
`browser_status`	探测 CDP 实例是否在跑（默认 9222）
`browser_launch`	幂等启动 CDP 调试 Chrome（复用日常登录态；`refresh` 强制重同步）
`browser_kill`	关闭 CDP 调试实例
`browser_open`	导航到 URL 并返回 title / 最终 URL / 文本预览 / console / pageError / networkError / 截图
`browser_screenshot`	导航并截图，返回截图路径
`browser_eval`	导航后在页面执行 JS 表达式并返回结果

安装¶

两种方式。npm 命令要等插件发布到 npm 后才可用：

dsh plugin --profile demo add dsh-browser-control

或直接从 GitHub 源码安装，源码安装需要 prepare 构建：

dsh plugin --profile demo add github:PangYiMing/dsh-browser-control

典型用法¶

脚本层面可以直接跑这两个文件。先起调试实例：

./scripts/launch.sh   # 起 :9222 调试实例（复用日常 Chrome 登录态；已在跑则复用）

launch.sh 还支持 --refresh / --kill / --status 三个参数，分别对应强制重同步登录态、关闭实例、查看状态。

再驱动浏览器导航并截图：

node scripts/drive.mjs "<url>" \
  --out /tmp/shot.png \
  [--mobile] [--wait 4000] [--eval "<expr>"]

三个可选参数：

--mobile：390x844 视口 + iPhone UA 仿真；
--wait 4000：等待毫秒数；
--eval "<expr>"：在页面执行任意 JS，可用来验证 DOM 状态、读 window 全局、调库 API。

在 agent 会话里则不需要记命令，用自然语言触发即可：

browser_launch 起 Chrome，然后 browser_open 打开 https://example.com 截图给我看

canvas 截图避坑¶

如果页面用 G6 / echarts / D3 / WebGL 这类可视化库画 canvas，直接截图可能拿到空白。原因是后台 tab 的 raf 会被节流，渲染根本没跑。插件的处理是：新建 tab + Page.bringToFront + 踢 raf。作者还特别提醒：判断是否渲染完成时别用 getImageData。细节见 docs/cdp-canvas-pitfalls.md。

适用场景与注意¶

适合的场景：让智能体检查需要登录的页面、排查前端报错（console / pageError / networkError 一次抓全）、验证可视化页面渲染结果、做移动端视口下的页面检查。

边界也要清楚。路线图中已完成的是登录态复用启动器、CDP 驱动和 6 个 browser_* 工具；尚未完成点击 / 填表 / 表单交互、Playwright 后端、多标签 / 多窗口管理。也就是说，当前它偏向「看」和「读」，还不是一个完整的浏览器操作方案。

另外提醒一点：插件以当前 dsh 进程的权限运行，安装前建议先到仓库检查源码与许可证（MIT，见 ./LICENSE），确认符合自己的安全要求。

结尾¶

dsh-browser-control 解决的是智能体操作浏览器时最常见的登录态问题，同时把导航、截图、报错抓取打包成一次调用就能拿全的 JSON 输出。如果你在用 DSH 做智能体开发，需要让 agent「登录着看网页」，可以试试。

目录页：https://www.skillhub.cn/plugins/PangYiMing/dsh-browser-control
GitHub：https://github.com/PangYiMing/dsh-browser-control