obscura-browser

Obscura Browser

概述

使用此技能帮助用户操作 obscura CLI，并将客户端库连接到其 CDP 服务。优先提供简短、可执行的命令，只有在有助于满足用户需求时，才补充可选标志或示例代码。对于本地开发，默认使用 Vite + hostc + Obscura，而不是建议访问 localhost。

工作流

1. 提供运行命令前，先检测本地是否有 obscura。
2. 如果缺少该工具，说明适用于当前操作系统的最简安装方式。
3. 如果目标是本地开发，不要建议修改 Obscura 或直接使用 localhost。默认采用以下方案：
   • 在本地应用上运行 Vite 或其他开发服务器
   • 使用 hostc 将本地端口公开为 https:// URL
   • 让 Obscura 访问此公开 URL
4. 根据需求选择最精简的 Obscura 流程：
   • 单个页面或单次提取：使用 fetch
   • 并行处理多个 URL：使用 scrape
   • 连接 Playwright 或 Puppeteer CDP：使用 serve
5. 首先提供一条最简命令或一段最简代码示例。
6. 只添加与用户目标相关的标志，例如 --stealth、--timeout、--wait-until、--output、--concurrency 或 --quiet。

快速开始

首先运行 scripts/detect_obscura.py。它会检查：

• obscura 是否位于 PATH 中
• 同一目录中是否存在 obscura-worker
• Windows、macOS 和 Linux 上可能的本地二进制文件位置

如果缺少二进制文件：

• 建议用户下载适用于其平台的 GitHub Releases 压缩包。
• 在 Windows 上，提醒用户将 obscura.exe 和 obscura-worker.exe 放在同一文件夹中，才能并行运行 scrape。
• 如果用户想从源代码构建，说明可运行 cargo build --release 和 cargo build --release --features stealth。

任务模式

使用 Vite 进行本地开发

用户希望 Obscura 访问 http://localhost:5173 或其他本地 Vite 端口时，将此作为默认方案。

推荐流程：

1. 在本地运行 Vite。
2. 使用 hostc 公开 Vite 端口。
3. 将生成的公开 https:// URL 提供给 Obscura。

使用 scripts/command_templates.py vite-hostc 生成最简可用命令集。 用户需要 hostc 流程以及可直接运行的 Playwright 或 Puppeteer 代码片段时，使用 scripts/command_templates.py vite-hostc-cdp。

最简步骤：

pnpm dev
npx hostc 5173
obscura fetch https://your-hostc-url --dump html

如果用户需要浏览器自动化，而不是单次抓取：

obscura serve --port 9222

然后提供一个导航到 hostc URL 的 Playwright 或 Puppeteer 代码片段。

示例：

python scripts/command_templates.py vite-hostc-cdp playwright --public-url https://your-hostc-url

使用 listhen 进行本地开发

仅当用户明确要求使用 listhen 或已经在使用它时，才将其作为备用方案。关键在于公开隧道 URL，而不是本地监听器。

不要推荐：

• localhost
• 127.0.0.1
• 类似 192.168.x.x 的 LAN IP
• 通过修改源代码禁用 SSRF 保护，除非用户明确要求更改代码

单页提取

使用 scripts/command_templates.py fetch 生成入门命令，然后根据需要调整。

常见示例：

obscura fetch https://example.com --eval "document.title"
obscura fetch https://example.com --dump links
obscura fetch https://news.ycombinator.com --dump html --wait-until networkidle0

优先使用：

• 对单个 DOM 表达式或计算值使用 --eval
• 对内置输出模式使用 --dump html|text|links
• 用户需要输出到文件时使用 --output

并行抓取

用户提供多个 URL 或要求并发处理时，使用 scripts/command_templates.py scrape。

常见示例：

obscura scrape https://example.com https://example.org --concurrency 10 --eval "document.querySelector('h1')?.textContent" --format json

如果输出要用于脚本或管道，优先使用 --quiet。

用于 Playwright 或 Puppeteer 的 CDP 服务

使用 scripts/command_templates.py serve 生成启动命令，使用 scripts/command_templates.py cdp 生成客户端代码示例。

典型的 serve 命令：

obscura serve --port 9222

添加：

• 与反检测相关时，添加 --stealth
• 需要代理时，添加 --proxy <url>
• 适合使用并行 CDP 工作进程时，添加 --workers <n>

然后提供匹配的客户端代码片段：

• Playwright 使用 chromium.connectOverCDP({ endpointURL: 'ws://127.0.0.1:9222' })
• Puppeteer 使用 puppeteer.connect({ browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser' })

响应风格

保持实用：

• 如果环境状态未知，先说明环境状态。
• 给出下一步要运行的确切命令。
• 如果需要代码，提供一个最简可运行代码片段。
• 选择标志时说明所依据的假设。

参考资料

仅在需要时阅读：

• references/cli-cheatsheet.md：了解命令模式和标志选择
• references/cdp-integration.md：了解 Playwright 和 Puppeteer 连接详情
• references/local-dev-tunnels.md：了解 Vite + hostc + Obscura 和 listhen 备用方案指南

脚本

• scripts/detect_obscura.py 用于查找已安装的二进制文件并验证工作进程是否位于同一位置。
• scripts/command_templates.py 用于生成 fetch、scrape、serve、CDP 客户端以及默认 Vite + hostc + Obscura 流程的入门命令和代码片段。