# Xhs Business Validator

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

- Skill: `liangdabiao/xhs-business-validator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add liangdabiao/xhs-business-validator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liangdabiao/xhs-business-validator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: liangdabiao (https://skillmd.com/u/liangdabiao)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/liangdabiao/xhs-business-validator

---


# 小红书业务创意验证器

## 你的任务

用户提供一个业务创意（如"在深圳卖陈皮"），你需要完成 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`（转义中文）**
```bash
# 错误：curl 会收到 "Invalid JSON"
curl -d '{"content": "中文"}'

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

**2. 复杂分析请求需要 120s 超时**
```bash
curl --max-time 120 "..."
```

**3. 响应内容可能包裹在 markdown 代码块中**
```json
// 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 提取笔记列表。对每篇笔记计算互动评分用于排序：

```python
# 互动评分 = 点赞 + 收藏×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（有一定市场潜力 🟡）。关键发现：..."