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

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

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

# 小红书采集 Skill

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

## 前置检查

1. **WebBridge 状态**
   ```bash
   ~/.kimi-webbridge/bin/kimi-webbridge status
   ```
   必须 `running: true` 且 `extension_connected: true`。

2. **浏览器已登录小红书**
   - 在 Chrome/Edge 访问 https://www.xiaohongshu.com 并登录

3. **项目依赖**
   ```bash
   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. **具体场景 > 笼统品类**
   - ❌ `护肤` → ✅ `油痘肌 刷酸 烂脸`
   - ❌ `美食` → ✅ `北京 探店 踩雷`

2. **情绪/结果词提高信息密度**
   - 加 `翻车` `踩坑` `避雷` `后悔` `吐槽` `难用` `失败` 等词，更容易抓到真实用户反馈

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

4. **先小规模验证**
   - 先用 `--limit=5` 跑一组看看结果质量，确认关键词有效后再加大采集量

### 执行采集

```bash
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 |

## 登录

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

## 输出

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

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

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

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

```bash
# 注册
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 中：
- 自动提取痛点标签
- 生成营销文案
- 做竞品对比分析

## 数据结构

```typescript
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` 登录