# @dougen/dsh-cdp 中文文档

规范地址：https://npmcn.com/package/%40dougen/dsh-cdp/

版本：0\.5\.0
npm 元数据更新时间：2026-11-06T02:27:56.748Z
中文译文更新时间：2026-11-13T00:48:13.047Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dougen/dsh-cdp
原文对照：https://npmcn.com/package/%40dougen/dsh-cdp/?lang=original
项目主页：https://github.com/dougen/dsh-cdp#readme
源码仓库：https://github.com/dougen/dsh-cdp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：281 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- 首次发布：2026-09-24T04:02:51.790Z
- 最新版本发布：2026-11-06T02:27:56.428Z
- 近 30 天下载量：2651（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

从DSH驱动一个已经运行的Chrimium浏览器来覆盖 CDP——Chrome, Edge, Brave, Vivaldi, Opera, Chrimium, Arc, Thorium:每个连接一个批准,没有新工具,没有运行时间依赖.

## 安装

```sh
npm install @dougen/dsh-cdp
```

也可以使用：`pnpm add @dougen/dsh-cdp`、`yarn add @dougen/dsh-cdp`、`bun add @dougen/dsh-cdp`

## README

# @dougen/dsh-cdp

[English](https://npmcn.com/package/%40dougen/dsh-cdp/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 工具调用 |
| 浏览器扩展 + 常驻监控程序 | 多一层扩展依赖，安装复杂 | **零运行时依赖**，纯插件 |

## 二、安装与卸载

### 安装

```sh
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：用独立配置目录启动（不弹窗，但没有现有登录态）**

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

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

### 卸载

```sh
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

## 常见问题

### @dougen/dsh-cdp 是什么？

从DSH驱动一个已经运行的Chrimium浏览器来覆盖 CDP——Chrome, Edge, Brave, Vivaldi, Opera, Chrimium, Arc, Thorium:每个连接一个批准,没有新工具,没有运行时间依赖\.

### 如何安装 @dougen/dsh-cdp？

在项目目录运行 npm install @dougen/dsh-cdp，或使用 pnpm add / yarn add / bun add。

### @dougen/dsh-cdp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dougen\_\_dsh-cdp 是否存在。

### @dougen/dsh-cdp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dougen/dsh-cdp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dougen/dsh-cdp 可以商用吗？

@dougen/dsh-cdp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dougen/dsh-cdp 的下载量有多少？

根据 npm 官方下载统计，@dougen/dsh-cdp 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,651 次，日均约 88 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dougen/dsh-cdp 还在维护吗？

最新版本 0\.5\.0 发布于 2026/11/06（7 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/09/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。