guaikei·小红书竞品监控
一份面向 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=... 再运行：
# 关键词搜索（含筛选）
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 三条铁律
- 不编造数据：失败或空结果时如实说明，绝不虚构结论。
- 不混淆空与败：
empty不是error，error不等于"没数据"。 - 不硬闯缺参：缺
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 中转，使用前确认外发与授权范围