小红书搜索笔记采集 Skill（xhs-search）

封装「小红书能力平台」（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），全部采集逻辑在后端完成。

客服支持

注册或使用过程中遇到任何问题（注册失败、点数充值、采集结果异常、批量采购等），请引导用户联系客服：

• 客服微信（扫码添加）：http://st.aidata366.com/assets/concat.png
• 客服电话：18722121663

收费价格

• 一次接口返回（20 条主帖）= 5 点数（1 点数 = 1 元以下优惠价请联系客服）。
• 预扣：ceil(请求条数/20) × 5（如 50 条预扣 15 点）；结算按实采量：ceil(实采条数/20) × 5，差值自动返还（如实采 45 条只收 15 点，实采 28 条收 10 点——不满 20 条的零头按一次计）。
• 零结果或失败全额返还：关键词无结果、节点离线超时、风控拦截等，预扣点数全额退还。
• 注册即送 10 免费点数（可采 40 条）。点数不足时提示用户充值；充值或大量购买可享优惠，请联系客服 18722121663 洽谈。

⚠️ 交互协议（agent 必须严格遵守）

本 skill 是确认制一次性任务，不是跑完就完。请按下面的流程驱动对话：

1. 查余额：node cli.js quota 确认点数充足（余额 < 预扣点数会被 3001 拒绝）。
2. 报价确认（必须）：向用户明确以下信息并等用户确认后再提交：
   - 搜索关键词、采集数量（1~500）、排序（默认综合）、笔记类型（默认全部）
   - 预估点数：ceil(数量/20) × 5（例：50 条 → 15 点；120 条 → 30 点）
   - 计费规则：预扣 ceil(N/20)×5，按实采 ceil(M/20)×5 结算退差，零头按一次计，零结果或失败全退
   - 未经用户确认不要执行 submit。
3. 提交并等待：node cli.js submit --keyword "<词>" --count <N> --wait --timeout 600。节点滚动约 3-5 分钟属正常，不要中途重试。
4. 如实汇报结算：结果里的 collected_count（实采条数）、settle_charged（实收点数）、refunded_diff（退还差值）必须如实告知用户（例：「实采 45 条，实收 15 点，退 0 点」/「请求 120 条实采 85 条，实收 25 点，退 5 点」）。
5. 需要文件时导出：node cli.js export <task_id> --wait --out 搜索结果.csv，把 CSV 路径交给用户。

排序说明：--sort 支持 general（综合）/ time_descending（最新）/ popularity_descending（最热）/ comment_descending（最多评论）/ collect_descending（最多收藏）；--note-type 0=全部 / 1=视频 / 2=图文。

前置条件

• 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.0.1","capability":"xhs_search"}}

register — 注册（注册即送 10 点数）

方式一：扫码/链接注册（唯一方式，用户在手机上完成）

node cli.js register --link        # 生成注册二维码/链接
node cli.js register --check --access-token "<上一步下发的串>"   # 用户完成后确认并保存 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
node cli.js login --check --access-token "<上一步下发的串>"

引导话术同 register（把"注册"换成"登录"）。成功后 token 自动保存。

quota — 查询点数

node cli.js quota

{"ok":true,"data":{"quota":10,...}}

submit — 提交搜索采集任务

node cli.js submit --keyword "机油"                          # 默认 50 条, 综合排序, 全部类型
node cli.js submit --keyword "机油" --count 120              # 120 条 (预扣 30 点)
node cli.js submit --keyword "美孚" --count 40 --sort time_descending --note-type 1
node cli.js submit --keyword "机油" --count 50 --wait        # 提交并等待结果 (约 3-5 分钟)
node cli.js submit --keyword "机油" --count 50 --wait --timeout 600 --force

• --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）。
• --wait：等待任务终态再返回（推荐）；--timeout 轮询超时（默认 600s）；--interval 轮询间隔（默认 5s）。
• --force：跳过 24h 相同内容去重强制重提（幂等键混入时间戳）。

--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":0},
   "result":{"keyword":"机油","requested_count":50,"collected_count":45,
             "settle_charged":15,"refunded_diff":0,
             "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>            # 单次查询
node cli.js query <task_id> --wait     # 轮询到终态 (默认 600s 超时)

export — 导出结果 CSV

node cli.js export <task_id> --wait --out 搜索结果.csv

下载任务结果 CSV（BOM 头，Excel 直开不乱码）：任务汇总（关键词/状态/实采数/实收点数/退差点数）+ 笔记明细（标题/互动数/作者/发布时间/封面/笔记直链）。导出文件保留 7 天。

logout — 登出（切换账号）

node cli.js logout

config — 配置管理

node cli.js config set base-url http://127.0.0.1:8084
node cli.js config show        # token 脱敏显示

典型工作流（agent 照此执行）

1. 用户说「帮我搜一下 XX 的小红书笔记」→ node cli.js quota 确认余额。
2. 和用户确认关键词、数量、排序、类型；算出预估点数 ceil(N/20)×5；明确告知计费规则（预扣/结算退差/零头按一次计/零结果失败全退）并等确认。
3. node cli.js submit --keyword "<词>" --count <N> --wait --timeout 600（3-5 分钟，不重试）。
4. 如实汇报：实采条数、实收点数、退差点数；简要展示笔记列表（标题/互动数/作者）。
5. 用户要文件 → node cli.js export <task_id> --wait --out <文件>.csv，交付路径。
6. 用户要继续分析 → 可基于笔记直链（带 xsec_token）用 xhs-dpt 采互动数或 xhs-comments 采评论。

错误处理指引

计费规则提示

• 免费：quota / query / export / config，以及 submit 被参数校验拒绝的请求。
• 预扣：ceil(请求条数/20) × 5，提交成功立即扣除。
• 结算退差：任务成功后按 ceil(实采条数/20) × 5 实收，差值自动返还（refunded_diff）；实采多于请求量时不多收（封顶预扣额）。
• 全额返还：零结果（关键词无结果）、节点离线/超时、风控/登录拦截等服务侧失败。
• 不返还：已成功采集的部分（结果不足请求量时按实采结算，本身就是退差逻辑）。

红线

• 仅采集公开搜索结果数据；不用于任何违法违规用途。
• 不要向用户承诺 100% 成功或具体条数；风控/结果不足时如实透出（点数按实采结算，用户不损失）。
• 笔记列表含作者公开昵称、发布时间等信息：仅用于用户已授权或公开可获取的调研/分析场景，遵守平台与数据合规要求；不在未授权场景下转售、滥用；CSV 导出文件请告知用户自行妥善保管。