rssWorkFlow/docs/dev-plan.md

RSS 信息处理平台：开发步骤文档

版本：v1.0 日期：2026-06-15 配套文档：rss-platform-design.md

---

一、总体策略

1.1 开发原则

原则	说明
渐进式重构	不是一次性推翻重写，而是逐步迁移现有能力
先跑通再优化	先让核心流程（抓取→清洗→AI→存储）跑起来，再扩展高级功能
数据先行	先确定数据模型和迁移方案，再写业务逻辑
可回滚	每个阶段都保留回退到旧系统的能力
测试护航	关键模块必须有单元测试和接口测试

1.2 阶段划分

阶段一：基础骨架（4-5 周）
  → 技术选型确认、项目结构、PostgreSQL 迁移、Docker 环境、基础 API

阶段二：核心流程（4-5 周）
  → RSS 抓取、清洗流水线、去重插件、AI 摘要/分类/Tag/打分、任务调度

阶段三：产出与聊天（3-4 周）
  → Skill 系统、日报任务、聊天窗口、引用链接

阶段四：自优化与工业化（3-4 周）
  → 自优化调度器、去重算法自优化、监控、日志、备份

阶段五：规模化与优化（持续）
  → 性能优化、OpenSearch、分库分表、服务拆分

---

二、阶段一：基础骨架（Week 1-5）

目标

搭建可运行的基础平台，完成数据库迁移、Docker 环境、用户鉴权、基础 API。

任务清单

Week 1：项目初始化与技术选型确认

任务	说明	产出
2.1.1 创建 monorepo	在 /home/congsh/workspace/dev/rss-platform 初始化项目	README.md、Makefile、docker-compose.yml
2.1.2 确定目录结构	按模块划分目录	见下方目录结构
2.1.3 选择并锁定依赖版本	Python 3.12、FastAPI、SQLAlchemy 2.0、Celery、PostgreSQL、Redis	backend/requirements.txt
2.1.4 配置代码质量工具	ruff、black、pytest、pre-commit	.pre-commit-config.yaml、pyproject.toml
2.1.5 创建 Docker 基础镜像	后端、前端、PostgreSQL、Redis、MinIO	Dockerfile、docker-compose.dev.yml

推荐目录结构：

rss-platform/
├── backend/
│   ├── app/
│   │   ├── core/           # 配置、日志、异常、鉴权
│   │   ├── models/         # SQLAlchemy 模型
│   │   ├── schemas/        # Pydantic 模型
│   │   ├── api/            # API 路由
│   │   ├── services/       # 业务服务
│   │   ├── tasks/          # Celery 任务
│   │   ├── plugins/        # 插件接口与加载器
│   │   ├── ai/             # AI 调用、Provider 路由
│   │   ├── skills/         # Skill 加载与执行
│   │   ├── search/         # 检索服务
│   │   ├── chat/           # 聊天引擎
│   │   └── optimization/   # 自优化
│   ├── alembic/            # 数据库迁移
│   ├── tests/
│   └── main.py
├── frontend/
│   ├── src/
│   │   ├── views/
│   │   ├── components/
│   │   ├── api/
│   │   ├── stores/
│   │   └── router/
│   └── package.json
├── plugins/
│   └── deduplication/
├── docker/
│   ├── backend.Dockerfile
│   ├── frontend.Dockerfile
│   └── docker-compose.yml
├── docs/
└── scripts/
    ├── migrate_from_sqlite.py
    └── init_dev_env.sh

Week 2：PostgreSQL 数据模型与迁移

任务	说明	产出
2.2.1 设计并创建核心表	users、feeds、raw_articles、cleaned_articles、article_references、skills 等	backend/app/models/
2.2.2 配置 Alembic	初始化迁移工具	alembic.ini、baseline migration
2.2.3 编写 SQLite → PostgreSQL 迁移脚本	从 rssKeeper + dataClean 导出并导入	scripts/migrate_from_sqlite.py
2.2.4 验证迁移数据完整性	对比条数、关键字段抽样	迁移报告
2.2.5 配置 pgvector 扩展	安装并创建向量表	article_embeddings 表

Week 3：FastAPI 基础与鉴权

任务	说明	产出
2.3.1 FastAPI 项目骨架	lifespan、中间件、异常处理、日志	backend/main.py
2.3.2 JWT 鉴权	登录、注册、Token 刷新、API Key	backend/app/core/auth.py
2.3.3 简单 RBAC	admin / member 角色	backend/app/core/rbac.py
2.3.4 CORS 安全配置	白名单、关闭 credentials	backend/main.py
2.3.5 健康检查与 OpenAPI	/health、/openapi.json	API 文档

Week 4：配置中心与锁服务

任务	说明	产出
2.4.1 配置中心	环境变量 + DB 覆盖 + 版本化	backend/app/core/settings.py
2.4.2 Redis 连接	缓存、锁、消息队列	backend/app/core/redis.py
2.4.3 分布式锁服务	任务锁、文章锁	backend/app/services/lock_service.py
2.4.4 任务运行时状态	进度追踪、任务日志	backend/app/services/task_runtime.py
2.4.5 日志与请求 ID	结构化日志、request_id	backend/app/core/logging.py

Week 5：前端基础与管理后台

任务	说明	产出
2.5.1 Vue 3 + TS 项目初始化	Vite、Element Plus、Pinia、Vue Router	frontend/
2.5.2 登录页	JWT 登录、API Key 管理	LoginView.vue
2.5.3 RSS 源管理页	列表、添加、编辑、删除	FeedsView.vue
2.5.4 文章列表页	分页、筛选	ArticlesView.vue
2.5.5 Docker Compose 联调	全栈本地启动	docker-compose.yml

阶段一交付物

• 可本地 docker-compose up 运行的基础平台
• PostgreSQL 数据库 + 迁移脚本
• JWT 鉴权 + 简单 RBAC
• RSS 源 CRUD + 文章列表
• 分布式锁服务

阶段一里程碑

M1：基础平台骨架完成，可管理 RSS 源和查看文章列表。

---

三、阶段二：核心流程（Week 6-10）

目标

实现抓取→清洗→去重→AI 处理→存储的完整流水线。

任务清单

Week 6：RSS 抓取迁移与增强

任务	说明	产出
3.6.1 迁移抓取逻辑	从 rssKeeper rss_fetcher.py 迁移	backend/app/services/feed_fetcher.py
3.6.2 Celery 抓取任务	fetch_feed_task、fetch_all_feeds_task	backend/app/tasks/feeds.py
3.6.3 Celery Beat 调度	按 Feed 间隔注册定时任务	backend/app/tasks/scheduler.py
3.6.4 抓取失败重试	指数退避、死信队列	重试装饰器
3.6.5 Feed 健康度统计	复用 rssKeeper 逻辑	backend/app/services/health_checker.py

Week 7：清洗流水线

任务	说明	产出
3.7.1 数据标准化	URL 规范化、HTML 清洗、时间标准化	backend/app/services/normalizer.py
3.7.2 正文提取	优先 RSS content，fallback 原文页	backend/app/services/content_extractor.py
3.7.3 清洗任务 Celery 化	process_raw_article_task	backend/app/tasks/pipeline.py
3.7.4 内容 hash 与语言检测	用于后续去重	辅助字段
3.7.5 清洗状态机	pending → processing → cleaned / failed	processing_status

Week 8：去重插件系统

任务	说明	产出
3.8.1 定义插件接口	DeduplicationPlugin	backend/app/plugins/base.py
3.8.2 实现默认去重插件	URL + 标题 exact + TF-IDF 内容相似	plugins/deduplication/current.py
3.8.3 插件加载器	动态 import + 热加载	backend/app/plugins/loader.py
3.8.4 引用关系写入	article_references + reference_links	去重服务
3.8.5 去重任务接口	手动触发、查看结果	/api/tasks/deduplicate
3.8.6 插件版本元数据	metadata.json	版本管理

Week 9：AI 处理中心

任务	说明	产出
3.9.1 AI Provider 配置模型	openai / anthropic / gemini / local	backend/app/models/ai_provider_config.py
3.9.2 AI 任务配置模型	每个任务独立配置	backend/app/models/ai_task_config.py
3.9.3 LiteLLM/自封装多供应商路由	统一调用接口	backend/app/ai/client.py
3.9.4 AI 摘要任务	复用 dataClean summarizer.py	backend/app/tasks/ai_tasks.py
3.9.5 AI 分类任务	从规则分类迁移到 AI 分类	backend/app/tasks/ai_tasks.py
3.9.6 AI Tag 任务	AI 打标签	backend/app/tasks/ai_tasks.py
3.9.7 AI 打分任务	heat/importance/composite	backend/app/tasks/ai_tasks.py

Week 10：流水线编排与任务调度

任务	说明	产出
3.10.1 流水线编排器	组合抓取→清洗→去重→AI 处理	backend/app/services/pipeline_orchestrator.py
3.10.2 任务进度追踪	复用 dataClean task_progress.py	backend/app/services/task_progress.py
3.10.3 手动/定时任务互斥	Redis 锁 + Celery	调度服务
3.10.4 仪表盘统计 API	文章数、分类分布、任务状态	/api/stats
3.10.5 前端仪表盘	统计卡片、任务进度	DashboardView.vue

阶段二交付物

• RSS 自动抓取 + Celery 调度
• 清洗流水线
• 去重插件系统（默认实现 + 热加载）
• AI 摘要/分类/Tag/打分
• 流水线编排与任务进度

阶段二里程碑

M2：核心流程跑通，一篇文章从 RSS 抓取到 AI 处理完成可自动化执行。

---

四、阶段三：产出与聊天（Week 11-14）

目标

实现 Skill 系统、日报任务、聊天窗口、引用链接。

任务清单

Week 11：Skill 系统基础

任务	说明	产出
4.11.1 Skill 数据模型	skills、skill_versions	数据库表
4.11.2 Skill 加载与执行	解析 prompt、schema、tools	backend/app/skills/loader.py
4.11.3 内置默认 Skills	摘要、分类、Tag、打分、日报、聊天	backend/app/skills/defaults/
4.11.4 Skill CRUD API	创建、修改、导入、导出、恢复默认	/api/skills/*
4.11.5 Skill 管理前端	编辑器、导入导出	SkillsView.vue

Week 12：日报任务系统

任务	说明	产出
4.12.1 OutputTask 模型	task + skill + filter + schedule	数据库表
4.12.2 日报生成任务	复用 dataClean brief.py，改为 Skill 驱动	backend/app/tasks/output_tasks.py
4.12.3 数据筛选 DSL	时间、分类、Tag、分数过滤	Filter builder
4.12.4 多种日报类型	科技观察、综合日报等	多个 OutputTask
4.12.5 日报前端	列表、详情、重新生成	BriefsView.vue

Week 13：聊天引擎

任务	说明	产出
4.13.1 聊天数据模型	sessions、messages	数据库表
4.13.2 聊天 API	创建会话、发送消息、历史记录	/api/chat/*
4.13.3 Tool 调用框架	搜索文章、获取文章详情、调用外部 API	backend/app/chat/tools.py
4.13.4 引用链接解析	从 AI 输出提取标记并映射链接	backend/app/chat/references.py
4.13.5 聊天前端	对话界面、引用渲染	ChatView.vue

Week 14：工具与产出集成

任务	说明	产出
4.14.1 外部 API Tool	调用用户配置的 HTTP API	fetch_external_api tool
4.14.2 产出导出	Markdown、JSON、邮件	backend/app/services/exporters.py
4.14.3 聊天中运行 Skill	用户选择 Skill 进行专项对话	Skill selector
4.14.4 会话上下文管理	窗口大小、历史摘要	Context manager
4.14.5 集成测试	端到端聊天流程	tests/test_chat.py

阶段三交付物

• Skill 系统（CRUD + 默认 Skills）
• 可配置的日报任务系统
• 聊天窗口（支持 Tool 调用和引用链接）
• 外部 API Tool

阶段三里程碑

M3：平台具备 AI 产出能力，日报和聊天均可调用 Skills 生成带引用链接的内容。

---

五、阶段四：自优化与工业化（Week 15-18）

目标

实现每日凌晨 2 点自优化、去重算法自优化、监控、备份、日志。

任务清单

Week 15：自优化调度器

任务	说明	产出
5.15.1 自优化数据收集	收集最近执行样例、历史优化记录	backend/app/optimization/collector.py
5.15.2 Prompt/Skill 优化器	用 AI 评审并生成候选 Prompt	backend/app/optimization/prompt_optimizer.py
5.15.3 优化器自评逻辑	候选 vs 当前版本评分	评估服务
5.15.4 自动发布机制	保存新版本、自动生效	发布服务
5.15.5 优化日志	optimization_logs 表 + API	留痕

Week 16：去重算法自优化

任务	说明	产出
5.16.1 去重算法优化器	分析样例生成候选算法代码	backend/app/optimization/dedup_optimizer.py
5.16.2 算法版本备份	自动生成 .bak	版本管理
5.16.3 算法热加载与回滚	失败自动回滚	插件加载器增强
5.16.4 算法性能评估	运行时间、内存、误判漏判	评估服务
5.16.5 手动回滚 API	/api/admin/deduplication/rollback	管理接口

Week 17：监控与可观测性

任务	说明	产出
5.17.1 Prometheus 指标	任务数、AI 调用数、延迟、失败率	/metrics
5.17.2 Grafana 仪表盘	系统状态、任务状态、AI 成本	docker/grafana/
5.17.3 Sentry 集成	错误追踪	配置
5.17.4 日志聚合	Loki 或文件日志	日志配置
5.17.5 告警规则	任务失败、AI 调用异常	Alert rules

Week 18：备份、安全与部署

任务	说明	产出
5.18.1 PostgreSQL 自动备份	每日备份、保留策略	scripts/backup_db.sh
5.18.2 对象存储备份	插件、导出产物备份	备份脚本
5.18.3 安全加固	API 限流、密码策略、敏感配置加密	安全文档
5.18.4 生产 Docker Compose	多 Worker 配置	docker-compose.prod.yml
5.18.5 部署文档	完整部署步骤	docs/deployment.md

阶段四交付物

• 每日 2:00 自优化调度器
• 去重算法自优化 + 版本回滚
• Prometheus + Grafana 监控
• 自动备份方案
• 生产部署文档

阶段四里程碑

M4：平台具备工业化能力，可无人值守运行并自动优化。

---

六、阶段五：规模化与持续优化（Week 19+）

目标

根据实际数据量和负载进行性能优化和架构扩展。

任务清单

任务	说明	时机
6.1 迁移到 OpenSearch	当 PG tsvector 性能不足时	10万+ 文章
6.2 向量检索优化	使用专用向量库（Qdrant/Milvus）	需要语义检索时
6.3 去重算法升级	LSH/MinHash/Embedding	日增 5000+ 时
6.4 数据库读写分离	主从复制	读压力高时
6.5 按时间分库	历史数据归档	50万+ 文章
6.6 服务拆分	拆分为 feed-service、ai-service 等	团队扩大时
6.7 缓存层优化	Redis 缓存热门查询、文章	读压力大时
6.8 AI 调用成本优化	缓存 Embedding、批量调用、模型降级	AI 成本高时

---

七、关键依赖清单

7.1 Python 后端

fastapi==0.115.0
uvicorn[standard]==0.30.0
sqlalchemy[asyncio]==2.0.31
asyncpg==0.29.0
alembic==1.13.2
psycopg2-binary==2.9.9
celery==5.4.0
redis==5.0.7
pydantic==2.8.2
pydantic-settings==2.3.4
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.9
httpx==0.27.0
feedparser==6.0.11
beautifulsoup4==4.12.3
lxml==5.2.2
scikit-learn==1.5.1
numpy==1.26.4
openai==1.35.0
litellm==1.41.0
langdetect==1.0.9
watchdog==4.0.1
prometheus-client==0.20.0
sentry-sdk==2.7.0
pytest==8.2.2
pytest-asyncio==0.23.7

7.2 前端

{
  "vue": "^3.4.0",
  "vue-router": "^4.3.0",
  "pinia": "^2.1.0",
  "element-plus": "^2.7.0",
  "axios": "^1.7.0",
  "typescript": "^5.4.0",
  "marked": "^13.0.0",
  "dompurify": "^3.1.0"
}

7.3 基础设施

组件	版本	用途
PostgreSQL	16+	主数据库
Redis	7+	缓存、锁、消息队列
MinIO	latest	对象存储
Prometheus	latest	指标采集
Grafana	latest	监控仪表盘

---

八、测试策略

8.1 单元测试

模块	测试重点
plugins/deduplication	URL/标题/内容去重、代表文章选择
app/services/normalizer	URL 规范化、HTML 清洗
app/ai/client	多 Provider 路由、Fallback
app/skills/loader	Skill 解析、Schema 校验
app/chat/references	引用标记解析与链接映射
app/services/lock_service	锁获取/释放/超时

8.2 集成测试

模块	测试重点
/api/feeds	CRUD、抓取触发
/api/tasks/deduplicate	去重任务全流程
/api/chat/sessions	创建会话、发送消息
/api/output-tasks	创建任务、手动运行
/api/admin/deduplication/rollback	算法回滚

8.3 端到端测试

• 发布 RSS → 抓取 → 清洗 → 去重 → AI 处理 → 日报生成
• 聊天中提问 → 检索文章 → AI 回答 → 验证引用链接

---

九、里程碑与验收标准

里程碑	时间	验收标准
M1 基础骨架	Week 5	docker-compose up 可运行；可管理 Feed；可查看文章列表；JWT 鉴权可用
M2 核心流程	Week 10	一条 RSS 文章能自动完成：抓取→清洗→去重→AI 摘要/分类/Tag/打分
M3 产出与聊天	Week 14	可创建日报任务并生成日报；可在聊天中提问并获得带引用链接的回答
M4 自优化与工业化	Week 18	每日 2:00 自优化成功执行并留痕；去重算法可热加载和回滚；监控可用
M5 规模化	持续	根据数据量完成 OpenSearch/分库等扩展

---

十、风险与应对

风险	阶段	影响	应对
SQLite → PostgreSQL 迁移复杂	阶段一	高	编写迁移脚本 + 数据校验 + 保留旧系统
Celery 任务状态丢失	阶段二	中	使用 Redis 持久化 + 任务结果 backend
去重插件热加载失败	阶段二/四	高	失败自动回滚上一个 .bak
AI 自优化产生劣质结果	阶段四	中	优化器自评 + 版本化 + 不自动删除旧版本
AI 调用成本高	全程	中	多供应商路由 + Fallback + 结果缓存
前端 TypeScript 迁移成本	阶段一	低	新平台前端直接用 TS，旧前端代码逐步重写
数据量增长超预期	阶段五	中	分区表 + 预留 OpenSearch/向量库扩展路径

---

十一、交付文档清单

文档	负责阶段	状态
本开发步骤文档	全程	✅
架构设计文档	全程	✅ rss-platform-design.md
API 接口详细文档	阶段一~三	待编写
Skill 开发指南	阶段三	待编写
自优化机制说明	阶段四	待编写
Docker 部署手册	阶段一/四	待编写
数据迁移手册	阶段一	待编写
运维监控手册	阶段四	待编写

---

十二、后续建议

1. 先验证核心假设：在阶段二结束前，用真实 RSS 源跑一周，观察去重效果和 AI 输出质量。
2. Prompt 工程优先于自优化：初期先人工调优 Prompt，阶段四再引入自优化。
3. 保留旧系统并行运行：直到阶段三结束，旧 rssKeeper + dataClean 可继续服务，降低切换风险。
4. 建立反馈闭环：即使不自优化，也要先收集用户对 AI 产出的反馈数据。
5. 控制 AI 成本：为每个任务设置预算上限和模型降级策略。

---

十三、快速启动命令（预期）

# 1. 克隆项目
cd /home/congsh/workspace/dev
git clone <new-repo-url> rss-platform
cd rss-platform

# 2. 启动基础设施
docker-compose -f docker-compose.dev.yml up -d postgres redis minio

# 3. 初始化数据库
cd backend
alembic upgrade head
python scripts/migrate_from_sqlite.py \
  --rsskeeper-db /path/to/rsskeeper.db \
  --dataclean-db /path/to/dataclean.db

# 4. 启动后端
uvicorn main:app --reload --port 8000

# 5. 启动前端
cd ../frontend
npm install
npm run dev

# 6. 启动 Celery Worker
cd ../backend
celery -A app.tasks worker -Q default,fetch,ai -l info
celery -A app.tasks beat -l info

---

本文档与 rss-platform-design.md 配套使用，开发过程中应根据实际情况迭代更新。