guaikei-xhs-tool

小红书公开数据获取技能｜核心：把小红书关键词搜索、笔记详情、笔记评论、博主作品列表抓取为结构化 JSON；一次最多 1W 条；需 GUAIKEI_API_TOKEN；仅公开数据，不含登录态/私密内容

✨ 一句话价值主张：面向小红书公开数据的检索与洞察技能，用于关键词搜索、笔记详情与评论查看、博主作品监控，并返回结构化结果供后续分析、汇总或生成报告，帮助你实现小红书账号的快速增长与精准营销。

1. 🛠️ 技能概述

这是一款专注于小红书数据挖掘的工具。它能够穿透小红书的公开数据层，为你提供深度的竞品监控、趋势预测和KOL 筛选服务。无论你是内容创作者、品牌营销人员还是市场分析师，都能通过此工具获取决策支持。

🔥核心优势

• 安全: 无需登录你的小红书账号，不担心风控风险 / 封号问题
• 强大: 一次可获取最多1W条数据，技能内置批量操作，使用简单方便
• 全面: 各功能出参数据全面，可见及有价值数据都会返回
• 灵活: 支持多维度筛选、批量操作、多格式导出
• 轻量: 无需部署服务，Node.js 一键运行
• 实用: 日志自动归档，适配营销报告 / 内容策划场景

2. ✅ 什么时候应该调用这个技能

🎯 在以下场景优先调用：

• 用户明确提到要查 小红书 内容。
• 用户要做 关键词搜索、爆款选题调研、竞品监控、评论洞察、博主作品追踪。
• 用户提供了小红书关键词、笔记链接或博主主页链接，希望拿到结构化数据。
• 用户后续还要基于结果继续做总结、对比、筛选、报告生成。

🚫 不要在这些场景误调用

• 用户只是想写文案、改标题、生成脚本，但并未要求查询小红书公开数据。
• 用户查询的平台不是小红书，例如抖音、B站、微博、公众号。
• 用户要求获取私密内容、登录态数据、隐藏数据或非公开信息。
• 用户既没有提供关键词，也没有提供可识别的小红书链接，且任务目标仍不明确。

如果意图不明确，先追问，不要盲目执行命令。

3. 🚧 能力边界

本技能当前只覆盖 4 类能力：

1. 关键词搜索：按关键词搜索小红书公开笔记。
2. 笔记详情：根据笔记链接获取笔记详情。
3. 博主作品监控：根据博主主页链接获取其公开作品列表。
4. 笔记评论获取：根据笔记链接单独获取该笔记的评论数据，便于做评论洞察与观点分析。

🛑 本技能不负责：

• 登录小红书账号
• 发布内容、互动、点赞、评论、关注
• 获取私密或非公开数据
• 代替用户做营销策略判断

它的职责是先把数据拿回来，再交给上层流程去分析、整理或生成结论。

4. 🔀 调用路由规则

Note: 请先通过 小红书实时数据获取技能官网 开通TOKEN，配置环境变量 GUAIKEI_API_TOKEN 后才能正常运行。

根据用户输入的关键信号，路由到对应脚本：

用户输入 / 意图	调用脚本	必填输入	典型结果
查某个关键词的小红书内容	src/xiaohongshu/search-cli.js	keyword	笔记列表、作者信息、互动信息、跳转链接
看某篇小红书笔记的详情	src/xiaohongshu/detail-cli.js	笔记 URL	笔记详情、作者信息
看某个小红书博主最近发布了什么	src/xiaohongshu/post-cli.js	博主主页 URL	博主公开作品列表
看某篇小红书笔记的评论数据	src/xiaohongshu/comment-cli.js	笔记 URL	该笔记的评论内容、评论者信息、互动数据

🧭 路由细则

• 用户给的是 关键词，没有链接：走 关键词搜索。
• 用户给的是 https://www.xiaohongshu.com/explore/... 或可解析到笔记的短链：若只关心评论，走 笔记评论查询；若要连同笔记详情一起看，走 笔记详情与评论。
• 用户给的是 https://www.xiaohongshu.com/user/profile/... 或可解析到主页的短链：走 博主作品监控。
• 如果用户同时给出多个目标，按用户目标拆分执行，不要把不同意图硬塞进一次命令。

5. 🧺 输入收集规则

执行前先收集足够输入，避免无效调用。

5.1 🔍 关键词搜索

至少要确认：

• keyword：搜索关键词，建议 2-50 个字符。

可选参数：

• type：内容类型，0 全部，1 视频，2 图文。
• sort：排序规则，0 综合，1 最新，2 最多点赞，3 最多评论，4 最多收藏。
• time：发布时间，0 全部，1 一天内，2 一周内，3 半年内。
• limit：返回数量，范围 1-10000，默认 10。

如果用户只说“帮我看看最近趋势”，优先补问：

• 关键词是什么？
• 更关心最新、点赞还是收藏？
• 要看图文、视频还是全部？

5.2 📰 笔记详情与评论

至少要确认：

• url：小红书笔记链接。

可选参数：

• limit：评论数量上限；不传时按脚本默认行为执行。

适用链接示例：

• https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy
• https://xhslink.com/m/xxx

如果用户给的是博主主页链接，不要误走详情脚本，先指出链接类型不匹配。

5.3 📡 博主作品监控

至少要确认：

• url：小红书博主主页链接。

可选参数：

• limit：返回作品数量上限；不传时按脚本默认行为执行。

适用链接示例：

• https://www.xiaohongshu.com/user/profile/xxx?xsec_token=yyy
• https://xhslink.com/m/xxx

如果用户给的是笔记详情链接，不要误走博主脚本，先说明需要主页链接。

5.4 💬 笔记评论获取

至少要确认：

• url：小红书笔记链接。

可选参数：

• limit：评论数量上限；不传时按脚本默认行为执行。

适用链接示例：

• https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy
• https://xhslink.com/m/xxx

如果用户给的是博主主页链接，不要误走评论脚本，先指出链接类型不匹配。 与「笔记详情」的区别：本能力只取评论数据，不返回笔记正文 / 互动详情，适合只想做评论洞察、观点聚类或舆情分析的场景。

👉 详细选项说明, 可参阅 完整选项说明

6. 📜 执行原则

6.1 ❓ 缺少必要输入时

• 没有关键词：先追问关键词。
• 没有链接：先追问笔记链接或博主主页链接。
• 链接类型不明确：先确认这是笔记还是博主主页。
• 没有 GUAIKEI_API_TOKEN：提醒用户先配置环境变量，再执行。

不要在缺关键输入时硬调命令。

6.2 📤 输出原则

执行完成后，优先返回：

• 本次执行的目标
• 关键参数
• 结构化 JSON 结果
• 如果有必要，再补充一小段摘要说明

适合继续衔接的后续动作包括：

• 选题汇总
• 高赞笔记对比
• 评论观点聚类
• 竞品内容风格总结
• 博主发文节奏分析
• 报告与表格生成

6.3 🩹 失败处理原则

出现以下情况时，应明确向用户说明原因：

• token 未配置或无效
• 链接不合法或类型错误
• 搜索结果为空
• 接口返回异常
• 网络或超时问题

失败时不要编造数据，不要把空结果当成成功结论。

7. 💡 推荐调用方式

7.1 🔍 关键词搜索

bash

node src/xiaohongshu/search-cli.js --keyword "夏季穿搭"

更细化的示例：

bash

node src/xiaohongshu/search-cli.js --keyword "露营装备" --type 2 --sort 2 --time 2 --limit 20

适合场景：

• 找爆款选题
• 看某关键词最近热度
• 比较不同关键词表现
• 做趋势洞察和竞品搜集

7.2 📰 笔记详情

bash

node src/xiaohongshu/detail-cli.js --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy"

适合场景：

• 看某篇爆款笔记的标题、正文、互动数据
• 分析单篇内容为何有效

7.3 📡 博主作品监控

bash

node src/xiaohongshu/post-cli.js --url "https://www.xiaohongshu.com/user/profile/xxx?xsec_token=yyy" --limit 20

适合场景：

• 观察竞品博主最近在发什么
• 看一个账号的发文节奏与主题分布
• 为 KOL 筛选和竞品分析准备原始数据

7.4 💬 笔记评论查询

bash

node src/xiaohongshu/comment-cli.js --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --limit 100

适合场景：

只拉评论区做观点归纳或情绪分析 统计某篇笔记的高频评论主题 识别评论区的主要负面反馈

8. 🚀 对 WorkBuddy / OpenClaw 更友好的使用方式

为了提升识别准确率与执行成功率，优先采用以下自然语言触发方式：

• 帮我搜一下小红书里“露营装备”的高赞图文笔记
• 分析这条小红书笔记评论区都在讨论什么
• 看看这个小红书博主最近 20 条作品主要发什么内容
• 监控“小红书夏季穿搭”最近一周的内容趋势

如果用户表达比较笼统，例如“帮我做小红书竞品分析”，优先把任务拆成两步：

1. 先确认关键词、竞品链接或博主主页链接。
2. 再调用对应脚本拿回数据。

9. 📦 环境与依赖

• 运行环境：Node.js 16.14.0+
• 系统兼容：Windows / Linux / macOS
• 必需环境变量：GUAIKEI_API_TOKEN
• 官方入口：https://www.guaikei.com
• 详细参数说明：见 references/options.md
• 更新记录：见 references/changelog.md

10. 🛡️ 合规与使用限制

• 仅处理小红书公开数据。
• 不支持私密、隐藏或需要登录态的数据。
• 不应将返回数据用于违规分发或违法用途。
• 本技能会依赖第三方 API 服务，请在使用前确认数据外发与授权范围。

11. 🚫 反模式与常见问题 FAQ

本章帮助你在不联系开发者的情况下，自行判断「是不是用错了」以及「报错时怎么处理」。结构化结果里都带有 status 和 error_code 字段，下游调用方请先按 status 分支（success / empty / error），再参考 error_code 决定重试还是换输入。

11.1 🚫 反模式（以下做法都会导致失败或拿到错误数据）

• 链接类型错配：把博主主页 user/profile/... 传给 detail-cli.js / comment-cli.js，或把笔记链接 explore/... 传给 post-cli.js。链接类型不对时接口会返回业务错误。
• 误信短链类型：xhslink.com/m/xxx、xhslink.cn/m/xxx 是不透明的短链，无法仅凭短链判断它指向笔记还是博主主页。如果用户给的是短链且结果异常，优先请用户提供完整链接（explore/ 或 user/profile/）。
• 缺关键输入就硬跑：没有 keyword、没有 url，或链接类型不明确时，先追问，不要执行命令。
• 传脏链接：带前后空格、用 http://（非 https://）的链接会被拒绝。需要的话先做 trim、http→https 归一。
• limit 超限被静默降级：limit 上限是 10000，写成 > 10000（如 20000）会被静默降到 10，并非「没返回」。
• 把空结果当成功 / 编造数据：search-cli.js 拿不到结果会按失败（退出码 1）返回；detail/comment 返回空数组则视为成功。无论哪种，失败都不要编造结论。
• 关键词喂 emoji / 纯符号：🔥🔥、（）【】 这类会被清洗成空串，触发「关键词无效」拦截。换有意义的文字关键词。
• 假设失败也会输出成功字段：失败 JSON 的 status 是 "error"（或 "empty"），results 为 null；只有成功时 results 才有数据。解析 stdout 时务必先看 status。

11.2 ❓ 常见问题 FAQ（自助排查）

Q1. 报错 error_code: 401 或 403 怎么办？

含义：GUAIKEI_API_TOKEN 未配置或无效。 自查：①确认运行环境里确实 export GUAIKEI_API_TOKEN=... 了（不是只在 shell 配置里写了）；②token 须为 32 位十六进制（如 abcdefghij0123456789abcdefghij12），核对是否有多余空格或换行；③是否已过期，去 https://www.guaikei.com 重新开通。

Q2. 报错 error_code: 429 怎么办？

含义：触发了接口频率限制。 自查：降低调用频率、减小 --limit、或稍后重试，不要短时间高频轮询。

Q3. 报错 error_code: 500 / 502 / 503 等服务端错误怎么办？

含义：第三方 API 临时故障。 自查：通常是 transient，等 1–2 分钟重试；若持续出现，再走 §12 联系支持，并附上 skill_metadata 里的 execution_time 与请求参数。

Q4. 报错 error_code: ERRCODE_xxx 怎么办？

含义：业务层错误（HTTP 200 但 errcode !== 0），常见如「笔记已删除 / 不存在 / 无权限」。 自查：换一条确认仍存在的笔记链接；该错误不会随重试变好，不要反复重试同一链接。

Q5. 报错 error_code: ETIMEDOUT 或 UNKNOWN 怎么办？

含义：网络超时或无法解析响应。 自查：检查本机网络 / 代理；确认能访问 guaikei.com；重试一次；仍失败再联系支持。

Q6. 提示「小红书链接格式无效」怎么办？

自查：确认链接①以 https:// 开头；②无前后空格；③是以下之一：www.xiaohongshu.com/explore/...、www.xiaohongshu.com/user/profile/...、xhslink.com/m/...、xhslink.cn/m/...。

Q7. 命令一启动就退出、没输出数据？

自查：多半是 GUAIKEI_API_TOKEN 未通过校验（见 Q1）。在运行命令前先 echo $GUAIKEI_API_TOKEN 确认变量已注入当前进程。

Q8. 搜索返回空、但退出码不是 0？

含义：search-cli.js 把「无结果」视为失败（退出码 1）。 自查：换更宽泛的关键词、放宽 --type / --time、或确认关键词不是被清洗成空串的符号（见 11.1）。detail/comment 的空数组则视为成功，属正常差异。

Q9. 设了 --limit 10000 却只拿到 10 条？

含义：limit 写成了超过 10000 的值，被静默降到默认 10（见 11.1）。 自查：确认 --limit 是 1–10000 之间的整数。

Q10. 下游程序解析 stdout 失败 / 报 Unexpected end of JSON input？

自查：失败输出通过 process.stdout.write(..., () => process.exit(1)) 异步写出后会退出；请确保消费方等进程退出后再读完整 stdout，且只取最后一份 JSON（status 字段唯一标识这份结果）。不要把 error/empty/success 多份输出拼在一起解析。

12. 🎧 支持信息

如需开通 token 或获得使用支持，可优先通过官网处理：

• 官网：小红书搜索评论数据获取技能官网

如需人工支持，可联系开发者：

• 微信：13395823479（备注：小红书技能）