browser_cdp

浏览器 CDP 连接参考

Chrome DevTools Protocol（CDP） 允许外部程序连接并控制一个已在运行的 Chrome 进程。本 skill 覆盖三类场景：

1. 扫描本地 CDP 端口 — 发现正在运行的可连接 Chrome
2. 连接已有 Chrome — 附加到外部 Chrome，不影响其运行
3. 启动暴露 CDP 端口的浏览器 — 让 Playwright 启动的浏览器对外可见

⚠️ 隐私提示：使用 CDP 前请知晓

• 默认模式（start 不带 cdp_port）：浏览器完全由 Playwright 私有管理，历史记录、Cookies、登录态不会暴露给任何外部程序。
• CDP 模式（start + cdp_port 或 connect_cdp）：任何能访问该端口的程序都可以读取浏览器的完整历史记录、Cookies、当前页面内容、已保存密码等敏感信息。仅在信任的本地环境中使用，不要在公共网络或多用户服务器上暴露 CDP 端口。

⚠️ 单实例限制：一个 workspace 同时只能运行/连接一个浏览器

无论是 Playwright 启动的浏览器还是 CDP 连接，同一 workspace 内同一时间只允许存在一个。需要切换时，必须先执行 stop，再启动或连接新的浏览器。

---

何时使用

仅在用户明确表达以下意图时才使用本 skill：

• 用户说：「连接到我已打开的 Chrome」「扫描一下本地有没有可连接的浏览器」
• 用户明确希望多个 agent 或外部工具共享同一个浏览器实例
• 用户明确要求浏览器对外可见/可调试
• 用户主动提到 CDP、远程调试端口等概念

以下情况不要使用 CDP 模式，直接用普通 start 即可：

• 用户只是说「打开浏览器」「帮我打开某网站」，没有提到共享或调试
• 用户没有明确说明需要暴露浏览器给其他程序
• 不确定用户是否了解 CDP 的隐私风险

使用前须告知用户 CDP 模式会暴露浏览器历史、Cookies 等敏感信息，确认用户知情后再操作。

---

场景一：扫描本地 CDP 端口

默认扫描端口范围 9000–10000，并发探测，速度很快。

{"action": "list_cdp_targets"}

指定单个端口：

{"action": "list_cdp_targets", "port": 9222}

自定义扫描范围（未找到时可扩大范围）：

{"action": "list_cdp_targets", "port_min": 8000, "port_max": 12000}

成功返回示例：

{
  "ok": true,
  "found": {
    "9222": [{"title": "New Tab", "url": "chrome://newtab/", ...}]
  },
  "message": "Found CDP endpoints on port(s): 9222"
}

未找到时 返回 ok: false，并提示扩大范围或确认 Chrome 是否以 --remote-debugging-port=N 启动。

---

场景二：连接已有 Chrome（connect_cdp）

先扫描到端口后，再连接：

{"action": "connect_cdp", "cdp_url": "http://localhost:9222"}

• 连接成功后可正常使用 open、snapshot、click、type 等所有操作
• 不会影响 Chrome 进程：执行 stop 时只断开 Playwright 连接，Chrome 继续运行
• 连接期间每次操作前会自动检查连接是否正常，断开时返回错误提示重新连接
• 隐私风险：连接后 agent 可读取该 Chrome 的完整 Cookies、历史记录、当前页面内容，请确认用户知情
• 单实例：如果当前已有浏览器在运行（无论是 Playwright 启动的还是另一个 CDP 连接），必须先 stop 再连接

---

场景三：启动带 CDP 端口的浏览器

让 Playwright 启动浏览器时暴露指定 CDP 端口，其他工具可同时连接：

{"action": "start", "cdp_port": 9222}