xhs-research

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

Security Scan

The skill's code, instructions, and requirements are internally consistent with its stated purpose (search Xiaohongshu and synthesize reports), but it downloads and executes third‑party binaries and stores login cookies — you should trust the upstream binaries before installing.

Purpose & Capability

Name/description describe Xiaohongshu research; required binaries (python3, git), local scripts, QR login flow, and an MCP binary are all consistent with implementing a local search engine + report synthesis. No unrelated credentials or surprising permissions are requested.

Instruction Scope

SKILL.md instructs the agent to generate search keywords, run the included Python scripts, perform a QR login (via a downloaded xiaohongshu-login binary), run a local MCP server, and save reports/cookies to ~/.local/share/xhs-research and ~/Documents/XHS-Research. These actions match the stated task but include storing login cookies and launching a local service and Chrome for QR login (user interaction required).

Install Mechanism

setup.py downloads a release tarball from GitHub (xpzouying/xiaohongshu-mcp) and extracts binaries into ~/.local/share/xhs-research/bin. Downloading release assets from GitHub is standard practice but still executes third‑party binaries on your machine — verify the upstream repo and release integrity before running.

Credentials

No required environment variables or external credentials are declared. The skill will create local files (cookies.json) containing login/session data — this is necessary for its function but is sensitive. Note: the scripts respect an optional XIAOHONGSHU_API_BASE env var which, if set, can change the backend endpoint used by the client.

Persistence & Privilege

always is false and the skill does not request platform-global privileges. It writes files under the user's home directory and runs a local binary server; it does not modify other skills or system-wide agent configs.

Assessment

This skill appears to do what it says: it runs a local MCP service, asks you to scan a Xiaohongshu QR code, and uses downloaded binaries to perform searches and produce reports. Before installing: - Inspect and verify the upstream GitHub project (xpzouying/xiaohongshu-mcp) and its releases; malicious actors can publish binaries to a release asset. - If you don't trust those binaries, don't run setup.py; you can audit source or build binaries yourself. - Be aware the skill saves login cookies (~/.local/share/xhs-research/cookies.json) and will launch Chrome for QR login; treat that file as sensitive and delete it when you no longer need the skill. - Note the optional XIAOHONGSHU_API_BASE env var can redirect network calls — ensure it is not set to an untrusted remote endpoint. - Run the skill in a controlled environment (or sandbox) if you want additional safety, and remove the ~/.local/share/xhs-research directory after use.

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/