PRD.md

# 小红书稳定采集微服务 (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 自动提取结构化内容）；提供可视化热更新管理后台（用于账号池、代理池调优）。