@dougen/dsh-cdp

dsh plugin --profile web add @dougen/dsh-cdp

@dougen/dsh-cdp

[English](README.md) · 中文

让 DSH 直接驱动你已经在用的 Chromium 内核浏览器——保留你的登录态、cookie 和扩展。

支持 Chrome、Edge、Brave、Vivaldi、Opera、Chromium、Arc、Thorium。

兼容 DSH 0.1.0 及以上版本——0.1.x 与 0.2.x 全系列，含预发布版。

一、它做什么

DSH 可以读取并操作你浏览器里真实打开的页面：导航、执行 JS、读取 DOM 或无障碍树、点击、悬停、拖拽、输入、按键、截图、模拟视口与深色模式、读取控制台与网络日志，以及做 DOM / 像素断言。所以「看看这个页面上有什么」「登录后把数据抓下来」「这个页面渲染对不对」这类事情，用的是你真实的登录态，不需要另开一个干净的浏览器。

它针对用 CDP 操作浏览器的三个常见麻烦：

常见做法 · 问题 · 本插件

每次操作新建 CDP 连接 · Chromium 的远程调试授权是按连接的 → 每次都要弹窗 · 常驻一条连接 + 心跳保活，授权一次

把浏览器能力注册成多个工具 / MCP · 每个工具的 schema 都进每一次请求，token 开销固定 · 零新增工具，agent 用已有的 shell 工具调用

浏览器扩展 + 常驻监控程序 · 多一层扩展依赖，安装复杂 · 零运行时依赖，纯插件

二、安装与卸载

安装

dsh plugin --profile web add @dougen/dsh-cdp

装完重启 Web GUI（dsh web）后生效。

插件自带 browser-cdp skill，无需另外安装 skill 文件。

让浏览器可以被连接

插件从不启动、也从不关闭你的浏览器——它只连接你自己启动的实例。这一步在 DSH 之外完成，所以 agent 永远不会因此请求授权。

方式 A：用浏览器自带的远程调试开关（推荐，保留登录态）

在浏览器地址栏打开 chrome://inspect（Edge 是 edge://inspect），勾选允许远程调试。之后照常启动浏览器即可。

方式 B：用独立配置目录启动（不弹窗，但没有现有登录态）

msedge.exe --remote-debugging-port=9222 --user-data-dir="C:\edge-debug"

这是一个全新的配置目录，没有你现有的 cookie、登录态和扩展。适合测试。

卸载

dsh plugin --profile web remove @dougen/dsh-cdp

重启 Web GUI 后生效。

可能遇到的情况

现象 · 原因与处理

图标是灰色 / 面板显示「未连接」 · 尚未连接浏览器。点面板按钮或执行任意浏览器命令即可连接，浏览器会询问一次授权。若没有检测到调试端点，在浏览器中打开 chrome://inspect 允许远程调试。

面板显示「等待授权」 · 切到浏览器窗口点 Allow。若没看到弹窗，检查浏览器是否被最小化或被其他窗口遮挡。

命令返回 awaiting-approval · 同上。让用户点授权后再重试一次，不要循环重试。

浏览器重启后图标变灰 · 正常，插件不会自行连接。下一次浏览器命令（或面板里的「连接浏览器」）会建立新连接，浏览器会再询问一次授权。

图标变成蓝色 · agent 正在操作你的浏览器。命令结束后还会保持约 5 秒，然后回到连接状态的颜色。

无法用 --remote-debugging-port 连默认配置目录 · Chrome/Edge 136+ 的官方安全限制（防止恶意程序借调试端口读取 cookie），用上面方式 A。

browsers 只列出部分浏览器 · 只会列出真实安装了且有配置目录的；可用 cordis.patch.yml 固定某个浏览器。

插件标题、插件说明、面板文案和本 README 跟随 Web GUI 的语言设置：中文界面显示中文，其他语言显示英文。

三、工作原理

DSH 宿主进程
├── 唯一一条 CDP WebSocket（心跳保活）
├── /api/dsh-cdp          本机 HTTP 路由，仅接受回环 Host
└── 自带 browser-cdp skill
        ↑ agent 用已有 shell 工具调用（无新增工具）
        ↓
   你的浏览器（Chrome / Edge / Brave / …）

宿主进程内保持唯一一条 CDP 连接，把浏览器操作挂在本机回环路由上。agent 用它已经有的 shell 工具（Invoke-RestMethod、curl）调用，所以新增的模型可见工具 schema 是 0 个；用法由随插件注册的 browser-cdp skill 说明，只在需要时加载。

因为连接是常驻的、并且带心跳保活，Chromium 的远程调试授权在每个浏览器会话里只发生一次——即建立连接的那一次。连接是按需建立的：插件从不主动连接，所以只是打开浏览器不会弹窗；下一次浏览器命令（或面板里的「连接浏览器」按钮）才会建立连接并请求授权。

两个实现细节：

• 浏览器发现走两路。 默认读浏览器配置目录下的 DevToolsActivePort 文件（浏览器自选端口时写它）；若浏览器是用显式非零 --remote-debugging-port 启动的，则用该端口——此时浏览器故意不写那个文件。判定始终以「TCP 可连 + WebSocket 握手成功」为准。
• 「等待授权」是独立状态，不是「连不上」。 浏览器等待授权时，socket 既不 open 也不 error，只是沉默。插件给握手设了期限，把这段沉默归类成该状态。被挂起的 socket 会保留并复用：你点 Allow 后直接接管，不会另开连接（那会弹出第二个授权框）。这个状态也不是死路：socket 若报错、或沉默到远超任何真实弹窗的时长（90 秒），插件会丢弃它——之后不会有任何自动重连，直到下一次浏览器命令（或面板的「连接浏览器」）主动建立连接。Chromium 的授权是按连接的，插件自作主张重连就会让弹窗在每次打开浏览器时冒出来。

browser-cdp skill 用机制而非约定来保证 agent 不碰你的标签页：读命令可以检查任何页面，而所有会改变页面显示的命令——导航、点击、输入、悬停、滚动、上传、视口/媒体覆盖、关闭标签、应答弹窗——只接受插件自己新开的标签。每条真正触达浏览器的命令都会追加到本地审计日志。

License

MIT