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