Spider_XHS (小红书稳定采集微服务) - 项目完成情况介绍
1. 项目概览
Spider_XHS 最初是一个基于小红书 PC 端和创作者平台 API 逆向签名的纯脚本库。经过最近几轮的大型架构重构，该项目已经脱胎换骨，全面升级为一个企业级、高可用、抗风控的稳定采集微服务，并在生产层面引入了“稳定性调度大脑 + 资源池化 + 双自动引擎 + RPA 回传兜底”的组合策略。
目前，项目已完成 V1.0.0 技术规格书中定义的所有核心指标，实现了从“个人学习用爬虫”到“AI Agent 数据底座”的跨越。
2. 核心架构完成情况
2.1 稳定性大脑与多链路协同 (Stability Controller & Multi-Path Fallback)
已完全实现。
- **稳定性调度大脑 (Stability Controller)**：不再将降级写死在代码中，而是抽象出统一的大脑，依据细粒度错误（
timeout/rate/auth/risk/captcha）决定：重试、账号冷却、会话失效、引擎降级或暂停任务。 - 资源池化底座：
Account Pool：提供账号风险分管理与连续报错（rate/risk）的自动冷却窗口。Session Pool：统一管理 API Cookie 会话与 Playwrightstorage_state，具备轻量级健康检查与会话轮换能力。Proxy Pool：支持从多个外部 API 或文件动态拉取 IP，基于执行结果同步打分，并具备高失败代理自动剔除逻辑。
- 多引擎自动采集 + 一条人工 RPA 兜底链路：
- **Engine A (API 引擎)**：作为极速并发的首选。
- **Engine B (Browser 引擎)**：增强了 Stealth 抹机脚本与随机拟人化行为，作为遭遇风控验证码时的第二链路。
- **Engine D (Agentic Crawler)**：全新引入的基于
browser-use和视觉大模型的智能引擎，专治小红书前端 DOM 改版导致传统爬虫失效的场景。 - Agentic Captcha Solver：智能风控解除。系统在遇到复杂验证码时，会自动唤醒大模型视觉实例去识别并完成验证码点选/滑块。
- RPA 回传链路（Chrome 扩展）：项目已提供可加载的 Chrome 插件与服务端回传接口
/api/v1/import/extension。该链路是最后兜底通道，用于将处于WAITING_RPA的任务结果回填并继续回调/入库流程。
2.2 人工兜底采集链路 (Offline Excel Import)
已完全实现。
- 针对极端情况（全网 IP 被封或大版本升级），开发了
/api/v1/import/excel接口。 - 支持直接上传由“小红书数据助手”或第三方平台导出的离线 Excel 数据。
- 解析器（
xhs_data_assistant）能够智能识别变体表头，自动完成字段映射（如提取曝光、阅读、互动、转粉等指标），并将其洗牌为标准的normalized数据结构，实现线上自动化与线下人工数据的无缝衔接。
3. 服务端能力完成情况
3.1 异步任务与 Webhook 回调
已完全实现。
- 采用 FastAPI 构建了无状态的轻量级微服务（
service/app.py）。 - 支持长轮询模式（
/api/v1/tasks/{id}/result）。 - 支持更丰富的细粒度任务状态流转（
queued->running->retrying/fallback_running->waiting_rpa/rpa_running->succeeded/failed/rpa_imported等）。 - 实现了基于
Idempotency-Key的 Webhook 回调推送机制，并在回调失败时支持指数退避的自动重试（最多 5 次），确保上游（如 Java 服务端）能够稳定、幂等地接收采集结果。
3.2 极高并发与文件锁存储
已完全实现。
- 数据持久化层（
service/storage.py）采用了基于本地文件系统（./storage）的 JSON 分片存储策略。 - 原子落盘 + 进程锁：写入采用临时文件 +
os.replace原子替换；为避免多进程并发更新造成覆盖，关键更新路径使用fcntl.flock做轻量进程互斥，保证一致性与可恢复性。
3.3 企业级运维与监控保障
已完全实现。
- 防雪崩 IP 限流：在 API 网关层实现了基于内存滑动窗口的 IP 限流器（
PerIPRateLimitMiddleware），默认100次/60秒，超出阈值立即返回429 Retry-After，同时优化了清理逻辑的 O(N) 开销，防止恶意流量打垮服务。 - Prometheus 监控：暴露了标准的
/api/v1/metrics接口，可直出各引擎的spider_xhs_tasks_total、队列积压及在途任务长度，以及spider_xhs_recent_failure_rate、代理池规模、评分及失败原因等核心业务指标，可对接 Grafana 看板。 - 结构化日志与基础脱敏：使用
loguru实现日志按天切割、保留与压缩；对部分错误日志做基础脱敏处理，但不保证对所有自定义日志字段自动脱敏，敏感凭证应只通过环境变量注入且避免打印。 - 自动清理：服务内置后台守护线程，自动清理过期（默认 7 天）的 Browser 引擎生成的 HTML 原始快照。
3.4 自动化获客闭环 MVP (Automated Customer Acquisition Closed-Loop)
已完全实现。
- 在服务上层新增了
orchestrator/编排层，实现了“采集同步 → 内容清洗 → AI 生成图文 → AI 自动发布 → AI 自动触达高意向用户 → 飞书线索同步”的完整业务闭环。 - 本地数据库底座：基于 SQLite 构建了 14 张核心业务表（
orchestrator/data/mvp.db），覆盖了从数据获取、图文草稿管理、任务重试到客户线索的所有生命周期。 - AI 生成与自动操作能力：
- 基于大模型实现了批量仿写与原创文案的生成（
ai_generation.py）。 - 引入了基于
browser-use框架的 AI Browser Agent，成功实现了无人值守的真实小红书笔记自动发布（publish_tracker.py）与高意向线索的自动私信回复（lead_service.py）。
- 基于大模型实现了批量仿写与原创文案的生成（
- 生态协同：
feishu_sync.py与alert.py完成了线索数据向上游 CRM（飞书多维表格）和报警群的 Mock 流转。
3.5 运营控制台可视化 (Ops Console Visualization)
已完全实现。
- 基于 React + Vite + Ant Design 构建了轻量级前端控制台（
frontend/）。 - 实现了只读模式的资源池中心（账号/会话/代理状态快照）、错误中心（任务错误聚合与失败任务扫描）以及内容库基础页（从 Orchestrator SQLite 数据库读取原始笔记与清洗后数据）。
- 通过复用内存中的
AccountPool,SessionPool,ProxyPool的快照和本地任务文件列表，以最小侵入的方式实现了前后端数据打通，提供了友好的看板展示与空态引导。
4. 部署与兼容性完成情况
4.1 容器化与独立运行
已完全实现。
- 提供了完整的
Dockerfile与docker-compose.yml。 - 支持一键拉起包括 FastAPI 服务、本地文件挂载（
./storage）在内的所有组件。 - 提供了
MEDIACRAWLER_MOCK模式，允许在没有安装 Playwright 依赖（或 CI/CD 环境）的情况下，通过 Mock HTML 直接验证服务调度、容灾及解析逻辑。
4.2 遗留系统兼容
已完全实现。
- 通过环境变量
ENABLE_LEGACY_ROUTES=1，支持无缝兼容不带/api/v1前缀的旧版路由请求。 - 存储层支持启动时自动识别并热迁移旧版的单一
tasks.json文件到全新的碎片化目录结构中，做到了对老用户的零感知升级。
5. 总结
目前，Spider_XHS 已达成当前版本既定的产品化目标。它不仅保留了作为底层爬虫框架逆向签名的硬核能力，更通过引入 FastAPI 微服务架构、稳定性调度大脑 (Stability Controller)、资源池化底座、双引擎自动容灾（API + Playwright Stealth）与 RPA 回传兜底、原子落盘 + 进程锁的本地持久化、Prometheus 监控以及 IP 防雪崩限流，形成了一个可用于上游 AI/数据业务调用的稳定采集底座。
此外，项目提供了一个脚本样例级的编排 MVP（orchestrator/ + SQLite），用于演示采集同步与基础清洗、以及 Mock 的飞书同步与告警落库，为后续完善 AI 生成/合规模块预留了清晰扩展点。同时，配合基于 React 的前端运营控制台，打通了资源池监控、错误聚合排查与内容展示的可视化闭环，极大提升了项目的可用性与运维体验。