guaikei·小红书热门清单
本技能是一套小红书公开数据检索工具：搜笔记、看详情、拉评论、抓博主作品，共 4 个命令。读法与用法：先匹配下方四大场景剧本，找到用户属于哪一幕；再按剧本第 2 步执行命令；最后按第 4 步验收。本文档只写一遍关键信息——参数看「附录 A」，链接看「附录 B」，报错看「附录 C」。
场景一 · 找内容（关键词搜索）
用户典型说法： "小红书XX什么火" / "帮我搜XX的笔记" / "看看XX最近有什么新内容" / "找XX的高赞图文"
-
识别：用户给了关键词（而非链接）→ 走关键词搜索。若只说"看趋势/找爆款"，追问：①关键词是什么？②更在意最新、点赞还是收藏？③图文、视频还是全部？
-
执行：
node src/xiaohongshu/search-cli.js --keyword "<关键词>" [--type 0|1|2] [--sort 0|1|2|3|4] [--time 0|1|2|3] [--limit N]--type：0 全部 / 1 视频 / 2 图文--sort：0 综合 / 1 最新 / 2 点赞 / 3 评论 / 4 收藏--time：0 全部 / 1 一天 / 2 一周 / 3 半年--limit：1-10000，默认 10
-
交付：返回笔记列表（标题/作者/互动/链接）。可接着做爆款选题汇总、关键词热度对比、趋势追踪。
-
验收：
status: "error"且退出码 1 = 搜索失败或空结果 → 换更宽关键词 / 放宽筛选；不要编造结论。
场景二 · 看单篇（笔记详情）
用户典型说法： "这篇笔记怎么样" / "看看这篇爆款讲了啥" / "分析一下这条笔记为什么火"
-
识别：用户给了笔记链接（
explore/...或短链）且想看笔记本身的内容与互动 → 走详情。 -
执行：
node src/xiaohongshu/detail-cli.js --url "<笔记链接>" [--limit N]--limit：评论数量上限，建议显式传 0-10000。
-
交付：返回笔记标题、正文、互动数据。可接着做单篇拆解、内容策略分析。
-
验收：返回空数组视为成功（笔记可能已删除时再核验链接）。若用户给的是博主主页链接，改走场景四，先说明链接类型。
场景三 · 听评论（评论获取）
用户典型说法： "大家怎么说这篇" / "分析评论区都在讨论什么" / "拉一下这篇笔记的评论"
-
识别：用户给了笔记链接且只关心评论区（不关心正文）→ 走评论。与场景二的区别：本命令只取评论，不返回笔记正文与互动详情，适合舆情/观点聚类。
-
执行：
node src/xiaohongshu/comment-cli.js --url "<笔记链接>" [--limit N]--limit：评论数量上限，建议显式传 1-10000。
-
交付：返回评论内容、评论者信息、互动数据。可接着做观点归纳、情绪判断、负面反馈识别。
-
验收：若用户给的是博主主页链接，改走场景四。空数组视为成功。
场景四 · 盯博主（作品监控）
用户典型说法： "这个博主最近发了什么" / "监控这个竞品账号" / "看看这个博主的发文节奏"
-
识别：用户给了博主主页链接（
user/profile/...或短链）→ 走作品监控。若只有博主昵称没有链接，先请用户提供主页链接。 -
执行：
node src/xiaohongshu/post-cli.js --url "<博主主页链接>" [--limit N]--limit：作品数量上限，建议显式传 1-10000。
-
交付：返回博主公开作品列表。可接着做账号分析、主题归类、发文节奏总结、KOL 评估。
-
验收：若用户给的是笔记链接，改走场景二/三，先说明链接类型。
附录 A · 参数速查
| 参数 | 简写 | 适用命令 | 说明 |
|---|---|---|---|
--keyword |
-k |
search | 搜索关键词，必填，建议 2-50 字符 |
--url |
-u |
detail / post / comment | 笔记或博主链接，必填 |
--limit |
-l |
全部 | 返回数量，1-10000；超过 10000 会被静默降到 10 |
--type |
-t |
search | 0 全部 / 1 视频 / 2 图文 |
--sort |
-s |
search | 0 综合 / 1 最新 / 2 点赞 / 3 评论 / 4 收藏 |
--time |
-i |
search | 0 全部 / 1 一天 / 2 一周 / 3 半年 |
--help |
-h |
全部 | 显示帮助 |
附录 B · 链接规则
| 链接形态 | 判定 | 处理 |
|---|---|---|
xiaohongshu.com/explore/... |
笔记链接 | 场景二（详情）或场景三（评论） |
xiaohongshu.com/user/profile/... |
博主主页 | 场景四 |
xhslink.com/m/... / xhslink.cn/m/... |
不透明短链 | 无法凭短链判断指向；结果异常时请用户提供完整链接 |
带空格 / http:// 开头 |
脏链接 | 先 trim、http → https 归一 |
附录 C · 报错自查（按 status 先分支：success / empty / error）
| 报错 | 含义 | 自查 |
|---|---|---|
401 / 403 |
token 未配置或无效 | 确认 GUAIKEI_API_TOKEN 已 export、32 位十六进制、未过期 |
429 |
频率限制 | 降频、减小 --limit、稍后重试 |
500 / 502 / 503 |
服务端临时故障 | 等 1-2 分钟重试 |
ERRCODE_xxx |
业务错误（笔记已删除/无权限） | 换一条确认存在的链接，不要反复重试同一链接 |
ETIMEDOUT / UNKNOWN |
网络超时 | 检查本机网络/代理，确认能访问 guaikei.com |
limit 设了 10000 却只拿 10 条 |
超上限被静默降级 | 确认 --limit 是 1-10000 整数 |
| 命令一启动就退出无输出 | token 未通过校验 | 运行前 echo $GUAIKEI_API_TOKEN 确认已注入 |
铁律： 失败不编造数据；search-cli 无结果按失败处理（退出码 1），detail/comment 空数组算成功；解析 stdout 只取最后一份 JSON（以 status 字段为标识），等进程退出后再读。
执行前置检查（任一场景都适用）
- Node.js 16.14.0+ 已安装
GUAIKEI_API_TOKEN已配置（未配置先提醒用户）- 输入是关键词 / 笔记链接 / 博主链接三者之一
- 平台确实是小红书（抖音、B站、微博不适用）
合规边界
- 仅处理小红书公开数据；不支持私密、隐藏或需登录态的内容
- 不负责登录、发布、点赞、评论、关注
- 不代替用户做营销策略判断；职责是把数据拿回来，交由上层分析
- 依赖第三方 API（guaikei.com）中转，使用前确认数据外发授权
环境与支持
- 运行环境：Node.js 16.14.0+（Windows / Linux / macOS）
- 必需环境变量：
GUAIKEI_API_TOKEN - 官方入口：https://www.guaikei.com （联系微信 13395823479）
- 详细参数：
references/options.md；更新记录：references/changelog.md