xiaobai2017666/dsh-chrome-cdp

Chrome DevTools Protocol 插件 for DeepSeek Harness(DSH)。通过 chrome-remote-interface(CRI)以 CDP 连接并操控 Chrome,提供两半能力:

• 连接面板(Web GUI):显示连接状态、编辑连接参数(host/port/自动重连)、连接/断开/重连 socket、浏览 target 列表;
• Agent 工具(11 个 chrome_* 工具):模型在会话里直接导航、求值、抓控制台/网络、打断点调试、截图、点击、输入,以及一个发任意 CDP 命令的万能直通。

┌──────────────── DSH Host 进程 ────────────────┐
│  host 树 fiber                                 │
│   └─ dsh-chrome-cdp (lib/index.js)            │
│       ├─ ChromeCdpService ── CRI ──► Chrome   │
│       └─ /cdp/* RPC ◄─ Web 面板               │
│                                                │
│  preset 树 fiber (会话组合)                    │
│   └─ dsh-chrome-cdp/tools (lib/tools.mjs)     │
│       └─ 11 个 chrome_* 工具                  │
│                                                │
│  两半通过包根 bridge.mjs 单例共享连接          │
└────────────────────────────────────────────────┘

目录

• 工具一览
• 安装到 DSH
• Chrome 侧准备
• 面板使用
• 验证与排查

---

工具一览

11 个工具按 5 组注册,preset 配置里 groups.<name>: false 可整组关闭(不注册、零 schema 占用)。全部开启时约占 2K tokens 常驻上下文。

工具	组	说明
chrome_list_targets	navigation	列出 CDP 可达的 target(标签页/窗口/worker),获取 targetId;排查起点
chrome_navigate	navigation	导航到 URL,等待 commit + load(有界等待);默认目标或指定 targetId
chrome_evaluate	navigation	在页面里求值 JS,支持 await Promise;paused 时自动改走 Debugger.evaluateOnCallFrame(同 session 的 Runtime.evaluate 在断点挂起时会永久排队)
chrome_console	diagnostics	读取页面 console.* 与浏览器级 Log 条目(环形缓冲 300 条),游标增量拉取
chrome_network	diagnostics	读取网络请求生命周期(状态/大小/耗时/重定向合并,环形缓冲 500 条),游标增量拉取
chrome_debug	debug	Debugger 控制:pause/resume/单步,在暂停的调用帧上求值(看局部变量)
chrome_breakpoint	debug	断点管理:按 URL+行号设置(可带条件)、列出、删除;列出已解析脚本定位行号
chrome_screenshot	interaction	页面截图;persist: true 时存为 attachment 供多模态查看,否则返回截断的 base64 文本
chrome_click	interaction	按 CSS 选择器或视口坐标点击;trusted input dispatch(非合成 DOM 事件)
chrome_type	interaction	向聚焦元素输入文本;ASCII 走按键事件,非 ASCII(中文等)走 Input.insertText
chrome_cdp	raw	万能直通:发任意 Domain.method CDP 命令。逃生舱,覆盖 50 域 568 命令的长尾

工具输出 schema 一律声明可选 error/hint 字段:错误分支返回结构化 {error, hint},不会被 additionalProperties: false 拒成 "invalid output"。

会话里可以这样用:

• "列出浏览器目标"
• "打开 example.com 并截图"
• "看当前页面控制台有没有 error"
• "刷新页面,列出失败的网络请求"
• "在 app.js 第 42 行下断点,点按钮,然后看暂停处的变量"

---

安装到 DSH

前置

• 任意方式安装的 dsh CLI(npm 全局或源码 checkout 运行均可)
• Node ≥ 20,pnpm(dsh plugin 底层转发给 pnpm)
• dsh ≥ 0.1.2-alpha.3:0.2.0 起插件对齐该版本的 settings/client API(installSettingsSection → SettingsProvider.installSection,dsh-client-runtime → dsh-client-store);旧版 dsh(≤ 0.1.1-rc.2)请用插件 0.1.1。

安装插件包(host 半边 + 面板 + bundle 层)——生产环境主要手段

dsh plugin --profile web add github:xiaobai2017666/dsh-chrome-cdp

这是生产环境安装的主要手段:不写 # ref 时 pnpm 跟踪仓库默认分支(本仓库为 master)的最新提交。lib/、client/ 等构建产物随 git 提交发布(不经 npm 发布、不挂 Release),包内没有任何 prepare/build 脚本,所以 pnpm 安装时不执行任何构建、不触发 allowBuilds 门禁——一条命令直接装完。dsh plugin 检测到包声明 dsh.bundle,自动把 dsh-chrome-cdp 追加进 dsh.profile.bundles;下次启动时 bundle patch 自动插入 host 行(chrome-cdp),面板经 dsh.client 声明自动挂进 Web GUI——不需要手写任何 profile patch。

默认分支前进后更新(无 pin 跟踪分支的唯一维护动作):

dsh plugin --profile web update dsh-chrome-cdp

因为包内没有构建脚本,更新也不涉及 allowBuilds 轮换——update 重新解析默认分支,直接跳到新 commit。

需要可复现/受控升级时,可以退回 pin 形式 #<commit-sha> 或 #v0.1.1(tag):spec 固定不变,更新完全受控;代价是失去"update 即跟进分支"的便利。两种形态随时可用 add 互换,lockfile 会随 add 重写。本仓库按 Keep a Changelog 记录每次发版变更,跟随 master 即可获得累积更新。

更新与卸载

dsh plugin --profile web update dsh-chrome-cdp   # 跟进默认分支最新 commit(白名单 key 轮换见步骤 1)
dsh plugin --profile web remove dsh-chrome-cdp   # 卸载:连依赖和 bundle 层一起摘
rm -rf ~/.dsh/.agent-presets/chrome-cdp-tools    # 卸载:摘 preset

开发循环

# 改 src/ 后:
npm run build                          # 三个产物
touch ~/.dsh/profiles/web/cordis.patch.yml   # host 半边热重载(~6-8s)
# preset YAML 改动即时生效;client 产物需浏览器刷新

• 诊断脚本:scripts/tools-probe.mjs(11 工具 25 用例,含断点真实命中)、cdp-probe.mjs/cdp-console.mjs(裸 CRI 驱动)
• 设计文档:DESIGN.tools.md

License

MIT