---
name: xhs
description: "小红书笔记搜索、创作者分析和内容趋势研究。当用户需要搜索小红书笔记（小红书/红书/XHS/种草/笔记）、查看小红书博主（博主/达人/KOL/创作者）、分析小红书内容（内容分析/爆款笔记）、或研究小红书市场趋势（小红书选品/什么好卖/种草趋势）时使用此技能。"
version: "1.1.0"
owner_repo: Optima-Chat/optima-scout
---

# 小红书 (XHS) - 笔记搜索与创作者分析

**开始前先加载 scout-intent skill 执行意图确认。** 平台已确定为小红书，只需确认目的和品类/关键词。

所有命令使用 `scout xhs` 前缀。

---

## 快速选择：我该用哪个命令？

| 你的目标 | 命令 | 说明 |
|---------|------|------|
| **搜产品/找灵感** | `search-notes "关键词"` | 搜索笔记，支持中英文关键词 |
| **分析某篇笔记** | `note-detail <noteId>` | 获取笔记详情（互动数据、标签等） |
| **看博主主页** | `user-profile <userId>` | 粉丝数、笔记数、获赞数 |
| **看博主作品** | `user-notes <userId>` | 博主发布的笔记列表 |
| **看笔记评论** | `note-comments <noteId>` | 一级评论，含账号/图片/表情包 |
| **看评论的完整回复/楼中楼** | `note-comments --with-replies` + `note-comment-replies <noteId> <commentId>` | 先取一级评论拿 `commentId`→再展开二级回复 |

---

## 典型场景

当用户说：
- "小红书上搜一下XX" / "小红书什么火" → `scout xhs search-notes "XX"`
- "看看这个笔记" + noteId → `scout xhs note-detail <noteId>`
- "看看这个博主" + userId → `scout xhs user-profile <userId>`
- "这个博主发了什么" → `scout xhs user-notes <userId>`
- "小红书上XX好不好卖" → `scout xhs search-notes "XX"` 分析互动数据
- "找小红书达人" → `scout xhs search-notes "品类关键词"` 从高赞笔记找创作者
- "看看这篇笔记的评论" → `scout xhs note-comments <noteId>`
- "评论下面有哪些回复" / "谁回复了这条评论" → 先 `scout xhs note-comments <noteId>` 拿到 `commentId`，再 `scout xhs note-comment-replies <noteId> <commentId>`

---

## URL 解析 - 小红书链接处理

用户可能贴小红书链接。**不要用 WebFetch**（会被登录墙拦截），按以下规则提取 ID：

| URL 特征 | 提取内容 | 调用命令 |
|----------|---------|---------|
| `xiaohongshu.com/explore/笔记ID` | note_id（末尾的十六进制字符串） | `scout xhs note-detail <noteId>` |
| `xiaohongshu.com/user/profile/用户ID` | user_id | `scout xhs user-profile <userId>` |
| `xhslink.com/短链接` | 无法直接提取，告知用户提供 note_id | — |

---

## 命令详情

### 搜索笔记 — `scout xhs search-notes`

```bash
scout xhs search-notes "瑜伽裤" --sort popularity_descending
```

**参数**（以 `scout xhs search-notes --help` 为准）：
- `关键词`（必填）：支持中英文
- `-p, --page <number>`：页码（默认 1，翻页用）
- `--sort <type>`：排序 —— `general`（综合，默认）| `time_descending`（最新）| `popularity_descending`（最热）
- `--note-type <type>`：笔记类型 —— `不限`（默认）| `视频笔记` | `普通笔记`
- `-f, --format`：`json`（默认）| `text`

> ⚠️ **每页数量不可调**：`search-notes` **没有** `--page-size` / `--limit` 参数（会报 `unknown option`）。每页数量固定，翻页用 `--page`（或换 `--sort` 角度）。

**返回数据**：
- `id` — 笔记 ID
- `title` — 标题
- `description` — 正文
- `type` — `image` 或 `video`
- `creator` — 作者（uid, username）
- `likes`, `comments`, `collects`, `shares` — 互动数据
- `url` — 笔记链接
- `hashtags` — 标签列表

### 笔记详情 — `scout xhs note-detail`

```bash
scout xhs note-detail 6489a2b0000000001e012345
```

### 用户主页 — `scout xhs user-profile`

```bash
scout xhs user-profile 5a1234567890abcdef012345
```

**返回数据**：
- `uid`, `username` — 用户基本信息
- `followers`, `following`, `totalNotes`, `totalLikes` — 数据概览
- `bio` — 简介
- `verified`, `verifyContent` — 认证状态
- `ipLocation` — IP 属地

### 用户笔记 — `scout xhs user-notes`

```bash
scout xhs user-notes 5a1234567890abcdef012345
```

**参数**（以 `scout xhs user-notes --help` 为准）：
- `userId`（必填）：小红书用户 ID
- `--cursor`：分页游标（翻页用；首次不传，用返回里的 cursor 取下一页）
- `-f, --format`：`json`（默认）| `text`

> ⚠️ **没有** `--num` / `--limit` 参数。返回数量由后端决定，翻页用 `--cursor`。

### 笔记评论 — `scout xhs note-comments`

获取笔记评论列表（一级评论）。

```bash
scout xhs note-comments 6a1fe3730000000035020235
scout xhs note-comments 6a1fe3730000000035020235 --with-replies --replies-top 3
scout xhs note-comments 6a1fe3730000000035020235 --cursor '{"index":2,"pageArea":"UNFOLDED"}'
```

**参数**（以 `scout xhs note-comments --help` 为准）：
- `<noteId>`（必填）：笔记 ID
- `--cursor <cursor>`：翻页游标，取上一页返回的 `cursor`——**是一段 JSON 字符串**（形如 `{"index":2,"pageArea":"UNFOLDED"}`），传参时**必须整体用单引号包住**，否则会被 shell 拆成多个参数报错
- `--with-replies`：连带展开每条一级评论的二级回复（内联到 `replies[]`）
- `--replies-top <number>`：展开前 N 条一级评论的回复，默认 3，最多 10（传了这个参数即使不加 `--with-replies` 也会自动展开）
- `-f, --format`：`json`（默认）| `text`

**⚠️ negative space（没有的东西，别猜）**：
- **没有 `-c/--count` 参数**——小红书评论接口不支持指定每页条数，每页数量由上游固定，想要更多用 `--cursor` 翻页，**不要**在命令里加 `--count`（会报 `unknown option`）
- `--replies-top` 超过 10 会直接报错拒绝（避免请求量和计费放大），**不是**静默截断
- 内联出来的 `replies[]` 只是**预览**（每条最多 3 条、正文截到 60 字、不带图片/表情包/点赞数）。要拿某条评论的**完整**二级回复（含图片/表情包），必须单独调 `note-comment-replies`（见下一节），不能只看内联预览就当作全部

**返回数据（json 摘要，逐条）**：
- `commentId` — 评论 ID，二级回复要用它（见下一节），**不能**直接传笔记链接或 noteId
- `author` — 评论者昵称
- `account` — **评论者小红书号**（斯巴达互联网医院要求必须展示）
- `profileUrl` — 评论者主页链接
- `likes` — 点赞数
- `text` — 评论正文（截断预览）
- `hasMedia` — 是否含图片/表情包（**注意**：有图片/表情包但链接全取不到时这里是 `false`，别只看这一个字段，见下面 `mediaUnavailable`）
- `mediaUnavailable` — 为 `true` 时表示该评论确实有图片/表情包，但所有 URL 都取不到（上游返回不全）
- `images[]` / `stickers[]` — 图片/表情包 URL（各最多预览 3 个）
- `mediaTruncated` — 图片或表情包超过 3 个时为 `true`，全量去 `cache_file` 取
- `replyCount` — 该评论的二级回复总数
- `replies[]` — 二级回复预览，**默认就有值**（上游在一级评论里免费内联返回的前几条回复，不需要任何开关）；`--with-replies`/`--replies-top` 只用来在 `replyCount` 大于已内联条数时**额外**发请求补齐
- `repliesTruncated` — 该评论回复数 >3 时为 `true`
- `repliesPartial` — 该评论的回复没抓全（上游拉取失败）

顶层还有：`count`、`hasMore`、`cursor`（翻页用，JSON 字符串，见上面的引号提醒）、`total`、`imagesExpire`（小红书图片链接不设过期，恒为 `false`，不用提醒用户"会失效"）、`repliesRequested`/`repliesFetched`/`partial`（`--with-replies` 展开的统计）。

---

### 【MANDATORY】评论必须这样呈现给用户 —— 不允许简化

给用户展示评论时，**每一条**都必须包含：

1. **昵称 + 小红书号**：格式 `昵称（小红书号：xxx）`，`account` 字段没有就写"小红书号未公开"，**绝不能只写昵称**
2. **主页链接**：用 `profileUrl` 生成可点击链接
3. `hasMedia` 为 `true` 时，**必须**用 `![](<url>)` 把图片/表情包**内联展示出来**并注明是"图片"还是"表情包"；`images` 和 `stickers` **都有时都要展示**，顺序是先 `images` 后 `stickers`。**绝不允许把有图片/表情包的评论显示成空白/"该评论无内容"** —— 这是甲方明确要验收的点
4. `mediaUnavailable` 为 `true`：说明图片/表情包存在但链接暂时取不到（此时 `hasMedia` 反而是 `false`，**不能**只看 `hasMedia` 判断），要如实说"该评论包含图片/表情包，但链接暂时不可用"，**不能**说成"无内容"
5. `mediaTruncated` 为 `true`：图片/表情包还有更多没在预览里，提示用户"完整图片见 `cache_file`"并去读那个文件
6. **绝不允许输出空白行冒充评论**——没有正文又没有媒体的评论，写"[无文字内容]"，不要留空

### 什么时候必须展开二级回复（正向触发，不是只写"别展开"）

以下情况**必须**加 `--with-replies`（配合 `--replies-top N` 控制成本，而不是选择不展开）：
- 用户明确问"有哪些回复"、"完整对话"、"谁回复了"、"楼中楼"
- 你在做患者/客户识别或舆情排查，且某条评论的 `replyCount` 大于已内联展示的回复条数（说明还有没看到的对话）

不确定要展开几条时，默认 `--replies-top 3`；需要更多用更大的数字（最多 10），**不要**为了省成本直接跳过用户明确要看的回复。

### 笔记二级评论 — `scout xhs note-comment-replies`

获取某条一级评论下的二级回复（完整版，不是预览）。

```bash
scout xhs note-comment-replies 6a1fe3730000000035020235 64a1b2c3d4e5f60000000001
scout xhs note-comment-replies 6a1fe3730000000035020235 64a1b2c3d4e5f60000000001 --cursor '{"index":2,"pageArea":"UNFOLDED"}'
```

**参数**：
- `<noteId>`：笔记 ID（必填）
- `<commentId>`：一级评论的 `commentId`（必填，**只能**从 `note-comments` 的输出里取，不能自己编、不能传笔记链接）
- `--cursor <cursor>`：翻页游标，**同样是 JSON 字符串，必须整体加单引号**
- `-f, --format`：`json`（默认）| `text`

> ⚠️ **没有 `-c/--count` 参数**（和 `note-comments` 一样，上游不支持指定每页条数）。

返回结构和 `note-comments` 完全一样（同样有 `account`/`profileUrl`/`hasMedia`/`images`/`stickers` 等字段），呈现规则同上面的【MANDATORY】模板。

---

## 数据解读

### 互动数据指标

| 指标 | 爆款 | 优质 | 普通 | 低迷 |
|------|------|------|------|------|
| likes | >1万 | 1000-1万 | 100-1000 | <100 |
| collects | >5000 | 500-5000 | 50-500 | <50 |
| comments | >500 | 100-500 | 10-100 | <10 |

- **高赞 + 高收藏** = 内容有价值，用户想留存
- **高赞 + 低收藏** = 娱乐性内容，不够实用
- **低赞 + 高收藏** = 实用干货，用户默默收藏
- **收藏/点赞比 > 0.5** = 强购买意向信号（选品关键指标）

### 创作者评估

| 指标 | 头部达人 | 腰部达人 | 尾部达人 |
|------|---------|---------|---------|
| followers | >50万 | 1万-50万 | <1万 |
| totalNotes | >200 | 50-200 | <50 |

---

## 使用场景

### 场景 1：选品调研

```bash
# 搜索品类，分析爆款笔记的互动数据
scout xhs search-notes "瑜伽裤测评" --sort popularity_descending

# 分析：
# - 高收藏/点赞比的笔记 = 有购买意向的品类
# - 多篇爆款笔记提到的品牌/功能 = 市场验证的卖点
```

### 场景 2：达人分析

```bash
# 从热门笔记找到达人 → 看主页 → 看作品
scout xhs search-notes "护肤推荐"
scout xhs user-profile <从笔记中获取的userId>
scout xhs user-notes <userId>
```

### 场景 3：跨平台验证

```bash
# 1. 小红书发现趋势
scout xhs search-notes "防晒霜推荐"

# 2. Amazon 验证海外市场需求
scout search "sunscreen"

# 3. 1688 找供应商
scout supplier-search "防晒霜"
```

---

## 重要提醒

1. **中文关键词效果更好**：小红书是中文平台，用中文搜索更精准
2. **收藏数是核心选品指标**：收藏 = 购买意向，比点赞更有参考价值
3. **笔记 ID 是十六进制字符串**：类似 `6489a2b0000000001e012345`
4. **用户 ID 也是十六进制字符串**：类似 `5a1234567890abcdef012345`
5. **不要用 WebFetch 访问小红书**：会被登录墙拦截，只能通过 API
6. **跨平台联动**：小红书发现趋势 → Amazon/TikTok 验证需求 → 1688 找供应商
7. **评论必须带账号和媒体**：展示评论时必须给小红书号 + 主页链接，`hasMedia` 为真的评论必须内联图片/表情包，绝不能显示成空白（见「笔记评论」一节的【MANDATORY】模板）
8. **评论 cursor 是 JSON 字符串**：`note-comments`/`note-comment-replies` 的 `--cursor` 值形如 `{"index":2,"pageArea":"UNFOLDED"}`，命令行里必须整体用单引号包住
9. **成本**：`note-comments`/`note-comment-replies` 每次调用都按请求计费（TIKHUB 与我们自己的计费层都是），`--replies-top` 别无脑设大