[仅供学习研究使用 / For Educational Purposes Only]
- 学习用途: 本项目仅供编程爱好者学习 Rust 与 Python 混合开发、逆向分析思路及浏览器自动化技术使用。
- 严禁商用: 严禁将本项目用于任何商业用途、黑灰产或其他非法目的。
- 后果自负: 使用本项目产生的任何后果（包括但不限于账号封禁、法律责任）由使用者自行承担。开发者不对任何衍生作品或使用行为负责。
- 接口变动: 项目基于特定时间点的目标网站状态开发，不保证长期有效性。
本项目是一个基于 Rust (后端 API) 和 Playwright (前端采集) 的小红书 API 逆向与自动化工具集。
小红书 Web 端接口的风控机制极为严格，核心在于：Cookie、Request Header 与 X-S 签名强绑定。 简单的签名生成往往无法通过校验，因为服务端会校验签名的生成环境（Cookie、Canvas 指纹等）是否与请求发起者一致。
本项目采用 Pure Algorithm (纯算法签名) 策略：
- 访客 Cookie 获取: 使用 Playwright 无头模式访问主页，获取合法的访客 Cookie。
- 纯 Rust 登录流程: QR 码创建、轮询、登录确认全部由 Rust 通过官方 API 完成。
- 实时签名: Python Agent 提供
xhshow算法签名服务，无需浏览器捕获。 - 持久化会话: 登录成功后 Cookie 自动存储到 MongoDB。
- 架构优势: Playwright 仅在首次获取访客 Cookie 时运行（极低频率），日常请求完全由 Rust 处理。
如果您希望以开发者身份运行源码，请按以下步骤操作：
1. 基础环境准备
- Rust: 安装最新版 Rust (及 Cargo)。
- Python: 安装 Python 3.10+。
- MongoDB: 本地安装并启动 MongoDB 服务 (默认端口 27017，用于存储 Cookie)。
2. 依赖安装 Rust 依赖会自动通过 Cargo 处理。Python 依赖需手动安装：
cd scripts
pip install -r requirements.txt
playwright install chromium
cd ..3. 启动服务 & 测试
# 启动服务 (自动启动 Python Agent)
cargo run
# 运行测试 (新终端)
python client_demo.py以下均为目前已实现并验证的功能：
- 媒体采集: 解析 视频笔记 (多画质 CDN) 和 图文笔记 (无水印/有水印)，支持服务端 通用下载。
- 纯 Rust 登录流程: QR 码创建、状态轮询、登录确认全部 API 化，无需浏览器子进程。
- 全套搜索接口: 支持搜索笔记(综合/视频/图文筛选)、搜索建议、OneBox、筛选器元数据、用户搜索。
- 全频道 Feed 采集: 支持首页推荐及所有 10 个子频道（穿搭、美食、彩妆、影视、职场、情感、家居、游戏、旅行、健身）。
- 通知页采集: 获取评论/@、新增关注、赞和收藏，及其分页数据。
- 笔记详情: 获取指定笔记的完整内容（标题、正文、图片、标签）。
- 笔记评论: 获取指定笔记的评论列表，支持分页。
- 实时签名: Python Agent 提供
xhshow算法实时签名。 - 高可靠性: Playwright 访客 Cookie 获取支持重试机制（最多 3 次）。
| 版本 | 日期 | 更新内容 |
|---|---|---|
| v1.7.0 | 2026-01-21 | 媒体采集功能 (视频+图片) |
- 🎬 视频采集: 新增 /api/note/video 解析视频笔记，返回多画质 CDN 直链 |
||
- 🖼️ 图片采集: 新增 /api/note/images 解析图文笔记，返回有水印/无水印两个版本 |
||
- 📥 通用下载: 新增 /api/media/download 下载视频/图片到服务端本地 |
||
- 📄 测试更新: test_media.py 新增视频和图片采集测试用例 |
||
| v1.6.2 | 2026-01-20 | Notification 分页支持 & Note Comment 分页文档 |
- 🔧 Notification 分页: mentions、connections、likes 三个接口支持 num/cursor 分页参数 |
||
| - 📄 分页指南: 新增 comment_pagination.md、likes_pagination.md、mentions_pagination.md、connections_pagination.md | ||
- 🔧 406 修复: 新增 get_with_query 方法，修复 Notification 接口签名问题 |
||
- 📝 Swagger 精简: 移除冗余的 /api/feed/homefeed/recommend 端点 |
||
| v1.6.1 | 2026-01-20 | Search Notes/Onebox 461 报错修复 & 分页指南 |
| - 🔧 461 修复: 移除多余 headers、调整 payload 字段顺序、修复 session 关联 | ||
| - 📄 分页指南: 新增 search_pagination.md、usersearch_pagination.md | ||
| v1.6.0 | 2026-01-20 | Homefeed 分页参数规则补充 |
- 📄 分页文档: 新增 doc/homefeed_pagination.md 详细说明分页机制 |
||
- 🔧 参数更新: homefeed 接口支持用户自定义 cursor_score、note_index 等分页参数 |
||
| - 📄 测试更新: 测试用例重构，更新测试用例client_demo.py，选取【穿搭】接口进行分页参数请求测试 | ||
| v1.5.0 | 2026-01-18 | 模块化重构 & Note API 完善 |
- 🏗️ Server 模块化: server.rs 精简，将 handlers 按领域拆分为 5 个模块 |
||
- 📝 Note API: 新增 note/detail 获取笔记详情，修正 note/page 为笔记评论 |
||
- 📦 OpenAPI 独立: 抽离 openapi.rs 管理 API 文档 |
||
| v1.4.0 | 2026-01-17 | Search API Suite 完整实现 |
- 🔍 搜索全家桶: 新增 search/notes, recommend, onebox, filter ,usersearch |
||
| - 📝 Swagger 更新: 新增 Search 聚合分组，完善 Request/Response 模型 | ||
| v1.3.1 | 2026-01-17 | 纯 Rust 登录流程重构 |
- 🚀 登录 API 化: 新增 /api/auth/guest-init、/qrcode/create、/qrcode/status |
||
| - 🔧 Playwright 职责简化: 仅用于获取初始访客 Cookie，无需浏览器子进程 | ||
| - 🔄 重试机制: 访客 Cookie 获取支持最多 3 次重试，超时容错增强 | ||
| v1.3.0 | 2026-01-16 | 架构重构与接口补全 |
| - 🏗️ 纯算法架构迁移: 移除 Playwright 签名依赖，全面转向 Python Agent 实时签名 | ||
| - 🐛 修复 406 错误: 修正 Notifications 接口的签名参数处理逻辑 | ||
- 🎉 新增接口: 赞和收藏通知 (/api/notification/likes) |
||
| - 🤖 Agent 管理: Rust 服务自动管理 Python Agent 生命周期 | ||
| v1.2.0 | 2026-01-16 | 新增端点与代码优化 |
- 🎉 新增 /api/auth/qrcode-status |
||
| - 🐛 修复 Python 脚本 UTF-8 编码问题 | ||
| v1.1.0 | 2026-01-15 | 新增接口与模块重构 |
- ✨ 新增通知页采集: /api/notification/mentions 和 /connections |
||
- ✨ 新增图文详情: /api/note/page |
||
| - ♻️ 重构 API 公共模块，统一请求处理逻辑 |
| Category | Endpoint | Status | Description |
|---|---|---|---|
| Auth | /api/auth/guest-init |
✅ | 获取访客 Cookie (Playwright) |
| Auth | /api/auth/qrcode/create |
✅ | 创建登录二维码 |
| Auth | /api/auth/qrcode/status |
✅ | 轮询登录状态 |
| User | /api/user/me |
✅ | 获取当前用户信息 |
| Search | /api/search/trending |
✅ | 获取热搜推荐词 |
| Search | /api/search/notes |
✅ | 笔记搜索 (📖 分页指南) |
| Search | /api/search/recommend |
✅ | 搜索建议 |
| Search | /api/search/onebox |
✅ | OneBox 聚合 |
| Search | /api/search/usersearch |
✅ | 用户搜索 (📖 分页指南) |
| Search | /api/search/filter |
✅ | 筛选器元数据 |
| Feed | /api/feed/homefeed/{category} |
✅ | 11 个垂直频道 (📖 分页指南) |
| Notification | /api/notification/mentions |
✅ | 获取评论和 @ 通知 (📖 分页指南) |
| Notification | /api/notification/connections |
✅ | 获取新增关注通知 (📖 分页指南) |
| Notification | /api/notification/likes |
✅ | 获取赞和收藏通知 (📖 分页指南) |
| Note | /api/note/page |
✅ | 获取笔记评论列表 (📖 分页指南) |
| Note | /api/note/detail |
✅ | 获取笔记完整内容 |
| Media | /api/note/video |
✅ (v1.7) | 视频笔记地址解析（多画质 CDN 直链） |
| Media | /api/note/images |
✅ (v1.7) | 图文笔记地址解析（有水印/无水印） |
| Media | /api/media/download |
✅ (v1.7) | 通用媒体下载（视频/图片到本地） |
本项目内置 Swagger UI，启动服务后即可访问：
- 地址:
http://localhost:3005/swagger-ui/ - 使用: 可在网页上直接发起请求测试接口。
本项目的灵感来源于我对 RPA (Robotic Process Automation) 技术及浏览器自动化控制的深入研究。
在前作 xhs_tools (1.1k stars) 的维护过程中，我深刻体会到单纯依赖 Python 脚本进行自动化操作的局限性。随着 AI 技术（特别是像 Google Gemini 这样具备强大浏览器理解能力的模型）的崛起，传统的硬编码自动化正在被智能代理所取代。
因此，我决定暂停旧项目的更新，转向探索通过纯后端API实现的服务端解决方案：
- 架构变更: 核心网络层采用 Rust 重写，确保极高的并发性能与类型安全。
- 自动化基座: 保留 Python (Playwright) 作为浏览器控制层，专注于处理登录二维码的获取。
- API 化: 将所有功能封装为标准 HTTP 接口，为未来接入 AI Agent 或其他上层应用提供坚实基础。
请务必仔细阅读：
- 技术研究性质: 本项目本质上是一个 浏览器自动化框架 的实践案例。所有的“采集”行为均基于模拟真实用户的常规浏览操作（点击、滚动、网络请求）
- 数据安全: 本项目不提供任何现成的账号或 Cookie。用户必须通过官方渠道（扫码）进行合法登录。项目仅作为数据的本地处理工具，不收集、不上传任何用户敏感信息。
- 合规使用: 请使用者严格遵守《中华人民共和国网络安全法》及目标网站的《用户服务协议》。严禁将本项目用于数据爬取（Scraping）、批量账号控制（Botting）或任何侵犯他人隐私/知识产权的商业行为。
- 免责条款: 开源作者不对任何因使用本项目而导致的法律纠纷或账号损失承担责任。代码仅作为技术交流用途，下载后请于 24 小时内删除。
特别感谢以下开源项目为本项目提供的技术支持与灵感：
- xhshow by Cloxl:
本项目中的 Python Agent 签名服务部分深度借鉴并集成了
xhshow的核心算法实现。xhshow是一个优秀的开源项目，提供了可靠的小红书 Web 端签名生成方案。Standing on the shoulders of giants.
以技术探索为名，行守法合规之事。
MIT License