前言¶
在 DSH 里让智能体操作网页，常见做法是再起一个自动化专用的浏览器实例：干净配置、无登录态，适合公开页面抓取，却难以复用你当前窗口里的 Cookie、已登录会话，或你正在看的那个标签页。
olegedly/dsh-plugin-brave-cdp 走另一条路：通过 Chrome DevTools Protocol（CDP）挂接到本机已在运行的 Brave，用真实窗口、真实配置和真实标签页做导航、快照、点击、填表与截图。智能体可以在你已登录的会话里读受保护页面、填表，或把任务交回给你时仍停留在同一窗口。插件归类为 DSH 社区目录中的「联网工具」，维护者为 olegedly。
这是什么¶
一句话：DSH tools that drive your running Brave browser over the Chrome DevTools Protocol（与仓库简介一致）。
实现上提供两套入口，共用同一 CDP 客户端，行为与报错一致：
| 入口 | 适用情况 |
|---|---|
DSH tools（brave_tabs、brave_goto 等） |
由智能体调用，带 schema 与结构化结果，无需在 shell 里拼引号 |
brave-cdp CLI（随包提供） |
人工或脚本驱动，或接入 jq、批处理管道 |
未指定 tab 参数时，工具作用于用户当前可见标签（document.visibilityState === 'visible'）；每次结果带 tab: 头，标明实际操作的标签。@eN 引用来自 brave_snapshot，在页面未导航前保持有效。
核心功能¶
DSH 工具面¶
| 工具 | 作用 |
|---|---|
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 并返回文件路径（非内联像素），便于用现有读图能力处理 |
截图返回路径而非内联图像，插件本身不内置视觉流水线。
CLI 能力概览¶
brave-cdp 支持状态检查、标签管理、导航、快照、点击、填表、按键、eval、等待、截图及 batch 串联等子命令。全局选项包括 --tab、--json、--timeout、--port；环境变量含 BRAVE_CDP_PORT（默认 9222）、BRAVE_CDP_HOST（默认 127.0.0.1）、BRAVE_CDP_TIMEOUT。完整子命令以 brave-cdp help 为准。
环境与依赖¶
- Brave 启动时开启 CDP 端口。 在启动器 flag 文件中加入（Arch
brave-bin示例路径为~/.config/brave-flags.conf）：
--remote-debugging-port=9222
该 flag 仅在启动时生效，修改后需重启 Brave。端口绑定在 loopback；启用前请阅读下文安全说明。
-
Node ≥ 22（CLI 使用内置
fetch与WebSocket，无额外依赖；DSH 本身也要求 Node ≥ 22）。 -
DSH 及 peer 包
@deepseek-ai/dsh-tools、@deepseek-ai/schemastery（常规 DSH 安装中已包含），用于挂载工具面。
CLI 位于包内 bin/brave-cdp.mjs；工具解析顺序为包内 CLI → ~/.local/bin/brave-cdp → 配置项 cliPath / 环境变量 BRAVE_CDP_CLI。
安装与启用¶
在 DSH profile 中安装（声明 dsh.bundle.patch，工具行会自动挂载）：
dsh plugin --profile web add "github:olegedly/dsh-plugin-brave-cdp"
或从本地 checkout / tarball 安装：
dsh plugin --profile web add /path/to/dsh-plugin-brave-cdp
确认 CDP 端点可用：
brave-cdp status
输出 endpoint 为 UP、浏览器版本与标签数量时，表示就绪。
不通过 DSH、仅使用 CLI 时（README 注明尚未发布到 npm，需从仓库安装）：
npm install -g "github:olegedly/dsh-plugin-brave-cdp"
brave-cdp tabs
brave-cdp snapshot -i
brave-cdp click '@e4'
brave-cdp eval 'document.title'
brave-cdp shot page.png --full
配置¶
| 键 | 默认值 | 含义 |
|---|---|---|
cliPath |
包内 bin/brave-cdp.mjs |
调用的 CLI |
port |
9222 |
CDP 端口（须与 Brave flag 一致） |
timeoutMs |
60000 |
单次调用超时 |
screenshotTimeoutMs |
120000 |
截图超时 |
bundle patch 将工具行挂载为 brave-cdp；profile 的 cordis.patch.yml 在其后合并，可通过覆盖该 id 改端口或 CLI，例如：
- id: brave-cdp
config:
port: 9223
典型用法¶
安装并重启带 CDP 的 Brave 后，先用 CLI 自检：
brave-cdp status
智能体侧则通过 DSH 调用 brave_snapshot 获取 @eN，再用 brave_click、brave_fill 等操作同一标签。脚本侧可用 batch 串联步骤，例如：
brave-cdp batch "open https://x" "wait --text Done" "shot done.png"
指定标签时，CLI 使用 --tab <n|id|url-substr>。
适用场景与注意¶
适合： 需要在已有登录态、真实用户配置下做自动化或智能体辅助的场景——例如已登录后台、需要与人工共用同一窗口、或希望避免并行无头配置与主浏览器会话不一致。
不适合或需权衡： 期望完全隔离、无人值守沙箱浏览器的任务；CDP 开启期间本机进程可对浏览器做全权控制。
安全： CDP 等同于对浏览器的完全控制：可读页面、Cookie 与已登录会话，并可代你在站点上操作。端口仅监听 loopback，限制在本地进程，这是边界而非绝对保证。仅在需要智能体驱动浏览器时添加 flag，用完后移除并重启 Brave。
权限与信任： 插件以当前 DSH 进程权限运行；安装前请自行查看 GitHub 仓库 源码与 MIT 许可证。DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
若你的痛点是「自动化必须附着在我已经打开、已经登录的 Brave 上」，而不是再起一个陌生实例，dsh-plugin-brave-cdp 用同一套 CDP 客户端同时服务 DSH 工具与 brave-cdp CLI，路径清晰、行为一致。
