Files
creator-hub/docs/research/xhs-all-in-one.md
T

28 KiB
Raw Blame History

XHS_ALL_IN_ONE 小红书能力吸收与落地研究

研究日期:2026-09-14 上游仓库:https://github.com/cv-cat/XHS_ALL_IN_ONE 研究快照:e86f82bmaster) 研究方式:只读检查源码、提交历史与公开 Issues;未向小红书真实账号发起请求,以下不等同于平台能力验收。 当前结论:本文形成小红书实现约束;main 已接入受限只读适配器,但未复制上游代码、签名脚本、Cookie 或指纹数据。

1. 结论先行

这个仓库最值得 CreatorHub 吸收的不是它的逆向接口代码,而是它暴露出来的平台适配边界、请求状态分类、数据标准化和失败场景

判断 结论
能否直接作为 CreatorHub 的小红书 SDK 不能。它依赖 Web 私有接口、动态签名、设备/浏览器状态和服务端下发程序,且公开 Issues 持续出现 406、461、登录失败和账号封禁反馈。
能否吸收工程做法 可以。重点吸收适配器分层、原始响应保留、xsec_token/xsec_source 端到端保留、评论父子关系、媒体处理分步状态和登录态健康检查。
能否直接复制签名/指纹/curl_cffi 方案 暂不可以。这属于高维护、强平台耦合和潜在合规风险路径;先取得真实平台能力证据,再决定是否需要平台专用实现。
能否证明小红书已经支持 CreatorHub 要求的事件监听 不能。上游主要是主动请求式读取和发布,没有解决“自有账号互动/私信事件监听、断连恢复、稳定事件 ID”的问题。
能否直接复制上游代码 当前不能确认。README 声称 MIT,但 GitHub API 的 licensenull,研究快照中也没有可读的 LICENSE 文件;在许可证和逆向产物来源确认前不复制代码。

**推荐落地顺序:**先做小红书只读能力和证据链,再做素材处理;写操作和事件监听分别独立验收,不能因为上游有发布接口就宣称 CreatorHub 已具备发布或自动响应能力。

1.1 当前实现边界

  • CreatorHub 当前已接入小红书只读 collector、详情/搜索/作品/一级评论读取、分享链接解析、原始 payload 保存、受限 gateway 路由和控制面平台分派;写操作与事件监听仍未接入。
  • 小红书竞品主页输入会校验稳定账号标识并保留主页中的 xsec_token/xsec_source;作品详情可通过受限浏览器解析官方分享短链。
  • internal/creator/collection.go 的分页、窗口、checkpoint 和 lease 模型可作为后续适配的复用边界,但不能证明小红书平台能力。

**未完成的真实能力验收:**私有接口签名是否能由浏览器当前会话完成、真实 UID/作品/评论分页、媒体下载、写操作和事件监听仍需真实小红书环境分别验证。HTTP 200、离线 fixture 和本地单元测试不能替代这些证据。

2. 上游实际做了什么

2.1 已能从源码确认的能力

能力 上游实现 对 CreatorHub 的价值 证据
PC 端搜索笔记 组装搜索请求、分页参数、排序和筛选,使用 /api/sns/web/v2/search/notes 可作为小红书只读采集字段和分页适配的参考 apis/xhs_pc_apis.pysearch_notesearch_some_note
笔记详情 从链接提取 note ID、xsec_tokenxsec_source,调用 feed 详情接口 提醒我们不能只保存 note ID;分享链接中的访问上下文也可能是请求材料 apis/xhs_pc_apis.pyget_note_infobackend/app/api/platforms/xhs/pc.py_note_url_normalize_detail_payload
用户作品读取 user_posted 分页读取用户作品 可作为竞品账号“按主页读取作品”的候选平台能力 apis/xhs_pc_apis.pyget_user_note_infoget_user_all_notes
一级/二级评论 分别调用 comment page 和 sub-comment page,后端递归扁平化并保留父评论 ID 可吸收评论层级模型;CreatorHub 当前需求首先要求一级评论,但应保留父子关系扩展位 apis/xhs_pc_apis.pyget_note_out_commentget_note_inner_commentbackend/app/api/platforms/xhs/pc.py_flatten_comments
图文/视频媒体上传 先申请上传许可,再向 /spectrum/{file_id} 上传;视频返回 X-Ros-Video-Id 上传许可、token、过期时间和实际上传结果应分步记录 apis/xhs_creator_apis.pyget_fileIdsupload_media
Creator 发布 话题/地点查询、媒体上传、图文发布;视频还涉及封面和转码查询 说明写操作不是一个 HTTP 请求,需要独立状态和结果证据 apis/xhs_creator_apis.pyget_topicget_location_infopost_note
登录 支持 Cookie、二维码和手机号路径,维护多域 Cookie 和安全初始化 可借鉴登录态与业务账号状态分离,以及登录后再次调用 user-info 验收 xhs_utils/xhs_pc/auth.pyapis/xhs_pc_login_apis.pyapis/xhs_creator_login_apis.py
监控/定时/草稿 有关键词、账号、品牌、笔记 URL 监控、快照、定时发布和 AI 草稿 可作为产品功能的反例和字段参考;不能当作已验证生产能力 backend/app/api/platforms/xhs/monitoring.pybackend/app/services/scheduler_service.py
原始响应与标准字段并存 标准化标题、正文、作者、媒体、指标,同时保留 raw/raw_json 适应平台字段变化时可重新解析历史数据,不必再次请求 backend/app/api/platforms/xhs/pc.pybackend/app/api/platforms/xhs/crawl.py

2.2 README 宣称但不能直接视为已实现

上游 README 的完整功能清单很大,包含数据采集、内容管理、AI 改写、图片处理、发布、定时和多账号健康检查。但代码中存在明显的 demo/placeholder

  • backend/app/api/platforms/xhs/pc.pysearch_users() 返回固定 demo-user
  • 同文件的 user_notes() 返回 sample_notes(),不是用户作品真实读取。
  • homefeed_channels()homefeed_recommend() 返回固定示例。
  • 监控、定时、AI 等业务接口存在,但不等于真实平台链路已成功,也不等于数据持续更新正确。

因此本研究把“README 功能清单”标为文档宣称,把上表源码路径标为源码存在;只有真实账号、真实响应和失败恢复证据才能升级为 CreatorHub 的“已支持”。

3. 上游已经暴露的关键坑

3.1 请求签名是动态协议,不是一个固定函数

源码同时维护:

  • 本地生成的 a1b1X-sX-tX-S-Common、trace ID、xy-direction、搜索 ID
  • 服务端下发或依赖会话的 _dslwebsectigasec_poison_idgid、登录 Cookie
  • PC 与 Creator 分开的 RAP 指纹模板;
  • MNS 分档、会话计数、设备状态、Cookie 域和请求头顺序;
  • curl_cffi Chrome impersonation、HTTP/2 和关闭默认 headers 的传输行为。

对应源码:

  • xhs_utils/xhs_pc/auth.py
  • xhs_utils/xhs_pc/state.py
  • xhs_utils/xhs_pc/params.py
  • xhs_utils/xhs_core/http.py
  • xhs_utils/xhs_creator/auth.py
  • xhs_utils/xhs_creator/params.py

**可吸收的原则:**把每个请求材料标注为“本地可计算、服务端签发、用户交互、会话状态”四类;服务端签发材料不能当静态配置,登录 Cookie 不能当作永久登录证明。

**不应吸收的做法:**把逆向签名、指纹模板或固定 Chrome 版本包装成长期稳定 SDK。它们应被视为平台专用、可替换、需要真实证据的适配层。

3.2 PC 和 Creator 是两套不同链路

上游同时维护 xhs_pc_*xhs_creator_* 两套认证、请求参数、Cookie 域、RAP 模板和业务 API。Creator 发布请求使用独立指纹模板;PC homefeed 使用的模板不能直接拿去发布,否则会被服务端以参数错误拒绝。

对 CreatorHub 的约束:

  • platform=xhs 不足以决定适配方式,还要区分读取/登录上下文和 Creator 写入上下文。
  • 不复用“PC 读取成功”作为 Creator 发布成功依据。
  • 账号登录状态、业务账号状态和浏览器环境状态必须分别保存。

Creator 登录实现明确分为匿名会话、honeypot、DS 程序、安全 Cookie、websectigagid、CAS 二维码/手机号登录和最终 user-info 验收。部分 _dsl 由服务端拉取并短时缓存;代码还记录不同 CDN 节点可能导致时间锚点不同。

这说明以下做法不可靠:

  • 用本机时间简单替代服务端时间锚点;
  • 只保存 a1 或网页 document.cookie
  • 只判断二维码接口 HTTP 200 就认为登录完成;
  • 把一个匿名设备会话的安全材料复制给另一个账号。

3.4 406 不是普通网络失败,重试边界取决于会话

上游源码区分了两类 406

  • 某些 customer 域请求被记录为按请求概率拒绝,可以在同一会话内有限重发;
  • Creator 登录/发布场景的另一些拒绝会标记整个匿名设备会话,需要重建 a1/webId、Cookie store 和连接,而不是重复发送原请求。

公开 Issue 也说明该判断会随服务端变化:

**CreatorHub 做法:**只对已证明是安全的、幂等的读取请求使用有限重试;写操作遇到 406 不得用重试掩盖不确定结果。已发送但缺乏确认时标为 uncertain,不自动补发。

3.5 461 可能来自流程变化,不一定是账号失效

Issue #25 记录:PC 二维码登录的 /api/sns/web/v1/login/activate 稳定返回 HTTP 461;前置安全接口均为 200。同一机器在旧提交 2819d74 中通过 webprofile 获取 gid 的流程可以继续生成二维码,算法更新后反而失败。

**可吸收的排查方式:**保留“最后成功提交/算法版本、请求阶段、HTTP 状态、响应 code、Cookie key、是否已拿到 gid”的结构化诊断,不把 461 直接归类为 Cookie 过期或账号封禁。

3.6 发布 payload 的微小差异会造成业务错误

apis/xhs_creator_apis.py 记录了几个具体失败点:

  • 没有地点时必须省略 common.post_loc,发送空对象 {} 可能返回 -9059
  • 话题需要先查到平台对象,不能只把用户输入字符串塞进 payload;
  • Creator 发布需要 Creator 专用 x-rap-param 指纹;
  • 视频上传成功后还涉及封面、异步转码和发布时机。

这类坑值得吸收为契约测试和失败证据,不值得吸收为“万能兼容字段清洗”。平台响应字段变化时应让适配器明确失败并记录原始响应。

3.7 视频转码失败不应被当作成功前置条件

上游视频发布分支在转码查询不可用时会 warning,然后直接继续发布;这是该仓库的取舍,不适合 CreatorHub 当前的结果模型。CreatorHub 已要求区分成功、失败和结果不明,不能把“转码状态无法确认”转换成“可以继续发布”。

3.8 上游的分页循环缺少 CreatorHub 所需的完整边界

上游的 get_user_all_notes()、评论聚合等循环主要依赖 has_more 和返回 cursor,源码没有统一的重复 cursor 检测、最大页数和 checkpoint/lease 机制。

CreatorHub 已有更严格的 internal/creator/collection.go

  • cursor 缺失、重复、不前进会失败;
  • 最大 100 页硬边界;
  • 采集窗口固定,不因分页时间变化而滑动;
  • 有 checkpoint、lease 和中断后续采基础。

**结论:**分页保护直接复用 CreatorHub 现有模型,不复制上游的简单 while True

3.9 媒体下载实现过于宽松

backend/app/services/asset_downloader.py

  • 仅检查 URL 前缀、HTTP 状态和内容长度;
  • 使用空 Referer
  • 不验证响应 MIME 与实际文件类型;
  • 不限制文件大小、不做断点、不保留明确失败状态;
  • 异常统一 warning 后返回 None,上层仍可能把笔记保存成“成功”。

**CreatorHub 不采用:**下载失败静默变成空路径。使用现有 internal/creator/creator_material.go 的分步状态、原子文件、大小限制、HTML 拒绝和失败步骤记录。

3.10 账号风控风险是真实运营风险

公开 Issue #13 及评论中,多名用户反馈使用工具发布后出现脚本操作警告、封禁;反馈包括视频发布后封号和“贵重账号慎用”。这些是用户报告,不是平台官方因果证明,但足以作为高风险信号。

CreatorHub 不应承诺“稳定”“不封号”或“无法识别”,也不应通过更换指纹、随机重试或隐藏错误来规避风控。真实写操作必须:

  1. 使用者明确授权;
  2. 登录环境和账号身份再次核对;
  3. 目标、文案、媒体和平台返回证据可追溯;
  4. 失败/不确定停止,不自动换账号、换代理或补发。

3.11 前端 refresh 递归和部署依赖也值得记录

  • Issue #23:前端 401 拦截器把 /auth/refresh 自身再次送入 refresh,导致登录页无限 checking。通用经验是 refresh 请求必须有明确标记,失败只清理一次并回到登录页。
  • Issue #22Debian Trixie 移除了 libgl1-mesa-glx,Docker 构建失败。不要固定过时系统包名,镜像构建要在当前基础镜像上实际验证。

这两项不是 CreatorHub 当前小红书业务核心,但可作为前端会话恢复和 Compose 构建检查的回归用例。

4. 对 CreatorHub 的吸收清单

4.1 现在就吸收:不增加平台耦合

吸收项 CreatorHub 落点 具体要求
平台适配器与业务逻辑分离 新增小红书适配时沿用 internal/platform/douyin 的边界,业务层不直接拼平台请求 读取、登录、媒体、动作、事件各自有清晰接口;不把上游 Python SDK 直接嵌进控制面
原始响应 + 标准字段 internal/creator 的 Work/Comment/Material 数据 保存原始平台 payload、来源链接、采集时间和标准化结果;字段变化先保原文再调整解析
xsec_token/xsec_source 端到端保留 作品来源/平台适配输入模型 详情链接、搜索结果和后续详情请求不得丢失访问上下文;没有 token 时不得猜测或拼造
评论父子关系 Comment 入库字段扩展时保留 parent_comment_id 当前业务先采一级评论,平台返回子评论时不丢弃层级;不要把昵称当用户 ID
指标三态 Work 指标和采集报告 0 只表示平台明确返回 0;缺失使用“不可获取/待采集”,不把缺失填成 0
分页安全 直接复用 internal/creator/collection.go 统一做 cursor 缺失、重复、不前进、页数上限和 checkpoint/lease,不复制上游无限循环
媒体分步处理 internal/creator/creator_material.go 下载、提音、转写、仿写分别记录状态、产物、失败步骤;不把整条任务压成一个 boolean
登录态健康检查 账号登录状态与动作前身份核对 Cookie 存在不等于登录有效;每次写操作前核对实际 UID、环境和目标
证据分级 ActionResult、Task、E2E evidence 区分源码存在、接口返回、业务确认、失败、结果不明;HTTP 200 不自动算成功
领域错误可观测 网关/控制面边界 记录平台、账号、环境、请求阶段、外部状态、业务 code、响应摘要和 trace;不在底层静默吞异常

4.2 只能带着改造吸收

上游做法 改造后才可用 原因
curl_cffi Chrome impersonation 仅在真实平台证据证明普通浏览器网关无法满足时评审引入 新增依赖和维护面大,不能先把私有签名客户端当默认架构
_dsl/websectiga 缓存 设计为有来源、TTL、版本和失效原因的短生命周期运行时材料 服务端程序可能轮换,不能写死或永久缓存
406 有限重试 只用于已证明幂等且不会产生写副作用的阶段 写操作重试会造成重复发布或掩盖不确定结果
Creator 上传许可 建立上传许可、过期时间、上传结果、媒体校验的状态机 token 过期和上传成功不是同一状态
视频封面/转码查询 转码未确认时状态为 pending/uncertain,禁止自动跳过门禁发布 上游“warning 后继续”不符合 CreatorHub 结果约束
监控/定时服务 使用 CreatorHub 既有计划、lease、任务和证据模型 上游 scheduler 在应用进程内运行,容易重复执行和丢失任务边界

4.3 明确不吸收

  • 复制或改造上游逆向签名 JavaScript、RAP 指纹模板、设备指纹模板、websectiga 执行器。
  • 固定 Chrome/Web build、固定 MNS 环境值,并把它们当作永久配置。
  • 通过重试 406/461 规避平台拒绝。
  • 把 Cookie 导入当作 CreatorHub 的生产登录方案;当前需求是用户在可见环境人工登录,系统核对身份。
  • 用普通翻页 cursor、昵称、头像、时间或内容哈希猜事件唯一 ID。
  • 用上游主动读取接口代替自有账号互动/私信事件监听。
  • 采用空 Referer 下载、内容长度阈值代替媒体真实性校验。
  • 采用上游固定 demo 返回或 README 清单作为功能回退。
  • 直接采用 Ant Design、lucide-react 等前端体系;CreatorHub 保持 shadcn/ui、Tailwind 和 RemixIcon。
  • 直接把上游 AI 自动改写、随机选笔记和定时发布流程当作本期业务。

5. 与当前 CreatorHub 的对照

5.1 已有基础,应直接复用

  • internal/creator/models.go:已有平台、作品、评论、素材、事件、策略和动作结果模型。
  • internal/creator/collection.go:已有分页边界、固定 UTC 窗口、checkpoint、lease 和续采。
  • internal/creator/content.go:已有竞品导入、启停、作品 upsert 和来源关联。
  • internal/creator/actions.go:已有事件永久去重、策略顺序、同 UID 冷却,以及 AI 失败/结果不明不补发。
  • cmd/control-plane/creator.go:已有写操作前身份核对、目标映射和结果证据保存。
  • cmd/control-plane/creator_material.go:已有人工选取、原子媒体文件、大小/HTML 校验、ffprobe/ffmpeg 和显式转写失败步骤。
  • cmd/control-plane/creator_events.gobrowser_gateway/platform/douyin.py:已有监听代际、baseline、gap、断连恢复、delivery ACK/retry 的抖音实现;小红书不能直接沿用为已验证能力。
  • docs/plan01.md:已明确先抖音后小红书、逐平台真实验收,以及读取/写入/事件的成功、失败、不明边界。

5.2 当前小红书缺口

当前已有小红书只读代码适配器和 gateway 路由,但尚未完成真实账号验收。不能因为 platform=xhs 可登记、代码测试通过或页面可打开,就宣称以下能力已经在生产环境可用:

  • 人工登录后的实际 UID 核对;
  • 主页/分享链接解析和稳定账号标识;
  • 作品和一级评论完整分页;
  • 30 天窗口、checkpoint 续采和指标计划;
  • 媒体下载、提音、转写;
  • 评论、点赞、关注、转发、私信写操作;
  • 自有账号互动和私信事件监听;
  • 断连恢复、稳定事件 ID、baseline 和缺口证据。

5.3 上游没有解决、CreatorHub 仍必须独立验收

  1. 事件监听:上游的搜索/评论/主页接口是主动读取,不证明平台会推送稳定事件,也没有跨重启事件身份闭环。
  2. 目标身份:读取到评论不等于能拿到可用于私信/关注的稳定互动者 UID。
  3. 公开数据完整性:第一页或当前接口返回不等于最近 30 天完整作品/评论。
  4. 媒体地址寿命:返回视频/图片 URL 不等于可下载、可长期复用或可提取音轨。
  5. 写操作结果:上传成功、发布请求返回和平台实际可见是不同证据层级。
  6. 账号风险:开源实现能跑不等于账号可安全长期运营。

6. 建议的落地阶段

XHS-G0:冻结能力矩阵和证据格式

先按平台能力单独建立小红书矩阵,不复制抖音结论。每一项记录:

  • 账号/环境/代理/登录方式;
  • 平台稳定 UID、作品 ID、评论 ID、互动者 UID 是否存在;
  • 请求阶段、平台时间、系统接收时间、原始响应摘要;
  • 成功、失败、结果不明或数据缺失;
  • 是否可跨重连/重启恢复;
  • 是否允许进入自动响应。

小红书事件如果无法证明稳定事件 ID、互动者 UID、目标作品/评论和恢复边界,自动响应保持阻塞。

XHS-G1:只读连接器

只实现最小纵向切片:

  1. 人工登录并核对账号 UID
  2. 输入主页链接或作品分享链接,解析并要求用户确认;
  3. 读取一页作品和详情;
  4. 读取超过一页的作品和一级评论;
  5. 保存原始 payload、原始链接、xsec_token/xsec_source(若平台提供)和标准字段;
  6. 证明固定 30 天窗口、分页不重复、cursor 不前进会失败、重启可续采。

这一阶段不做签名引擎复制、不做自动登录、不做事件监听、不做自动动作。

XHS-G2:素材处理

在 G1 取得真实可用媒体地址后,接入现有人工选取链路:

  • 下载原始媒体并做大小/MIME/文件真实性校验;
  • 无视频、无音轨、无语音、下载失败分别记录;
  • 提取音轨、转写、仿写分别产生状态和产物;
  • AI 失败和转写失败不得用原文或空文本冒充成功。

XHS-G3:人工写操作

仅在每个动作分别取得真实证据后实现平台专用 adapter:

  • 回复评论;
  • 点赞评论/作品;
  • 关注互动用户;
  • 转发作品;
  • 人工发送私信。

每次写入前再次核对登记账号 UID、当前浏览器身份、目标 UID/评论/作品;平台返回不完整或连接中断时保存 uncertain,不自动重试或换小号。

XHS-G4:事件监听

上游仓库不能提供现成方案。需要单独研究小红书已登录页面/平台可观察事件:

  • 事件是否能由真实页面监听取得;
  • 是否存在稳定事件 ID 或可证明的新旧边界;
  • 互动者 UID、评论 ID、作品 ID 是否齐全;
  • 断连和进程重启后能否恢复;
  • 是否满足 5 秒开始处理、30 秒页面可见的时限。

未通过这些证据前,不启用小红书自动响应。

XHS-G5:双平台回归

小红书独立通过 G0-G4 后,再做双平台共存回归:账号、Profile、代理、Cookie/登录态、事件、冷却、任务和证据不能串号;不能用上游 README 或离线 fixture 替代真实证据。

7. 第一批推荐实现项

优先级 项目 原因 验收门槛
P0 小红书只读适配器 + 原始响应归档 价值最大、风险最低,能验证平台真实读取边界 真实账号 UID、详情、分页作品、一级评论、失败证据
P0 作品/评论字段三态和 xsec_* 上下文保留 直接解决字段缺失、链接失效和后续重解析 缺字段不变 0;上下文可回放/诊断
P1 竞品账号固定窗口采集 对应当前 C1/C2/W1 需求 最近 30 天、超过一页、重启续采、重复 cursor 失败
P1 人工选取后的媒体处理 对应当前 C4,且不依赖自动写操作 下载/提音/转写逐步成功、失败、无内容证据
P2 人工评论/私信写操作 先满足工作台最小闭环 UID/目标/身份核对,成功/失败/不明三态
P2 互动/私信事件监听 依赖平台真实事件身份和恢复能力 稳定事件 ID、baseline、重连/gap、时限证据
P3 自动响应策略 只有事件、动作和账号隔离都通过后才有意义 永久去重、UID 冷却、AI 失败不补发、全量真实证据

8. 研究后形成的明确决策

  1. 把上游当作坑位和协议观察资料,不作为 CreatorHub 运行时依赖。
  2. **先复用 CreatorHub 自有分页、任务、素材和结果证据模型。**上游简单循环、静默下载失败和 warning 后继续发布不符合当前验收标准。
  3. **小红书读取、Creator 发布和事件监听分别建立适配器和证据门。**不把一个能力的成功外推到另一个能力。
  4. **许可证未确认前不复制上游代码或静态逆向产物。**即使后续确认 MIT,也要单独核对签名脚本、指纹模板和其上游来源的版权/授权。
  5. **不建设“反检测/不封号”承诺。**风控拒绝和账号处罚是外部平台结果,必须如实暴露并保留人工处理入口。
  6. **当前不新增 curl_cffi、APScheduler 或另一套前端组件体系。**只有真实平台证据证明现有浏览器 gateway/标准库不足时,才提交针对性技术评审。

9. 来源与证据索引

上游仓库与提交

公开 Issues

CreatorHub 当前依据

  • 业务需求与验收基线
  • internal/creator/models.go
  • internal/creator/collection.go
  • internal/creator/content.go
  • internal/creator/actions.go
  • cmd/control-plane/creator.go
  • cmd/control-plane/creator_events.go
  • cmd/control-plane/creator_material.go
  • 容器与 gateway 架构

10. 研究范围限制

  • 未使用真实小红书账号验证登录、搜索、详情、评论、下载、发布或事件监听。
  • 上游 README 的功能清单、用户 Issue 的账号封禁反馈和平台风控判断不能当作官方因果证明。
  • LICENSE 文本当前未能确认,不能据此进行代码复制或商业化授权判断。
  • 上游实现可能继续随 Web 版本变化;后续若要实现小红书能力,必须重新锁定源码提交、真实环境和证据时间。