# Xhs Research

> 小红书调研工具 — 搜索小红书笔记，AI 合成调研报告。

- Skill: `kunhai1994/xhs-research` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kunhai1994/xhs-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kunhai1994/xhs-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: kunhai1994 (https://skillmd.com/u/kunhai1994)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kunhai1994/xhs-research

---


# xhs-research v2: 小红书调研工具

> 搜索小红书笔记，AI 合成调研报告。
> 底层：自建调研引擎（借鉴 last30days 全平台策略） + [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)

---

## Step 0: 环境检查

找到 skill 安装路径：
```bash
for dir in \
  "${CLAUDE_PLUGIN_ROOT:-}" \
  "${OPENCLAW_SKILL_ROOT:-}" \
  "${GEMINI_EXTENSION_DIR:-}" \
  "$HOME/.claude/skills/xhs-research" \
  "$HOME/.agents/skills/xhs-research" \
  "$HOME/.codex/skills/xhs-research" \
  "$HOME/.gemini/extensions/xhs-research"; do
  [ -n "$dir" ] && [ -f "$dir/scripts/xhs_research.py" ] && SKILL_ROOT="$dir" && break
done
echo "SKILL_ROOT=$SKILL_ROOT"
```

运行状态检查：
```bash
python3 "${SKILL_ROOT}/scripts/status.py" --json
```

根据返回的 JSON 修复失败项：

1. **`mcp_binary_installed` 为 false** → 运行安装：
   ```bash
   python3 "${SKILL_ROOT}/scripts/setup.py"
   ```

2. **`mcp_running` 为 false** → 启动服务：
   ```bash
   python3 "${SKILL_ROOT}/scripts/start.py"
   ```

3. **`xhs_logged_in` 为 false** → 告诉用户「正在打开小红书登录页面，请准备好手机扫码」，然后直接运行：
   ```bash
   python3 "${SKILL_ROOT}/scripts/login.py"
   ```
   Chrome 会自动弹出二维码，用户扫码后脚本自动完成验证。

   **macOS 用户注意**：可能弹出「security 想要使用钥匙串 Chrome Safe Storage」弹窗，点「拒绝」即可。

4. **`all_ready` 为 true** → 进入调研。

---

## Step 1: 生成搜索关键字（LLM 智能生成）

**这一步由你（LLM）完成，不是脚本。** 分析用户意图，生成 5-8 个搜索关键字。

思考维度：
- **同义词/别名**：分镜脚本 → storyboard → 故事板
- **细分维度**：按品牌/场景/人群/价位/地域拆分
- **正反面**：推荐 + 避雷
- **XHS 术语**：种草/拔草/测评/攻略/教程/保姆级
- **用户视角**：新手/小白/入门/进阶
- **竞品/关联词**：调研咖啡机 → 也搜"磨豆机"
- **具体品牌/产品**：如果主题涉及特定领域，加上头部品牌名

示例：

输入「咖啡机推荐 家用」→ 关键字：
1. "家用咖啡机推荐"
2. "咖啡机选购攻略"
3. "咖啡机避雷"
4. "半自动全自动咖啡机"
5. "咖啡小白第一台咖啡机"
6. "德龙咖啡机"

输入「调研AI影视创作者的分镜脚本痛点」→ 关键字：
1. "AI分镜脚本"
2. "AI故事板 storyboard"
3. "AI分镜工具"
4. "AI分镜脚本怎么写"
5. "AI影视创作 分镜痛点"
6. "AI漫剧 分镜"
7. "分镜脚本 AI生成"

输入「深圳产检医院推荐」→ 关键字：
1. "深圳产检医院推荐"
2. "深圳生孩子医院排名"
3. "深圳分娩医院体验"
4. "深圳妇幼保健院产检"
5. "深圳无痛分娩医院"
6. "深圳公立私立医院生娃"
7. "深圳顺产剖腹产医院"

输入「调研XX产品的用户需求和痛点」→ 关键字策略：
- 搜产品名 + 使用场景：「XX产品 使用体验」
- 搜用户吐槽：「XX产品 吐槽」「XX产品 缺点」
- 搜未满足需求：「XX产品 希望」「XX产品 建议」
- 搜竞品对比：「XX产品 vs YY产品」
- 搜用户类型：「XX产品 新手」「XX产品 专业用户」
- 搜使用场景：「XX产品 工作流」「XX产品 怎么用」

输入「咖啡机避雷」→ 关键字：
1. "咖啡机避雷"
2. "咖啡机踩坑"
3. "咖啡机 别买"
4. "咖啡机 缺点 吐槽"
5. "咖啡机推荐"（反向搜正面的做对比）

输入「AI绘画新手教程」→ 关键字：
1. "AI绘画新手教程"
2. "AI绘画入门攻略"
3. "AI绘画零基础"
4. "AI绘画工具推荐"
5. "AI绘画 怎么学"
6. "Midjourney 新手教程"（具体工具）

输入「调研XX赛道竞品格局」→ 关键字策略：
- 搜赛道整体：「XX赛道 推荐」「XX行业 排名」
- 搜头部竞品（每个竞品名单独搜）：「{竞品A}」「{竞品B}」「{竞品C}」
- 搜对比帖：「{竞品A} vs {竞品B}」
- 搜用户选择：「XX 哪个好」「XX 怎么选」

**显示解析结果后再执行搜索：**
```
我将在小红书上调研「{TOPIC}」。
- 关键字：{列出生成的关键字}
开始搜索，通常需要 1-3 分钟...
```

---

## Step 2: 执行搜索引擎

将生成的关键字传给引擎：

```bash
python3 "${SKILL_ROOT}/scripts/xhs_research.py" \
  --keywords "{关键字1},{关键字2},{关键字3},{关键字4},{关键字5}" \
  --deep \
  --save-dir "$HOME/Documents/XHS-Research"
```

**timeout 300000**（5 分钟），前台运行。

引擎会自动：
1. 并行搜索所有关键字（每轮 ~42 条）
2. feed_id 精确去重 + Jaccard 标题去重
3. 三维评分（相关性 40% + 时间 25% + 互动 35%）
4. Top 20 帖子获取完整正文 + 评论区
5. 输出结构化 Markdown

**读取完整输出。** 输出包含：
- 详情笔记（正文 + 热评）
- 其他相关笔记（标题 + 互动数据）
- 统计汇总

---

## Step 3: 合成调研报告

### 核心原则

1. **基于真实数据** — 只引用引擎输出中的真实内容，不要用预训练知识替代小红书用户的真实观点
2. **评论区 > 正文** — 评论区的高赞评论往往比正文更真实、更有价值
3. **标注争议** — 不同用户观点矛盾时，两边都引用
4. **Self-check** — 写完后回读，删除任何没有真实来源的断言

### 引用格式（强制）

**每条信息、每个观点、每条引用都必须附带原帖链接。没有链接的信息不允许出现在报告中。这是硬性要求，不可省略。**

正文引用：
```
per 作者昵称（❤️N）[链接](https://www.xiaohongshu.com/explore/{id})
```

详细引用：
```
「笔记标题」— 作者昵称（❤️N 💬N ⭐N）
https://www.xiaohongshu.com/explore/{id}
```

评论区引用（使用所属帖子的链接）：
```
评论区 用户昵称（N赞）：「评论内容」— [来源](https://www.xiaohongshu.com/explore/{id})
```

**Self-check 时必须检查：报告中是否每条信息都有链接？如果没有，补上或删除该条信息。**

### 按查询类型输出

**推荐类**（推荐/排名/最好）：

```markdown
## 小红书调研: {TOPIC}

### Top N 推荐排名
| 排名 | 名称 | 提及次数 | 代表帖互动 | 一句话评价 |
|------|------|---------|-----------|-----------|

### 各项详细分析
**{推荐1}**
- 正面评价：引用正文 + 评论区
- 负面评价/避雷：引用评论区吐槽
- 适合人群 / 费用参考

### 核心对比表
| 维度 | {A} | {B} | {C} |
|------|-----|-----|-----|

### 用户决策逻辑
（从评论区提炼的真实选择逻辑，带引用）

### 避雷清单
| 名称 | 负面信号 | 来源 |
|------|---------|------|
```

**调研类**（调研/痛点/需求/场景/产品调研/竞品调研）：

根据调研具体方向，选择合适的子模板组合：

**A. 产品调研模板**（用户说「调研XX产品」）：
```markdown
## 小红书产品调研: {产品名}

### 用户画像
| 用户类型 | 占比 | 特征 | 代表帖 |
|---------|------|------|--------|

### 使用场景
1. **场景1** — [描述，per 作者昵称]
   评论区佐证：「引用」

### 用户为什么用这个产品？
（使用动机，带引用）

### 用户为什么选这个不选别的？
（决策因素，带引用和竞品对比）

### 用户在吐槽什么？（痛点）
| 痛点 | 频次 | 严重度 | 代表性原话 |
|------|------|--------|-----------|

### 用户想要什么？（未满足需求）
| 需求 | 频次 | 代表性原话 |
|------|------|-----------|

### 用户怎么评价？（口碑分布）
- 正面：N 条（占比 X%）— 关键词：...
- 负面：N 条（占比 X%）— 关键词：...
- 中性：N 条
```

**B. 竞品调研模板**（用户说「调研XX赛道竞品」）：
```markdown
## 小红书竞品调研: {赛道}

### 竞品格局
| 排名 | 产品 | 提及次数 | 互动量 | 一句话定位 |
|------|------|---------|--------|-----------|

### 各竞品详细分析
**{竞品1}**
- 用户为什么用？场景？
- 相比其他产品优势？
- 用户吐槽什么？
- 缺什么功能？

### 竞品对比表
| 维度 | {A} | {B} | {C} |
|------|-----|-----|-----|

### 用户迁移路径
（从X产品转到Y产品的用户，为什么转？per 评论区）
```

**C. 需求/痛点调研模板**（用户说「调研XX的痛点」「XX的需求」）：
```markdown
## 小红书需求调研: {TOPIC}

### 痛点矩阵
| 痛点 | 严重度 | 频次 | 代表性证据 |
|------|--------|------|-----------|
| 🔴 高 | ... | N次 | per 作者（❤️N） |

### 各痛点详细分析
**痛点1: {描述}**
- 用户原话：引用正文
- 评论区附议：引用高赞评论
- 影响范围：什么用户受影响最大

### 用户需求清单（按优先级）
1. **需求1** — N 次提及，per 作者昵称
2. **需求2** — ...

### 用户的创作/使用流程
1. 步骤1 → 工具/方法
2. 步骤2 → 工具/方法
（从多篇教程/经验帖中提炼的典型流程）

### 现有解决方案及评价
| 解决方案/工具 | 用户评价 | 优势 | 不足 |
|-------------|---------|------|------|
```

**D. 通用调研模板**（不属于以上场景）：
```markdown
## 小红书调研: {TOPIC}

### 核心发现（3-5 条）
**发现1** — [描述，per 作者昵称]

### 详细分析
（按主题分组，每个主题引用多条笔记 + 评论区）

### 关键趋势
1. [趋势] — per 作者昵称

### 争议/分歧
（对立观点，两边都引用）

### 用户群画像
| 类型 | 占比 | 特征 | 代表 |
```

**对比类**（A vs B / 哪个好）：

```markdown
## {A} vs {B}: 小红书用户怎么说

### 快速结论
[1-2句数据驱动结论]

### {A} / {B} 分别分析
（优势/劣势，带引用）

### 逐项对比
| 维度 | {A} | {B} |

### 怎么选
选 {A} 如果... 选 {B} 如果...
```

**避雷类**（避雷/踩坑）：

```markdown
## 小红书避雷: {TOPIC}

### 高频踩坑点
1. [坑] — per 作者昵称，评论区 N 人附议

### 详细避雷（带案例 + 评论区佐证）

### 反面推荐（大家说好的）
```

### 通用结尾

每份报告末尾必须包含：

1. **数据偏差声明**：
> 本报告数据仅来源于小红书用户个人体验，可能存在推广帖、幸存者偏差等问题。

2. **统计行**（从引擎输出末尾提取）：
```
📕 小红书: N 条笔记（N轮搜索）│ N 篇详情 │ N 赞 │ N 收藏 │ N 评论
🔥 最高互动: {帖标题}（❤️N）
🗣️ 主要作者: {作者1}, {作者2}, {作者3}
```

---

## Step 4: 保存报告

合成完报告后，用 Write 工具保存到本地：

```
路径：~/Documents/XHS-Research/{主题}-{YYYYMMDD}.md
```

示例：`~/Documents/XHS-Research/深圳产检医院推荐-20260328.md`

- macOS: `~/Documents/XHS-Research/`
- Linux: `~/Documents/XHS-Research/`（如果 ~/Documents 不存在则用 `~/.local/share/xhs-research/reports/`）

保存后明确告知用户：「报告已保存到 {完整路径}」

> 注意：`--save-dir` 保存的是引擎原始数据（`*-raw.md`），这里保存的是你合成后的完整报告，两者不同。

---

## Step 5: 邀请后续

```
报告已保存到 {完整路径}。

我已经是「{TOPIC}」的小红书调研专家。可以继续问我：
- [基于实际调研内容的具体建议1]
- [具体建议2]
- [具体建议3]
```

**邀请必须基于实际调研内容，不要泛泛建议。**

后续提问从已有结果回答，不重新搜索。用户明确要求新话题才重新搜索。

---

## Security & Permissions

- 只读搜索，不发帖/点赞/评论
- 搜索通过本地 MCP 服务（localhost:18060），不直接发送数据到外部
- Cookie 由 xiaohongshu-mcp 管理，存在 `~/.local/share/xhs-research/cookies.json`
- 调研报告保存到 `~/Documents/XHS-Research/`