| # 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 会话与 Playwright `storage_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 的**前端运营控制台**，打通了资源池监控、错误聚合排查与内容展示的可视化闭环，极大提升了项目的可用性与运维体验。 |
| |
