| # 小红书稳定采集微服务 (Spider_XHS) - 产品需求文档 (PRD) |
| |
| ## 1. 产品概述 |
| |
| ### 1.1 产品名称 |
| 小红书稳定采集微服务 (Spider_XHS Stability Data Service) |
|
|
| ### 1.2 产品定位 |
| 一款面向企业级大模型（AI Agent）、数据分析、内容运营等上游业务，提供**高可用、抗风控、全链路可溯源**的小红书数据采集基础设施。本产品将底层的反爬对抗与数据清洗封装为标准 RESTful API，使得上游业务无需关注账号、风控及底层协议细节，即可稳定获取所需数据。 |
|
|
| ### 1.3 背景与痛点 |
| - **风控严苛**：小红书针对协议级 API 采集有着极强的反爬策略（封号、IP 限流、滑动验证码）。单一的协议破解（如逆向 `x-s` 签名）往往在遭遇强风控时全线崩溃。 |
| - **效率与稳定性的博弈**：传统的浏览器自动化方案（Playwright/Selenium）虽能较好地模拟真人绕过风控，但并发低、极其消耗 CPU/内存资源，无法满足大规模跑批需求。 |
| - **业务不能断流**：对于上游的内容生成和监控业务，数据的断流意味着业务停滞，必须拥有 100% 可用的兜底机制。 |
|
|
| ### 1.4 核心解决方案 |
| **“稳定性调度大脑 (Stability Controller) + 三引擎自动降级 + RPA 回传兜底 + AI Agent 自动化获客闭环”**： |
| 1. **主链路（三引擎自动降级）**： |
| - 引擎 A (Spider_XHS): 协议逆向极速采集（高并发、低成本） |
| - 引擎 B (MediaCrawler): Playwright Stealth 增强页面采集（含拟人化） |
| - 引擎 D (AgenticCrawler): 基于大模型视觉的智能自适应页面解析引擎（抗前端 DOM 改版） |
| 2. **统一调度与资源池**：前置 Stability Controller 负责基于错误策略（`auth/rate/risk/captcha/timeout` 等）对 Account Pool（账号冷却池）、Session Pool（会话轮换）和 Proxy Pool（动态代理评分与剔除）进行资源分配、重试与引擎降级决策。在遇到复杂验证码时，主动唤醒 **AI Agentic Captcha Solver** 智能解除风控。 |
| 3. **兜底链路（Chrome 插件 RPA 回传）**：当所有自动引擎和 AI 解除验证码均失效，任务进入 `WAITING_RPA` 时，由人工在真实浏览器环境中通过插件采集并调用 `POST /api/v1/import/extension` 回传结果。 |
| 4. **离线导入链路（人工离线导入）**：支持运营人员导出的 Excel（小红书数据助手等）格式化导入。 |
| 5. **AI 编排脚本（Orchestrator）**：提供基于 SQLite 的业务编排闭环，包含数据清洗、AI 智能生成图文内容、基于 AI Agent（`browser-use`）的**全自动真实发布**与**高意向线索自动私信触达**。 |
| 6. **运营控制台 (Ops Console)**：提供基于 React + Ant Design 的前端看板，实现资源池（账号/会话/代理）监控、错误分析聚合与内容库的只读可视化。 |
|
|
| --- |
|
|
| ## 2. 核心架构设计 |
|
|
| ### 2.1 系统架构图概览 |
| ```text |
| 上游业务 (Java/Agent) ──► [ OpenAPI / Webhook ] ──► (Spider_XHS FastAPI 微服务) |
| │ |
| ┌──────────────────────────────────────────────────────┤ |
| ▼ ▼ |
| [ 稳定性大脑: Stability Controller ] [ 兜底链路：数据导入 (Importer) ] |
| ├─► 资源分配：Account Pool + Session Pool + Proxy Pool ├─► 解析器: xhs_data_assistant |
| ├─► AI Agent 风控解除 (Captcha Solver) ├─► 解析器: fixed_template |
| ▼ │ |
| [ 多引擎执行链路 (Runner) ] └─► 字段标准化、元数据注入 |
| ├─► 引擎 A (Spider_XHS): 协议逆向、极速并发 │ |
| │ └─ 遇 timeout/rate/auth/risk/captcha ─重试/降级─┐ │ |
| │ ▼ │ |
| ├─► 引擎 B (MediaCrawler): Stealth 防抖模拟人行为 │ |
| │ └─ DOM 解析失效/改版 ─降级─┐ │ |
| │ ▼ │ |
| └─► 引擎 D (Agentic Crawler): AI 视觉自动解析 ───────────┤ |
| └─ 若仍被验证码拦截 → 状态 WAITING_RPA（等待人工回传） │ |
| ┌──────────────────────┴───────────────────────────────┘ |
| ▼ |
| [ 持久化与监控 ] |
| ├─► 文件存储 (JSON + HTML快照) 带有 fcntl 进程锁 |
| ├─► 限流拦截 (IP 滑动窗口 RateLimit) |
| └─► Prometheus 指标监控 (/metrics) |
| │ |
| ▼ |
| [ AI 自动化业务编排 (Orchestrator) ] |
| ├─► 核心数据库: SQLite (14张业务表: 关键词、生成草稿、线索等) |
| ├─► AI Agent 自动操作: 发布图文 (publish_tracker.py) |
| ├─► AI Agent 自动操作: 线索私信触达 (lead_service.py) |
| └─► 生态协同: 数据清洗、AI 图文生成、飞书同步 |
| |
| [ 运营控制台 (Ops Console) ] |
| ├─► 资源池中心 (账号/会话/代理健康快照) |
| ├─► 错误中心 (任务失败聚合与异常扫描) |
| └─► 内容库看板 (基于 SQLite 数据的全量只读展示) |
| |
| (第三兜底链路：Chrome 插件 RPA 回传) |
| 浏览器插件 ──► POST /api/v1/import/extension ──► 写入任务结果 |
| ``` |
|
|
| --- |
|
|
| ## 3. 功能需求说明 |
|
|
| ### 3.1 核心采集业务 (Data Scraping) |
| - **笔记详情采集 (`note_url`)**：输入笔记链接，获取无水印图文、视频信息、正文、点赞/收藏/评论等互动数据。 |
| - **用户主页采集 (`user_profile`)**：输入用户 ID 或主页链接，获取博主基本信息、粉丝数、关注数、获赞与收藏总数。 |
| - **关键词搜索采集 (`search`)**：输入关键词，获取相关笔记列表，支持按综合/最新/热门排序。 |
|
|
| ### 3.2 智能引擎调度与稳定性控制 (Stability Controller) |
| - **资源池化管理**：系统内置账号池 (Account Pool)、会话池 (Session Pool) 和代理池 (Proxy Pool)，所有采集任务通过 Stability Controller 动态获取最佳健康资源。 |
| - **代理打分与剔除**：代理池支持多 provider 聚合，根据任务执行结果实时回写分数，自动降权并剔除高失败率代理。 |
| - **账号防封冷却**：连续遭遇 `rate` 或 `risk` 错误的账号将进入冷却窗口，避免被平台拉黑。 |
| - **三引擎容灾与降级（服务端自动执行）**： |
| - 任务默认以 `auto` 策略下发，优先分配给 **Spider_XHS 引擎 (Engine A)** 以最高效率执行。 |
| - 监听执行异常并按策略表处置：`timeout` 换代理重试；`rate` 账号冷却+换账号降频；`auth` 标记会话失效+换 Session。 |
| - 遇到强风控 (`risk`/`captcha`) 时，降级至 **MediaCrawler 引擎 (Engine B)**。 |
| - Engine B 内置 Stealth 脚本与随机拟人化行为。若 Engine B 报 `parse` 错误（说明 DOM 结构发生变化），任务自动流转至 **Agentic Crawler (Engine D)**，由大模型视觉接管。 |
| - **智能验证码解除 (Captcha Solver)**：遇到复杂滑块或点选验证码时，系统主动实例化基于大模型的 `AgenticCaptchaSolver`，尝试自动操控浏览器完成过验。若 Agent 仍失败，任务进入 `WAITING_RPA` 状态。 |
| - **终极免疫链路（人工 RPA 回传）**：处于 `WAITING_RPA` 的任务可由人工通过 Chrome 浏览器插件拦截并回传数据，完成闭环；该链路属于人工兜底通道，而非服务端自动执行的引擎线程。 |
| |
| ### 3.3 异步任务与状态流转 (Task Lifecycle) |
| - **扩展任务状态机**：支持 `queued` -> `running` -> `retrying` -> `fallback_running` -> `succeeded` / `failed` / `waiting_rpa` / `rpa_imported` / `risk_paused` 等细粒度状态。 |
| - **异步拉取**：上游业务通过创建任务获取 `task_id`，并可通过长轮询获取执行结果。 |
| - **Webhook 回调**：支持配置全局 `CALLBACK_URL`。任务到达终态后自动触发回调推送。 |
| - **回调重试**：如遇上游网络抖动，系统自动采用指数退避算法最多重试 5 次，并在头部携带 `Idempotency-Key` 确保上游幂等消费。 |
| |
| ### 3.4 离线数据人工兜底 (Offline Import) |
| - **Excel 文件解析**：提供 `/api/v1/import/excel` 接口，支持上传 Excel 文件。 |
| - **模板智能识别**：自动识别“小红书数据助手”等特定报表格式。 |
| - **数据标准化**：提取“曝光、阅读、互动、转粉”等高阶流量指标，将其与自动化采集的数据结构对齐 (`normalized` 数据契约)。 |
| - **全链路溯源**：保留 `operator` (操作人)、`source_name` (来源)、行号及表名等元数据，便于数据审计。 |
| |
| ### 3.5 运营控制台与可视化 (Ops Console) |
| - **资源池中心**：直接复用内存池（Account/Session/Proxy Pool）状态快照，提供只读的可视化列表，方便运维人员实时监控风控与资源健康度。 |
| - **错误聚合分析**：基于本地任务文件系统，扫描近期（如近 1000 条）采集任务，并根据错误类别（auth/rate/risk/captcha 等）进行高阶聚合分析，提供失败列表过滤能力。 |
| - **内容库基础页**：对接 Orchestrator 的 SQLite 底座，为业务人员提供原始笔记和标准化笔记的分页查询与模糊检索视图。 |
| |
| --- |
| |
| ## 4. 非功能需求 |
| |
| ### 4.1 并发与数据一致性 |
| - **无状态服务设计**：服务进程应尽量无状态化，数据落盘依赖本地文件系统（`./storage`）。 |
| - **并发控制锁**：针对单机多进程/多线程场景，写入任务状态时必须使用 `fcntl.flock` 实现进程间排他锁，配合 `.tmp` 文件原子替换 (`os.replace`)，杜绝高并发下的文件写坏或数据覆盖问题。 |
| |
| ### 4.2 限流与防雪崩 |
| - **IP 级滑动窗口限流**：内置轻量级基于内存的 API 限流（如 `100 次 / 60 秒`），超出阈值立即返回 HTTP 429 状态码与 `Retry-After` 头，防止恶意或异常流量打垮服务。 |
| |
| ### 4.3 监控与可观测性 |
| - **Prometheus 集成**：暴露标准 `/api/v1/metrics` 接口，输出以下核心指标： |
| - `spider_xhs_tasks_total{engine, status}`：各引擎任务执行计数。 |
| - `spider_xhs_queue_length` 与 `spider_xhs_tasks_inflight`：当前排队及在途队列长度。 |
| - `spider_xhs_recent_failure_rate`：滑动窗口内的实时失败率报警指标。 |
| - 代理池指标：`spider_xhs_proxy_pool_size`、`spider_xhs_proxy_pool_avg_score` 及失败原因分布统计。 |
| - **结构化日志**：使用 `loguru` 输出结构化日志并按天切割；对部分错误日志做基础脱敏处理，但不保证对所有自定义日志字段自动脱敏，敏感凭证应只通过环境变量注入且避免打印。 |
| |
| ### 4.4 部署与兼容性 |
| - **容器化支持**：提供 Dockerfile 与 Docker Compose 编排，支持一键部署。存储目录独立挂载，保障数据持久化。 |
| - **向后兼容**：针对历史未带版本号的旧 API，可通过配置 `ENABLE_LEGACY_ROUTES=1` 提供兼容层平滑过渡。 |
| |
| --- |
| |
| ## 5. API 接口契约说明 |
| |
| ### 5.1 全局契约 |
| 所有 RESTful API 的响应体均采用标准三段式包装： |
| ```json |
| { |
| "code": 200, // 业务状态码，200 为成功，100xx 为特定业务错误 |
| "msg": "success", // 提示信息 |
| "data": { ... } // 载荷数据 |
| } |
| ``` |
| |
| ### 5.2 核心端点规划 |
| | 端点路径 | Method | 用途 | 核心参数/说明 | |
| |---|---|---|---| |
| | `/api/v1/tasks` | POST | 创建采集任务 | 必传: `task_type`, `target`; 可选: `engine`, `payload` | |
| | `/api/v1/tasks/{id}` | GET | 查询任务状态 | 返回当前状态 (`queued`, `running` 等) | |
| | `/api/v1/tasks/{id}/result`| GET | 获取任务结果 | 若未完成返回 409；完成后返回 `raw`, `normalized`, `meta` | |
| | `/api/v1/tasks/{id}/callback/retry` | POST | 手动重试回调 | 用于 Webhook 推送彻底失败后的人工介入 | |
| | `/api/v1/import/excel` | POST | 上传并解析 Excel | 必传: `file`, `operator`; 输出标准化清洗结果 | |
| | `/api/v1/import/extension` | POST | 插件 RPA 结果回传 | 必传: `task_id`, `raw`, `normalized`; 更新任务为 `RPA_IMPORTED` | |
| | `/api/v1/metrics` | GET | Prometheus 指标 | 面向监控采集系统 (如 Grafana)，含任务、队列、代理池状态 | |
| | `/api/v1/health` | GET | 健康检查与看板 | 包含队列长度、在途数、各引擎执行统计及实时失败率 | |
| |
| --- |
| |
| ## 6. 演进规划 (Roadmap) |
| |
| - **Phase 1 (V1.0) - 历史版本**：完成双引擎双链路架构重构，实现核心采集、容灾降级、IP限流、并发控制与容器化监控交付。 |
| - **Phase 2 (MVP) - 当前版本**：新增轻量级 Orchestrator 编排脚本与 SQLite 核心业务数据库，提供“采集同步→内容清洗→Mock 飞书同步/告警”的最小闭环样例。 |
| - **Phase 3 (Stability) - 当前版本**：完成 Stability Controller (稳定性大脑) 重构，补齐 Account Pool、Session Pool 与 Proxy Pool 的全链路生命周期管理。完成 Chrome 插件回传通道（`/api/v1/import/extension` + `WAITING_RPA` 状态机），形成“双引擎自动采集 + 人工 RPA 回传兜底”的可控闭环。新增基于 React 的运营控制台，落地资源池中心、错误中心与内容库基础页的只读可视化。 |
| - **Phase 4 (V1.1)**：增加任务优先级队列 (Priority Queue)，支持高优紧急任务插队；集成 Redis 作为分布式存储与分布式锁的选项，支持多节点横向扩容部署。 |
| - **Phase 5 (V2.0)**：接入大模型智能提取链路（针对未知格式或乱码的 Excel，通过 LLM 自动提取结构化内容）；提供可视化热更新管理后台（用于账号池、代理池调优）。 |
| |
