cdp

CDP 是一个通过 Chrome DevTools Protocol（CDP）从 JavaScript 驱动 Chrome 的技能。它包含两部分：一是自动生成的 CDP SDK，browser_protocol.json 与 js_protocol.json 中的每个方法都有类型化封装；二是一个轻量 HTTP 服务器，持有单个持久 CDP 会话。browser-harness-js CLI 在首次使用时自动启动服务器，并把 JS 片段转发给它，因此后续调用复用同一会话、同一 WebSocket 连接以及已设置的全局变量。

【用途】用于在 JavaScript 中直接调用 CDP 控制浏览器，例如连接正在运行的 Chromium 系浏览器、选择标签页、导航、执行页面内 JS、监听事件等。

【主要能力】

类型化 SDK：覆盖 56 个 CDP 域、652 个方法，每个方法接收一个与 CDP 线上参数一致的对象，返回类型化结果，无需处理 result 信封与 id 关联。
持久会话：服务器保持一个 CDP Session，跨多次 CLI 调用复用。
自动检测浏览器：session.connect() 无参数时扫描各操作系统特定的 profile 目录中的 DevToolsActivePort 文件，按最近启动排序，选择第一个 WebSocket 可接受的浏览器，支持 Chrome、Chromium、Edge、Brave、Arc、Vivaldi、Opera、Comet、Canary，跨 macOS、Linux、Windows。
目标（标签页）管理：listPageTargets() 通过 Target.getTargets 列出真实页面目标，过滤 chrome:// 与 devtools:// URL，兼容 Chrome 144+。
事件：session.onEvent 订阅事件并返回取消订阅函数；session.waitFor 等待单个匹配事件，支持谓词与超时。
状态持久化：片段内的 let/const 在返回后消失，需把数据挂到 globalThis 上；session、活动 sessionId 与事件订阅由服务器保留。

【使用方式】首次使用需把 CLI 放到 PATH 上（npx skills add 不会自动放）。示例：

macOS (Apple Silicon + Homebrew)

command -v browser-harness-js >/dev/null || ln -sf <skill-dir>/sdk/browser-harness-js /opt/homebrew/bin/browser-harness-js

macOS (Intel) / most Linux — may need sudo

command -v browser-harness-js >/dev/null || ln -sf <skill-dir>/sdk/browser-harness-js /usr/local/bin/browser-harness-js

Linux without sudo (ensure ~/.local/bin is on PATH)

command -v browser-harness-js >/dev/null || { mkdir -p ~/.local/bin && ln -sf /sdk/browser-harness-js ~/.local/bin/browser-harness-js; }

CLI 首次运行会自动安装 bun（服务器为 Bun 原生），可用 BROWSER_HARNESS_SKIP_BUN_INSTALL=1 退出。

基本调用：

browser-harness-js 'await session.connect()' browser-harness-js 'await session.Page.navigate({url:"https://example.com"})' browser-harness-js '(await session.Runtime.evaluate({expression:"document.title",returnByValue:true})).result.value'

输出为原始结果内容，无 {ok,result} 信封：字符串为裸文本，数字/布尔为 42、true，非空对象/数组为紧凑 JSON，undefined/null/""/{}/[] 无输出。错误输出到 stderr，退出码 1。

多行片段可用 stdin heredoc，但多语句片段不会自动返回最后一个表达式，需显式写 return X；作为第一个参数传入的单表达式片段会自动返回。

CLI 命令：browser-harness-js '<js>'（自动启动服务器并求值）、browser-harness-js <<EOF…EOF（从 stdin 读取代码）、--status（打印健康 JSON 或退出 1）、--start、--stop、--restart、--logs（tail -f 服务器日志 /tmp/browser-harness-js.log）。环境变量：CDP_REPL_PORT（默认 9876）、CDP_REPL_LOG（默认 /tmp/browser-harness-js.log）。

片段内预加载的全局对象：session（持久 Session，挂载全部 CDP 域）、listPageTargets()、detectBrowsers()、resolveWsUrl(opts)、CDP（生成的命名空间）。

连接方式：默认 session.connect() 自动检测；也可用 { profileDir } 指定浏览器，或 { wsUrl } 直接给出 WebSocket 地址。每个候选的 WS 打开超时默认 5 秒，若 Chrome 正在显示 Allow 弹窗等待用户点击，可传 timeoutMs: 30000。

选择目标：连接后调用一次 session.use(targetId)，后续页面级调用自动路由到该目标的 sessionId；Browser.* 与 Target.* 始终走浏览器端点。切换标签页用 session.use(otherTargetId)，分离用 session.setActiveSession(undefined)。

【适用场景】

在 JavaScript 中自动化控制已运行的 Chromium 系浏览器。
通过 CDP 执行页面导航、DOM 查询、运行时求值、网络事件监听等操作。
需要跨多次调用保持同一浏览器会话与状态的脚本化流程。

【限制】

首次使用需手动把 CLI 符号链接到 PATH。
多语句 stdin 片段不会自动返回最后一个表达式，需显式 return。
片段内的 let/const 不跨调用保留，需挂到 globalThis。
CDP 目标顺序不等于可见标签栏顺序，Target.activateTarget 只能切换到已知 targetId。
若浏览器启用了远程调试但用户未点击 Allow，会出现 No detected browser accepted a connection。
自动检测失败时需用户手动开启远程调试（chrome://inspect/#remote-debugging）。
上游协议 JSON 变更后需重新生成 SDK：cd <skill-dir>/sdk && bun gen.ts，然后 browser-harness-js --restart。

【文件】所有路径相对于 <skill-dir>：/usr/local/bin/browser-harness-js → <skill-dir>/sdk/browser-harness-js（CLI）；sdk/repl.ts（HTTP 服务器，Bun.serve on 127.0.0.1:9876）；sdk/session.ts（Session 类）；sdk/generated.ts（代码生成输出，约 655 KB）；sdk/gen.ts（代码生成脚本）；sdk/{browser,js}_protocol.json（上游协议）。

技能介绍

macOS (Apple Silicon + Homebrew)

macOS (Intel) / most Linux — may need sudo

Linux without sudo (ensure ~/.local/bin is on PATH)