name: xhs-catch
description: |
小红书笔记采集工具。当用户需要从小红书按关键词搜索并批量采集笔记数据时，使用此 skill。

触发关键词：采集小红书、抓小红书、小红书搜索、小红书笔记、小红书数据、小红书竞品、小红书调研、小红书内容、小红书痛点、小红书用户反馈。

功能：基于 WebBridge 控制浏览器，采集笔记标题、正文、作者、点赞/收藏/评论数、图片 URL、一级评论。输出 JSON 原始数据 + HTML 可视化报告。可同步到「好痛 Howtone」做进一步分析。

小红书采集 Skill

⚠️ 重要安全提示（风控防封指南）

1. 强烈建议使用小号！ 小红书具有极其严格的反爬虫与异常行为检测机制。高频、批量或自动化的采集行为极易触发风控，导致账号被永久封禁。请务必使用不重要的测试账号（小号）进行登录与采集，切勿使用主力账号或商业账号！

2. 控制单次采集数量： 单次采集建议限制在 10-20 条以内（--limit=10 或 20）。请勿高频连续运行脚本。

3. 内置真人模拟： 本工具虽然已内置了随机延时、真人上下滚动等反爬优化，但依然无法 100% 规避账号风险。

按关键词搜索小红书笔记，批量采集结构化数据。输出 JSON + HTML 报告。可选同步到「好痛 Howtone」。

前置检查

1. WebBridge 状态

   ~/.kimi-webbridge/bin/kimi-webbridge status

必须 running: true 且 extension_connected: true。

1. 浏览器已登录小红书

• 在 Chrome/Edge 访问 https://www.xiaohongshu.com 并登录

1. 项目依赖

   cd scripts && npm install

脚本说明

| 脚本 | 说明 |
|------|------|
| webbridge-crawl.ts | 通过 WebBridge 控制用户真实浏览器采集 |
| login.ts | 小红书扫码登录，保存 cookies.json |
| zion-login.ts | 登录「好痛 Howtone」项目，保存 JWT Token |
| sync.ts | 将采集数据同步到「好痛 Howtone」项目（含图片上传） |
| generate-report.ts | 读取 output/*.json 生成静态 HTML 报告 |

关键词设计（关键！先想清楚再采集）

⚠️ 不要直接执行用户给的关键词。 普通用户的关键词往往过于笼统（如"护肤""旅游"），采集回来的数据噪音大、难以分析。AI 必须先引导用户把搜索意图转化为具体、可采集、可分析的关键词。

引导用户明确采集目标

通过 1-3 轮对话，帮用户把模糊需求转化为精准关键词：

| 用户原始需求 | ❌ 直接执行 | ✅ 引导后关键词 |
|-------------|-----------|---------------|
| "帮我看看护肤" | 护肤（太泛，结果杂乱） | 早C晚A 翻车 油痘肌 烂脸修复 A醇 脱皮 |
| "调研一下旅游" | 旅游（太泛） | 日本自由行 踩坑 新疆自驾 避雷 三亚 被坑 |
| "看看竞品" | 竞品名（可能搜不到） | 品牌名 吐槽 品牌名 缺点 品牌名 后悔 |
| "了解用户痛点" | 产品名 痛点（生硬） | 产品名 不好用 产品名 避雷 买了产品名 后悔 |

关键词设计原则

1. 具体场景 > 笼统品类

• ❌ 护肤 → ✅ 油痘肌 刷酸 烂脸
• ❌ 美食 → ✅ 北京 探店 踩雷

1. 情绪/结果词提高信息密度

• 加 翻车 踩坑 避雷 后悔 吐槽 难用 失败 等词，更容易抓到真实用户反馈

1. 多组关键词分别采集

• 不要试图用一个词覆盖所有，分 2-3 组关键词采集，每组 10-20 条，质量远好于一组 50 条

1. 先小规模验证

• 先用 --limit=5 跑一组看看结果质量，确认关键词有效后再加大采集量

执行采集

cd scripts

# 基础用法
npx ts-node webbridge-crawl.ts --keyword="关键词" --limit=20

# 不采评论
npx ts-node webbridge-crawl.ts --keyword="关键词" --limit=20 --no-comments

# 限制评论数
npx ts-node webbridge-crawl.ts --keyword="关键词" --limit=20 --max-comments=10

# 小规模验证关键词有效性
npx ts-node webbridge-crawl.ts --keyword="关键词" --limit=5

参数说明

| 参数 | 说明 | 默认 |
|------|------|------|
| --keyword | 搜索关键词（必填） | - |
| --limit | 采集数量上限，建议 ≤20 | 20 |
| --no-comments | 不采集评论区 | 默认采集 |
| --max-comments | 每篇最多评论数 | 20 |

登录

# 小红书登录（扫码）
npx ts-node login.ts

输出

• output/关键词_YYYYMMDD.json — JSON 格式原始数据（用于同步、二次分析）
• output/index.html — 可视化报告（运行 generate-report.ts 生成，带筛选/搜索/导出）

同步到「好痛 Howtone」（可选）

如果用户需要痛点分析、文案生成、数据洞察等进阶功能，需要把数据同步到「好痛 Howtone」。

前提：先注册/登录好痛 Howtone 账户

# 注册
npx ts-node zion-login.ts --username="新用户" --password="密码" --register

# 登录（保存 JWT Token）
npx ts-node zion-login.ts --username="用户名" --password="密码"

# 同步数据
npx ts-node sync.ts --file=output/关键词_YYYYMMDD.json

同步后，用户可在好痛 Howtone 中：

• 自动提取痛点标签
• 生成营销文案
• 做竞品对比分析

数据结构

interface XHSNote {
  xhs_note_id: string;
  title: string;
  content: string;
  author_name: string;
  images: string[];
  likes: number;
  collects: number;
  comments_count: number;
  comments: { author: string; content: string; likes: number }[];
  comments_extracted: number;
  keyword: string;
  source_url: string;
  crawl_time: string;
}

故障处理

• WebBridge 未运行：~/.kimi-webbridge/bin/kimi-webbridge start
• 数据为空：检查浏览器登录状态，或减少 limit
• 弹窗未弹出：笔记未加载完，增大 limit 让预加载更充分
• Cookie 不存在：先运行 npx ts-node login.ts 登录