Skill: rednote-contacts

版本: 1.1.0

分块: 1/2

red-crawler-ops

当你需要从 OpenClaw 工作流中操作已安装的 red-crawler CLI 时，使用此技能。它是爬虫运行时的便携式封装，而非独立的爬虫实现。

使用时机

在以下场景使用 red-crawler-ops：

• 为 red-crawler 准备本地工作目录
• 爬取默认的小红书时尚首页 feed
• 将登录会话保存到 Playwright 存储状态
• 爬取某个小红书种子用户主页
• 针对工作区数据库运行夜间数据收集
• 导出每周报告
• 从 SQLite 数据库中列出可联系的创作者

red-crawler CLI 命令

所有爬取任务必须使用原生的 red-crawler CLI 命令：

1. crawl-homefeed（默认）

从小红书时尚首页 feed 中收集用户。当省略 action 时，这是默认的爬取模式。它会点击卡片作者链接，而不是笔记链接。

red-crawler crawl-homefeed \
  --homefeed-url "https://www.xiaohongshu.com/explore?channel_id=homefeed.fashion_v3" \
  --max-accounts 20 \
  --db-path "./data/red_crawler.db" \
  --output-dir "./output"

在本地浏览器模式下进行 IP 轮换时，需提供 proxy 或 proxy_list，并设置 rotation_mode: session。封装器将这些参数透传给 red-crawler；收到 403 或 429 后，爬虫会使用下一个代理启动新的浏览器会话。每个代理确定性地映射到一组浏览器标头，因此相同的出口 IP 会保持相同的 User-Agent。

Bright Data 浏览器 API 模式不使用本地代理设置。请使用 browser_mode: bright-data 加上 browser_auth 或 browser_endpoint；如果任一值包含 {session}，爬虫会将其替换为随机会话 ID，用于每个浏览器会话。

2. crawl-seed

爬取特定小红书用户主页并提取联系方式。

red-crawler crawl-seed \
  --seed-url "https://www.xiaohongshu.com/user/profile/USER_ID" \
  --max-accounts 5 \
  --max-depth 2 \
  --db-path "./data/red_crawler.db" \
  --output-dir "./output"

参数：

• --seed-url（必填）：目标用户主页 URL
• --storage-state：可选的 Playwright 存储状态文件
• --max-accounts：最大爬取账户数（默认：20）
• --max-depth：相关账户的爬取深度（默认：2）
• --include-note-recommendations：包括笔记推荐
• --safe-mode：启用安全模式
• --cache-dir：缓存目录路径
• --cache-ttl-days：缓存存活天数（默认：7）
• --db-path：SQLite 数据库路径（默认：./data/red_crawler.db）
• --output-dir：输出目录（默认：./output）

输出：

• accounts.csv：爬取的账户信息
• contact_leads.csv：提取的联系方式（电子邮件等）
• run_report.json：执行报告

3. login

可选的交互式登录，用于保存浏览器会话。

red-crawler login --save-state "./state.json"

参数：

• --save-state（必填）：存储状态保存路径
• --login-url：登录页面 URL（默认：https://www.xiaohongshu.com）

4. login-qr-start / login-qr-finish

基于二维码的登录，适用于无头环境。

# 开始二维码登录（生成二维码）
red-crawler login-qr-start \
  --save-state "./state.json" \
  --qr-path "./login-qr.png" \
  --session-path "./login-session.json" \
  --timeout 180

# 用户扫码后完成二维码登录
red-crawler login-qr-finish \
  --save-state "./state.json" \
  --session-path "./login-session.json"

5. collect-nightly

运行定期的夜间数据收集。

red-crawler collect-nightly \
  --db-path "./data/red_crawler.db" \
  --report-dir "./reports" \
  --crawl-budget 30 \
  --search-term-limit 4

参数：

• --storage-state：可选的存储状态文件
• --db-path：数据库路径（默认：./data/red_crawler.db）
• --report-dir：报告目录（默认：./reports）
• --cache-dir：缓存目录
• --cache-ttl-days：缓存存活天数（默认：7）
• --crawl-budget：爬取预算（默认：30）
• --search-term-limit：搜索词限制（默认：4）
• --startup-jitter-minutes：启动抖动时间
• --slot-name：调度槽位名称

6. report-weekly

从数据库导出每周报告。

red-crawler report-weekly \
  --db-path "./data/red_crawler.db" \
  --report-dir "./reports" \
  --days 7

参数：

• --db-path：数据库路径（默认：./data/red_crawler.db）
• --report-dir：报告目录（默认：./reports）
• --days：报告周期天数（默认：7）

输出：

• weekly-growth-report.json
• contactable_creators.csv

7. list-contactable

从数据库中列出可联系的创作者。

red-crawler list-contactable \
  --db-path "./data/red_crawler.db" \
  --lead-type "email" \
  --creator-segment "creator" \
  --min-relevance-score 0.5 \
  --limit 20 \
  --format csv

参数：

• --db-path：数据库路径（默认：./data/red_crawler.db）
• --lead-type：线索类型过滤器（默认：email）
• --creator-segment：创作者细分过滤器（默认：creator）
• --min-relevance-score：最低相关度分数（默认：0.0）
• --limit：结果限制（默认：20）
• --format：输出格式 - table 或 csv（默认：table）

8. open

使用保存的会话在浏览器中打开小红书。

red-crawler open --storage-state "./state.json"

支持的操作

• bootstrap
• crawl_homefeed（省略时默认）
• crawl_seed
• login
• collect_nightly
• report_weekly
• list_contactable
• job_status
• job_logs
• job_stop
• ack_event

长时间爬取与心跳

对于长时间爬取操作，请设置 run_mode: background。技能会启动一个本地后台封装器，立即返回 job_id，并在 heartbeat_dir（默认 ./.openclaw/red-crawler）下写入 OpenClaw 可读的状态。

后台任务会写入：

Skill: rednote-contacts

版本: 1.1.0

分块: 2/2

• HEARTBEAT.md: 用于 OpenClaw 心跳轮询的简洁状态和待处理用户更新
• jobs/<job_id>.json: 机器可读的任务状态
• events/<job_id>.jsonl: 完成或失败事件
• logs/jobs/<job_id>.out.log 和 .err.log: 爬虫日志

使用 job_status（配合返回的 job_id）手动读取最新状态。使用 job_logs 检查最近的输出，使用 job_stop 请求终止。如果启用了 OpenClaw 心跳轮询，代理可以读取 HEARTBEAT.md，并在后续的心跳周期中将待处理的完成事件呈现给用户。呈现事件后，使用 event_id 调用 ack_event，以确保同一更新不会重复报告。

示例提示

• "帮我准备当前小红书爬虫项目的本地环境"（自动映射到 bootstrap 用于现有工作空间）
• "开始爬小红书彩妆博主" / "帮我抓取一批小红书博主"（默认映射到 crawl_homefeed）
• "我需要登录爬虫" / "我要登录小红书"（自动映射到 login 以获取/刷新 Playwright 会话状态）
• "开始执行每日夜间数据采集" / "运行自动收集任务"（自动映射到 collect_nightly 以基于数据库队列继续爬取）
• "帮我生成一份本周的爬虫数据周报"（自动映射到 report_weekly，指向工作空间的数据库）

爬取新数据 vs 查询数据库：

• "帮我从这个博主去爬10个相关的美妆博主: https://www.xiaohongshu.com/..."（爬取新数据：自动映射到 crawl_seed，附带 seed_url，设置 max_accounts 为 10。_注意：爬取新数据需要种子 URL。_）
• "帮我从数据库/已爬取的数据中找出10个美妆/游戏/科技博主的联系方式"（查询现有数据库：自动将 action 设置为 list_contactable，limit 设置为 10，creator_segment 设置为 "美妆" 以筛选本地 SQLite 数据库）

（也理解技术性提示变体：）

• "在安装 CLI 后，用 install_browser: true 引导此工作空间。"
• "以深度 2 爬取此种子资料，并将输出写入 output/。"
• "导出本周的报告并返回生成的工件。"

环境设置

Windows (WSL2)

在 Windows 上，red-crawler 运行在 WSL2 内。你需要：

1. WSL2 及 Ubuntu（建议使用 20.04 或 22.04）
2. WSLg（WSL2 内置图形支持）——用于浏览器图形界面
3. 依赖项：

   sudo apt-get update
   sudo apt-get install -y git python3 python3-pip

1. red-crawler CLI，从发布的包安装。

已知问题及修复：

1. 未设置 DISPLAY（WSLg）

- 错误：Missing X server or $DISPLAY

- 修复：运行前导出 DISPLAY：

     export DISPLAY=:0

1. 无头浏览器 vs 有头浏览器

- login 命令需要有头浏览器（图形界面）

- crawl-seed 和其他命令在 WSL 上也要求有头浏览器

- 运行任何涉及浏览器的命令前，始终设置 DISPLAY=:0

Linux（原生）

1. 依赖项：

   sudo apt-get update
   sudo apt-get install -y git python3 python3-pip

1. red-crawler CLI，从发布的包安装。
2. X Server（用于有头浏览器）：

   sudo apt-get install -y xvfb
   export DISPLAY=:99
   Xvfb :99 -screen 0 1024x768x16 &

macOS

1. red-crawler CLI：

   uv tool install red-crawler==0.1.3

1. Playwright 浏览器运行时： 运行 bootstrap 并设置 install_browser: true。

前提条件

• 此技能从不克隆仓库。将 red-crawler 作为包安装，然后将 workspace_path 指向本地工作目录。
• 仅当你打算从源代码检出运行时，才设置 require_local_checkout: true。
• 仅当对本地源代码检出使用 sync_dependencies: true 时，才需要 uv。
• bootstrap 不会创建登录会话。需显式调用 login。
• login 会显式创建可选的 Playwright 存储状态。
• crawl_seed、crawl_homefeed 和 collect_nightly 可以在没有存储状态文件的情况下运行。
• report_weekly 和 list_contactable 从数据库运行，不需要存储状态。
• 工作空间必须包含 pyproject.toml。

安全限制

• 请勿将此技能指向你不控制的目录。
• 请勿静默创建登录会话；仅在用户要求认证时调用 login。
• 将 Playwright 存储状态文件保留在本地，不提交至代码、日志或共享工件。
• 请勿指向生产数据或未知数据库。
• 除非用户明确要求认证，否则不要创建或要求 state.json。
• 不要在提示或配置中硬编码特定机器的路径。
• 对于输出和报告，优先使用工作空间范围的相对路径。

输入形状

提供一个包含 action 及所选行动使用的可选字段的对象。常见字段包括：

• workspace_path
• require_local_checkout
• runner_command
• storage_state
• db_path
• report_dir
• output_dir
• cache_dir
• heartbeat_dir
• job_log_dir
• run_mode（sync/background）
• job_id
• event_id
• tail_lines

行动专用字段包括：

• sync_dependencies
• install_browser
• seed_url
• login_url
• max_accounts
• max_depth
• include_note_recommendations
• safe_mode
• cache_ttl_days
• gender_filter（male/female 或 男/女）
• crawl_budget
• search_term_limit
• startup_jitter_minutes
• slot_name
• days
• lead_type
• creator_segment
• min_relevance_score
• limit
• format
• browser_mode
• browser_endpoint
• browser_auth
• proxy
• proxy_list
• rotation_mode（none/session）
• rotation_retries
• randomize_headers

输出形状

成功运行返回：

• status
• action
• command
• summary
• artifacts
• metrics
• next_step
• stdout
• stderr
• 当 run_mode: background 接受任务时返回 job_id 和 pid
• 对于任务状态操作返回 job

错误运行返回：

• status
• action
• error_type
• message
• suggested_fix
• 执行时失败则返回 action、command、stdout 和 stderr
• 早期验证或配置失败可能省略 action、command、stdout 和 stderr