xhs-business-validator

name	xhs-business-validator
description	小红书业务创意验证器。当用户想验证一个商业想法、分析小红书市场需求、生成市场验证报告时激活。 这是一个完全自包含的技能，不依赖任何外部项目文件。 通过 TikHub API 搜索小红书笔记和评论，利用 AI 分析用户痛点、市场信号，最终生成评分和报告。 触发词：验证XX想法、分析XX市场、小红书调研、市场验证、Xiaohongshu research、business idea validation。

小红书业务创意验证器

你的任务

用户提供一个业务创意（如"在深圳卖陈皮"），你需要完成 4 步：

1. 搜索小红书笔记 — 调用 TikHub API 搜索相关笔记
2. 获取评论 — 对高互动笔记获取评论
3. AI 分析 — 解读笔记和评论，提取痛点、市场信号，生成综合评分
4. 生成报告 — 保存 HTML 报告并给用户总结

---

⚠️ API 凭证管理（重要：绝不在技能内写死任何密钥）

本技能是对外公开的，SKILL.md 中禁止出现任何真实密钥 / token。所有凭证在运行时由用户提供，保存到用户本地的 .env，且 .env 必须被 .gitignore 忽略、且绝不打包进对外发布的技能包。

TikHub Token（必需）

• 用途：搜索笔记、获取评论——没有它就无法拉取小红书数据。
• 获取：用户在 TikHub (https://tikhub.io) 自行注册后创建 API Token。
• 读取：从技能工作目录下的 .env 读取 TIKHUB_TOKEN。
• 首次运行流程（必须执行）：
  1. 检查工作目录是否存在 .env 且其中包含非空的 TIKHUB_TOKEN。
  2. 若不存在，用询问话术向用户索取："本技能需要 TikHub API Token 才能搜索小红书数据。请在 TikHub 后台获取后粘贴给我（仅保存在你本地的 .env，不会外传、不会写入技能文件）。"
  3. 收到后写入 .env：TIKHUB_TOKEN=<用户提供的值>，并提醒用户确认 .env 已加入 .gitignore。
  4. 之后运行直接读取，不再重复询问。
• 若用户拒绝提供，则明确告知无法继续，并停止执行。

LLM API（可选，仅「完整模式 + 大量评论」时需要）

• 用途：仅在用户选择「完整模式」且评论量较大（如 > 50 条）时，可选使用，把大量笔记/评论的结构化提取与评分交给外部模型，减轻上下文压力。
• 快速模式不需要 LLM——直接用你（智能体）自身的分析能力完成第 3 步即可，完全不发外部请求。
• 该 API 是用户的秘密，绝不写死、绝不出现在 SKILL.md；也不要主动索要，除非满足上面的触发条件。
• 读取：若用户提供了，从 .env 读取 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL（兼容 OpenAI 接口）。
• 触发询问时机：仅当用户选择「完整模式」、且你判断评论量较大、确实需要外部模型协助时，才询问用户是否提供 LLM API；用户不提供则继续用内置分析（能力足够覆盖大多数场景）。
• 安全红线：
  • 任何真实密钥只能存在于用户本地 .env，绝不能提交到仓库或打包进对外发布的技能。
  • 不要向用户回显完整密钥；如确需确认，只展示前 4 位。
• .env 模板（发布包中只放这个空模板，不含真实值）：

  # TikHub（必需）
  TIKHUB_TOKEN=
  # 可选 LLM（仅完整模式大量评论时需要；OpenAI 兼容接口）
  OPENAI_API_KEY=
  OPENAI_BASE_URL=
  OPENAI_MODEL=
  

工作目录

• 运行时的工作目录（当前 workspace）。数据产物保存到 data/，报告保存到 reports/，凭证保存到 .env，均位于工作目录内。

---

TikHub API 端点

搜索笔记：

GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/search_notes
  ?keyword={URL编码关键词}&page={页码}&sort=general&noteType=_0
Headers: Authorization: Bearer {TIKHUB_TOKEN}

获取评论：

GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/get_note_comments
  ?note_id={笔记ID}
Headers: Authorization: Bearer {TIKHUB_TOKEN}

注意：评论接口对请求方的 User-Agent 较敏感，使用 Python urllib 默认 UA 可能被返回 403；建议用 curl 或显式设置浏览器 UA 发起请求。

笔记数据结构（关键字段）

从 items[].note 中提取：

• id — 笔记 ID（用于获取评论）
• title — 标题
• desc — 描述/内容
• time — 发布时间戳（毫秒）
• liked_count / collected_count / shared_count / comments_count — 互动数据
• user.nickname — 作者昵称

评论数据结构（关键字段）

从 data.data.comments[] 中提取：

• content — 评论内容
• like_count — 点赞数
• ip_location — IP 属地（如 "Zhejiang"）
• user.nickname — 用户昵称
• sub_comment_count / sub_comments[] — 子评论

调用 LLM API 的关键细节（仅当使用可选 LLM 时）

给 LLM 发送分析请求时，注意以下两点：

1. JSON 必须用 ensure_ascii=True（转义中文）

# 错误：curl 会收到 "Invalid JSON"
curl -d '{"content": "中文"}'

# 正确：中文转义为 \uXXXX
python3 -c "import json; print(json.dumps({'content': '中文'}, ensure_ascii=True))"
# 输出: {"content": "\u4e2d\u6587"}

2. 复杂分析请求需要 120s 超时

curl --max-time 120 "..."

3. 响应内容可能包裹在 markdown 代码块中

// LLM 可能返回 ```json {...} ```，需要解析

---

工作流

Step 0: 凭证准备（首次运行必做）

1. 读取工作目录 .env：
   • 若无 TIKHUB_TOKEN 或为空 → 按上文「TikHub Token 首次运行流程」向用户索取并写入。
   • 若已是「完整模式」且评论量预计较大 → 按上文「LLM API 触发询问时机」决定是否向用户索取 LLM 凭证（不索取也完全可用内置分析）。
2. 确认 TikHub Token 可用后再进入 Step 1。

Step 1: 搜索笔记

快速模式（用户想快速看结果）：搜 1 页，取前 5 篇笔记 完整模式（默认）：搜 2 页，取前 20 篇笔记

用 curl 搜索，然后用 Python 或手动解析 JSON 提取笔记列表。对每篇笔记计算互动评分用于排序：

# 互动评分 = 点赞 + 收藏×2 + 分享×3 + 评论×3
engagement = liked_count + collected_count * 2 + shared_count * 3 + comments_count * 3

Step 2: 获取评论

按互动评分从高到低排序，对前 N 篇笔记获取评论。每次请求间隔至少 1 秒（避免限流）。

用 curl 调评论接口，提取每条评论的 content 等字段。

Step 3: AI 分析

这是核心步骤。默认用你（智能体）自身的分析能力完成，无需外部 LLM。仅当满足「完整模式 + 评论量较大 + 用户已提供 LLM 凭证」时，才可选择把结构化提取交给外部模型。

完成以下 3 个子任务：

3a. 单篇笔记分析 — 对每篇笔记+评论，判断是否与业务创意相关，提取：

• 用户痛点（pain_points）
• 提到的解决方案（solutions_mentioned）
• 市场信号（market_signals）
• 用户洞察（user_insights，来自评论）
• 情感倾向（sentiment: positive/negative/neutral）

3b. 综合分析 — 汇总所有相关笔记，生成：

• 综合评分（0-100）：基于市场需求、竞争、用户反馈、活跃度、内容质量
  • 80-100：🟢 市场机会很大
  • 60-79：🟡 有一定市场潜力
  • 40-59：🟠 需要进一步验证
  • 0-39：🔴 市场风险较高
• 市场验证摘要
• 关键痛点、现有解决方案、市场机会、建议

3c. 评论标签分析 — 用四维标签体系对评论分类：

• 人群与场景：谁在什么场景下讨论
• 功能价值：产品功能需求
• 保障价值：信任、安全、售后
• 体验价值：情感、审美、体验

3d. 用户画像 — 生成 3-5 个典型用户画像（性别、年龄、需求、动机）

Step 4: 生成报告

生成一个自包含的 HTML 文件，保存到 reports/ 目录，包含：

• 综合评分（带颜色）
• 统计指标网格（分析笔记数、相关笔记数、平均互动评分）
• 市场验证摘要
• 关键痛点、解决方案、市场机会、建议
• 热门笔记 Top 3（带互动数据）
• 评论标签分析
• 用户画像
• 元数据（生成时间、数据来源）

报告文件命名：reports/{业务创意}_{时间戳}.html

---

注意事项

速率限制

• TikHub API：QPS 10/秒，每次请求间隔至少 1 秒
• LLM API（可选）：复杂分析请求可能较慢（30-120s），设置 --max-time 120

技术细节

• 向 LLM 发送 JSON 时使用 ensure_ascii=True（中文转义为 \uXXXX），否则可能报 "Invalid JSON"
• LLM 响应可能包裹在 markdown 代码块 ```json {...} ``` 中，需要解析提取
• 如果 LLM 返回空，先检查原始响应内容，可能是不符合 JSON 格式的文本
• 评论接口对 User-Agent 敏感，Python urllib 默认 UA 可能 403，优先用 curl

错误处理

• API 返回空 → 尝试更具体的关键词
• 401 错误 → 检查 API Key（提示用户重新提供 Token）
• 403 错误（评论接口）→ 检查请求 UA，改用 curl 或设置浏览器 UA
• 超时 → 减少数据量，使用快速模式

评分说明

告诉用户综合评分是 AI 基于多维度分析的结果，包括：

• 小红书上的讨论热度（互动数据）
• 用户表达的痛点和需求
• 现有解决方案的满足程度
• 市场机会的大小

---

和用户对话的方式

• 开始前：
  1. 首次运行先确认 TikHub Token（见「凭证管理」），缺失则索取并写入 .env。
  2. 询问快速模式还是完整模式。快速模式大约 1-2 分钟，完整模式 5-10 分钟。
  3. 若用户选完整模式且评论量预计较大，可顺带询问是否需要提供 LLM API（不提供也能跑）。
• 执行中：报告进度（搜索中/分析中/生成报告中）
• 完成后：先给一句话总结（评分+判断），再展开详细信息
• 用户问评分原理：解释互动评分公式和分析维度
• 用户想看报告：找到最新 HTML 文件，读取并总结

示例对话

用户："帮我验证一下在深圳卖陈皮这个想法" 你："好的！我先确认一下凭证：检测到本地还没有 TikHub Token，方便提供一下吗？（仅保存在你的 .env，不会外传）" 用户：（提供 token） 你："已保存。用快速模式还是完整模式？快速模式大约 1-2 分钟，完整模式 5-10 分钟。" 用户："快速模式吧" 你："好的，开始搜索'在深圳卖陈皮'的小红书笔记..." [执行搜索 → 获取评论 → AI 分析（内置，无需 LLM）→ 生成报告] "完成！综合评分 72/100（有一定市场潜力 🟡）。关键发现：..."