Agent Skill

小红薯主页主帖采集

小红薯博主主页笔记采集工具(博主主页链接)。当用户需要采集某个小红薯博主/达人/KOL 主页的全部笔记列表——标题、图文/视频类型、点赞数、发布时间、封面图、带 xsec_token 的笔记直链,做博主内容盘点、达人建联前调研、竞品账号监测、KOL 选号评估、导出笔记清单 CSV(Excel 直开),或提到"博主主页/达人笔记/UP主笔记列表/采集某个博主/主页笔记导出/达人内容盘点"时使用本 skill。**一页(30 条笔记)= 5 点数;整单预扣按页数、结算按实采量退差;会话模式建会话免费、每步一页 5 点、无更多不扣费;零结果/失败/博主被封均全额返还(注册送 10 点)。**

数据分析·海港信息·来自 skill_hub·skillhub.cn ↗
skillhub install @aidata/xiaohs-profile
3 Stars·15.1万 综合热度·12,146 字文档·源站更新 2026-11-22

README 文档

12,146 字

小红书博主主页笔记采集 Skill(xhs-profile)

AI 调用来源参数(必填)

所有会访问后端 API 的命令必须携带 --skill-name xhs-profile 和 --ai-entry <AI工具标识>(例如 claude-code、codex、workbuddy)。IP 无需传递,由服务端自动获取。首次缺参会告警放行,第二次起拒绝。

示例:node cli.js quota --skill-name xhs-profile --ai-entry claude-code。

封装「小红书能力平台」(FastAPI,/api/v1)的 CLI,供 AI agent 调用。输入博主主页链接,平台调度内网浏览器节点以真人滚动方式打开博主主页,SSR 首屏解析 + 拦截官方列表接口响应,采集该博主的笔记列表。

  • 能采什么:博主主页的笔记明细(title 标题、notetype 视频/图文、likedcount 点赞数、publishtime 发布时间、coverurl 封面图、noteurl 带 xsectoken 的笔记直链、sticky 是否置顶)。
  • 适用场景:博主内容盘点、达人建联前调研、竞品账号监测、KOL 选号评估、批量取博主笔记链接(后续可接 xhs-dpt 采完整互动数 / xhs-comments 采评论)。
  • 采集方式:内网浏览器节点拟人滚动博主主页 + SSR 首屏解析 + 拦截官方接口(不调签名 API);列表接口只带点赞数,不含收藏/评论数(需要完整互动数时,用采到的笔记直链走 xhs-dpt 逐篇采集)。
  • 限制:每任务 1 个博主;整单 1~10 页(每页 30 条);会话模式不限页数、一页一页采;节点滚动每页约 5-10 秒。
  • 采集由平台调度内网浏览器节点完成(节点登录态在浏览器端人工维护,平台不持有账号)。
  • 客户端是零依赖 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-profile --ai-entry <ai-entry>(不传 --yuan 默认 10 元;可加 --channel alipay 或 --channel wechat)。
  • 不想自动充值:设环境变量 XHSNOAUTO_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 点数。
  • 一页(30 条笔记)= 1 点数。
  • 整单模式(collect):预扣 页数(如 3 页预扣 3 点);结算按实采量:ceil(实采条数/30),差值自动返还(如 3 页只实采 45 条收 2 点——不满 30 条的零头按一页计)。
  • 会话模式(session):建会话免费;每步进一页 = 1 点;已没有更多笔记时步进返回 no_more 不扣费;博主昵称和笔记总数在第一个付费步返回。
  • 全额返还:博主暂无笔记(零结果)、节点离线超时、风控拦截、博主被封或主页不可见,点数全额退还。
  • 注册即送 10 免费点数(可采 2 页 / 60 条)。点数不足时提示用户充值;充值或大量购买可享优惠,请联系客服 18722121663 洽谈。

⚠️ 交互协议(agent 必须严格遵守)

本 skill 支持两种模式,按用户需求选择:

整单模式(用户明确要采 N 页 / 一次性采完)

  1. 查余额:node cli.js quota --skill-name xhs-profile --ai-entry <ai-entry> 确认点数充足(余额 < 预扣点数会被 3001 拒绝)。
  2. 报价确认(必须):向用户明确以下信息并等用户确认后再提交:
  • 博主主页链接、采集页数(1~10 页,每页 30 条)
  • 预估点数:页数(例:3 页 → 3 点)
  • 计费规则:预扣 页数,按实采 ceil(条数/30) 结算退差,零头按一页计,零结果/失败/博主被封全退
  • 未经用户确认不要执行 collect。
  1. 提交并等待:node cli.js collect --url "<主页链接>" --pages <N> --wait --timeout 600 --skill-name xhs-profile --ai-entry <ai-entry>。节点滚动每页约 5-10 秒,不要中途重试。
  2. 如实汇报结算:结果里的 collectedcount(实采条数)、settlecharged(实收点数)、refunded_diff(退还差值)必须如实告知用户。
  3. 需要文件时导出:node cli.js export <task_id> --wait --out 博主笔记.csv --skill-name xhs-profile --ai-entry <ai-entry>,把 CSV 路径交给用户。

会话模式(用户想一页一页看结果再决定要不要继续)

  1. 建会话(免费):node cli.js session start --url "<主页链接>" --skill-name xhs-profile --ai-entry <ai-entry> → 拿到 session_id。
  2. 逐页步进:每次 node cli.js session step <sessionid> --skill-name xhs-profile --ai-entry <ai-entry> 采一页(30 条 = 1 点),步进前向用户确认扣 1 点;返回本页笔记 + hasmore + 博主昵称/笔记总数(首步)+ 余额。
  3. 到底自动免费:no_more: true 表示已采完,不扣费;引导用户 session finish 结束会话释放节点。
  4. 随时拉取/导出:session notes <sessionid> 免费拉已采笔记;session export <sessionid> --out 文件.csv 导出累计结果。
  5. 注意:会话空闲 3 分钟自动过期(节点释放),之后需重新建会话(已采数据仍在,session notes/export 仍可拉取)。

链接要求:--url 接受 https://www.xiaohongshu.com/user/profile/<id> 主页直链(可带 xsec_token 参数)或 xhslink 短链;不接受笔记链接(笔记互动数请用 xhs-dpt,评论请用 xhs-comments)。

前置条件

  • Node.js ≥ 18(使用内置 fetch,零 npm 依赖)。
  • 不注册不登录没有任何点数:所有接口都需要 token,10 免费点数在注册成功后发放到账号。
  • 首次使用需先 register --link(注册即送 10 点数;用户手机微信扫码/点链接在网页完成,页面自带图形+短信验证码)或 login --link(已有账号)。成功后 token 自动保存,后续调用免输。
  • 配置文件(含 token)存放于用户级目录 ~/.xhs-platform/config.json(升级/重装 skill 不丢配置)。可用环境变量 XHSCONFIGPATH 覆盖(测试隔离用)。
  • 安全策略:登录和注册(发短信)每次都强制图形验证码,终端无法展示,所以一律走 --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 其它业务错误。
  • collect --wait 单次最长 10 分钟(默认 600s 超时),属正常现象,不要中途重试。

命令清单

version — 查看版本与安装信息

node cli.js version
{"ok":true,"data":{"name":"xhs-profile","version":"2.0.1","capability":"xhs_profile"}}

register — 注册(注册即送 10 点数)

方式一:扫码/链接注册(唯一方式,用户在手机上完成)

node cli.js register --link --skill-name xhs-profile --ai-entry <ai-entry>        # 生成注册二维码/链接
node cli.js register --check --access-token "<上一步下发的串>" --skill-name xhs-profile --ai-entry <ai-entry>   # 用户完成后确认并保存 token

register --link 的 stdout 返回 qrurl / registerurl / 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-profile --ai-entry <ai-entry>
node cli.js login --check --access-token "<上一步下发的串>" --skill-name xhs-profile --ai-entry <ai-entry>

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

quota — 查询点数

node cli.js quota --skill-name xhs-profile --ai-entry <ai-entry>
{"ok":true,"data":{"quota":10,...}}

collect — 提交整单主页采集任务

node cli.js collect --url "https://www.xiaohongshu.com/user/profile/5b4c369611be104d815b1ba9" --skill-name xhs-profile --ai-entry <ai-entry>                 # 默认 1 页 (30 条)
node cli.js collect --url "<主页链接>" --pages 3 --skill-name xhs-profile --ai-entry <ai-entry>                    # 3 页 (约 90 条, 预扣 3 点)
node cli.js collect --url "<主页链接>" --pages 3 --wait --skill-name xhs-profile --ai-entry <ai-entry>             # 提交并等待结果
node cli.js collect --url "<主页链接>" --pages 3 --wait --timeout 600 --force --skill-name xhs-profile --ai-entry <ai-entry>
  • --url:博主主页链接(/user/profile/<id> 直链或 xhslink 短链;填笔记链接会被拒绝)。
  • --pages:采集页数 1~10(默认 1,每页 30 条)。
  • --wait:等待任务终态再返回(推荐);--timeout 轮询超时(默认 600s);--interval 轮询间隔(默认 5s)。
  • --force:已失效(后端无去重,重提即新任务);保留仅为兼容旧命令行,可省略。

--wait 完成后的输出示例:

{"ok":true,"data":{"task_id":"t_20261012_ab12cd34","capability":"xhs_profile","status":"done",
 "success_count":1,"fail_count":0,"charged_quota":15,"refunded_quota":5,
 "items":[{"id":"1","payload":{"profile_url":"https://...","pages":3},
   "result":{"profile_url":"https://...","blogger_id":"5b4c...","blogger_nickname":"某博主",
             "requested_pages":3,"collected_count":62,
             "settle_charged":10,"refunded_diff":5,
             "notes":[{"note_id":"64ab...","title":"秋季穿搭合集",
                        "note_type":"normal","liked_count":"1.2万","publish_time":"2026-09-15",
                        "sticky":false,
                        "cover_url":"https://sns-webpic-qc.xhscdn.com/...",
                        "url":"https://www.xiaohongshu.com/explore/64ab...?xsec_token=...&xsec_source=pc_user"},
                       ...]},
   "status":"success"}]}}

拿到结果后必须把 collectedcount / settlecharged / refunded_diff 如实汇报给用户(见「交互协议」)。

query — 查询任务状态与结果

node cli.js query <task_id> --skill-name xhs-profile --ai-entry <ai-entry>            # 单次查询
node cli.js query <task_id> --wait --skill-name xhs-profile --ai-entry <ai-entry>     # 轮询到终态 (默认 600s 超时)

export — 导出整单结果 CSV

node cli.js export <task_id> --wait --out 博主笔记.csv --skill-name xhs-profile --ai-entry <ai-entry>
node cli.js session watch <id> --skill-name xhs-profile --ai-entry <ai-entry>
node cli.js session inbox --days 7 --skill-name xhs-profile --ai-entry <ai-entry>

下载任务结果 CSV(BOM 头,Excel 直开不乱码):任务汇总(主页链接/博主/状态/请求页数/实采数/实收点数/退差点数)+ 笔记明细(标题/类型/点赞数/发布时间/置顶/封面/笔记直链)。导出文件保留 7 天。

session — 会话模式(一页一页采)

node cli.js session start --url "<主页链接>" --skill-name xhs-profile --ai-entry <ai-entry>     # 建会话 (免费), 返回 session_id
node cli.js session step <session_id> --skill-name xhs-profile --ai-entry <ai-entry>            # 步进一页 (30 条 = 1 点; no_more 不扣费)
node cli.js session status <session_id> --skill-name xhs-profile --ai-entry <ai-entry>          # 会话状态/累计统计/余额
node cli.js session list [--status active] --skill-name xhs-profile --ai-entry <ai-entry>       # 会话列表
node cli.js session notes <session_id> [--page 2] --skill-name xhs-profile --ai-entry <ai-entry>  # 已采笔记分页拉取 (免费)
node cli.js session export <session_id> --out 博主笔记.csv --skill-name xhs-profile --ai-entry <ai-entry>  # 累计结果 CSV (免费)
node cli.js session finish <session_id> --skill-name xhs-profile --ai-entry <ai-entry>          # 主动结束 (释放节点)

session step 输出示例:

{"ok":true,"data":{"no_more":false,"type":"page","page_no":1,
 "notes":[{"note_id":"64ab...","title":"...","note_type":"video","liked_count":"890",
           "publish_time":"2026-10-01","sticky":false,"cover_url":"...","url":"https://..."},...],
 "has_more":true,"nickname":"某博主","note_total":"135",
 "pages_collected":1,"notes_collected":30,"charged_steps":1,"quota_balance":5}}
  • 首步返回 nickname(博主昵称)和 note_total(笔记总数,供估算总页数)。
  • hasmore: false 后再次 step 返回 nomore: true,不扣费。
  • 会话空闲 3 分钟自动过期;session finish 主动结束(幂等)。

logout — 登出(切换账号)

node cli.js logout --skill-name xhs-profile --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 照此执行)

  1. 用户说「帮我采集这个博主的主页笔记」→ node cli.js quota --skill-name xhs-profile --ai-entry <ai-entry> 确认余额。
  2. 和用户确认模式:
  • 知道要采多少 → 整单:确认页数,算预估点数 页数,明确告知计费规则(预扣/结算退差/零头按一页计/零结果失败被封全退)并等确认 → collect --url <链接> --pages N --wait。
  • 想边采边看 → 会话:session start(免费)→ 逐次 session step(每步前确认扣 1 点)→ no_more 或用户说停 → session finish。
  1. 如实汇报:实采条数、实收点数、退差点数;简要展示笔记列表(标题/点赞数/发布时间)。
  2. 用户要文件 → export <taskid> --wait --out <文件>.csv 或 session export <sessionid> --out <文件>.csv,交付路径。
  3. 用户要继续分析 → 基于笔记直链(带 xsec_token)用 xhs-dpt 采完整互动数(含收藏/评论/分享数)或 xhs-comments 采评论。
  4. 会话过期不等于失败:step 拿到 3006 时结果已随错误输出带回,或跑 watch / inbox 取回,把已采条数 + CSV 路径交给用户;要接着采只能重新 session start 建会话。

错误处理指引

code含义agent 下一步
1001参数错误 / 链接无效(非主页链接)检查链接形态;笔记链接引导用 xhs-dpt / xhs-comments(退出码 1)
1002 / 1003未登录 / token 失效未注册走 register --link(送 10 点数),已有账号走 login --link;完成后 --check(退出码 2)
LOGINPENDING / LOGINEXPIRED用户未完成 / 会话过期提醒用户完成扫码后重试 --check,或重新 --link(退出码 2)
2003需要图形验证码终端无法完成,统一走 --link;仍无法解决拨打客服电话 18722121663
3001点数不足提示用户拨打客服电话 18722121663 充值,不要重试(退出码 3)
3006会话不存在/已过期/已结束已采结果会自动带在错误输出的 data 里(collected / notescount / notespreview / csv_path)→ 直接把摘要和 CSV 交给用户;想提前拿结果用 watch,回来时用 inbox;继续采集需重新 start
TIMEOUT等待超时(任务仍在跑)任务未丢:稍后 query <task_id> 查终态;预扣仍在,终态后按实采结算
5001采集服务暂不可用(节点回传超时/风控)点数已全额返还;稍后重试;持续不可用提示联系客服 18722121663
5001(博主被封/主页不可见)「该账户违反《社区规范》其内容无法查看」或主页 404点数已全额返还;如实告知用户该博主无法采集,不要重试同一链接
4290触发限流稍等后重试(Retry-After)
NETWORK_ERROR网络/服务不可达检查 config show 的 base_url(退出码 4)

计费规则提示

  • 免费:quota / query / session status|list|notes|export / config,以及参数校验拒绝的请求;会话 session start 建会话免费;no_more 步进免费。
  • 预扣(整单):页数,提交成功立即扣除。
  • 结算退差(整单):任务成功后按 ceil(实采条数/30) 实收,差值自动返还(refunded_diff);实采多于请求量时不多收(封顶预扣额)。
  • 按步扣费(会话):每次成功步进一页扣 1 点,扣费前会检查是否还有下一页(没有则免费返回 no_more)。
  • 全额返还:零结果(博主暂无笔记)、节点离线/超时、风控/登录拦截、博主被封或主页不可见。
  • 置顶笔记:置顶笔记可能跨页重复出现,已自动去重,实采条数以去重后为准(退差随之准确)。

红线

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

会话结束/过期:必须主动把结果交给用户

会话有 3 分钟空闲上限(步进中断兜底 15 分钟)。过期/结束不是失败:已采数据仍然有效、仍然能读能导,服务端不会推送,必须由你主动交给用户。三条路,按场景选:

  1. step 撞上 code=3006:CLI 已把结果收敛进错误输出的 data(status / expiredreason / collected / notescount / notespreview / csvpath),退出码 5。直接把这份摘要 + CSV 路径告诉用户,不要只回一句「会话已结束」。
  2. 用户说「我先忙,等它采完」:跑 session watch <id> 守候,过期那一刻自动导出并输出结果;--interval(默认 10s)控制轮询间隔,--max-wait(默认 1800s)到点返回 watching_timeout:true + 当前进度。
  3. 用户隔一段时间回来:先跑 session inbox,列出近 7 天「已结束但还没播报过」的笔记会话(本地 ~/.xhs-platform/sessioninboxseen.json 去重,最多 10 条),有就主动告知标题/状态/已采条数/CSV 路径。

watch / inbox 都不扣点。要继续采集只能重新 session start 建新会话(原会话已采数据仍可用 session notes <id> / export 读取)。

同分类其他技能

查看全部 ›