391 lines
12 KiB
Markdown
391 lines
12 KiB
Markdown
# TravelContentCreator 项目总览
|
||
|
||
> 更新日期: 2024-12-10
|
||
> 版本: 2.3.0
|
||
|
||
---
|
||
|
||
## 一、项目简介
|
||
|
||
TravelContentCreator 是一个 **旅游内容自动创作系统** 的 Python 后端服务，主要功能包括：
|
||
|
||
- **选题生成** - 基于热点、节日、目标人群生成小红书选题
|
||
- **内容生成** - 生成小红书风格的图文笔记正文
|
||
- **海报生成** - 自动生成配图海报
|
||
- **热点数据** - 多平台热点数据采集
|
||
|
||
### 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|-----|------|
|
||
| Web 框架 | FastAPI |
|
||
| AI 模型 | OpenAI GPT-4 |
|
||
| 模板引擎 | Jinja2 |
|
||
| 配置格式 | YAML / JSON |
|
||
| 图像处理 | Pillow |
|
||
| 爬虫 | aiohttp / MediaCrawler |
|
||
|
||
---
|
||
|
||
## 二、目录结构
|
||
|
||
```
|
||
TravelContentCreator/
|
||
├── api/ # FastAPI 应用层
|
||
│ ├── main.py # 应用入口
|
||
│ ├── routers/ # API 路由
|
||
│ │ ├── aigc.py # V2 AIGC 统一接口
|
||
│ │ ├── hotspot.py # 热点数据 API
|
||
│ │ ├── prompt.py # Prompt 管理 API
|
||
│ │ └── reference.py # 参考文献 API
|
||
│ ├── models/ # 请求/响应模型
|
||
│ └── services/ # 服务层 (部分已迁移)
|
||
│
|
||
├── domain/ # 领域层 (核心业务逻辑)
|
||
│ ├── aigc/ # AIGC 引擎
|
||
│ │ ├── engines/ # 引擎实现
|
||
│ │ │ ├── base.py # 引擎基类
|
||
│ │ │ ├── topic_generate_v2.py
|
||
│ │ │ ├── content_generate_v2.py
|
||
│ │ │ └── poster_generate_v2.py
|
||
│ │ ├── engine_registry.py # 引擎注册
|
||
│ │ ├── engine_executor.py # 引擎执行器
|
||
│ │ └── shared/ # 共享组件
|
||
│ │ └── llm_client.py # LLM 客户端
|
||
│ │
|
||
│ ├── hotspot/ # 热点数据模块
|
||
│ │ ├── crawlers/ # 爬虫实现
|
||
│ │ │ ├── base.py # 爬虫基类
|
||
│ │ │ ├── baidu.py # 百度热搜
|
||
│ │ │ ├── bing.py # Bing 搜索
|
||
│ │ │ ├── calendar.py # 节日日历
|
||
│ │ │ ├── weibo.py # 微博热搜
|
||
│ │ │ ├── xiaohongshu.py # 小红书
|
||
│ │ │ └── mediacrawler/ # MediaCrawler 桥接
|
||
│ │ ├── manager.py # 热点管理器
|
||
│ │ └── models.py # 数据模型
|
||
│ │
|
||
│ ├── prompt/ # Prompt 管理
|
||
│ │ ├── registry.py # PromptRegistry
|
||
│ │ └── reference_manager.py # 参考文献管理
|
||
│ │
|
||
│ ├── poster/ # 海报领域
|
||
│ │ ├── poster_service.py # 海报服务
|
||
│ │ ├── poster_renderer.py # 渲染器
|
||
│ │ ├── template_manager.py # 模板管理
|
||
│ │ └── fabric_generator.py # Fabric.js JSON
|
||
│ │
|
||
│ ├── content/ # 内容领域
|
||
│ │ ├── topic_engine.py # 选题引擎
|
||
│ │ ├── content_engine.py # 内容引擎
|
||
│ │ └── judge_engine.py # 评判引擎
|
||
│ │
|
||
│ └── container.py # 依赖注入容器
|
||
│
|
||
├── prompts/ # Prompt 模板 (YAML)
|
||
│ ├── topic_generate/ # 选题生成 Prompt
|
||
│ ├── content_generate/ # 内容生成 Prompt
|
||
│ ├── content_judge/ # 内容评判 Prompt
|
||
│ └── reference/ # 参考文献库
|
||
│ ├── titles.yaml # 标题范例
|
||
│ └── contents.yaml # 正文范例
|
||
│
|
||
├── poster/ # 海报模板
|
||
│ ├── templates/ # 模板实现
|
||
│ │ ├── vibrant_template.py # 活力风格
|
||
│ │ ├── business_template.py # 商务风格
|
||
│ │ └── collage_template.py # 拼图风格
|
||
│ └── utils.py # 图像处理工具
|
||
│
|
||
├── config/ # 配置文件
|
||
│ ├── ai_model.json # AI 模型配置
|
||
│ ├── engines.json # 引擎配置
|
||
│ ├── poster_gen.json # 海报生成配置
|
||
│ └── ...
|
||
│
|
||
├── libs/ # 外部库
|
||
│ └── MediaCrawler/ # 社交媒体爬虫
|
||
│
|
||
├── core/ # 核心模块 (部分遗留)
|
||
├── docs/ # 文档
|
||
└── tests/ # 测试
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心模块
|
||
|
||
### 3.1 AIGC 引擎 (`domain/aigc/`)
|
||
|
||
统一的 AIGC 引擎框架，支持选题、内容、海报生成。
|
||
|
||
#### 引擎列表
|
||
|
||
| 引擎 | 类 | 状态 | 说明 |
|
||
|-----|-----|------|------|
|
||
| `topic_generate` | `TopicGenerateEngineV2` | ✅ | 选题生成 |
|
||
| `content_generate` | `ContentGenerateEngineV2` | ✅ | 内容生成 |
|
||
| `poster_generate` | `PosterGenerateEngineV2` | ✅ | 海报生成 |
|
||
|
||
#### 架构设计
|
||
|
||
```
|
||
EngineRegistry (引擎注册)
|
||
↓
|
||
EngineExecutor (引擎执行)
|
||
↓
|
||
BaseEngine (引擎基类)
|
||
├── TopicGenerateEngineV2
|
||
├── ContentGenerateEngineV2
|
||
└── PosterGenerateEngineV2
|
||
```
|
||
|
||
#### API 调用
|
||
|
||
```bash
|
||
POST /api/v2/aigc/execute
|
||
{
|
||
"engine": "topic_generate",
|
||
"params": {
|
||
"style_id": "travel_casual",
|
||
"audience_id": "young_couple",
|
||
"hot_topics": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 热点数据模块 (`domain/hotspot/`)
|
||
|
||
多平台热点数据采集和管理。
|
||
|
||
#### 爬虫列表
|
||
|
||
| 爬虫 | 类 | 状态 | 说明 |
|
||
|-----|-----|------|------|
|
||
| 百度热搜 | `BaiduCrawler` | ✅ | 实时热点 + 旅游榜 |
|
||
| 节日日历 | `CalendarCrawler` | ✅ | 预设节日数据 |
|
||
| 小红书 | `XiaohongshuCrawler` | ✅ | MediaCrawler 集成 |
|
||
| Bing | `BingCrawler` | ✅ | 搜索建议 |
|
||
| 微博 | `WeiboCrawler` | ⚠️ | 需要优化 |
|
||
|
||
#### 架构设计
|
||
|
||
```
|
||
HotspotManager (热点管理器)
|
||
├── BaiduCrawler
|
||
├── BingCrawler
|
||
├── CalendarCrawler
|
||
├── XiaohongshuCrawler (→ XHSCrawlerBridge → MediaCrawler)
|
||
└── WeiboCrawler
|
||
```
|
||
|
||
#### API 路由
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|-----|------|------|
|
||
| GET | `/api/v2/hotspot/all` | 获取所有来源 |
|
||
| GET | `/api/v2/hotspot/baidu` | 百度热搜 |
|
||
| GET | `/api/v2/hotspot/bing` | Bing 搜索 |
|
||
| GET | `/api/v2/hotspot/calendar` | 节日日历 |
|
||
| GET | `/api/v2/hotspot/xiaohongshu` | 小红书热门 |
|
||
| GET | `/api/v2/hotspot/travel` | 旅游相关聚合 |
|
||
| GET | `/api/v2/hotspot/trending` | 热门话题 |
|
||
|
||
---
|
||
|
||
### 3.3 Prompt 管理 (`domain/prompt/`)
|
||
|
||
YAML 格式的 Prompt 版本管理系统。
|
||
|
||
#### 核心组件
|
||
|
||
| 组件 | 说明 |
|
||
|-----|------|
|
||
| `PromptRegistry` | Prompt 加载、版本管理、模板渲染 |
|
||
| `ReferenceManager` | 参考文献库管理 (标题/正文范例) |
|
||
|
||
#### Prompt YAML 结构
|
||
|
||
```yaml
|
||
meta:
|
||
name: topic_generate
|
||
version: "2.0.0"
|
||
description: "选题生成"
|
||
|
||
model:
|
||
temperature: 0.2
|
||
top_p: 0.3
|
||
|
||
variables:
|
||
- name: style
|
||
type: object
|
||
required: true
|
||
|
||
system_prompt: |
|
||
你是一个小红书内容策划专家...
|
||
|
||
user_prompt: |
|
||
请根据以下信息生成选题:
|
||
风格: {{ style.name }}
|
||
```
|
||
|
||
#### 参考文献库
|
||
|
||
位置: `prompts/reference/`
|
||
|
||
| 文件 | 说明 |
|
||
|-----|------|
|
||
| `titles.yaml` | 55+ 爆款标题模板 |
|
||
| `contents.yaml` | 10+ 完整正文范例 |
|
||
| `index.yaml` | 配置索引 |
|
||
|
||
---
|
||
|
||
### 3.4 海报模块 (`domain/poster/` + `poster/`)
|
||
|
||
自动生成配图海报。
|
||
|
||
#### 组件
|
||
|
||
| 组件 | 说明 |
|
||
|-----|------|
|
||
| `PosterServiceV2` | 轻量服务，无数据库依赖 |
|
||
| `PosterRenderer` | 渲染引擎 |
|
||
| `TemplateManager` | 模板管理 |
|
||
| `FabricGenerator` | Fabric.js JSON 输出 |
|
||
|
||
#### 模板
|
||
|
||
| 模板 | 说明 |
|
||
|-----|------|
|
||
| `vibrant` | 活力风格 |
|
||
| `business` | 商务风格 |
|
||
| `collage` | 拼图风格 |
|
||
|
||
---
|
||
|
||
### 3.5 MediaCrawler 集成 (`libs/MediaCrawler/`)
|
||
|
||
第三方社交媒体爬虫项目。
|
||
|
||
- **来源**: https://github.com/NanmiCoder/MediaCrawler
|
||
- **支持平台**: 小红书、抖音、微博、B站、快手、知乎、贴吧
|
||
- **桥接器**: `domain/hotspot/crawlers/mediacrawler/xhs_crawler.py`
|
||
|
||
---
|
||
|
||
## 四、API 概览
|
||
|
||
### V2 API (主要使用)
|
||
|
||
| 路由前缀 | 说明 |
|
||
|---------|------|
|
||
| `/api/v2/aigc` | AIGC 统一接口 |
|
||
| `/api/v2/hotspot` | 热点数据 |
|
||
| `/api/v2/reference` | 参考文献管理 |
|
||
|
||
### V1 API (部分保留)
|
||
|
||
| 路由前缀 | 状态 |
|
||
|---------|------|
|
||
| `/api/v1/prompt` | ✅ 可用 |
|
||
| `/api/v1/tweet` | ❌ 已禁用 |
|
||
| `/api/v1/poster` | ❌ 已禁用 |
|
||
|
||
---
|
||
|
||
## 五、配置文件
|
||
|
||
| 文件 | 说明 |
|
||
|-----|------|
|
||
| `config/ai_model.json` | AI 模型配置 (API Key, Model) |
|
||
| `config/engines.json` | 引擎配置 |
|
||
| `config/poster_gen.json` | 海报生成配置 |
|
||
| `config/paths.json` | 路径配置 |
|
||
| `config/database.json` | 数据库配置 (遗留) |
|
||
|
||
---
|
||
|
||
## 六、快速启动
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 启动服务
|
||
cd /root/TravelContentCreator
|
||
PYTHONPATH=. uvicorn api.main:app --host 0.0.0.0 --port 8001
|
||
|
||
# 测试
|
||
curl http://localhost:8001/
|
||
curl http://localhost:8001/api/v2/hotspot/baidu?limit=10
|
||
```
|
||
|
||
---
|
||
|
||
## 七、文档索引
|
||
|
||
| 文档 | 说明 |
|
||
|-----|------|
|
||
| `PROJECT_OVERVIEW.md` | 项目总览 (本文档) |
|
||
| `PROJECT_STATUS.md` | 详细项目状态 |
|
||
| `HOTSPOT_MODULE.md` | 热点模块文档 |
|
||
| `NEXT_PHASE_PLAN.md` | 下阶段计划 |
|
||
| `POSTER_REFACTOR_PLAN.md` | 海报重构计划 |
|
||
| `TECHNICAL_DEBT.md` | 技术债务分析 |
|
||
| `JAVA_MIGRATION_GUIDE.md` | Java 端迁移指南 |
|
||
| `ARCHITECTURE_V2_MAINTAINABLE.md` | 架构设计 V2 |
|
||
|
||
---
|
||
|
||
## 八、技术债务 (摘要)
|
||
|
||
详见 `docs/TECHNICAL_DEBT.md`
|
||
|
||
| 问题 | 优先级 |
|
||
|-----|--------|
|
||
| 数据库双端访问 | 🔴 高 |
|
||
| ppid/sid/pid 混乱 | 🔴 高 |
|
||
| 图片 Base64 传输 | 🟡 中 |
|
||
| 临时文件堆积 (943MB) | 🟡 中 |
|
||
| 巨型文件 (poster.py 3031行) | 🟡 中 |
|
||
|
||
---
|
||
|
||
## 九、模块依赖关系
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ API Layer │
|
||
│ api/routers/aigc.py hotspot.py reference.py prompt.py │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Domain Layer │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ aigc │ │ hotspot │ │ prompt │ │ poster │ │
|
||
│ │ engines │ │ crawlers │ │ registry │ │ service │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Infrastructure │
|
||
│ prompts/ config/ libs/MediaCrawler poster/templates │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 十、版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|-----|------|------|
|
||
| 2.3.0 | 2024-12-10 | 热点模块增强，MediaCrawler 集成 |
|
||
| 2.2.0 | 2024-12-09 | 海报服务重构，参考文献库 |
|
||
| 2.1.0 | 2024-12-08 | V2 AIGC API，Prompt Registry |
|
||
| 2.0.0 | 2024-12-07 | 架构重构 |
|