guaikei·小红书数据助手

guaikei 出品的小红书公开数据技能：笔记搜索、详情、评论、博主作品监控，返回结构化数据。当用户需要小红书内容数据做爆款挖掘/竞品分析/KOL筛选/评论洞察时使用本技能；即使用户没点名小红书，只要语境涉及红笔记内容挖掘也适用。需 GUAIKEI_API_TOKEN。不用于登录或私密数据。

一份面向 AI 执行者的调用指南。整份文档按一次完整调用的生命周期组织：每一步该做什么、判断依据是什么，都按执行时序排在对应位置。

---

第 0 站 · 启程前：先判"该不该用我"

该用（满足任一即触发）：

• 用户想要小红书平台上的内容数据：按关键词找笔记、看单篇详情、读评论、盯博主发文
• 用户给出小红书链接（xiaohongshu.com 或 xhslink.com）并想据此拿数据
• 用户提到 红笔记 / xhs / rednote，且诉求指向"找内容、看数据"

不该用（任一命中即拒绝）：

• 目标平台不是小红书（抖音、B站、微博、公众号等）
• 用户只是想写文案、改标题、生成脚本，并不要求查数据
• 诉求涉及登录态、私密内容、隐藏数据，或要求发布/点赞/评论
• 既无关键词也无链接，任务目标完全不明

判断不了时，先问清楚，不要硬执行。

---

第 1 站 · 听需求：识别是哪一类

用户的表达可以五花八门，但只映射到 4 类能力。按"用户给了什么、想干什么"定位：

用户给了	用户想干	对应能力	脚本
关键词	找这个主题的笔记	关键词搜索	search-cli.js
笔记链接	看这篇笔记的正文与互动	笔记详情	detail-cli.js
笔记链接	只拉这篇的评论区	评论获取	comment-cli.js
博主主页链接	看他发了什么	博主作品	post-cli.js

拆单规则： 用户一口气提多个目标时，按意图拆开分别执行；不要把不同意图硬塞进一次命令。

---

第 2 站 · 备料：收齐输入再动手

2.1 参数总表（含简写）

参数	简写	必填	取值/默认	适用能力
--keyword	-k	是	2–50 字符，避免纯符号	仅搜索
--url	-u	是	笔记链接或博主主页链接	详情/评论/作品
--type	-t	否	0 全部（默认）1 视频 2 图文	仅搜索
--sort	-s	否	0 综合 1 最新 2 点赞 3 评论 4 收藏	仅搜索
--time	-i	否	0 全部 1 一天 2 一周 3 半年	仅搜索
--limit	-l	否	1–10000，默认 10	全部

2.2 缺什么、问什么

• 没关键词 → 追问关键词
• 没链接 → 追问笔记或博主主页链接
• 链接有但类型不明（尤其短链）→ 追问是笔记还是主页
• 搜索诉求笼统（"看看最近趋势"）→ 补问关键词 + 更关心最新/点赞/收藏 + 图文/视频/全部

2.3 链接形态速判

链接形态	判定	处理
xiaohongshu.com/explore/...	笔记链接	走详情或评论
xiaohongshu.com/user/profile/...	博主主页	走作品
xhslink.com/m/... / xhslink.cn/m/...	不透明短链	无法仅凭形态判断指向，先请用户给完整链接
带空格 / http:// 开头	脏链接	先 trim、http→https 归一化

错配是头号事故源： 主页链接传给详情/评论脚本、笔记链接传给作品脚本，接口都会报业务错误。传参前先对照上表确认链接类型。

---

第 3 站 · 执行：调脚本

四类命令在此汇齐，先 export GUAIKEI_API_TOKEN=... 再运行：

bash

# 关键词搜索（含筛选）
node src/xiaohongshu/search-cli.js --keyword "露营装备" --type 2 --sort 2 --time 2 --limit 20

# 笔记详情
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 100

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

---

第 4 站 · 验收：读懂返回结果

4.1 先看 status，再谈其他

所有脚本的 stdout 都是一份 JSON，status 是唯一入口：

status	含义	后续动作
success	正常返回，results 有数据	直接使用
empty	合法但无数据（详情/评论常见）	视为正常空结果，向用户如实说明
error	失败，results 为 null	按下表定位原因

4.2 失败对照表

现象	含义	处理
401 / 403	token 未配置或无效	确认 export 已注入当前进程、token 为 32 位十六进制、未过期
429	触发频率限制	降频、减小 --limit、稍后重试
500 / 502 / 503	服务端临时故障	等 1–2 分钟重试，仍失败再联系支持
ERRCODE_xxx	业务层错误（笔记已删除/不存在/无权限）	换一条仍存在的链接；重试同一链接无效
ETIMEDOUT / UNKNOWN	网络超时或响应异常	检查本机网络/代理，确认可访问 guaikei.com，重试一次
启动即退出、无输出	token 未通过校验	运行前 echo $GUAIKEI_API_TOKEN 确认注入
搜索空结果但退出码 1	search 把"无结果"视为失败	换宽泛关键词、放宽 --type/--time（详情/评论的空数组则视为成功）
--limit 设 >10000 只拿到 10 条	超限被静默降到默认值	确认 --limit 在 1–10000 之间
stdout 解析报 Unexpected end of JSON input	未等进程退出就读取	等进程完全退出后再取完整 stdout，只解析最后一份 JSON

4.3 三条铁律

1. 不编造数据：失败或空结果时如实说明，绝不虚构结论。
2. 不混淆空与败：empty 不是 error，error 不等于"没数据"。
3. 不硬闯缺参：缺 keyword/url/token 时先补齐，别拿残缺输入跑命令。

---

第 5 站 · 交付：把数据变成价值

取回结构化数据后，常见四种收尾链路：

用户诉求	执行链路
选题调研	搜索关键词 → 挑高赞笔记看详情 → 汇总标题/主题/互动特征
评论舆情	拉评论 → 观点归类、情绪判断、负面反馈识别
竞品/KOL 监控	抓博主作品 → 分析更新频率、内容主题、互动表现
趋势跟踪	搜索（--sort 1 + --time）→ 对比时间窗热度变化

交付格式：本次目标 + 关键参数 + 结构化 JSON，必要时附一小段摘要。

---

补给站 · 环境与支持

• 运行时：Node.js 16.14.0+；Windows / Linux / macOS
• 必配环境变量：GUAIKEI_API_TOKEN
• 文档：参数细节见 references/options.md；更新记录见 references/changelog.md
• 支持：官网 https://www.guaikei.com（开通 token）；开发者微信 13395823479（备注：小红书技能）
• 合规：仅处理公开数据；不支持私密/隐藏/登录态内容；返回数据不得用于违规分发或违法用途；数据经第三方 API 中转，使用前确认外发与授权范围