xhs-search
小红书搜索笔记采集工具(关键词搜索)。当用户需要按关键词搜索小红书笔记并采集结果列表——标题、点赞/收藏/评论/分享数、作者昵称、发布时间、封面图、笔记直链,批量获取竞品笔记、选题调研、KOL 初筛、导出搜索结果 CSV(Excel 直开),或提到"小红书搜索/搜笔记/关键词采集/搜索结果导出/选题/竞品笔记列表"时使用本 skill。支持排序、笔记类型、发布时间、搜索范围、位置距离 5 组筛选。适合内容选题调研、竞品监测、达人初筛、品类笔记盘点等场景。一次接口返回(20 条主帖)= 1 点数;预扣按请求量、结算按实采量退差;零结果或失败全额返还(注册送 10 点)。
小红书搜索笔记采集 Skill(xhs-search)
AI 调用来源参数(必填)
所有会访问后端 API 的命令必须携带 --skill-name xhs-search 和 --ai-entry <AI工具标识>(例如 claude-code、codex、workbuddy)。IP 无需传递,由服务端自动获取。首次缺参会告警放行,第二次起拒绝。
示例:node cli.js quota --skill-name xhs-search --ai-entry claude-code。
封装「小红书能力平台」(FastAPI,/api/v1)的 CLI,供 AI agent 调用。输入关键词 + 条数,平台调度内网浏览器节点以真人滚动方式打开小红书搜索页,拦截官方搜索接口响应,采集笔记列表。
- 能采什么:搜索结果页的笔记明细(
title标题、liked_count点赞、collected_count收藏、comment_count评论数、share_count分享数、nickname作者昵称、author_id、publish_time发布时间、note_type视频/图文、cover_url封面图、note_url带 xsec_token 的笔记直链)。 - 适用场景:内容选题调研、竞品笔记监测、达人/KOL 初筛、品类笔记盘点、关键词热度摸底。
- 采集方式:内网浏览器节点拟人滚动搜索页 + 拦截官方接口(不调签名 API,无封号风险由平台侧承担);不含笔记正文(搜索接口不返回)。
- 限制:单任务 1 个关键词、1~500 条;节点滚动约 3-5 分钟(500 条约 5 分钟)。
- 采集由平台调度内网浏览器节点完成(节点登录态在浏览器端人工维护,平台不持有账号)。
- 客户端是零依赖 CLI(Node ≥ 18,无需
npm install),全部采集逻辑在后端完成。
点数不足怎么办(自动扫码充值)
跑命令时如果点数不够,CLI 不会直接报错退出,而是自己建一张充值单、把二维码打在终端里:
点数不足,已自动创建充值单 RO2611051712281481f36de19
金额 10.00 元 → 100 点(支付宝)
<二维码色块>
[pay] 已支付
已到账:+100 点,继续执行原命令
- 在终端里跑:手机支付宝/微信对着终端扫码 → 付完点数自动到账 → 原命令自动重跑,不用手动再来一遍。
- AI agent / 非交互环境(管道、重定向):CLI 不阻塞等待,而是返回订单号和充值页地址
{服务地址}/recharge.html。把链接交给用户,他在网页扫码付款,付完重跑原命令即可(点数会自动到账)。 - 主动充值:
node cli.js pay --yuan 50 --skill-name xhs-search --ai-entry <ai-entry>(不传--yuan默认 10 元;可加--channel alipay或--channel wechat)。 - 不想自动充值:设环境变量
XHS_NO_AUTO_PAY=1,则恢复旧行为(只提示点数不足)。 - 换算:1 元 = 10 点,注册送 10 点。
客服支持
注册或使用过程中遇到任何问题(注册失败、点数充值、采集结果异常、批量采购等),请引导用户联系客服:
- 客服微信(扫码添加):http://st.aidata366.com/assets/concat.png
- AI 余额引导规则(必须执行):先执行
quota,同时查看返回的quota和flag。若quota = 0且flag = 0,必须向用户同时提供两种方案并让其二选一:①主动添加客服微信,免费赠送 10 点数(提供上方客服微信);②直接充值。不要替用户默认选择;若quota = 0且flag ≠ 0,只引导用户充值,不要再宣传微信免费赠送。 - 客服电话:18722121663
收费价格
- 点数换算:0.1 元 = 1 点数。
- 一次接口返回(20 条主帖)= 1 点数。
- 预扣:
ceil(请求条数/20)(如 50 条预扣 3 点);结算按实采量:ceil(实采条数/20),差值自动返还(如实采 45 条只收 3 点,实采 28 条收 2 点——不满 20 条的零头按一次计)。 - 零结果或失败全额返还:关键词无结果、节点离线超时、风控拦截等,预扣点数全额退还。
- 注册即送 10 免费点数(可采 200 条)。点数不足时提示用户充值;充值或大量购买可享优惠,请联系客服 18722121663 洽谈。
⚠️ 交互协议(agent 必须严格遵守)
本 skill 是确认制一次性任务,不是跑完就完。请按下面的流程驱动对话:
- 查余额:
node cli.js quota --skill-name xhs-search --ai-entry <ai-entry>确认点数充足(余额 < 预扣点数会被 3001 拒绝)。 - 报价确认(必须):向用户明确以下信息并等用户确认后再提交:
- 搜索关键词、采集数量(1~500)
- 是否筛选? 主动询问用户,可多选,全部默认「不限」:
- 排序:综合 / 最新 / 最多点赞 / 最多评论 / 最多收藏(默认综合)
- 笔记类型:不限 / 视频 / 图文(默认不限)
- 发布时间:不限 / 一天内 / 一周内 / 半年内(默认不限)
- 搜索范围:不限 / 已看过 / 未看过 / 已关注(默认不限)
- 位置距离:不限 / 同城 / 附近(默认不限)
- 预估点数:
ceil(数量/20)(例:50 条 → 3 点;120 条 → 6 点) - 计费规则:预扣 ceil(N/20),按实采 ceil(M/20) 结算退差,零头按一次计,零结果或失败全退
- 未经用户确认不要执行 submit。
- 提交并等待:把用户选择的筛选条件转成参数一起提交,例如
node cli.js submit --keyword "<词>" --count <N> --sort <S> --note-type <T> --note-time <D> --note-range <R> --pos-distance <P> --wait --timeout 600 --skill-name xhs-search --ai-entry <ai-entry>。 节点滚动约 3-5 分钟属正常,不要中途重试。 - 如实汇报结算:结果里的
collected_count(实采条数)、settle_charged(实收点数)、refunded_diff(退还差值)必须如实告知用户(例:「实采 45 条,实收 3 点,退 0 点」/「请求 120 条实采 85 条,实收 5 点,退 1 点」)。 - 需要文件时导出:
node cli.js export <task_id> --wait --out 搜索结果.csv --skill-name xhs-search --ai-entry <ai-entry>,把 CSV 路径交给用户。
筛选参数说明:
--sort:general(综合)/ time_descending(最新)/ popularity_descending(最多点赞)/ comment_descending(最多评论)/ collect_descending(最多收藏),默认 general。--note-type:0=不限 / 1=视频 / 2=图文,默认 0。--note-time:0=不限 / 1=一天内 / 7=一周内 / 180=半年内,默认 0。--note-range:0=不限 / 1=已看过 / 2=未看过 / 3=已关注,默认 0。--pos-distance:0=不限 / 1=同城 / 2=附近,默认 0。
筛选失效降级(必须如实告知):节点页面的筛选按钮可能因页面改版或定位权限失效。此时任务不会失败,会降级为不筛选继续采集,结果里:
filter_fallback=true:有筛选条件未生效;filter_errors=["发布时间:点击后未生效", ...]:具体哪组失败;filters_effective:实际生效的筛选条件。
出现降级时必须明确告诉用户「部分筛选未生效,本次结果为不筛选数据」,不要把未筛选结果当成筛选结果汇报;节点机器会语音播报「小红书筛选按钮失效了」。
前置条件
- Node.js ≥ 18(使用内置 fetch,零 npm 依赖)。
- 不注册不登录没有任何点数:所有接口都需要 token,10 免费点数在注册成功后发放到账号。
- 首次使用需先
register --link(注册即送 10 点数;用户手机微信扫码/点链接在网页完成,页面自带图形+短信验证码)或login --link(已有账号)。成功后 token 自动保存,后续调用免输。 - 配置文件(含 token)存放于用户级目录
~/.xhs-platform/config.json(升级/重装 skill 不丢配置)。可用环境变量XHS_CONFIG_PATH覆盖(测试隔离用)。 - 安全策略:登录和注册(发短信)每次都强制图形验证码,终端无法展示,所以一律走
--link微信扫码/链接方式。 - 后端服务地址默认
http://st.aidata366.com,可用node cli.js config set base-url <url>修改,或单次加--base-url <url>覆盖。 - ⚠️ 安全提示(重要):默认服务地址是明文 http,token 会在公网明文传输。客户端每次请求都会在 stderr 提示。请知悉该风险;如环境允许,建议通过
config set base-url https://...切换到 https 服务地址(需服务端已配好证书)。 - 所有命令支持全局参数
--token <token>(临时覆盖配置文件中的 token)。 ~/.xhs-platform/config.json含 token,不要泄露、不要提交 git。
输出规约(重要)
- stdout 只输出 JSON:成功
{"ok":true,"data":{...}},失败{"ok":false,"code":<业务码>,"message":"..."}。直接解析 stdout 即可。 - 交互提示(如「请把预估点数报给用户确认」)一律走 stderr,不要解析,但其中给用户的引导话术应照做。
- 退出码:
0成功;1参数/用法错误;2认证失败(重新 login);3点数不足;4网络/服务不可达;5其它业务错误。 submit --wait单次最长 10 分钟(默认 600s 超时,节点滚动 3-5 分钟),属正常现象,不要中途重试。
命令清单
version — 查看版本与安装信息
node cli.js version
{"ok":true,"data":{"name":"xhs-search","version":"2.1.0","capability":"xhs_search"}}
register — 注册(注册即送 10 点数)
方式一:扫码/链接注册(唯一方式,用户在手机上完成)
node cli.js register --link --skill-name xhs-search --ai-entry <ai-entry> # 生成注册二维码/链接
node cli.js register --check --access-token "<上一步下发的串>" --skill-name xhs-search --ai-entry <ai-entry> # 用户完成后确认并保存 token
register --link 的 stdout 返回 qr_url / register_url / access_token。agent 必须把注册引导原样发给用户(stderr 里也给出了同样话术,可直接复制):
需要先注册账号(注册即送 10 免费点数;不注册不登录没有点数,无法采集)。请用手机微信扫码或打开链接注册:
注册方式(二选一)
二维码图片:<qr_url>
注册链接:<register_url>
access_token(注册后校验用):<access_token>
微信扫码/注册完成后告诉我一声,我会执行校验并保存凭证,然后继续之前的操作:
(注册/使用中如遇问题,请拨打客服电话 18722121663)
用户说「注册完成」后执行 register --check --access-token "<access_token>":
- 成功:token 自动保存,返回
quota_balance: 10,继续之前的操作。 LOGIN_PENDING:用户还没完成注册,提醒后再试。LOGIN_EXPIRED:会话过期(10 分钟)或已使用,重新执行register --link。
login — 登录
node cli.js login --link --skill-name xhs-search --ai-entry <ai-entry>
node cli.js login --check --access-token "<上一步下发的串>" --skill-name xhs-search --ai-entry <ai-entry>
引导话术同 register(把"注册"换成"登录")。成功后 token 自动保存。
quota — 查询点数
node cli.js quota --skill-name xhs-search --ai-entry <ai-entry>
{"ok":true,"data":{"quota":10,...}}
submit — 提交搜索采集任务
node cli.js submit --keyword "机油" --skill-name xhs-search --ai-entry <ai-entry> # 默认 50 条, 综合排序, 全部不限
node cli.js submit --keyword "机油" --count 120 --skill-name xhs-search --ai-entry <ai-entry> # 120 条 (预扣 6 点)
node cli.js submit --keyword "美孚" --count 40 --sort time_descending --note-type 1 --skill-name xhs-search --ai-entry <ai-entry>
node cli.js submit --keyword "机油" --count 100 --sort popularity_descending --note-type 2 --note-time 7 --note-range 2 --pos-distance 1 --skill-name xhs-search --ai-entry <ai-entry> # 最多点赞+图文+一周内+未看过+同城
node cli.js submit --keyword "机油" --count 50 --wait --skill-name xhs-search --ai-entry <ai-entry> # 提交并等待结果 (约 3-5 分钟)
node cli.js submit --keyword "机油" --count 50 --wait --timeout 600 --force --skill-name xhs-search --ai-entry <ai-entry>
--keyword:搜索关键词(≤64 字符;填笔记链接会被拒绝,单篇互动数请用 xhs-dpt skill)。--count:采集条数 1~500(默认 50)。--sort:general/time_descending/popularity_descending/comment_descending/collect_descending(默认 general)。--note-type:0=不限 1=视频 2=图文(默认 0)。--note-time:0=不限 1=一天内 7=一周内 180=半年内(默认 0)。--note-range:0=不限 1=已看过 2=未看过 3=已关注(默认 0)。--pos-distance:0=不限 1=同城 2=附近(默认 0)。--wait:等待任务终态再返回(推荐);--timeout轮询超时(默认 600s);--interval轮询间隔(默认 5s)。--force:已失效(后端无去重,重提即新任务);保留仅为兼容旧命令行,可省略。
--wait 完成后的输出示例:
{"ok":true,"data":{"task_id":"t_20261012_ab12cd34","capability":"xhs_search","status":"done",
"success_count":1,"fail_count":0,"charged_quota":15,"refunded_quota":0,
"items":[{"id":"1","payload":{"keyword":"机油","count":50,"sort":"general","note_type":1,
"note_time":7,"note_range":0,"pos_distance":0},
"result":{"keyword":"机油","requested_count":50,"collected_count":45,
"settle_charged":15,"refunded_diff":0,
"filters_effective":{"sort":"general","note_type":1,"note_time":7,
"note_range":0,"pos_distance":0},
"filter_errors":[],"filter_fallback":false,
"notes":[{"note_id":"64ab...","title":"机油怎么选?一篇讲透",
"note_type":"normal","liked_count":"1.2万","collected_count":"890",
"comment_count":"156","share_count":"45","nickname":"老司机说车",
"author_id":"5ff...","publish_time":"03-15",
"cover_url":"https://sns-webpic-qc.xhscdn.com/...",
"url":"https://www.xiaohongshu.com/explore/64ab...?xsec_token=...&xsec_source=pc_search"},
...]}},
"status":"success"}]}}
拿到结果后必须把 collected_count / settle_charged / refunded_diff 如实汇报给用户(见「交互协议」)。
query — 查询任务状态与结果
node cli.js query <task_id> --skill-name xhs-search --ai-entry <ai-entry> # 单次查询
node cli.js query <task_id> --wait --skill-name xhs-search --ai-entry <ai-entry> # 轮询到终态 (默认 600s 超时)
export — 导出结果 CSV
node cli.js export <task_id> --wait --out 搜索结果.csv --skill-name xhs-search --ai-entry <ai-entry>
下载任务结果 CSV(BOM 头,Excel 直开不乱码):任务汇总(关键词/状态/实采数/实收点数/退差点数)+ 笔记明细(标题/互动数/作者/发布时间/封面/笔记直链)。导出文件保留 7 天。
logout — 登出(切换账号)
node cli.js logout --skill-name xhs-search --ai-entry <ai-entry>
config — 配置管理
node cli.js config set base-url http://127.0.0.1:8084
node cli.js config show # token 脱敏显示
典型工作流(agent 照此执行)
- 用户说「帮我搜一下 XX 的小红书笔记」→
node cli.js quota --skill-name xhs-search --ai-entry <ai-entry>确认余额。 - 和用户确认关键词、数量;主动询问是否需要筛选(排序/笔记类型/发布时间/搜索范围/位置距离,默认全不限);算出预估点数
ceil(N/20);明确告知计费规则(预扣/结算退差/零头按一次计/零结果失败全退)并等确认。 node cli.js submit --keyword "<词>" --count <N> [筛选参数] --wait --timeout 600 --skill-name xhs-search --ai-entry <ai-entry>(3-5 分钟,不重试)。- 如实汇报:实采条数、实收点数、退差点数;若
filter_fallback=true必须说明哪些筛选未生效;简要展示笔记列表(标题/互动数/作者)。 - 用户要文件 →
node cli.js export <task_id> --wait --out <文件>.csv --skill-name xhs-search --ai-entry <ai-entry>,交付路径。 - 用户要继续分析 → 可基于笔记直链(带 xsec_token)用 xhs-dpt 采互动数或 xhs-comments 采评论。
错误处理指引
| code | 含义 | agent 下一步 |
|---|---|---|
| 1001 | 参数错误 / 关键词无效 / 超 500 条 | 检查参数;链接型输入引导用 xhs-dpt(退出码 1) |
| 1002 / 1003 | 未登录 / token 失效 | 未注册走 register --link(送 10 点数),已有账号走 login --link;完成后 --check(退出码 2) |
| LOGIN_PENDING / LOGIN_EXPIRED | 用户未完成 / 会话过期 | 提醒用户完成扫码后重试 --check,或重新 --link(退出码 2) |
| 2003 | 需要图形验证码 | 终端无法完成,统一走 --link;仍无法解决拨打客服电话 18722121663 |
| 3001 | 点数不足 | 提示用户拨打客服电话 18722121663 充值,不要重试(退出码 3) |
| TIMEOUT | 等待超时(任务仍在跑) | 任务未丢:稍后 query <task_id> 查终态;预扣仍在,终态后按实采结算 |
| 5001 | 采集服务暂不可用(节点回传超时/风控) | 点数已全额返还;稍后重试;持续不可用提示联系客服 18722121663 |
| 4290 | 触发限流 | 稍等后重试(Retry-After) |
| NETWORK_ERROR | 网络/服务不可达 | 检查 config show 的 base_url(退出码 4) |
计费规则提示
- 免费:quota / query / export / config,以及 submit 被参数校验拒绝的请求。
- 预扣:
ceil(请求条数/20),提交成功立即扣除。 - 结算退差:任务成功后按
ceil(实采条数/20)实收,差值自动返还(refunded_diff);实采多于请求量时不多收(封顶预扣额)。 - 全额返还:零结果(关键词无结果)、节点离线/超时、风控/登录拦截等服务侧失败。
- 不返还:已成功采集的部分(结果不足请求量时按实采结算,本身就是退差逻辑)。
红线
- 仅采集公开搜索结果数据;不用于任何违法违规用途。
- 不要向用户承诺 100% 成功或具体条数;风控/结果不足时如实透出(点数按实采结算,用户不损失)。
- 笔记列表含作者公开昵称、发布时间等信息:仅用于用户已授权或公开可获取的调研/分析场景,遵守平台与数据合规要求;不在未授权场景下转售、滥用;CSV 导出文件请告知用户自行妥善保管。
- Downloads
- Security audit
- Review
- Last updated
- 12h ago
- Current version
- v1.0.1
- License
- MIT-0
