xhs-research

name	xhs-research
version	2.0.0
description	小红书调研工具 — 搜索小红书笔记，AI 合成调研报告。
argument-hint	xhs-research 深圳产检医院推荐, xhs-research AI绘画教程
allowed-tools	Bash, Read, Write, AskUserQuestion
author	kunhai1994
license	MIT
user-invocable	true
metadata	{"openclaw":{"emoji":"📕","requires":{"bins":["python3","git"]},"primaryEnv":""},"gemini":{"extension_type":"skill"}}

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

搜索小红书笔记，AI 合成调研报告。 底层：自建调研引擎（借鉴 last30days 全平台策略） + xiaohongshu-mcp

---

Step 0: 环境检查

找到 skill 安装路径：

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"

运行状态检查：

python3 "${SKILL_ROOT}/scripts/status.py" --json

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

1. mcp_binary_installed 为 false → 运行安装：

   python3 "${SKILL_ROOT}/scripts/setup.py"
   

2. mcp_running 为 false → 启动服务：

   python3 "${SKILL_ROOT}/scripts/start.py"
   

3. xhs_logged_in 为 false → 告诉用户「正在打开小红书登录页面，请准备好手机扫码」，然后直接运行：

   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: 执行搜索引擎

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

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 时必须检查：报告中是否每条信息都有链接？如果没有，补上或删除该条信息。

按查询类型输出

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

## 小红书调研: {TOPIC}

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

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

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

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

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

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

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

A. 产品调研模板（用户说「调研XX产品」）：

## 小红书产品调研: {产品名}

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

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

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

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

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

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

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

B. 竞品调研模板（用户说「调研XX赛道竞品」）：

## 小红书竞品调研: {赛道}

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

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

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

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

C. 需求/痛点调研模板（用户说「调研XX的痛点」「XX的需求」）：

## 小红书需求调研: {TOPIC}

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

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

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

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

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

D. 通用调研模板（不属于以上场景）：

## 小红书调研: {TOPIC}

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

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

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

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

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

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

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

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

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

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

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

避雷类（避雷/踩坑）：

## 小红书避雷: {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/