# 浏览器取证与打开网页规则

本文件用于验证码识别任务中必须打开真实网页、截图、抓包、收集脚本或观察验证组件时。默认优先离线分析用户已提供的 HTML、截图、URL、脚本片段和页面文案；只有证据不足且用户确认授权范围后，才进入浏览器取证。

## 何时读取

出现以下任一情况时读取本文件：

- 需要打开目标网页。
- 需要截图、查看页面标题、读取组件 DOM 或 iframe。
- 需要抓包、导出 HAR/cURL、查看请求 initiator。
- 需要收集 JS bundle、chunk、sourcemap。
- 需要注入最小 Hook、观察 XHR/fetch、Cookie 或 Storage 写入。
- 页面出现验证码、登录、MFA、设备验证或风控验证。
- 需要采集用户手动完成验证码后的成功基线样本。
- 用户明确要求避免普通自动化、CDP 或 WebDriver 检测。

## 硬性规则

- 启动任何浏览器前，先让用户确认取证模式。
- 用户未确认前，只能做离线材料分析和缺失证据提示。
- 不要直接使用普通 Playwright、Puppeteer、Selenium、系统 Chrome、系统 Firefox 或 CDP 路线打开目标页。
- 已选模式后，后续所有浏览器取证动作都沿用该模式。
- 工具不可用、路径缺失、runtime 不合格、需要登录或必须更换工具时，暂停并让用户确认；不要静默 fallback 到普通浏览器自动化。
- 出现登录、验证码、MFA、设备验证时暂停，让用户手动完成；不要自动破解、代过验证、注入 token 或调用第三方打码服务。
- 授权取证中需要建立成功基线时，用户手动完成验证码；AI 只采集经确认的证据、成功状态和时间线，不替用户提交或代过。
- 浏览器取证只用于识别和证据采集，不进入最终交付方案作为自动化执行路径。

## 取证模式

让用户从以下模式中选择：

| 模式 | 说明 | 建议 |
| --- | --- | --- |
| ruyiPage + RuyiTrace | 使用 ruyiPage 打开页面并采集网络/页面证据，RuyiTrace 采集运行时日志 | 高风控、需要环境日志时推荐 |
| 仅 ruyiPage | 使用 ruyiPage 打开页面、截图、抓包、收集 JS，不采集 RuyiTrace 日志 | 只需要网页证据时 |
| Camoufox + camoufox-reverse-mcp | 使用 Camoufox 反指纹浏览器和 MCP 工具做网络、脚本、Hook 与调用栈取证 | 需要 Firefox/Camoufox 路线和 MCP 工具链时 |
| 仅 Camoufox | 使用 Camoufox 官方 API 做轻量取证 | 用户已有 Camoufox 或只需打开页面时 |
| CloakBrowser | 使用 CloakBrowser 有头 + humanize 的 Chromium 路线 | 目标更适合 Chromium 或用户已有 CloakBrowser 时 |
| 用户手动取证 | 用户自行提供 HTML、截图、HAR、cURL、JS 文件、调用栈截图 | 不允许自动化或需要真实登录态时 |
| AI 自行决定 | 先检测本机工具，提出将使用的模式，用户确认后再启动 | 用户不确定时 |

## 各模式最低要求

### ruyiPage / RuyiTrace

- 使用有头模式。
- 使用专用临时 profile。
- 从第一次打开目标页开始使用 ruyiPage，不先用普通浏览器探测。
- 如果选择 ruyiPage + RuyiTrace，但 RuyiTrace 不可用，不得静默降级；让用户确认安装、提供路径或明确降级为仅 ruyiPage。
- 导航后应确认 `navigator.webdriver === false`。
- 只检测到系统 Firefox fallback 不视为通过；必须确认 ruyiPage 定制 Firefox runtime 可用。

### Camoufox / camoufox-reverse-mcp

- 使用 Camoufox 官方入口或 MCP 工具，不用普通 Playwright 指向系统浏览器。
- 默认有头：`headless=False`。
- 默认启用拟人行为：`humanize=True`。
- 如使用代理，需考虑语言、时区、地理位置、WebRTC 与出口 IP 的一致性。
- 选择 MCP 但 MCP 不可用时，不得静默降级为仅 Camoufox；先让用户确认。

### CloakBrowser

- 使用 CloakBrowser 官方包装器入口。
- 默认有头并启用 `humanize`。
- 不直接调用普通 `chromium.launch()`、`puppeteer.launch()` 或普通 browserType 启动。
- 需要登录态或高风控时，优先使用持久化 profile；profile 是否保留或删除由用户确认。

## 工具缺失时的引导

所选模式的工具缺失、包可导入但浏览器本体缺失、路径缺失或 runtime 不合格时，必须先向用户说明当前缺口，并提供“已安装则提供路径 / 未安装则确认安装目录和安装方式 / 明确降级或切换模式”的选项。不要静默 fallback 到普通 Playwright、Puppeteer、Selenium、系统 Chrome、系统 Firefox 或 CDP 路线。

真实安装、下载、克隆或修改环境前，先输出安装计划，等待用户确认后再执行。安装计划中只使用相对目录、用户提供目录或占位符，不要写入当前机器的绝对路径。

### ruyiPage / RuyiTrace 缺失

优先检测：

```bash
python -c "import ruyi; print('ruyiPage package ok')"
python -c "import requests; print('requests ok')"
python -c "from pathlib import Path; print('请在检测脚本或用户提供路径中校验 ruyiPage 定制 Firefox runtime')"
```

如果已有外部检测脚本，可使用等价命令检查 ruyiPage browsers 目录、定制 Firefox 可执行文件和 RuyiTrace 目录：

```bash
node scripts/check_external_tools.js --markdown
node scripts/check_external_tools.js --python <python> --ruyipage-install-dir <ruyipage-browsers-dir> --markdown
node scripts/check_external_tools.js --python <python> --ruyipage-browser-path <firefox-exe> --ruyitrace-home <RuyiTrace-dir> --json
```

未检测到 ruyiPage 定制 Firefox runtime 时，使用这个提示：

```markdown
当前没有检测到 ruyiPage 定制 Firefox runtime，或 ruyiPage 可能会退回系统 Firefox。系统 Firefox 不视为通过。

请确认：
1. 你是否已经提前安装好 ruyiPage 定制 Firefox？
2. 如果已经安装，请提供 ruyiPage browsers 安装目录或定制 Firefox 可执行文件路径。
3. 如果没有安装，请提供希望安装到的目录；我会先输出安装计划，确认后再安装或下载 runtime。

在检测通过前，我不会改用普通 Playwright、Puppeteer、系统 Firefox 或 CDP 取证。
```

选择 `ruyiPage + RuyiTrace` 但未检测到 RuyiTrace 时，使用这个提示：

```markdown
当前没有检测到可用 RuyiTrace，或 RuyiTrace 目录不完整。你选择的是 ruyiPage + RuyiTrace，因此不能静默降级为仅 ruyiPage。

请确认：
1. 是否已经安装 RuyiTrace？如果已安装，请提供 RuyiTrace 目录。
2. 如果没有安装，请提供希望下载或解压到的目录；我会先输出安装计划，确认后再下载或安装。
3. 如果暂时不需要 RuyiTrace NDJSON，请明确回复“降级为仅 ruyiPage”。
```

### Camoufox / camoufox-reverse-mcp 缺失

优先检测：

```bash
python -c "from camoufox.sync_api import Camoufox; print('Camoufox package ok')"
python -m camoufox path
```

Camoufox 官方流程不只是安装 Python 包，还需要下载浏览器本体。常见安装和下载命令：

```bash
python -m pip install camoufox --upgrade
python -m camoufox fetch
python -m camoufox path
```

如果已有外部检测脚本，可使用等价命令检查 Python 包、浏览器缓存目录和 MCP 项目目录：

```bash
node scripts/check_external_tools.js --python <python> --require-camoufox --markdown
node scripts/check_external_tools.js --python <python> --require-camoufox --camoufox-install-dir <camoufox-cache-dir> --markdown
node scripts/check_external_tools.js --python <python> --require-camoufox --require-camoufox-mcp --camoufox-mcp-project-dir <camoufox-reverse-mcp-dir> --json
```

未检测到 Camoufox 或未检测到 `python -m camoufox fetch` 下载的浏览器本体时，使用这个提示：

```markdown
当前没有检测到可用 Camoufox，或只检测到 Python 包但未检测到 `python -m camoufox fetch` 下载的浏览器本体。

请确认：
1. 你是否已经在某个 Python / venv 中安装 Camoufox？如果已安装，请提供 Python 解释器路径或 venv 激活方式。
2. 你是否已经执行过 `python -m camoufox fetch`？如果已执行，请提供 `python -m camoufox path` 输出，或 Camoufox 缓存目录。
3. 如果没有安装，请提供希望使用的 Python / venv 和下载缓存目录；如果不提供目录，我会说明将使用 Camoufox 默认缓存目录。

在检测通过前，我不会改用普通 Playwright、Puppeteer、系统 Firefox 或 CDP 取证。
```

选择 `Camoufox + camoufox-reverse-mcp` 但 MCP 缺失时，使用这个提示：

```markdown
当前没有检测到 camoufox-reverse-mcp。你选择的是 Camoufox + camoufox-reverse-mcp，因此不能直接降级为仅 Camoufox。

请确认：
1. 是否已经克隆并安装 camoufox-reverse-mcp？如果已安装，请提供项目目录或可导入该包的 Python / venv。
2. 如果未安装，请提供希望克隆到的目录；我会先输出安装计划，确认后再执行 `git clone <camoufox-reverse-mcp-repo-url> <camoufox-reverse-mcp-dir>` 与 `python -m pip install -e .`。
3. 如果你不想安装 MCP，请明确回复“降级为仅 Camoufox”。
```

### CloakBrowser 缺失

优先检测 Python 或 Node.js 包，以及 stealth Chromium 二进制是否存在：

```bash
python -c "import cloakbrowser; print('CloakBrowser Python package ok')"
python -m cloakbrowser info
npx cloakbrowser info
```

如果已有外部检测脚本，可使用等价命令检查 Python 包、Node 项目目录和二进制路径：

```bash
node scripts/check_external_tools.js --require-cloakbrowser --markdown
node scripts/check_external_tools.js --require-cloakbrowser --cloakbrowser-project-dir <node-project-dir> --markdown
node scripts/check_external_tools.js --python <python> --require-cloakbrowser --cloakbrowser-binary-path <chromium-or-chrome-path> --json
```

未检测到 CloakBrowser 时，使用这个提示：

```markdown
当前未检测到可用 CloakBrowser 环境。

请确认：
1. 你是否已经提前安装好 CloakBrowser？
2. 如果已经安装，请提供 Python 解释器 / Node 项目目录 / CloakBrowser Chromium 二进制路径。
3. 如果没有安装，请确认希望使用 Python 路线还是 Node.js 路线，并提供安装目录或项目目录；我会先输出安装计划，确认后再安装或预下载二进制。

在 CloakBrowser 检测通过前，我不会改用普通 Playwright、Puppeteer、系统 Chrome 或 CDP 取证。
```

Python 路线：

```bash
python -m pip install cloakbrowser playwright --upgrade
python -m cloakbrowser install
python -m cloakbrowser info
python -m cloakbrowser update
python -m cloakbrowser clear-cache
```

Node.js / Playwright 路线：

```bash
npm install cloakbrowser playwright-core
npx cloakbrowser install
npx cloakbrowser info
npx cloakbrowser update
npx cloakbrowser clear-cache
```

Node.js / Puppeteer 路线只有用户明确要求 Puppeteer 风格 API 时才使用：

```bash
npm install cloakbrowser puppeteer-core
```

## 取证顺序

1. 确认授权范围和目标页面。
2. 让用户确认取证模式。
3. 检测用户选择的工具是否可用。
4. 工具不可用时，暂停并让用户确认安装、提供路径、降级或切换模式。
5. 按确认模式从第一次导航开始打开页面。
6. 如需要登录、验证码、MFA 或设备验证，暂停等待用户手动完成。
7. 如果本次取证用于后续验证方案或失败复盘，采集用户手动成功样本基线：
   - 默认同一授权目标至少 5 次成功样本。
   - 如果过程中出现新的验证码类型，每个新类型至少补到 2 次成功样本。
   - 每轮记录验证码类型、厂商、变体、成功前后截图或截图元信息、验证码区域 DOM 摘要、脚本/iframe URL、关键请求摘要、成功 UI/callback/response token 或服务端成功状态、challenge id、时间线和刷新/切题信息。
   - 动态切题时不要只保留最后一轮；每一轮都作为独立 `success_samples` 记录。
8. 用 `scripts/evaluate_success_baseline.py --samples success_samples.json --pretty` 评估成功基线；不足时输出强提示，用户确认后仍可继续离线分析或受控验证。
9. 只执行最少必要操作：截图、网络捕获、脚本列表、接口 initiator、页面文案和组件特征。
10. 用采集到的 HTML、URL、文案或截图元信息运行 `scripts/classify_verify.py`。
11. 输出类型、厂商、命中信号、置信度、推荐方案和成功基线状态。

## 成功样本基线格式

建议把用户手动完成的成功样本整理为：

```json
{
  "authorization_scope": "用户确认的自有/授权测试目标",
  "provider": "custom-or-unknown",
  "success_samples": [
    {
      "sample_id": "manual-success-001",
      "success": true,
      "captcha_type": "slider",
      "captcha_variant": null,
      "evidence": {
        "screenshot_before": "<relative path or description>",
        "screenshot_after": "<relative path or description>",
        "dom_summary": "<captcha container summary>",
        "script_or_iframe_urls": ["<url without secrets>"],
        "network_summary": ["<request/response summary without secrets>"],
        "success_signal": "UI 显示验证成功 / callback 被调用 / 服务端返回成功",
        "challenge_id": "<non-secret challenge id if available>",
        "timeline": ["challenge rendered", "user solved", "success state observed"]
      }
    }
  ]
}
```

不要把 Cookie、Authorization、账号材料、API key 或可复用 token 写入样本文件；需要说明时只写字段名、状态和脱敏摘要。

## 用户确认模板

```markdown
本次需要打开真实网页取证。为避免普通自动化或 CDP 特征影响验证码判断，请先确认取证模式：

- ruyiPage + RuyiTrace
- 仅 ruyiPage
- Camoufox + camoufox-reverse-mcp
- 仅 Camoufox
- CloakBrowser
- 用户手动取证
- AI 自行决定

在你确认前，我不会打开页面、截图、抓包、读取 Cookie/Storage 或启动浏览器工具。
```