guaikei·小红书搜索·详情·评论·博主

面向小红书公开数据的检索技能：只负责把数据拿回来（结构化 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，重试一次

三条铁律：

1. 失败时不编造数据，明确告知用户原因。
2. 解析 stdout 只取最后一份 JSON（status 字段唯一标识），等进程退出后再读完整输出，不要拼接多份输出。
3. --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 中转，使用前确认授权范围