# Xiaohongshu Keyword Search

> 小红书公开数据检索工具，覆盖关键词搜笔记、笔记详情、评论、博主作品、博主粉丝量等互动数据；当用户提到小红书并需要查/分析公开内容时调用。可用于爆款选题、竞品监控、KOL 筛选、评论舆情分析，无需登录账号

- Skill: `why20261/xiaohongshu-keyword-search` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add why20261/xiaohongshu-keyword-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/why20261/xiaohongshu-keyword-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: why20261 (https://skillmd.com/u/why20261)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/why20261/xiaohongshu-keyword-search

---


# 小红书关键词搜索

> ✨ **一句话**：给关键词或链接，拿回结构化的小红书公开数据——笔记、详情、评论、博主作品，直接喂给后续的选题分析、竞品对比、舆情归纳。

> ✨ **解决什么问题**：小红书运营最费时间的不是写内容，是「先搞清楚该写什么」。人工翻 1000 条笔记记录点赞收藏要一小时，本工具一条命令返回 1000 条结构化数据，AI 直接接着做归纳。

| 你要做的事     | 这个技能给你什么                         | 省掉的动作             |
| -------------- | ---------------------------------------- | ---------------------- |
| 找选题方向     | 按点赞/收藏排序的笔记列表 + 完整互动数据 | 手动翻页、逐条记录数据 |
| 盯竞品账号     | 博主公开作品列表 + 发布时间 + 互动表现   | 每天手动刷对方主页     |
| 筛 KOL 真实性  | 点赞/评论/收藏三项原始数值               | 靠感觉判断数据是否注水 |
| 摸用户真实想法 | 单篇笔记的评论区全量数据                 | 手动往下翻评论         |
| 追热点         | 按「最新」+「一天内」筛出的实时内容      | 反复刷发现页           |

**🔥核心优势**

> - 安全: 无需登录你的小红书账号，不担心风控风险 / 封号问题
> - 强大: 一次可获取最多1W条数据，使用简单方便
> - 全面: 各功能出参数据全面，可见及有价值数据都会返回
> - 灵活: 支持多维度筛选与排序
> - 轻量: 无需部署服务，Node.js 一键运行
> - 实用: 日志自动归档，适配营销报告 / 内容策划场景

---

## 1. ✅ 什么时候应该调用这个技能

### 1.1 🎯 满足以下**任一**条件即调用

- 用户提到「小红书」「小红薯」「xhs」「rednote」并要求查看、搜索、分析内容
- 用户要做 **关键词搜索**、**爆款选题调研**、**竞品监控**、**评论洞察**、**博主作品追踪**、 **KOL/博主筛选**、**评论区舆情分析**、**关键词趋势跟踪**。
- 用户提供了小红书关键词、笔记链接或博主主页链接，希望拿到结构化数据。
- 用户给出 `xiaohongshu.com` 或 `xhslink.com` 开头的链接
- 用户说「帮我看看 XX 在小红书上的情况」这类需要真实数据支撑的判断
- 用户后续还要基于结果继续做总结、对比、筛选、报告生成。

### 1.2 🚫 以下情况**不要调用**

- 用户只让写文案、起标题、改脚本，没要求查数据
- 用户查询的平台是抖音、B站、微博、公众号
- 用户要求获取私密内容、登录态数据、隐藏数据或非公开信息。
- 用户既没有提供关键词，也没有提供可识别的小红书链接，且任务目标不明确。

### 1.3 👀 意图模糊时的追问模板

用户说「帮我做小红书竞品分析」——信息不足，按此追问：

> 需要确认三件事：1）竞品是具体某个账号（给我主页链接），还是某个品类关键词？2）关注最新动态还是历史高赞？3）大概看多少条？

拿到答案再执行。**不要自行编造关键词或链接。**

---

## 2. 🔀 四个能力与路由

> **Note:** 请先通过 [小红书搜索技能官网](https://www.guaikei.com) 开通TOKEN，配置环境变量 `GUAIKEI_API_TOKEN` 后才能正常运行。

| 用户意图信号                          | 脚本                             | 必填        | 返回                                                              |
| ------------------------------------- | -------------------------------- | ----------- | ----------------------------------------------------------------- |
| 给的是**关键词**，无链接              | `src/xiaohongshu/search-cli.js`  | `--keyword` | 笔记列表 + 作者 + 互动数据 + 可点击 url                           |
| 给的是**笔记链接**，要看正文/互动数据 | `src/xiaohongshu/detail-cli.js`  | `--url`     | 笔记详情 + 作者信息                                               |
| 给的是**笔记链接**，只要评论          | `src/xiaohongshu/comment-cli.js` | `--url`     | 评论内容 + 评论者 + 互动数据                                      |
| 给的是**博主主页链接**                | `src/xiaohongshu/post-cli.js`    | `--url`     | 该博主公开作品列表 / 该播主的互动数据（粉丝量、点赞量、收藏量等） |

### 2.1 🧭 路由细则

- 用户给的是 **关键词**，没有链接：走 **关键词搜索**。
- 用户给的是 `https://www.xiaohongshu.com/explore/...` 或可解析到笔记的短链：若只关心评论，走 **笔记评论查询**；若需要笔记详情，走 **笔记详情**。
- 用户给的是 `https://www.xiaohongshu.com/user/profile/...` 或可解析到主页的短链：走 **博主作品监控**。
- 如果用户同时给出多个目标，按用户目标拆分执行，不要把不同意图硬塞进一次命令。

### 2.2 ⚖️ detail 与 comment 的区别

- `detail-cli.js`：要笔记本身（标题、正文、图片、点赞收藏数）。
- `comment-cli.js`：只要评论区数据，不返回正文。

**同时需要正文和大量评论时**：调 `detail-cli.js` 拿正文，再调 `comment-cli.js --limit 500` 拿评论。

### 2.3 🧩 组合工作流

**选题调研**

```
search-cli --sort 2 --time 2 --limit 20    # 先拿一周高赞
→ 挑出前 10 条的 url
→ detail-cli 逐条看正文结构
→ 汇总标题公式 / 开头钩子 / 话题标签
```

**竞品监控**

```
post-cli --limit 100                        # 拿对方近 100 条
→ 按发布时间算更新频率
→ 按互动数据找出爆款
→ comment-cli 拉爆款的评论区看用户为什么买
```

**KOL 筛选**

```
post-cli --limit 100
→ 计算 评论数/点赞数、收藏数/点赞数 比值
→ 比值异常偏低 → 疑似刷量，标记风险
```

---

## 3. 🧺 输入规则

### 3.1 🔍 关键词搜索

| 参数             | 必填 | 取值                                                                       | 默认 |
| ---------------- | ---- | -------------------------------------------------------------------------- | ---- |
| `--keyword` `-k` | 是   | 2-50 字符，不能是链接                                                      | —    |
| `--type` `-t`    | 否   | 内容类型，`0` 全部 / `1` 视频 / `2` 图文                                   | `0`  |
| `--sort` `-s`    | 否   | 排序规则，`0` 综合 / `1` 最新 / `2` 最多点赞 / `3` 最多评论 / `4` 最多收藏 | `0`  |
| `--time` `-i`    | 否   | 发布时间，`0` 不限 / `1` 一天内 / `2` 一周内 / `3` 半年内                  | `0`  |
| `--limit` `-l`   | 否   | 返回数量，整数 1-10000                                                     | `10` |

**参数选择建议**（直接影响结果质量，请按意图选）：

| 用户说                             | 应该传              |
| ---------------------------------- | ------------------- |
| 「爆款」「高赞」「什么内容火」     | `--sort 2`          |
| 「最新」「刚发的」「实时」「现在」 | `--sort 1 --time 1` |
| 「这周趋势」「近期」               | `--sort 1 --time 2` |
| 「大家都在收藏什么」「值得存的」   | `--sort 4`          |
| 「讨论度高」「评论多」             | `--sort 3`          |
| 「文案怎么写」「图文笔记」         | `--type 2`          |
| 「视频怎么拍」                     | `--type 1`          |

`--limit` 建议：快速看一眼 `10`；正经做选题 `30-50`；批量分析 `200+`（注意返回体积，超过 1000 条时告知用户数据量）。

### 3.2 📰 笔记详情

至少要确认：

- `url`：小红书笔记链接。

适用链接示例：

- `https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy`
- `https://xhslink.com/m/xxx`

如果用户给的是博主主页链接，不要误走详情脚本，先指出链接类型不匹配。

### 3.3 📡 博主作品监控

至少要确认：

- `url`：小红书博主主页链接。

可选参数：

- `limit`：返回作品数量上限；为 `0` 时返回该博主的互动数据（粉丝量、点赞量、收藏量等）。

适用链接示例：

- `https://www.xiaohongshu.com/user/profile/xxx?xsec_token=yyy`
- `https://xhslink.com/m/xxx`

如果用户给的是笔记详情链接，不要误走博主脚本，先说明需要主页链接。

### 3.4 💬 笔记评论获取

至少要确认：

- `url`：小红书笔记链接。

可选参数：

- `limit`：评论数量上限，整数 1-10000，不传时默认 10。

适用链接示例：

- `https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy`
- `https://xhslink.com/m/xxx`

如果用户给的是博主主页链接，不要误走评论脚本，先指出链接类型不匹配。
与「笔记详情」的区别：本能力只取评论数据，不返回笔记正文 / 互动详情，适合只想做评论洞察、观点聚类或舆情分析的场景。

**👉 详细选项说明**, 可参阅 [完整选项说明](references/options.md)

---

## 4. 📜 执行原则

### 4.1 ❓ 缺少必要输入时

- 没有关键词：先追问关键词。
- 没有链接：先追问笔记链接或博主主页链接。
- 链接类型不明确：先确认这是笔记还是博主主页。
- 没有 `GUAIKEI_API_TOKEN`：提醒用户先配置环境变量，再执行。

不要在缺关键输入时硬调命令。

### 4.2 📤 输出原则

执行完成后，优先返回：

- 本次执行的目标
- 关键参数
- 结构化 JSON 结果
- 如果有必要，再补充一小段摘要说明

适合继续衔接的后续动作包括：

- 选题汇总
- 高赞笔记对比
- 评论观点聚类
- 竞品内容风格总结
- 博主发文节奏分析
- 报告与表格生成

### 4.3 🩹 失败处理原则

出现以下情况时，应明确向用户说明原因：

- token 未配置或无效
- 链接不合法或类型错误
- 搜索结果为空
- 接口返回异常
- 网络或超时问题

失败时不要编造数据，不要把空结果当成成功结论。

---

## 5. 💡 命令示例

```bash
# 关键词搜索：一周内图文，按点赞排序，取 20 条
node src/xiaohongshu/search-cli.js --keyword "露营装备" --type 2 --sort 2 --time 2 --limit 20

# 追最新：一天内，按最新排序
node src/xiaohongshu/search-cli.js --keyword "多巴胺穿搭" --sort 1 --time 1 --limit 50

# 笔记详情（不带评论，省 token）
node src/xiaohongshu/detail-cli.js --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy"

# 只拉评论，做舆情分析
node src/xiaohongshu/comment-cli.js --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --limit 200

# 博主近 30 条作品
node src/xiaohongshu/post-cli.js --url "https://www.xiaohongshu.com/user/profile/xxx?xsec_token=yyy" --limit 30

# 博主互动数据（粉丝量、点赞量、收藏量等）
node src/xiaohongshu/post-cli.js --url "https://www.xiaohongshu.com/user/profile/xxx?xsec_token=yyy" --limit 0
```

支持 `--flag value` 与 `--flag=value` 两种写法；`--keyword` 也可作为第一个位置参数省略 flag 名。

---

## 6. 🚧 能力边界

**能做**：搜索公开笔记 / 读公开笔记详情 / 读公开评论 / 读博主公开作品列表。

**不能做**（问到直接说不支持，不要尝试变通）：

- 登录小红书账号、使用登录态数据
- 发布、点赞、评论、收藏、关注、私信等任何写操作
- 私密笔记、草稿、仅粉丝可见内容
- 创作者后台数据（涨粉曲线、粉丝画像、流量来源）
- 用户手机号、微信、真实身份等个人信息
- 商业化数据（报价、投放后台、聚光平台）
- 替用户下营销决策——本技能只提供数据，判断交给用户

---

## 7. 📦 环境与依赖

- 运行环境：Node.js 16.14.0+
- 系统兼容：Windows / Linux / macOS
- 必需环境变量：`GUAIKEI_API_TOKEN`
- xhs技能官方入口：<https://www.guaikei.com>
- 详细参数说明：见 `references/options.md`
- 更新记录：见 `references/changelog.md`

## 8. 🛡️ 合规与使用限制

- 国内网络直连可用，无需代理
- 数据流向：本机 → guaikei.com API → 返回结果。除关键词/链接等查询参数外，不上传本机任何数据
- 仅处理小红书公开可见数据，不涉及登录态与个人隐私
- 结果限个人 / 团队内部分析使用，不得违规分发或用于违法用途
- 查询参数（关键词 / 链接）会发送至 guaikei.com API，请在使用前确认数据外发与授权范围。

## 9. 🚫 反模式

| 错误做法                                    | 后果                   | 正确做法                                |
| ------------------------------------------- | ---------------------- | --------------------------------------- |
| 把主页链接传给 `detail-cli` / `comment-cli` | 不返回数据             | 主页链接走 `post-cli`                   |
| 把笔记链接传给 `post-cli`                   | 不返回数据             | 笔记链接走 `detail-cli` / `comment-cli` |
| 关键词只含 emoji / 控制字符 / 纯符号        | 清洗后变空导致校验失败 | 换有意义的文字关键词                    |
| `--limit 20000`                             | 超上限被回退为 10      | 上限是 10000                            |
| 用本技能查抖音/微信/快手                         | 无结果                 | 明确告知不支持                          |

---

## 10. ❓ 常见问题

**Q1. 报错 `error_code: 401` 或 `403` 怎么办？**

> 含义：`GUAIKEI_API_TOKEN` 未配置或无效。
> 自查：①确认运行环境里确实 `export GUAIKEI_API_TOKEN=...` 了（不是只在 shell 配置里写了）；②token 长度16-256位，由字母、数字、下划线、短横线组成的字符串（以 guaikei.com 开通页显示为准），核对是否有多余空格或换行；③是否已过期，去 <https://www.guaikei.com> 重新开通。

**Q2. 报错 `error_code: 429` 怎么办？**

> 含义：触发了接口频率限制。
> 自查：降低调用频率、减小 `--limit`、或稍后重试，不要短时间高频轮询。

**Q3. 报错 `error_code: 500 / 502 / 503` 等服务端错误怎么办？**

> 含义：第三方 API 临时故障。
> 自查：通常是 transient，等 1–2 分钟重试；若持续出现，再走 §12 联系支持，并附上 `skill_metadata` 里的 `execution_time` 与请求参数。

**Q4. 报错 `error_code: ERRCODE_xxx` 怎么办？**

> 含义：业务层错误（HTTP 200 但 `errcode !== 0`），常见如「笔记已删除 / 不存在 / 无权限」。
> 自查：换一条确认仍存在的笔记链接；该错误不会随重试变好，不要反复重试同一链接。

**Q5. 报错 `error_code: ETIMEDOUT` 或 `UNKNOWN` 怎么办？**

> 含义：网络超时或无法解析响应。
> 自查：检查本机网络 / 代理；确认能访问 `guaikei.com`；重试一次；仍失败再联系支持。

**Q6. 提示「小红书链接格式无效」怎么办？**

> 自查：确认链接①以 `https://` 开头；②无前后空格；③是以下之一：`www.xiaohongshu.com/explore/...`、`www.xiaohongshu.com/user/profile/...`、`xhslink.com/m/...`、`xhslink.cn/m/...`。

**Q7. 命令一启动就退出、没输出数据？**

> 自查：多半是 `GUAIKEI_API_TOKEN` 未通过校验（见 Q1）。在运行命令前先 `echo $GUAIKEI_API_TOKEN` 确认变量已注入当前进程。

**Q8. 搜索返回空、但退出码不是 0？**

> 含义：`search-cli.js` 把「无结果」视为失败（退出码 1）。
> 自查：换更宽泛的关键词、放宽 `--type` / `--time`、或确认关键词不是被清洗成空串的符号（见 11.1）。`detail/comment` 的空数组则视为成功，属正常差异。

**Q9. 设了 `--limit 10001` 却只拿到 10 条？**

> 含义：`limit` 写成了超过 `10000` 的值，被静默降到默认 `10`（见 11.1）。
> 自查：确认 `--limit` 是 `1–10000` 之间的整数。

**Q10. 下游程序解析 stdout 失败 / 报 `Unexpected end of JSON input`？**

> 自查：失败输出通过 `process.stdout.write(..., () => process.exit(1))` 异步写出后会退出；请确保消费方**等进程退出后再读完整 stdout**，且只取最后一份 JSON（`status` 字段唯一标识这份结果）。不要把 `error`/`empty`/`success` 多份输出拼在一起解析。

## 11. 🎧 支持信息

- 官网 / TOKEN 开通：[小红书搜索、详情、作品、评论数据获取官网](https://www.guaikei.com)
- 问题反馈：https://github.com/um-why/xiaohongshu-openclaw-skill/issues