Xiaohongshu Keyword Search

小红书关键词搜索

✨ 一句话：给关键词或链接，拿回结构化的小红书公开数据——笔记、详情、评论、博主作品，直接喂给后续的选题分析、竞品对比、舆情归纳。

✨ 解决什么问题：小红书运营最费时间的不是写内容，是「先搞清楚该写什么」。人工翻 1000 条笔记记录点赞收藏要一小时，本工具一条命令返回 1000 条结构化数据，AI 直接接着做归纳。

🔥核心优势

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

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

1.1 🎯 满足以下任一条件即调用

• 用户提到「小红书」「小红薯」「xhs」「rednote」并要求查看、搜索、分析内容
• 用户要做 关键词搜索、爆款选题调研、竞品监控、评论洞察、博主作品追踪、 KOL/博主筛选、评论区舆情分析、关键词趋势跟踪。
• 用户提供了小红书关键词、笔记链接或博主主页链接，希望拿到结构化数据。
• 用户给出 xiaohongshu.com 或 xhslink.com 开头的链接
• 用户说「帮我看看 XX 在小红书上的情况」这类需要真实数据支撑的判断
• 用户后续还要基于结果继续做总结、对比、筛选、报告生成。

1.2 🚫 以下情况不要调用

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

1.3 👀 意图模糊时的追问模板

用户说「帮我做小红书竞品分析」——信息不足，按此追问：

需要确认三件事：1）竞品是具体某个账号（给我主页链接），还是某个品类关键词？2）关注最新动态还是历史高赞？3）大概看多少条？

拿到答案再执行。不要自行编造关键词或链接。

2. 🔀 四个能力与路由

Note: 请先通过 小红书搜索技能官网 开通TOKEN，配置环境变量 GUAIKEI_API_TOKEN 后才能正常运行。

2.1 🧭 路由细则

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

2.2 ⚖️ detail 与 comment 的区别

• detail-cli.js：要笔记本身（标题、正文、图片、点赞收藏数）。
• comment-cli.js：只要评论区数据，不返回正文。

同时需要正文和大量评论时：调 detail-cli.js 拿正文，再调 comment-cli.js --limit 500 拿评论。

2.3 🧩 组合工作流

选题调研

search-cli --sort 2 --time 2 --limit 20    # 先拿一周高赞
→ 挑出前 10 条的 url
→ detail-cli 逐条看正文结构
→ 汇总标题公式 / 开头钩子 / 话题标签

竞品监控

post-cli --limit 100                        # 拿对方近 100 条
→ 按发布时间算更新频率
→ 按互动数据找出爆款
→ comment-cli 拉爆款的评论区看用户为什么买

KOL 筛选

post-cli --limit 100
→ 计算 评论数/点赞数、收藏数/点赞数 比值
→ 比值异常偏低 → 疑似刷量，标记风险

3. 🧺 输入规则

3.1 🔍 关键词搜索

参数选择建议（直接影响结果质量，请按意图选）：

--limit 建议：快速看一眼 10；正经做选题 30-50；批量分析 200+（注意返回体积，超过 1000 条时告知用户数据量）。

3.2 📰 笔记详情

至少要确认：

• url：小红书笔记链接。

适用链接示例：

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

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

3.3 📡 博主作品监控

至少要确认：

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

可选参数：

• limit：返回作品数量上限；为 0 时返回该博主的互动数据（粉丝量、点赞量、收藏量等）。

适用链接示例：

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

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

3.4 💬 笔记评论获取

至少要确认：

• url：小红书笔记链接。

可选参数：

• limit：评论数量上限，整数 1-10000，不传时默认 10。

适用链接示例：

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

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

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

4. 📜 执行原则

4.1 ❓ 缺少必要输入时

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

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

4.2 📤 输出原则

执行完成后，优先返回：

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

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

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

4.3 🩹 失败处理原则

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

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

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

5. 💡 命令示例

# 关键词搜索：一周内图文，按点赞排序，取 20 条
node src/xiaohongshu/search-cli.js --keyword "露营装备" --type 2 --sort 2 --time 2 --limit 20

# 追最新：一天内，按最新排序
node src/xiaohongshu/search-cli.js --keyword "多巴胺穿搭" --sort 1 --time 1 --limit 50

# 笔记详情（不带评论，省 token）
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 200

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

# 博主互动数据（粉丝量、点赞量、收藏量等）
node src/xiaohongshu/post-cli.js --url "https://www.xiaohongshu.com/user/profile/xxx?xsec_token=yyy" --limit 0

支持 --flag value 与 --flag=value 两种写法；--keyword 也可作为第一个位置参数省略 flag 名。

6. 🚧 能力边界

能做：搜索公开笔记 / 读公开笔记详情 / 读公开评论 / 读博主公开作品列表。

不能做（问到直接说不支持，不要尝试变通）：

• 登录小红书账号、使用登录态数据
• 发布、点赞、评论、收藏、关注、私信等任何写操作
• 私密笔记、草稿、仅粉丝可见内容
• 创作者后台数据（涨粉曲线、粉丝画像、流量来源）
• 用户手机号、微信、真实身份等个人信息
• 商业化数据（报价、投放后台、聚光平台）
• 替用户下营销决策——本技能只提供数据，判断交给用户

7. 📦 环境与依赖

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

8. 🛡️ 合规与使用限制

• 国内网络直连可用，无需代理
• 数据流向：本机 → guaikei.com API → 返回结果。除关键词/链接等查询参数外，不上传本机任何数据
• 仅处理小红书公开可见数据，不涉及登录态与个人隐私
• 结果限个人 / 团队内部分析使用，不得违规分发或用于违法用途
• 查询参数（关键词 / 链接）会发送至 guaikei.com API，请在使用前确认数据外发与授权范围。

9. 🚫 反模式

10. ❓ 常见问题

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

含义：GUAIKEI_API_TOKEN 未配置或无效。 自查：①确认运行环境里确实 export GUAIKEI_API_TOKEN=... 了（不是只在 shell 配置里写了）；②token 长度16-256位，由字母、数字、下划线、短横线组成的字符串（以 guaikei.com 开通页显示为准），核对是否有多余空格或换行；③是否已过期，去 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 10001 却只拿到 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 多份输出拼在一起解析。

11. 🎧 支持信息

• 官网 / TOKEN 开通：小红书搜索、详情、作品、评论数据获取官网
• 问题反馈：https://github.com/um-why/xiaohongshu-openclaw-skill/issues