Brave 浏览器直连 olegedly/dsh-plugin-brave-cdp

dsh-plugin-brave-cdp

通过 Chrome DevTools Protocol 驱动你自己已经开着的 Brave：真实窗口、你的配置档、你的 cookie、你的登录状态、你的标签页——包括你此刻正在看的那个标签页。

多数浏览器自动化会另起一个自己拥有的新浏览器。这个插件挂到你已经开着的那个上，智能体因此能读登录墙后的页面、在你已登录的会话里填表，或者把任务中途交回给你，就在同一个窗口里。不从另一个配置档抓任何东西。

两个入口，一套实现：

| 入口 | 什么时候用 |
| DSH 工具（brave_tabs、brave_goto、…） | 智能体驱动浏览器——有 schema、有渲染结果、不用 shell 转义 |
| brave-cdp 命令行（本包自带） | 人或脚本驱动，或者你想用 jq/batch 管道 |

两者调用同一个 CDP 客户端，所以行为和报错信息一致。

工具

| 工具 | 作用 |
| brave_tabs | 列出 / 打开 / 聚焦 / 关闭标签页 |
| brave_goto | 让标签页（或新标签页）导航，并等待加载完成 |
| brave_snapshot | 列出可交互元素，带 @eN 引用（role、name、value、href、state） |
| brave_click | 按 @eN 引用、CSS 选择器或可见文本做真实鼠标点击 |
| brave_fill | 设置 input / textarea / contenteditable，并触发 input/change |
| brave_key | 按键，可选带 ctrl / shift / alt / meta |
| brave_eval | 在页面里执行 JavaScript，等待 promise |
| brave_wait | 等待选择器、文本、url 或文档加载 |
| brave_screenshot | 截一张 PNG，返回它的路径 |

不带 tab 参数时，工具作用于用户正在看的标签页（document.visibilityState === 'visible'），每个结果都带命令行的 tab: 头，一眼看出是哪个标签页执行的调用。@eN 引用来自 brave_snapshot，页面导航前一直有效。

截图返回路径，不返回内联像素：智能体用它已有的读图工具去读 PNG，所以这个插件不需要自带视觉管线。

要求

1. Brave 启动时带 CDP 端口。 把参数加进启动器的参数文件（Arch 的 brave-bin wrapper 用 ~/.config/brave-flags.conf）：

--remote-debugging-port=9222

这个参数只在启动时生效，加完必须重启 Brave。端口绑在回环地址上，但启用前先看安全。

2. Node ≥ 22 跑命令行（它用内置的 fetch 和 WebSocket，无依赖）。DSH 本身也要求 Node ≥ 22。

3. DSH，带 @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery 两个 peer 包（任何 DSH 安装里都有），供工具入口使用。

命令行本身打包在 bin/brave-cdp.mjs；工具从包里解析它，找不到就退回 ~/.local/bin/brave-cdp，再退回 cliPath / BRAVE_CDP_CLI。

安装

into a DSH profile (declares dsh.bundle.patch, so the tools row mounts itself)bash
dsh plugin --profile web add "github:olegedly/dsh-plugin-brave-cdp"

or from a checkout / tarball

dsh plugin --profile web add /path/to/dsh-plugin-brave-cdp

然后确认端点可达： bash
brave-cdp status # endpoint UP + browser version + tab count => ready

独立命令行，不依赖 DSH（还没上 npm，所以从仓库安装）： bash
npm install -g "github:olegedly/dsh-plugin-brave-cdp" # provides brave-cdp
brave-cdp tabs
brave-cdp snapshot -i
brave-cdp click '@e4'
brave-cdp eval 'document.title'
brave-cdp shot page.png --full

命令行

brave-cdp status endpoint, browser version, tab count
brave-cdp tabs [list] tabs, 1-based indices, * marks the target
brave-cdp tabs new <url> open a tab
brave-cdp tabs select <n|id|text> focus a tab and raise its window
brave-cdp tabs close <n|id|text> close a tab
brave-cdp open <url> [--new] navigate (or open) and wait for load
brave-cdp back | forward | reload [--hard]
brave-cdp snapshot [scope] [-i] [--compact] [--json]
brave-cdp click <@eN|css|--text T> [--exact] [--dblclick]
brave-cdp fill <@eN|css> <text> [--append]
brave-cdp type [@eN|css] <text>
brave-cdp key <Enter|Tab|Escape|ArrowDown|...> [--ctrl --shift --alt --meta]
brave-cdp eval <js> [--file <path>|-] evaluate JS, print JSON
brave-cdp html [css] [--text] / text [css]
brave-cdp shot [file] [--full]
brave-cdp wait <ms>|@eN|--selector S|--text T|--url U|--load
brave-cdp batch "open https://x" "wait --text Done" "shot done.png"

全局参数：--tab <n|id|url-substr>、--json、--timeout <ms>、--port <n>。
环境变量：BRAVE_CDP_PORT（9222）、BRAVE_CDP_HOST（127.0.0.1）、BRAVE_CDP_TIMEOUT。

brave-cdp help 是权威说明。

配置

| 键 | 默认值 | 含义 |
| cliPath | 内置的 bin/brave-cdp.mjs | 要调用的命令行 |
| port | 9222 | CDP 端口（必须与 Brave 的启动参数一致） |
| timeoutMs | 60000 | 单次调用超时 |
| screenshotTimeoutMs | 120000 | 截图超时 |

内置补丁把这一行挂载为 brave-cdp；配置档自己的 cordis.patch.yml 会在之后应用，所以覆盖这个 id 就能改端口，或指向另一个命令行： yaml
- id: brave-cdp
config:
port: 9223

安全

CDP 意味着完全控制浏览器：页面内容、cookie，以及你登录的任何会话都可读，它还能在任何网站上以你的身份操作。端口只绑定回环地址，这把它限制在本地进程——这是一道边界，不是保证。想让智能体驱动浏览器时再加这个参数，不想时就去掉（并重启）。

开发 bash
npm run check # node --check on the plugin and the CLI
npm test # node --test test/ (no network, no browser needed)

| 路径 | 内容 |
| lib/index.js | 九个工具：schema、参数映射、结果渲染 |
| bin/brave-cdp.mjs | CDP 客户端：传输、目标选择、DOM 引用、输入、截图 |
| cordis.patch.yml | 挂载工具行的 bundle 补丁 |
| test/ | 命令行行为与打包不变量 |

CDP 客户端放在命令行里，插件因此只是一层薄适配器：工具接口和 shell 共用同一条经过测试的代码路径，DSH 宿主进程也无需引入任何浏览器自动化依赖。

许可证

MIT — 见 LICENSE。