jinye_huang/TravelContentCreator
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

增加了文档，完成了生文模块

Browse Source
This commit is contained in:
jinye_huang 2025-07-09 16:33:38 +08:00
parent a7cd96ecb8
commit 8326485d8a
3 changed files with 1025 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
README.md Normal file
View File

@ -0,0 +1,230 @@
# 旅游内容自动生成系统
## 系统概述
旅游内容自动生成系统是一个基于AI的内容创作平台，专注于为旅游景点和产品生成营销内容。系统采用三阶段生成流程：选题生成、内容创作和内容审核，每个阶段都由专门的AI模型处理，并通过配置文件进行精细控制。
## 系统架构
系统由以下主要模块组成：
### 核心模块 (core)
- **config**: 配置管理，负责加载和管理各种配置
- **ai**: AI代理，处理与大模型的交互
- **exception**: 异常处理
### 工具模块 (utils)
- **file_io**: 文件输入输出，包括ResourceLoader和OutputManager
- **prompts**: 提示词模板和构建器
- **pipeline**: 流程管理
- **tweet**: 内容生成相关模块，包括topic_generator、content_generator、content_judger
## 功能模块
### 1. 选题生成 (TopicGenerator)
根据指定月份和节日生成旅游营销选题，考虑目标受众、营销风格和产品特性，输出标准化JSON格式的选题信息。
**主要功能**:
- 基于时间节点生成选题
- 考虑产品特性和目标受众
- 输出结构化选题数据
### 2. 内容创作 (ContentGenerator)
基于选题生成小红书风格的营销文案，包含吸引人的标题、详细正文和SEO优化的标签，遵循特定的文案风格和目标受众需求。
**主要功能**:
- 生成符合平台特性的标题
- 创建详细、有吸引力的正文
- 生成优化的标签
### 3. 内容审核 (ContentJudger)
审核生成内容是否符合产品资料，检查价格、活动、服务等关键信息的准确性，保留原始内容中的标签和引流语句。
**主要功能**:
- 检查内容准确性
- 修正不符合产品资料的内容
- 保留原始内容中的关键元素
## 配置说明
系统通过JSON配置文件管理各组件参数：
### 系统配置 (system.json)
```json
{
"debug": false,
"log_level": "INFO",
"parallel_processing": false,
"max_workers": 4
}
```
### AI模型配置 (ai_model.json)
```json
{
"model": "qwen-plus",
"api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "your_api_key",
"temperature": 0.3,
"top_p": 0.4,
"presence_penalty": 1.2,
"timeout": 120,
"max_retries": 3
}
```
### 资源配置 (resource.json)
```json
{
"resource_dirs": ["."],
"style": {
"paths": ["resource/prompt/Style/攻略风文案提示词.md", "..."]
},
"demand": {
"paths": ["resource/prompt/Demand/亲子向文旅需求.md", "..."]
},
"refer": {
"refer_list": [
{ "path": "resource/prompt/Refer/2025各月节日宣传节点时间表.md", "sampling_rate": 1, "step": "topic" },
{ "path": "resource/prompt/Refer/标题参考格式.json", "sampling_rate": 0.25, "step": "content" },
{ "path": "resource/prompt/Refer/正文范文参考.json", "sampling_rate": 0.5, "step": "content" }
]
},
"object": {
"paths": ["resource/data/Object/天津冒险湾.txt"]
},
"product": {
"paths": ["resource/data/Product/天津冒险湾-2大2小套票.txt"]
},
"output_dir": {
"base_dir": "result"
}
}
```
### 选题生成配置 (topic_gen.json)
```json
{
"topic_system_prompt": "resource/prompt/generateTopics/system.txt",
"topic_user_prompt": "resource/prompt/generateTopics/user.txt",
"model": {
"temperature": 0.2,
"top_p": 0.3,
"presence_penalty": 1.5
},
"topic": {
"date": "2024-07-20",
"num": 5,
"variants": 1
}
}
```
### 内容生成配置 (content_gen.json)
```json
{
"content_system_prompt": "resource/prompt/generateContent/system.txt",
"content_user_prompt": "resource/prompt/generateContent/user.txt",
"judger_system_prompt": "resource/prompt/judgeContent/system.txt",
"judger_user_prompt": "resource/prompt/judgeContent/user.txt",
"enable_content_judge": true,
"model": {
"temperature": 0.3,
"top_p": 0.5,
"presence_penalty": 1.2
},
"judger_model": {
"temperature": 0.2,
"top_p": 0.3,
"presence_penalty": 0.8
}
}
```
## 使用指南
### 安装依赖
```bash
pip install -r requirements.txt
```
### 运行系统
```bash
python main.py --config_dir config --run_id custom_run_id
```
参数说明:
- `--config_dir`: 配置文件目录路径，默认为 "config"
- `--run_id`: 运行ID，用于标识本次运行，默认为时间戳格式
### 输出结果
系统运行后，会在 `result/{run_id}` 目录下生成以下文件:
- `topics_generated.json`: 生成的选题列表
- `topics_generated.txt`: 人类可读的选题列表
- 每个选题的子目录 `topic_{index}`:
- `content_system_prompt.txt`: 内容生成的系统提示
- `content_user_prompt.txt`: 内容生成的用户提示
- `content_raw_response.txt`: AI返回的原始响应
- `article.json`: 生成的文章内容
- `judger_system_prompt.txt`: 审核的系统提示
- `judger_user_prompt.txt`: 审核的用户提示
- `judger_raw_response.txt`: 审核的原始响应
- `article_judged.json`: 审核后的文章内容
## 系统特性
1. **资源加载增强**:
- 支持基于文件名(不含后缀)的模糊匹配
- 对JSON文件内容的直接采样
2. **引用内容的阶段控制**:
- 通过step字段控制在不同阶段(topic/content/judge)使用哪些引用资源
- 通过采样率控制参考内容的使用量
3. **模型参数独立配置**:
- 为不同生成阶段配置独立的模型参数
- 提高各阶段生成内容的质量和多样性
4. **内容审核系统**:
- 保留原始内容中的tags标签
- 对价格、活动等关键信息进行审核
5. **文件IO系统**:
- 灵活的资源加载和输出管理
- 结构化的文件组织方式
## 目录结构
```
.
├── main.py # 主程序入口
├── config/ # 配置文件目录
│ ├── ai_model.json # AI模型配置
│ ├── content_gen.json # 内容生成配置
│ ├── resource.json # 资源配置
│ ├── system.json # 系统配置
│ └── topic_gen.json # 选题生成配置
├── core/ # 核心模块
│ ├── ai/ # AI代理
│ ├── config/ # 配置管理
│ └── exception/ # 异常处理
├── utils/ # 工具模块
│ ├── file_io.py # 文件IO
│ ├── pipeline.py # 流程管理
│ ├── prompts.py # 提示词构建
│ └── tweet/ # 内容生成相关
│ ├── content_generator.py # 内容生成器
│ ├── content_judger.py # 内容审核器
│ └── topic_generator.py # 选题生成器
├── resource/ # 资源文件
│ ├── data/ # 数据文件
│ └── prompt/ # 提示词模板
├── result/ # 输出结果
└── requirements.txt # 依赖包
```

309
docs/使用指南.md Normal file
View File

@ -0,0 +1,309 @@
# 旅游内容自动生成系统 - 使用指南
## 1. 系统概述
旅游内容自动生成系统是一个基于AI的内容创作平台，专注于为旅游景点和产品生成营销内容。系统采用三阶段生成流程：选题生成、内容创作和内容审核，每个阶段都由专门的AI模型处理，并通过配置文件进行精细控制。
## 2. 环境准备
### 系统要求
- Python 3.8+
- 足够的内存（推荐8GB以上）
- 互联网连接（用于API调用）
### 安装依赖
```bash
# 克隆仓库
git clone [仓库地址]
cd [仓库名称]
# 安装依赖包
pip install -r requirements.txt
```
## 3. 配置系统
系统通过JSON配置文件进行控制，所有配置文件位于`config`目录下：
### 3.1 AI模型配置 (ai_model.json)
```json
{
"model": "qwen-plus", // 使用的模型名称
"api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", // API地址
"api_key": "your_api_key", // 替换为您的API密钥
"temperature": 0.3, // 生成多样性控制
"top_p": 0.4, // 采样控制
"presence_penalty": 1.2, // 重复惩罚
"timeout": 120, // API超时时间（秒）
"max_retries": 3 // 最大重试次数
}
```
> **重要提示**: 请替换`your_api_key`为您的实际API密钥。
### 3.2 选题生成配置 (topic_gen.json)
```json
{
"topic_system_prompt": "resource/prompt/generateTopics/system.txt", // 系统提示路径
"topic_user_prompt": "resource/prompt/generateTopics/user.txt", // 用户提示路径
"model": {
"temperature": 0.2, // 选题生成的温度参数
"top_p": 0.3, // 选题生成的top_p参数
"presence_penalty": 1.5 // 选题生成的重复惩罚参数
},
"topic": {
"date": "2024-07-20", // 选题目标日期
"num": 5, // 生成选题数量
"variants": 1 // 每个选题的变体数量
}
}
```
### 3.3 内容生成配置 (content_gen.json)
```json
{
"content_system_prompt": "resource/prompt/generateContent/system.txt", // 内容生成系统提示
"content_user_prompt": "resource/prompt/generateContent/user.txt", // 内容生成用户提示
"judger_system_prompt": "resource/prompt/judgeContent/system.txt", // 审核系统提示
"judger_user_prompt": "resource/prompt/judgeContent/user.txt", // 审核用户提示
"enable_content_judge": true, // 是否启用内容审核
"model": {
"temperature": 0.3, // 内容生成温度参数
"top_p": 0.5, // 内容生成top_p参数
"presence_penalty": 1.2 // 内容生成重复惩罚参数
},
"judger_model": {
"temperature": 0.2, // 内容审核温度参数
"top_p": 0.3, // 内容审核top_p参数
"presence_penalty": 0.8 // 内容审核重复惩罚参数
}
}
```
### 3.4 资源配置 (resource.json)
```json
{
"resource_dirs": ["."], // 资源基础目录
"style": {
"paths": [ // 文案风格文件路径
"resource/prompt/Style/攻略风文案提示词.md",
"resource/prompt/Style/极力推荐风文案提示词.md"
]
},
"demand": {
"paths": [ // 用户需求文件路径
"resource/prompt/Demand/亲子向文旅需求.md",
"resource/prompt/Demand/周边游文旅需求.md"
]
},
"refer": {
"refer_list": [ // 参考资料配置
{
"path": "resource/prompt/Refer/2025各月节日宣传节点时间表.md",
"sampling_rate": 1, // 采样率，1表示100%使用
"step": "topic" // 使用阶段：topic/content/judge
},
{
"path": "resource/prompt/Refer/标题参考格式.json",
"sampling_rate": 0.25,
"step": "content"
},
{
"path": "resource/prompt/Refer/正文范文参考.json",
"sampling_rate": 0.5,
"step": "content"
}
]
},
"object": {
"paths": [ // 景点对象文件路径
"resource/data/Object/天津冒险湾.txt"
]
},
"product": {
"paths": [ // 产品信息文件路径
"resource/data/Product/天津冒险湾-2大2小套票.txt"
]
},
"output_dir": {
"base_dir": "result" // 输出目录
}
}
```
### 3.5 系统配置 (system.json)
```json
{
"debug": false, // 是否开启调试模式
"log_level": "INFO", // 日志级别
"parallel_processing": false, // 是否启用并行处理
"max_workers": 4 // 最大工作线程数
}
```
## 4. 运行系统
### 4.1 基本运行命令
```bash
python main.py
```
这将使用默认配置运行系统。
### 4.2 自定义运行参数
```bash
python main.py --config_dir custom_config --run_id my_run_20240601
```
参数说明:
- `--config_dir`: 配置文件目录路径，默认为 "config"
- `--run_id`: 运行ID，用于标识本次运行，默认为时间戳格式
## 5. 输出结果
系统运行后，会在 `result/{run_id}` 目录下生成以下文件:
- `topics_generated.json`: 生成的选题列表（JSON格式）
- `topics_generated.txt`: 人类可读的选题列表（文本格式）
- 每个选题的子目录 `topic_{index}`:
- `content_system_prompt.txt`: 内容生成的系统提示
- `content_user_prompt.txt`: 内容生成的用户提示
- `content_raw_response.txt`: AI返回的原始响应
- `article.json`: 生成的文章内容
- `judger_system_prompt.txt`: 审核的系统提示（如果启用审核）
- `judger_user_prompt.txt`: 审核的用户提示（如果启用审核）
- `judger_raw_response.txt`: 审核的原始响应（如果启用审核）
- `article_judged.json`: 审核后的文章内容（如果启用审核）
## 6. 资源文件准备
### 6.1 提示词模板
系统使用以下提示词模板：
- **选题生成**:
- `resource/prompt/generateTopics/system.txt`: 选题生成系统提示
- `resource/prompt/generateTopics/user.txt`: 选题生成用户提示
- **内容生成**:
- `resource/prompt/generateContent/system.txt`: 内容生成系统提示
- `resource/prompt/generateContent/user.txt`: 内容生成用户提示
- **内容审核**:
- `resource/prompt/judgeContent/system.txt`: 内容审核系统提示
- `resource/prompt/judgeContent/user.txt`: 内容审核用户提示
### 6.2 风格和需求文件
- **风格文件** (`resource/prompt/Style/`):
- 每个文件描述一种文案风格
- 例如：`攻略风文案提示词.md`, `极力推荐风文案提示词.md`
- **需求文件** (`resource/prompt/Demand/`):
- 每个文件描述一种用户需求
- 例如：`亲子向文旅需求.md`, `周边游文旅需求.md`
### 6.3 参考资料文件
- **参考资料** (`resource/prompt/Refer/`):
- 节日时间表：`2025各月节日宣传节点时间表.md`
- 标题参考：`标题参考格式.json`
- 正文参考：`正文范文参考.json`
### 6.4 产品和景点数据
- **景点数据** (`resource/data/Object/`):
- 每个文件包含一个景点的详细信息
- 例如：`天津冒险湾.txt`
- **产品数据** (`resource/data/Product/`):
- 每个文件包含一个产品的详细信息
- 例如：`天津冒险湾-2大2小套票.txt`
## 7. 常见问题解答
### 7.1 系统运行失败
**问题**: 系统运行时出现错误或无法生成内容。
**解决方案**:
1. 检查API密钥是否正确配置
2. 检查网络连接是否正常
3. 查看日志输出，定位具体错误
4. 确保所有资源文件路径正确且文件存在
### 7.2 生成内容质量不佳
**问题**: 生成的内容质量不符合预期。
**解决方案**:
1. 调整模型参数（temperature、top_p、presence_penalty）
2. 改进提示词模板
3. 提供更高质量的参考资料
4. 确保产品和景点信息详尽准确
### 7.3 审核功能不生效
**问题**: 内容审核功能似乎没有生效。
**解决方案**:
1. 检查`content_gen.json`中的`enable_content_judge`是否设为`true`
2. 确保审核提示词模板存在且路径正确
3. 检查日志中是否有审核相关的错误信息
### 7.4 如何添加新的景点或产品
**步骤**:
1. 在`resource/data/Object/`目录下创建新的景点文件
2. 在`resource/data/Product/`目录下创建新的产品文件
3. 更新`resource.json`中的`object.paths`和`product.paths`数组
4. 重新运行系统
### 7.5 如何自定义生成内容的风格
**步骤**:
1. 在`resource/prompt/Style/`目录下创建新的风格文件
2. 更新`resource.json`中的`style.paths`数组
3. 在选题生成时，系统会自动考虑新添加的风格
## 8. 高级使用技巧
### 8.1 调整模型参数
不同的内容类型可能需要不同的模型参数：
- 高`temperature`（0.7-1.0）：更有创意但可能不够精确
- 低`temperature`（0.1-0.3）：更精确但可能缺乏创意
- 高`presence_penalty`：减少重复内容
- 低`top_p`：更保守的输出
### 8.2 参考内容采样率调整
通过调整`sampling_rate`参数，可以控制参考内容的使用量：
- `1.0`：全部使用
- `0.5`：使用约50%
- `0.25`：使用约25%
### 8.3 自定义提示词模板
可以根据需要修改提示词模板，但请确保：
1. 保持JSON输出格式一致
2. 不要改变关键指令
3. 测试修改后的效果
### 8.4 批量生成内容
对于需要批量生成内容的场景，可以：
1. 准备多个景点和产品数据
2. 编写脚本循环调用主程序
3. 为每次运行指定不同的`run_id`
## 9. 联系与支持
如有问题或需要支持，请联系系统管理员或开发团队。

486
docs/开发指南.md Normal file
View File

@ -0,0 +1,486 @@
# 旅游内容自动生成系统 - 开发指南
## 1. 系统架构
旅游内容自动生成系统采用模块化架构设计，主要分为核心模块(core)和工具模块(utils)两大部分。系统通过Pipeline模式协调各个组件的工作，实现从选题生成到内容审核的完整流程。
### 1.1 架构图
```
┌─────────────┐
│ 主程序 │
│ main.py │
└──────┬──────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ PipelineManager │
└───────┬───────────────────┬──────────────────┬──────────────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ TopicGenerator │ │ContentGenerator│ │ ContentJudger │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ AIAgent │
└─────────────────────────────────────────────────────────────┘
▲ ▲ ▲
│ │ │
│ │ │
┌───────┴───────┐ ┌───────┴───────┐ ┌──────┴────────┐
│PromptBuilders │ │ ResourceLoader│ │ OutputManager │
└───────────────┘ └───────────────┘ └───────────────┘
```
### 1.2 数据流
1. 配置加载: 系统启动时，ConfigManager加载所有配置文件
2. 选题生成: TopicGenerator调用AIAgent生成选题
3. 内容生成: ContentGenerator为每个选题调用AIAgent生成内容
4. 内容审核: ContentJudger审核生成的内容
5. 结果保存: OutputManager保存所有生成的内容和中间产物
## 2. 代码结构
### 2.1 目录结构
```
.
├── main.py # 主程序入口
├── config/ # 配置文件目录
│ ├── ai_model.json # AI模型配置
│ ├── content_gen.json # 内容生成配置
│ ├── resource.json # 资源配置
│ ├── system.json # 系统配置
│ └── topic_gen.json # 选题生成配置
├── core/ # 核心模块
│ ├── ai/ # AI代理
│ │ ├── __init__.py
│ │ └── ai_agent.py # AI代理实现
│ ├── config/ # 配置管理
│ │ ├── __init__.py
│ │ └── config_manager.py # 配置管理器
│ └── exception/ # 异常处理
│ ├── __init__.py
│ └── exceptions.py # 自定义异常类
├── utils/ # 工具模块
│ ├── file_io.py # 文件IO
│ ├── pipeline.py # 流程管理
│ ├── prompts.py # 提示词构建
│ └── tweet/ # 内容生成相关
│ ├── __init__.py
│ ├── content_generator.py # 内容生成器
│ ├── content_judger.py # 内容审核器
│ ├── topic_generator.py # 选题生成器
│ └── topic_parser.py # 选题解析器
├── resource/ # 资源文件
│ ├── data/ # 数据文件
│ └── prompt/ # 提示词模板
├── result/ # 输出结果
└── requirements.txt # 依赖包
```
### 2.2 主要模块说明
#### 2.2.1 核心模块 (core)
- **ai_agent.py**: 负责与AI模型的交互，封装API调用逻辑
- **config_manager.py**: 负责加载和管理配置文件
- **exceptions.py**: 定义系统自定义异常类
#### 2.2.2 工具模块 (utils)
- **file_io.py**: 提供文件读写功能，包括ResourceLoader和OutputManager
- **pipeline.py**: 实现整个生成流程的管理
- **prompts.py**: 提供提示词模板和构建功能
- **tweet/**: 内容生成相关的具体实现
- **topic_generator.py**: 选题生成器
- **content_generator.py**: 内容生成器
- **content_judger.py**: 内容审核器
- **topic_parser.py**: 选题解析器
## 3. 核心类说明
### 3.1 AIAgent 类
`AIAgent` 类是系统与AI模型交互的核心，负责发送请求并处理响应。
```python
class AIAgent:
def __init__(self, config: AIModelConfig):
# 初始化AI代理，设置API客户端
async def generate_text(
self, system_prompt: str, user_prompt: str, use_stream: bool = False,
temperature: Optional[float] = None, top_p: Optional[float] = None,
presence_penalty: Optional[float] = None, stage: str = ""
) -> Tuple[str, int, int, float]:
# 生成文本，支持流式和非流式输出
# 返回: (生成文本, 输入token数, 输出token数, 耗时)
```
### 3.2 ConfigManager 类
`ConfigManager` 类负责加载和管理配置文件。
```python
class ConfigManager:
def __init__(self):
# 初始化配置管理器
def load_from_directory(self, config_dir: str):
# 从目录加载所有配置文件
def get_config(self, config_name: str, config_class: Type[T]) -> T:
# 获取指定名称的配置对象
```
### 3.3 PipelineManager 类
`PipelineManager` 类负责协调整个内容生成流程。
```python
class PipelineManager:
def __init__(self, config_dir: str, run_id: Optional[str] = None):
# 初始化管道管理器
async def process_content_generation(self, topics: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
# 处理内容生成
async def process_content_judging(self, generated_contents: List[Dict[str, Any]]):
# 处理内容审核
async def run_pipeline(self):
# 按顺序执行整个流程
```
### 3.4 提示词构建器类
系统包含多个提示词构建器，负责构建不同阶段的提示词。
```python
class BasePromptBuilder(PromptTemplate):
# 基础提示词构建器，提供通用方法
class TopicPromptBuilder(BasePromptBuilder):
# 选题生成提示词构建器
class ContentPromptBuilder(BasePromptBuilder):
# 内容生成提示词构建器
class JudgerPromptBuilder(BasePromptBuilder):
# 内容审核提示词构建器
```
## 4. 关键流程
### 4.1 选题生成流程
1. 加载配置和资源
2. 构建系统提示和用户提示
3. 调用AI模型生成选题
4. 解析AI响应，提取选题信息
5. 保存选题结果
```python
# 在TopicGenerator.generate_topics方法中实现
async def generate_topics(self) -> Optional[List[Dict[str, Any]]]:
# 构建提示
system_prompt = self.prompt_builder.get_system_prompt()
user_prompt = self.prompt_builder.build_user_prompt(...)
# 调用AI
raw_result = await self.ai_agent.generate_text(...)
# 解析结果
topics = self.parser.parse(raw_result)
# 保存结果
self.output_manager.save_json(topics, "topics_generated.json")
return topics
```
### 4.2 内容生成流程
1. 为每个选题构建提示
2. 调用AI模型生成内容
3. 解析AI响应，提取内容信息
4. 保存生成的内容
```python
# 在ContentGenerator.generate_content_for_topic方法中实现
async def generate_content_for_topic(self, topic: Dict[str, Any]) -> Dict[str, Any]:
# 构建提示
system_prompt = self.prompt_builder.get_system_prompt()
user_prompt = self.prompt_builder.build_user_prompt(topic=topic)
# 调用AI
raw_result = await self.ai_agent.generate_text(...)
# 解析和保存结果
content_data = json.loads(raw_result)
self.output_manager.save_json(content_data, "article.json", ...)
return content_data
```
### 4.3 内容审核流程
1. 为每个生成的内容构建审核提示
2. 调用AI模型进行审核
3. 解析审核结果，提取修改后的内容
4. 保存审核后的内容
```python
# 在ContentJudger.judge_content方法中实现
async def judge_content(self, generated_content: str, topic: Dict[str, Any]) -> Dict[str, Any]:
# 构建提示
system_prompt = self.prompt_builder.get_system_prompt()
user_prompt = self.prompt_builder.build_user_prompt(...)
# 调用AI
raw_result = await self.ai_agent.generate_text(...)
# 解析结果
judged_data = json_repair_loads(raw_result)
# 保存结果
self.output_manager.save_json(judged_data, "article_judged.json", ...)
return judged_data
```
## 5. 扩展指南
### 5.1 添加新的生成阶段
要添加新的生成阶段（例如图像生成），需要以下步骤：
1. 创建新的生成器类，例如 `ImageGenerator`
2. 创建对应的提示词构建器，例如 `ImagePromptBuilder`
3. 在 `PipelineManager` 中添加新的处理方法
4. 在 `run_pipeline` 方法中调用新的处理方法
```python
# 1. 创建新的生成器类
class ImageGenerator:
def __init__(self, ai_agent, config_manager, output_manager):
# 初始化
async def generate_image_for_content(self, content):
# 生成图像的逻辑
# 2. 在PipelineManager中添加
def __init__(self, ...):
# 现有初始化代码
self.image_generator = ImageGenerator(...)
async def process_image_generation(self, contents):
# 处理图像生成的逻辑
async def run_pipeline(self):
# 现有流程代码
# 添加新阶段
if generated_contents:
await self.process_image_generation(generated_contents)
```
### 5.2 添加新的AI模型
要支持新的AI模型，需要修改 `AIAgent` 类：
1. 更新 `__init__` 方法，支持新的模型配置
2. 在 `generate_text` 方法中添加对新模型的支持
3. 更新配置文件结构
```python
class AIAgent:
def __init__(self, config: AIModelConfig):
self.config = config
if config.provider == "openai":
self.client = AsyncOpenAI(...)
elif config.provider == "new_provider":
self.client = NewProviderClient(...)
async def generate_text(self, ...):
# 根据provider选择不同的API调用方式
if self.config.provider == "openai":
# 现有OpenAI调用逻辑
elif self.config.provider == "new_provider":
# 新提供商的API调用逻辑
```
### 5.3 自定义资源加载器
要支持新的资源类型或加载方式，可以扩展 `ResourceLoader` 类：
```python
class ResourceLoader:
# 现有方法
@staticmethod
def load_special_format(file_path: str) -> Optional[Dict]:
# 加载特殊格式文件的逻辑
@staticmethod
def load_from_database(query: str) -> Optional[str]:
# 从数据库加载资源的逻辑
```
### 5.4 添加新的输出格式
要支持新的输出格式，可以扩展 `OutputManager` 类：
```python
class OutputManager:
# 现有方法
def save_html(self, content: str, filename: str, subdir: Optional[str] = None):
# 保存HTML格式的逻辑
def export_to_cms(self, content: Dict, api_endpoint: str):
# 导出到CMS系统的逻辑
```
## 6. 最佳实践
### 6.1 代码风格
- 遵循PEP 8规范
- 使用类型注解提高代码可读性
- 为所有公共方法和类提供文档字符串
- 使用异步编程处理IO密集型操作
### 6.2 错误处理
- 使用自定义异常类区分不同类型的错误
- 实现重试机制处理临时性故障
- 记录详细的错误信息，便于调试
```python
try:
result = await self.ai_agent.generate_text(...)
except RetryableError as e:
# 处理可重试错误
logger.warning(f"遇到可重试错误: {e}")
# 实现重试逻辑
except NonRetryableError as e:
# 处理不可重试错误
logger.error(f"遇到不可重试错误: {e}")
# 返回错误信息
except Exception as e:
# 处理未预期的错误
logger.critical(f"遇到未知错误: {e}", exc_info=True)
# 返回通用错误信息
```
### 6.3 性能优化
- 使用异步IO提高并发性能
- 实现缓存机制减少重复计算
- 优化提示词减少token使用量
- 使用采样率控制参考内容的使用量
### 6.4 测试策略
- 为核心功能编写单元测试
- 使用模拟对象测试AI调用
- 编写集成测试验证完整流程
- 使用参数化测试覆盖多种场景
```python
# 单元测试示例
async def test_topic_parser():
parser = TopicParser()
raw_json = '{"topics": [{"index": "1", "date": "2024-07-01", ...}]}'
topics = parser.parse(raw_json)
assert len(topics) == 1
assert topics[0]["index"] == "1"
assert topics[0]["date"] == "2024-07-01"
```
## 7. 常见问题与解决方案
### 7.1 AI调用超时
**问题**: AI模型调用经常超时。
**解决方案**:
1. 增加超时设置
2. 实现指数退避重试
3. 减少提示词长度
4. 考虑使用流式响应
```python
# 实现指数退避重试
backoff_time = 1.0
for attempt in range(max_retries):
try:
response = await client.chat.completions.create(...)
return response
except APITimeoutError:
logger.warning(f"尝试 {attempt + 1}/{max_retries} 超时")
await asyncio.sleep(backoff_time)
backoff_time *= 2 # 指数增长
```
### 7.2 内存使用过高
**问题**: 处理大量内容时内存使用过高。
**解决方案**:
1. 使用生成器处理大量数据
2. 实现批处理机制
3. 及时释放不再需要的资源
```python
# 使用生成器处理大量数据
async def process_topics_in_batches(self, topics, batch_size=5):
for i in range(0, len(topics), batch_size):
batch = topics[i:i+batch_size]
results = await self.process_batch(batch)
for result in results:
yield result
```
### 7.3 JSON解析错误
**问题**: AI返回的内容无法解析为JSON。
**解决方案**:
1. 使用更健壮的JSON解析库（如json_repair）
2. 在提示词中强调JSON格式要求
3. 实现后处理逻辑修复常见错误
```python
# 使用json_repair修复JSON
try:
data = json.loads(raw_result)
except json.JSONDecodeError:
try:
data = json_repair_loads(raw_result)
logger.warning("使用json_repair修复了JSON格式")
except Exception as e:
logger.error(f"JSON修复失败: {e}")
# 返回错误信息
```
## 8. 未来扩展方向
1. **多模态支持**: 添加图像生成和处理能力
2. **用户反馈系统**: 收集和利用用户对生成内容的反馈
3. **内容分发集成**: 与社交媒体平台API集成，自动发布内容
4. **A/B测试框架**: 比较不同提示词和参数的效果
5. **本地模型支持**: 支持本地部署的开源模型
## 9. 贡献指南
1. Fork仓库并创建功能分支
2. 编写代码并添加测试
3. 确保所有测试通过
4. 提交Pull Request并描述变更
5. 等待代码审查和合并