Scan to join WeChat groupguaikei·小红书热门关键词
面向小红书公开数据的检索技能：只负责把数据拿回来（结构化 JSON），不负责登录、发布、互动，也不代替你做策略判断。分析、汇总、报告交给上层流程。
1. 本技能产出什么（交付物清单）
用户最终想要的结果只有 4 种，先对号入座：
| # | 交付物 | 用户想要什么 | 对应脚本 |
|---|---|---|---|
| A | 笔记清单 | "找 XX 相关的笔记 / 什么火 / 高赞选题" | search-cli.js |
| B | 单篇详情 | "看这篇笔记的标题、正文、互动数据" | detail-cli.js |
| C | 评论区数据 | "看大家怎么评论 / 评论观点" | comment-cli.js |
| D | 博主作品集 | "看这个博主发了什么 / 盯竞品账号" | post-cli.js |
2. 何时该用 / 何时不该用
该用：平台是小红书（含红笔记/xhs/rednote 说法），且诉求是拿公开数据——搜笔记、看详情、拉评论、盯博主，或为后续分析/报告准备数据。
不该用：
- 平台不是小红书（抖音/B站/微博/公众号等）
- 用户只想写文案、改标题、出脚本，并未要求查数据
- 要求登录态、私密、隐藏内容
- 没有关键词、没有链接，且目标不明确——先追问，不要硬跑
3. 交付物详解
交付物 A · 笔记清单（关键词搜索）
用户话术：搜/找/查 XX、XX 什么火、找爆款选题、XX 最近趋势
命令：
node src/xiaohongshu/search-cli.js --keyword "关键词" [选项]
参数：
| 参数 | 简写 | 必填 | 取值 / 默认 |
|---|---|---|---|
| --keyword | -k | 是 | 2-50 字符，避免纯符号/emoji（会被清洗成空串触发拦截） |
| --type | -t | 否 | 0 全部(默认)，1 视频，2 图文 |
| --sort | -s | 否 | 0 综合(默认)，1 最新，2 最多点赞，3 最多评论，4 最多收藏 |
| --time | -i | 否 | 0 全部(默认)，1 一天内，2 一周内，3 半年内 |
| --limit | -l | 否 | 1-10000，默认 10；超过 10000 会被静默降为 10 |
验收：status=success 且 results 有数据为成功；搜索无结果按失败处理（退出码 1），应换更宽泛关键词或放宽 --type/--time，不要当"没有内容"直接下结论。
加工：按互动数据排序 → 提取标题/主题 → 汇总成选题清单或对比表。
交付物 B · 单篇详情（笔记详情）
用户话术：看这篇/这条笔记、这篇为什么火、这篇的标题正文数据
命令：
node src/xiaohongshu/detail-cli.js --url "笔记链接" [--limit N]
参数：--url/-u 必填（笔记链接）；--limit/-l 可选（评论数量上限，0-10000，不传按脚本默认）。
验收：返回笔记正文 + 互动数据；若评论为空数组则视为成功（与搜索不同），不需要重试。
加工：拆解爆款要素（标题/正文/互动）→ 分析单篇内容为何有效。
交付物 C · 评论区数据（评论获取）
用户话术：评论区怎么说、大家的观点、负面反馈、评论舆情
命令：
node src/xiaohongshu/comment-cli.js --url "笔记链接" [--limit N]
参数：--url/-u 必填（笔记链接）；--limit/-l 可选（评论数量上限，1-10000）。
注意：与详情（交付物 B）的区别——只返回评论，不含笔记正文/互动详情，适合专注评论分析。只关心评论时优先用它（更快更轻）。
验收：status=success；空数组视为成功。
加工：观点归类 → 情绪判断 → 高频主题统计 → 负面反馈识别。
交付物 D · 博主作品集（博主作品监控）
用户话术：这个博主发了什么、盯竞品账号、看博主发文节奏
命令：
node src/xiaohongshu/post-cli.js --url "博主主页链接" [--limit N]
参数：--url/-u 必填（博主主页链接）；--limit/-l 可选（作品数量上限，1-10000）。
注意：需要的是 user/profile/ 主页链接，不是 explore/ 笔记链接。
验收：status=success；空数组视为成功。
加工：发文频率分析 → 内容主题归类 → 互动表现对比（为 KOL 筛选/竞品分析备料）。
4. 输入与链接规则
输入规则：缺 --keyword 先问关键词；缺 --url 先问链接；只说业务目标（如"做竞品分析"）先拆解成上面 4 种交付物之一再执行；缺 GUAIKEI_API_TOKEN 先提醒配置。
链接形态速判：
| 链接形态 | 判断 | 去向 |
|---|---|---|
| www.xiaohongshu.com/explore/... | 笔记链接 | 交付物 B 或 C |
| www.xiaohongshu.com/user/profile/... | 博主主页 | 交付物 D |
| xhslink.com/m/... / xhslink.cn/m/... | 不透明短链，无法判断指向笔记还是主页 | 若结果异常，请用户提供完整链接 |
| 带空格 / http:// 开头 | 脏链接 | 先 trim、http→https 归一 |
链接类型错配（主页链接传给详情/评论脚本，或笔记链接传给博主脚本）会返回业务错误，不要硬跑。
5. 结果怎么读（验收速查）
每次执行后先看 status，再按 error_code 分支：
| status | 含义 | 动作 |
|---|---|---|
| success | 成功 | results 有数据，正常交付 |
| empty | 空结果 | 搜索视为失败（退出码 1）；详情/评论/博主空数组视为成功 |
| error | 失败 | results=null，按下方 error_code 处理 |
error_code 速查：
| error_code | 原因 | 自查 |
|---|---|---|
| 401 / 403 | token 未配置或无效 | 确认 GUAIKEI_API_TOKEN 已注入当前进程、为 32 位十六进制、未过期 |
| 429 | 频率限制 | 降低调用频率、减小 --limit、稍后重试 |
| 500 / 502 / 503 | 服务端临时故障 | 等 1-2 分钟重试 |
| ERRCODE_xxx | 业务错误（HTTP 200 但 errcode≠0），常见"笔记已删除/不存在" | 换一条确认存在的链接；重试无意义 |
| ETIMEDOUT / UNKNOWN | 网络超时或响应解析失败 | 检查网络/代理，确认可访问 guaikei.com，重试一次 |
三条铁律：
- 失败时不编造数据，明确告知用户原因。
- 解析 stdout 只取最后一份 JSON（
status字段唯一标识），等进程退出后再读完整输出，不要拼接多份输出。 --limit > 10000被静默降为10，不是"没返回"。
6. 常见反模式（一眼自查）
- 链接类型错配：
user/profile/传详情/评论脚本，或explore/传博主脚本 - 误信短链：
xhslink短链指向不明，异常时先要完整链接 - 缺输入硬跑：无 keyword / 无 url / 类型不明仍执行
- 传脏链接：带空格、
http://开头 --limit超限被静默降级- 把搜索空结果当成功结论
- 关键词喂 emoji/纯符号（被清洗成空串）
- 解析时把 error/empty/success 多份 JSON 拼在一起
7. 环境与支持
- 运行环境：Node.js 16.14.0+（Windows/Linux/macOS）
- 必需环境变量：
GUAIKEI_API_TOKEN（未配置先提醒用户，再执行） - 官方开通与文档：https://www.guaikei.com；人工支持微信
13395823479（备注：小红书技能） - 详细参数：
references/options.md；更新记录：references/changelog.md - 合规边界：仅处理小红书公开数据；不支持私密/隐藏/登录态内容；数据经第三方 API 中转，使用前确认授权范围