\r \r

browser-use-init Skill\r

\r

概述\r

\r 此 Skill 提供完整的 Chrome DevTools Protocol（CDP）初始化和连接方案，用于在 Chrome 145+ 版本下远程控制浏览器。\r \r

为什么需要这个 Skill\r

\r Chrome 130+ 引入了安全限制，--remote-debugging-port 强制要求使用非默认的 user-data-dir 路径。直接用默认 Profile 启动 CDP 调试会失败，导致无法用 Playwright 或 browser-use 连接浏览器。\r \r 此 Skill 通过自动复制 Profile 到自定义目录的方式绕过此限制，同时保留登录态。\r \r ---\r \r

快速开始\r

\r

1. 首次初始化（一次性）\r

\r

cd \x3Cskill 目录>/scripts\r
python start_chrome.py\r
```\r
\r
输出示例：\r
```\r
[1] 关闭现有 Chrome...\r
[2] 准备 profile...\r
[profile] 首次复制 profile...\r
  复制 Default (~可能需要几分钟)...\r
[profile] 复制完成: \x3CCHROME_PROFILE_DIR>\r
[3] 启动 Chrome (CDP 模式)...\r
[4] 等待 CDP 就绪...\r
[OK] Chrome 已启动: Chrome/145.0.7632.160\r
[OK] CDP 端口 9222 就绪\r
[OK] WS URL: ws://localhost:9222/devtools/browser/...\r
```\r
\r
此时 Chrome 窗口已打开，可用浏览器操作。\r
\r
### 2. 处理首次登录态丢失\r
\r
如果登录状态丢失（DPAPI 绑定限制），需要**手动登录一次**：\r
\r
- 在弹出的 Chrome 窗口中打开：你的登录网址\r
- 使用你的登录方式（App 扫码、验证码、账号密码等）完成登录\r
- 登录成功后关闭 Chrome\r
\r
重新运行 `start_chrome.py`，登录态现已保存，以后启动无需重新登录。\r
\r
### 3. 查询 CDP 连接信息\r
\r
```bash\r
python query_cdp.py\r
```\r
\r
输出：\r
```\r
Browser: Chrome/145.0.7632.160\r
WS URL: ws://localhost:9222/devtools/browser/8c3e...\r
Version: 12.7\r
\r
标签页 (1):\r
  - 京东首页 | https://www.jd.com/\r
```\r
\r
---\r
\r
## 工作流场景\r
\r
### 场景 A：用 Playwright 直接操作（确定性任务）\r
\r
适用于：数据提取、页面截图、表单填充等明确的操作\r
\r
```python\r
import asyncio\r
from scripts.playwright_connect import get_page\r
\r
async def extract_data():\r
    pw, browser, page = await get_page()\r
    try:\r
        await page.goto("https://example.com/data-page")\r
        await page.wait_for_load_state("networkidle")\r
        \r
        # 用 JS 提取页面信息\r
        items = await page.evaluate("""\r
        () => {\r
            return Array.from(document.querySelectorAll('.item-name'))\r
                .map(el => el.textContent.trim());\r
        }\r
        """)\r
        print("提取的数据:", items)\r
    finally:\r
        await pw.stop()\r
\r
asyncio.run(extract_data())\r
```\r
\r
**优点**：\r
- 快速、可靠、确定性强\r
- 直接控制 DOM，支持 JS 注入\r
- 无需 LLM\r
\r
---\r
\r
### 场景 B：用 browser-use Agent（自然语言任务）\r
\r
适用于：开放式任务、需要 AI 判断的操作\r
\r
```bash\r
python run_agent.py --task "打开网站，找出最新发布的产品名称" --model qwen3.5:9b\r
```\r
\r
或在代码中：\r
\r
```python\r
import asyncio\r
from scripts.run_agent import run_task\r
\r
asyncio.run(run_task(\r
    task="打开网站列表页，提取所有商品的名称和价格",\r
    model="qwen3.5:9b"\r
))\r
```\r
\r
**优点**：\r
- 支持自然语言描述任务\r
- AI 自动判断操作流程\r
- 适合复杂的人机交互\r
\r
**注意**：\r
- 需要本地 Ollama 运行且模型可用\r
- LLM 输出质量直接影响效果\r
\r
---\r
\r
## 技术详解\r
\r
### 核心脚本说明\r
\r
| 脚本 | 用途 | 何时使用 |\r
|------|------|--------|\r
| `start_chrome.py` | 启动 Chrome CDP 模式，复制 Profile | 首次初始化、每次重启浏览器 |\r
| `query_cdp.py` | 查询 CDP 连接状态和已打开标签页 | 诊断、获取 WebSocket URL |\r
| `playwright_connect.py` | 用 Playwright 直连 CDP Chrome | 需要确定性自动化操作 |\r
| `run_agent.py` | 用 browser-use Agent + LLM | 需要 AI 驱动的自然语言任务 |\r
\r
### Chrome Profile 复制机制\r
\r
首次运行 `start_chrome.py` 时：\r
\r
1. **复制 Local State**：包含加密密钥元数据，确保旧 Cookie 能被解密\r
2. **复制 Default Profile**：包含所有 Cookie、历史记录、书签等\r
3. **排除大文件**：自动跳过 Cache、Code Cache、日志等不必要的文件（加快速度）\r
\r
```\r
原始路径：%LOCALAPPDATA%\Google\Chrome\User Data\r
    ↓ (复制)\r
自定义路径：\x3CCHROME_PROFILE_DIR>（可通过环境变量配置）\r
    ↓ (启动 Chrome)\r
Chrome 以 --remote-debugging-port 识别为"非默认路径" ✓\r
    ↓ (DPAPI 解密)\r
旧 Cookie 被解密并加载 ✓\r
```\r
\r
### DPAPI 与登录态\r
\r
**首次登录态可能丢失的原因**：DPAPI 密钥绑定到原始 user-data-dir 路径。\r
\r
**解决方案**：手动登录一次后，新 Cookie 使用新路径的 DPAPI 密钥加密，之后自动保持。\r
\r
详见：`references/chrome-cdp-solution.md` 中的 DPAPI 章节。\r
\r
---\r
\r
## 依赖与环境\r
\r
### 最小依赖\r
\r
```bash\r
# 仅启动 Chrome（无需额外包）\r
python start_chrome.py\r
\r
# 查询 CDP（仅需标准库）\r
python query_cdp.py\r
```\r
\r
### Playwright 支持\r
\r
```bash\r
pip install playwright\r
playwright install chromium\r
```\r
\r
### browser-use Agent 支持\r
\r
```bash\r
pip install browser-use langchain-ollama\r
ollama pull qwen3.5:9b  # 或其他模型\r
```\r
\r
---\r
\r
## 常见问题\r
\r
### Q: 为什么首次登录态丢失？\r
\r
A: Chrome 126+ 用 DPAPI 加密 Cookie，密钥绑定到原始 user-data-dir。复制 Profile 后需重新登录一次，之后会自动保持。详见参考文档。\r
\r
### Q: 我想多开几个 Chrome 实例，怎么做？\r
\r
A: 修改 `start_chrome.py` 中的 `PORT` 和 `DST_DIR` 变量，为每个实例指定不同端口（如 9222、9223）和独立 Profile 目录。\r
\r
### Q: CDP 端口 9222 一直不通\r
\r
A: 检查清单（详见参考文档故障排查章节）：\r
- `tasklist | grep chrome` 确认 Chrome 进程\r
- `netstat -ano | grep 9222` 检查端口占用\r
- 确认 `--user-data-dir` 是非默认路径\r
\r
### Q: Playwright 连接报 WebSocket 错误\r
\r
A: 运行 `query_cdp.py` 确认 CDP 在线，再尝试连接。如仍失败，检查防火墙设置。\r
\r
---\r
\r
## 进阶用法\r
\r
### 用法 1: 自定义 Profile 位置和端口\r
\r
```bash\r
# 方式 1：修改脚本中的常数（开发模式）\r
# 编辑 start_chrome.py，修改 DST_DIR 和 PORT\r
\r
# 方式 2：使用环境变量（推荐，更灵活）\r
$env:CHROME_PROFILE_DIR = "E:\my-chrome-profile"\r
$env:CDP_PORT = 9223\r
python start_chrome.py\r
```\r
\r
### 用法 2: Playwright 中的高级操作\r
\r
```python\r
async def fill_form():\r
    pw, browser, page = await get_page()\r
    try:\r
        await page.fill("input[name='username']", "user_input")\r
        await page.fill("input[name='password']", "pass_input")\r
        await page.click("button[type='submit']")\r
        await page.wait_for_load_state("networkidle")\r
        await page.screenshot(path="result.png")\r
    finally:\r
        await pw.stop()\r
```\r
\r
### 用法 3: Agent 中自定义提示词\r
\r
```python\r
asyncio.run(run_task(\r
    task="打开网站，用中文列出首页推荐商品的名称和价格",\r
    model="qwen3.5:9b"\r
))\r
```\r
\r
---\r
\r
## 技术参考\r
\r
详细的技术说明、Chrome 版本历史、DPAPI 机制、故障排查等信息，见：\r
\r
📄 **`references/chrome-cdp-solution.md`**\r
\r
---\r
\r
## 本 Skill 解决的核心问题\r
\r
1. ✅ Chrome 130+ 强制非默认 user-data-dir 限制\r
2. ✅ DPAPI App-Bound Encryption 导致的登录态丢失\r
3. ✅ 简化 CDP 初始化流程（一条命令搞定）\r
4. ✅ 提供 Playwright 和 browser-use 两种使用方式\r
5. ✅ 完整的故障诊断和排查工具\r
\r
---\r
\r
## 下一步\r
\r
- 运行 `python start_chrome.py` 启动 Chrome\r
- 查看 `references/chrome-cdp-solution.md` 深入了解技术细节\r
- 选择 Playwright（确定性）或 Agent（AI 驱动）的方式操作浏览器\r