整体架构设计
# ============================================
# 项目结构
# ============================================
"""
tutorial-generator/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI应用
│ ├── config.py # 配置
│ └── database.py # 数据库
│
├── core/
│ ├── llm/
│ │ ├── client.py # LLM客户端（带重试）
│ │ ├── prompt_template.py # 提示词模板引擎
│ │ └── rate_limiter.py # 速率限制
│ │
│ ├── generators/
│ │ ├── text_generator.py
│ │ └── image_generator.py
│ │
│ ├── executor/
│ │ ├── parallel_executor.py # 并行执行器
│ │ └── retry_handler.py # 重试机制
│ │
│ └── validators/
│ └── content_validator.py # 内容验证
│
├── pipelines/
│ ├── base_pipeline.py
│ └── batch_tutorial_pipeline.py # 批量教程Pipeline
│
├── templates/ # Jinja2模板
│ ├── base.html
│ ├── task_create.html
│ ├── task_monitor.html
│ └── preview.html
│
├── static/
│ ├── css/
│ └── js/
│
├── prompts/ # 提示词模板
│ ├── system/
│ │ ├── tutorial_writer.jinja2
│ │ └── code_expert.jinja2
│ └── user/
│ ├── chapter_text.jinja2
│ └── chapter_image.jinja2
│
└── requirements.txt
"""
架构设计方案
一、系统架构图
┌─────────────────────────────────────────────────────────────┐
│ 前端层 (Web UI) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 任务创建页面 │ │ 执行监控页面 │ │ 预览发布页面 │ │
│ │ (Alpine.js) │ │ (WebSocket) │ │ (Markdown) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
↕ HTTP/WebSocket
┌─────────────────────────────────────────────────────────────┐
│ API层 (FastAPI) │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ 任务管理API │ │ 执行API │ │ 发布API │ │
│ │ CRUD │ │ Execute │ │ GitHub │ │
│ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ 业务逻辑层 (Core) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Pipeline 编排引擎 │ │
│ │ • 选择Pipeline • 协调执行 • 状态管理 │ │
│ └──────────────────────────────────────────────────────┘ │
│ ↕ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 并行执行引擎 (Executor) │ │
│ │ • 任务队列 • 并发控制 • 进度追踪 • 结果聚合 │ │
│ └──────────────────────────────────────────────────────┘ │
│ ↙ ↓ ↓ ↘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │重试机制 │ │速率限制 │ │内容验证 │ │错误处理 │ │
│ │Handler │ │Limiter │ │Validator │ │Handler │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ 原子能力层 (Generators) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 文本生成器 │ │ 图片生成器 │ │ 格式化器 │ │
│ │ TextGen │ │ ImageGen │ │ Formatter │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ↓ ↓ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 提示词模板引擎 (Jinja2) │ │
│ │ • 系统提示词 • 用户提示词 • 上下文注入 │ │
│ └──────────────────────────────────────────────────────┘ │
│ ↓ ↓ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Claude Client│ │ OpenAI Client│ │
│ │ (重试+超时) │ │ (重试+超时) │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ 基础设施层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 数据库 │ │ 文件存储 │ │ GitHub API │ │
│ │ SQLite/PG │ │ Local FS │ │ Publisher │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
二、数据流设计
2.1 任务创建流程
用户输入配置
↓
验证配置完整性
↓
选择Pipeline
↓
保存到数据库（状态：DRAFT）
↓
返回任务ID
2.2 任务执行流程
点击执行按钮
↓
加载任务配置 + Pipeline
↓
Pipeline预处理（构建任务DAG）
↓
┌─────────────────────────────────────┐
│ 并行执行引擎启动 │
│ │
│ 1. 构建任务列表（文本+图片） │
│ 2. 按依赖关系分组 │
│ 3. 使用信号量控制并发数 │
│ │
│ 执行循环： │
│ ┌────────────────────────────┐ │
│ │ while 有待执行任务: │ │
│ │ 取一批任务（并发限制内） │ │
│ │ ↓ │ │
│ │ 调用LLM（带重试） │ │
│ │ ↓ │ │
│ │ 验证结果 │ │
│ │ ↓ │ │
│ │ 保存结果/错误 │ │
│ │ ↓ │ │
│ │ 更新进度（WebSocket推送） │ │
│ │ ↓ │ │
│ │ 继续下一批 │ │
│ └────────────────────────────┘ │
└─────────────────────────────────────┘
↓
聚合结果（成功+失败）
↓
生成Markdown文件
↓
更新任务状态（COMPLETED/PARTIAL）
↓
通知前端完成
2.3 预览和发布流程
任务执行完成
↓
前端加载生成的Markdown
↓
用户预览（可编辑）
↓
用户确认
↓
点击发布按钮
↓
合并所有章节
↓
提交到GitHub（PR或直接Push）
↓
更新任务状态（PUBLISHED）
三、关键模块设计
3.1 并行执行引擎（核心）
设计要点：
- 任务分组策略
- 按章节依赖关系构建DAG
- 无依赖的章节可完全并行
- 有依赖的章节按层级执行
- 并发控制
- 使用
asyncio.Semaphore限制同时进行的请求数 - 文本和图片生成可以并行
- 同一章节的多张图片可以并行
- 使用
- 任务队列
待执行队列 → 执行中队列 → 完成队列
↓
失败队列（重试）
- 进度追踪
- 实时计算：已完成/总任务数
- 通过WebSocket推送进度到前端
- 记录每个任务的状态、耗时、重试次数
3.2 重试机制
三层重试策略：
层级处理对象重试条件策略L1: LLM客户端单个API调用速率限制、超时、网络错误指数退避（2s, 4s, 8s）L2: 生成器单个任务返回内容验证失败立即重试3次L3: 执行器批次任务整体失败率>30%暂停并报警
错误分类：
python
可重试错误：
- RateLimitError（速率限制）
- TimeoutError（超时）
- InvalidResponseError（内容不符合预期）
不可重试错误：
- AuthenticationError（API密钥错误）
- InvalidConfigError（配置错误）
- SystemError（系统错误）
3.3 内容验证机制
验证层级：
1. 基础验证（快速）
- 非空检查
- 最小长度检查
- 格式检查（是否为Markdown）
2. 结构验证（中速）
- 标题层级是否正确
- 是否包含必需的代码块
- 图片链接是否有效
3. 质量验证（慢速，可选）
- 内容相关性（使用Embedding）
- 术语一致性
- 逻辑连贯性
3.4 提示词模板系统
目录结构：
prompts/
├── system/ # 系统提示词
│ ├── tutorial_writer.jinja2
│ ├── code_expert.jinja2
│ └── image_designer.jinja2
├── user/ # 用户提示词
│ ├── chapter_text.jinja2
│ ├── chapter_code.jinja2
│ └── chapter_image.jinja2
└── includes/ # 可复用片段
├── terminology.jinja2
├── style_guide.jinja2
└── reference_docs.jinja2
模板变量设计：
jinja2
{# 全局变量 #}
{{ tutorial_theme }} # 教程主题
{{ target_audience }} # 目标读者
{{ difficulty_level }} # 难度等级
{# 上下文变量 #}
{{ previous_chapters }} # 前文章节摘要
{{ terminology }} # 术语表
{{ code_dependencies }} # 代码依赖关系
{# 章节变量 #}
{{ chapter.title }}
{{ chapter.level }}
{{ chapter.core_content }}
{{ chapter.key_points }}
{# 参考资料 #}
{{ reference_docs }} # 参考文档列表
{{ style_guide }} # 写作规范
四、Pipeline设计模式
4.1 Pipeline基类接口
python
class BasePipeline(ABC):
"""所有Pipeline必须实现的接口"""
@abstractmethod
async def execute(self, task_config: Dict) -> Dict:
"""执行Pipeline，返回生成结果"""
pass
@abstractmethod
def get_metadata(self) -> Dict:
"""返回Pipeline元数据（用于前端展示）"""
pass
@abstractmethod
def validate_config(self, config: Dict) -> bool:
"""验证配置是否符合此Pipeline的要求"""
pass
def pre_process(self, config: Dict) -> Dict:
"""预处理：构建任务DAG"""
pass
def post_process(self, results: Dict) -> Dict:
"""后处理：整合结果、生成目录"""
pass
4.2 Pipeline类型设计
Pipeline名称适用场景特点并行策略SimplePipeline纯文本教程只生成文本，无图片章节间完全并行StandardPipeline标准教程文本+少量图片文本和图片并行RichPipeline富媒体教程文本+大量图片+代码按章节分批，批内并行APIPipelineAPI文档结构化强，模板驱动按接口并行生成
4.3 Pipeline参数化
python
pipeline_params = {
"concurrency": {
"max_concurrent_chapters": 5, # 最多同时生成5个章节
"max_concurrent_images": 10, # 最多同时生成10张图片
},
"retry": {
"max_retries": 3,
"retry_delay": 2.0,
},
"validation": {
"enable_quality_check": True,
"min_word_count": 800,
},
"llm": {
"text_model": "claude-sonnet-4-5",
"image_model": "dall-e-3",
"temperature": 0.7,
}
}
五、前端交互设计
5.1 页面流转
1. 任务创建页 (/)
- 输入基本信息
- 配置章节列表
- 配置提示词模板
- 选择Pipeline
↓
2. 执行监控页 (/tasks/{id}/monitor)
- 实时显示进度条
- 显示各章节状态
- 显示错误信息
- 支持暂停/继续
↓
3. 预览页 (/tasks/{id}/preview)
- 章节列表（树形结构）
- Markdown预览（可编辑）
- 下载按钮
↓
4. 发布页 (/tasks/{id}/publish)
- 配置GitHub仓库
- 选择提交方式（PR/Push）
- 确认发布
5.2 WebSocket实时通信
消息格式：
json
{
"type": "progress_update",
"task_id": "task_123",
"data": {
"total": 100,
"completed": 45,
"failed": 2,
"current": "chapter_05_text",
"status": "running"
}
}
{
"type": "task_complete",
"task_id": "task_123",
"data": {
"status": "success",
"output_path": "/output/task_123",
"stats": {...}
}
}
{
"type": "error",
"task_id": "task_123",
"data": {
"chapter_id": "chapter_03",
"error_message": "Rate limit exceeded",
"retry_count": 2
}
}
六、数据库设计
sql
-- 任务表
CREATE TABLE tasks (
id VARCHAR(50) PRIMARY KEY,
name VARCHAR(200),
config TEXT, -- JSON格式的完整配置
pipeline VARCHAR(50),
status VARCHAR(20), -- draft, running, completed, failed, published
progress INT DEFAULT 0, -- 0-100
output_path VARCHAR(500),
error_message TEXT,
created_at TIMESTAMP,
updated_at TIMESTAMP,
completed_at TIMESTAMP
);
-- 章节结果表
CREATE TABLE chapter_results (
id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id VARCHAR(50),
chapter_id VARCHAR(100),
status VARCHAR(20), -- pending, running, success, failed
content TEXT, -- 生成的Markdown内容
error_message TEXT,
retries INT DEFAULT 0,
duration FLOAT, -- 生成耗时（秒）
created_at TIMESTAMP,
FOREIGN KEY (task_id) REFERENCES tasks(id)
);
-- 执行日志表
CREATE TABLE execution_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id VARCHAR(50),
level VARCHAR(10), -- info, warning, error
message TEXT,
timestamp TIMESTAMP,
FOREIGN KEY (task_id) REFERENCES tasks(id)
);
七、文件组织结构
tutorial-generator/
├── app/
│ ├── main.py # FastAPI应用入口
│ ├── config.py # 配置管理
│ ├── database.py # 数据库连接
│ └── websocket.py # WebSocket管理
│
├── core/
│ ├── llm/
│ │ ├── base_client.py # 基础客户端（重试、超时）
│ │ ├── claude_client.py
│ │ ├── openai_client.py
│ │ └── rate_limiter.py # 速率限制器
│ │
│ ├── templates/
│ │ └── prompt_engine.py # Jinja2模板引擎
│ │
│ ├── generators/
│ │ ├── text_generator.py # 文本生成（原子能力）
│ │ ├── image_generator.py # 图片生成（原子能力）
│ │ └── formatter.py # Markdown格式化
│ │
│ ├── executor/
│ │ ├── parallel_executor.py # 并行执行引擎
│ │ ├── task_queue.py # 任务队列管理
│ │ └── progress_tracker.py # 进度追踪
│ │
│ ├── validators/
│ │ ├── content_validator.py # 内容验证
│ │ └── config_validator.py # 配置验证
│ │
│ └── handlers/
│ ├── retry_handler.py # 重试处理
│ └── error_handler.py # 错误处理
│
├── pipelines/
│ ├── base.py # Pipeline基类
│ ├── registry.py # Pipeline注册器
│ ├── simple_pipeline.py
│ ├── standard_pipeline.py
│ └── rich_pipeline.py
│
├── api/
│ ├── tasks.py # 任务CRUD API
│ ├── execution.py # 执行控制API
│ ├── preview.py # 预览API
│ └── publish.py # 发布API
│
├── models/ # SQLAlchemy模型
│ ├── task.py
│ ├── chapter_result.py
│ └── execution_log.py
│
├── schemas/ # Pydantic Schema
│ ├── task_schema.py
│ ├── chapter_schema.py
│ └── pipeline_schema.py
│
├── templates/ # Jinja2 HTML模板
│ ├── base.html
│ ├── task_create.html
│ ├── task_monitor.html
│ ├── preview.html
│ └── publish.html
│
├── prompts/ # LLM提示词模板
│ ├── system/
│ ├── user/
│ └── includes/
│
├── static/
│ ├── css/
│ │ └── main.css
│ └── js/
│ ├── alpine-components.js # Alpine.js组件
│ └── websocket-client.js # WebSocket客户端
│
├── output/ # 生成文件输出
│ └── tasks/
│
├── tests/
│ ├── test_executor/
│ ├── test_pipelines/
│ └── test_validators/
│
├── requirements.txt
├── .env.example
└── README.md
八、技术栈总结
层级技术选型理由Web框架FastAPI异步支持、类型安全、自动文档模板引擎Jinja2强大、灵活、与FastAPI集成好前端框架Alpine.js轻量、易学、适合渐进增强数据库SQLite → PostgreSQL开发用SQLite，生产用PGORMSQLAlchemy成熟、功能全面异步库asyncio + aiohttpPython原生、性能好LLM SDKanthropic + openai官方SDK重试库tenacity灵活的重试策略提示词模板Jinja2复用HTML模板引擎进度通信WebSocket实时双向通信任务队列（可选）Celery + Redis如需分布式
0