503 lines
17 KiB
Markdown
503 lines
17 KiB
Markdown
# Creative Studio - 项目架构说明
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端 (React) │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ Skill管理 │ │ 项目管理 │ │ 记忆系统 │ │ 审核系统 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓ HTTP/WebSocket
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 后端 (FastAPI) │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ API 层 │ │
|
||
│ │ /api/v1/skills /api/v1/projects /api/v1/memory │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ ↓ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ 核心层 │ │
|
||
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
|
||
│ │ │ GLM Client │ │Skill Mgr │ │ Agent引擎 │ │ │
|
||
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
|
||
│ │ ┌────────────┐ ┌────────────┐ │ │
|
||
│ │ │Memory Mgr │ │Review Mgr │ │ │
|
||
│ │ └────────────┘ └────────────┘ │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 外部服务 │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │ GLM-4.7 │ │ MongoDB │ │ Redis │ │
|
||
│ └────────────┘ └────────────┘ └────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 核心设计原则
|
||
|
||
1. **"Agent 固定，Skill 可配"** - 平台维护 Agent 框架，用户配置 Skills
|
||
2. **"Skill 指导行为"** - Skill 行为指导融入提示词，指导 LLM 行为
|
||
3. **"全局上下文 + 记忆系统"** - 确保多集内容一致性
|
||
4. **"全自动 + 人工审核"** - 自动创作与人工审核相结合
|
||
|
||
---
|
||
|
||
## 核心模块说明
|
||
|
||
### 1. GLM Client (GLM 客户端)
|
||
|
||
**位置**: `backend/app/core/llm/glm_client.py`
|
||
|
||
**功能**:
|
||
- 封装智谱 AI GLM-4.7 API
|
||
- 将 Skill 的行为指导融入提示词
|
||
- 支持同步和异步调用
|
||
- 错误处理和重试机制
|
||
|
||
**核心方法**:
|
||
```python
|
||
async def chat_with_skill(
|
||
skill_behavior: str, # Skill 的行为指导
|
||
user_input: str, # 用户输入
|
||
context: Dict, # 上下文信息
|
||
temperature: float # 温度参数
|
||
) -> str
|
||
```
|
||
|
||
---
|
||
|
||
### 2. Skill Manager (Skill 管理器)
|
||
|
||
**位置**: `backend/app/core/skills/skill_manager.py`
|
||
|
||
**功能**:
|
||
- 加载和解析 Skill 文件
|
||
- 提取行为指导内容
|
||
- 缓存管理
|
||
- Skill 验证
|
||
|
||
**核心方法**:
|
||
```python
|
||
async def load_skill(skill_id: str) -> Skill
|
||
async def list_skills(skill_type: str, category: str) -> List[Skill]
|
||
async def create_user_skill(skill_data: SkillCreate) -> Skill
|
||
```
|
||
|
||
---
|
||
|
||
### 3. Skill 存储结构
|
||
|
||
```
|
||
skills_storage/
|
||
├── builtin_skills/ # 内置 Skills（平台维护）
|
||
│ ├── consistency_checker/
|
||
│ │ └── SKILL.md
|
||
│ └── dialogue_writer_ancient/
|
||
│ └── SKILL.md
|
||
│
|
||
└── user_skills/ # 用户 Skills（用户创建）
|
||
└── {skill_id}/
|
||
└── SKILL.md
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Memory Manager (记忆管理器)
|
||
|
||
**位置**: `backend/app/core/memory/memory_manager.py`
|
||
|
||
**功能**:
|
||
- 事件时间线管理
|
||
- 伏笔追踪
|
||
- 人物状态变化记录
|
||
- 关系网络维护
|
||
|
||
**核心方法**:
|
||
```python
|
||
async def extract_events_from_episode(
|
||
episode_content: str,
|
||
episode_number: int
|
||
) -> List[TimelineEvent]
|
||
|
||
async def detect_foreshadowing(
|
||
episode_content: str,
|
||
episode_number: int
|
||
) -> List[ForeshadowingEvent]
|
||
|
||
async def update_character_states(
|
||
episode_content: str,
|
||
episode_number: int,
|
||
characters: List[str]
|
||
) -> Dict[str, CharacterStateChange]
|
||
```
|
||
|
||
---
|
||
|
||
### 5. Review Manager (审核管理器)
|
||
|
||
**位置**: `backend/app/core/review/review_manager.py`
|
||
|
||
**功能**:
|
||
- 多维度质量审核
|
||
- 自定义规则执行
|
||
- 问题定位和修复建议
|
||
- 审核结果聚合
|
||
|
||
**核心方法**:
|
||
```python
|
||
async def review_episode(
|
||
episode: Episode,
|
||
project: SeriesProject,
|
||
config: ReviewConfig
|
||
) -> ReviewResult
|
||
```
|
||
|
||
---
|
||
|
||
### 6. Agent 执行引擎
|
||
|
||
**位置**: `backend/app/core/agents/series_creation_agent.py`
|
||
|
||
**功能**:
|
||
- 固定的工作流框架
|
||
- 五阶段执行：结构分析 → 大纲生成 → 对话创作 → 一致性审核 → 记忆更新
|
||
- 质量控制和自动重试
|
||
|
||
**执行流程**:
|
||
```
|
||
开始
|
||
↓
|
||
1. 结构分析 (Structure Analysis)
|
||
↓
|
||
2. 大纲生成 (Outline Generation)
|
||
↓
|
||
3. 对话创作 (Dialogue Creation)
|
||
↓
|
||
4. 一致性审核 (Consistency Review)
|
||
↓ (如果未通过，重试)
|
||
5. 记忆更新 (Memory Update)
|
||
↓
|
||
完成
|
||
```
|
||
|
||
---
|
||
|
||
## 数据流设计
|
||
|
||
### Skill 行为指导融入流程
|
||
|
||
```
|
||
用户请求
|
||
↓
|
||
加载 Skill (Skill Manager)
|
||
↓
|
||
提取行为指导 (behavior_guide)
|
||
↓
|
||
构建提示词 (GLM Client)
|
||
↓
|
||
发送到 GLM-4.7
|
||
↓
|
||
返回结果
|
||
```
|
||
|
||
### 提示词构建示例
|
||
|
||
```
|
||
系统提示词:
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
你是剧集创作专家。
|
||
|
||
以下是你的行为指导（来自配置的 Skill）：
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
[Skill 的 behavior_guide 内容]
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
当前上下文：
|
||
- 场景: 御花园
|
||
- 人物: 李云飞、苏婉儿
|
||
- 历史: EP01中两人初遇...
|
||
|
||
用户输入:
|
||
请创作 EP02 场景 3 的对话
|
||
```
|
||
|
||
---
|
||
|
||
## API 路由结构
|
||
|
||
```
|
||
/api/v1/
|
||
├── /skills # Skill 管理
|
||
│ ├── GET / # 列出所有 Skills
|
||
│ ├── GET /{id} # 获取 Skill 详情
|
||
│ ├── POST / # 创建新 Skill
|
||
│ ├── PUT /{id} # 更新 Skill
|
||
│ ├── DELETE /{id} # 删除 Skill
|
||
│ ├── POST /{id}/test # 测试 Skill
|
||
│ └── POST /{id}/reload # 重新加载 Skill
|
||
│
|
||
├── /projects # 项目管理
|
||
│ ├── GET / # 列出项目
|
||
│ ├── POST / # 创建项目
|
||
│ ├── GET /{id} # 获取项目详情
|
||
│ ├── PUT /{id} # 更新项目
|
||
│ ├── DELETE /{id} # 删除项目
|
||
│ ├── POST /{id}/execute # 执行剧集创作
|
||
│ └── POST /{id}/execute-batch # 批量执行
|
||
│
|
||
├── /memory # 记忆系统
|
||
│ ├── GET /projects/{id}/memory # 获取记忆
|
||
│ ├── GET /projects/{id}/memory/timeline # 获取时间线
|
||
│ ├── GET /projects/{id}/memory/threads # 获取待收线问题
|
||
│ ├── POST /projects/{id}/memory/threads # 添加待收线问题
|
||
│ └── POST /projects/{id}/memory/resolve-thread # 标记已解决
|
||
│
|
||
└── /review # 审核系统
|
||
├── GET /projects/{id}/review-config # 获取审核配置
|
||
├── PUT /projects/{id}/review-config # 更新审核配置
|
||
├── POST /projects/{id}/episodes/{ep_num}/review # 执行审核
|
||
└── GET /review/dimensions # 获取可用维度
|
||
```
|
||
|
||
---
|
||
|
||
## 前端架构
|
||
|
||
### 组件结构
|
||
|
||
```
|
||
src/
|
||
├── pages/ # 页面组件
|
||
│ ├── Dashboard.tsx # 仪表板
|
||
│ ├── Skills/
|
||
│ │ ├── SkillList.tsx # Skill 列表
|
||
│ │ ├── SkillDetail.tsx # Skill 详情
|
||
│ │ └── SkillEditor.tsx # Skill 编辑器
|
||
│ ├── Projects/
|
||
│ │ ├── ProjectList.tsx # 项目列表
|
||
│ │ ├── ProjectCreate.tsx # 创建项目
|
||
│ │ └── ProjectDetail.tsx # 项目详情
|
||
│ ├── Memory/
|
||
│ │ └── MemorySystem.tsx # 记忆系统
|
||
│ └── Review/
|
||
│ ├── ReviewConfig.tsx # 审核配置
|
||
│ └── ReviewResults.tsx # 审核结果
|
||
│
|
||
├── components/ # 通用组件
|
||
│ ├── Layout/
|
||
│ │ ├── Header.tsx
|
||
│ │ ├── Footer.tsx
|
||
│ │ └── Sidebar.tsx
|
||
│ ├── SkillCard.tsx
|
||
│ ├── EpisodeCard.tsx
|
||
│ └── QualityScore.tsx
|
||
│
|
||
├── stores/ # Zustand 状态管理
|
||
│ ├── skillStore.ts
|
||
│ ├── projectStore.ts
|
||
│ ├── memoryStore.ts
|
||
│ └── reviewStore.ts
|
||
│
|
||
├── services/ # API 服务
|
||
│ ├── api.ts # Axios 配置
|
||
│ ├── skillService.ts
|
||
│ ├── projectService.ts
|
||
│ ├── memoryService.ts
|
||
│ └── reviewService.ts
|
||
│
|
||
├── hooks/ # 自定义 Hooks
|
||
│ ├── useSkills.ts
|
||
│ ├── useProjects.ts
|
||
│ └── useEpisodeExecution.ts
|
||
│
|
||
└── types/ # TypeScript 类型
|
||
├── skill.ts
|
||
├── project.ts
|
||
├── memory.ts
|
||
└── review.ts
|
||
```
|
||
|
||
### 状态管理
|
||
|
||
使用 Zustand 进行轻量级状态管理：
|
||
|
||
```typescript
|
||
// stores/skillStore.ts
|
||
interface SkillStore {
|
||
skills: Skill[];
|
||
loading: boolean;
|
||
error: string | null;
|
||
fetchSkills: () => Promise<void>;
|
||
createSkill: (skill: Partial<Skill>) => Promise<void>;
|
||
}
|
||
|
||
export const useSkillStore = create<SkillStore>((set, get) => ({
|
||
skills: [],
|
||
loading: false,
|
||
error: null,
|
||
fetchSkills: async () => { /* ... */ },
|
||
createSkill: async (skill) => { /* ... */ }
|
||
}));
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### 核心数据模型
|
||
|
||
```python
|
||
# Skill
|
||
class Skill(BaseModel):
|
||
id: str
|
||
name: str
|
||
version: str
|
||
type: Literal["builtin", "user"]
|
||
category: str
|
||
behavior_guide: str
|
||
tags: List[str]
|
||
config: SkillConfig
|
||
|
||
# Project
|
||
class SeriesProject(BaseModel):
|
||
id: str
|
||
name: str
|
||
description: str
|
||
agent_id: str
|
||
status: str
|
||
global_context: GlobalContext
|
||
memory: Memory
|
||
episodes: List[Episode]
|
||
|
||
# Memory
|
||
class Memory(BaseModel):
|
||
eventTimeline: List[TimelineEvent]
|
||
pendingThreads: List[PendingThread]
|
||
characterStates: Dict[str, List[CharacterStateChange]]
|
||
foreshadowing: List[ForeshadowingEvent]
|
||
relationships: Dict[str, Dict[str, str]]
|
||
|
||
# Review Result
|
||
class ReviewResult(BaseModel):
|
||
episode_id: str
|
||
overall_score: float
|
||
passed: bool
|
||
dimension_scores: Dict[str, float]
|
||
issues: List[ReviewIssue]
|
||
```
|
||
|
||
---
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新的内置 Skill
|
||
|
||
1. 在 `backend/skills_storage/builtin_skills/` 下创建目录
|
||
2. 创建 `SKILL.md` 文件
|
||
3. 按照模板编写内容
|
||
4. 重启后端服务自动加载
|
||
|
||
### 添加新的 API 端点
|
||
|
||
1. 在 `backend/app/api/v1/` 下创建路由文件
|
||
2. 定义路由和处理器
|
||
3. 在 `backend/app/main.py` 中注册路由
|
||
|
||
### 添加新的前端页面
|
||
|
||
1. 在 `frontend/src/pages/` 下创建组件
|
||
2. 在 `frontend/src/App.tsx` 中添加路由
|
||
3. 配置导航菜单
|
||
|
||
---
|
||
|
||
## 性能优化建议
|
||
|
||
### 后端
|
||
|
||
1. **Skill 缓存**: 使用内存缓存避免频繁文件读取
|
||
2. **异步处理**: 使用 Celery 处理耗时任务
|
||
3. **连接池**: 复用 MongoDB 和 Redis 连接
|
||
4. **响应压缩**: 启用 Gzip 压缩
|
||
|
||
### 前端
|
||
|
||
1. **代码分割**: 使用 React.lazy 和 Suspense
|
||
2. **状态管理**: 使用 Zustand 避免不必要的重渲染
|
||
3. **请求缓存**: 使用 SWR 或 React Query
|
||
4. **图片优化**: 使用 WebP 格式和懒加载
|
||
|
||
---
|
||
|
||
## 安全考虑
|
||
|
||
1. **API Key 保护**: 使用环境变量，不提交到 Git
|
||
2. **输入验证**: 使用 Pydantic 验证所有输入
|
||
3. **CORS 配置**: 限制允许的源
|
||
4. **错误处理**: 不暴露敏感信息
|
||
|
||
---
|
||
|
||
## 部署架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Nginx 反向代理 │
|
||
│ (静态文件 + API 转发 + SSL) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ FastAPI 应用 (多实例 + Gunicorn) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Celery Worker (异步任务 + LLM 调用) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ MongoDB │ │ Redis │ │ MinIO/S3 │
|
||
│ (数据存储) │ │ (任务队列) │ │ (文件存储) │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 技术栈总览
|
||
|
||
### 后端
|
||
|
||
- **Python 3.11+** - 编程语言
|
||
- **FastAPI** - 高性能异步 Web 框架
|
||
- **MongoDB** - 文档数据库
|
||
- **Redis** - 缓存和消息队列
|
||
- **zai-sdk** - 智谱 AI SDK
|
||
- **Pydantic** - 数据验证
|
||
- **Uvicorn** - ASGI 服务器
|
||
|
||
### 前端
|
||
|
||
- **React 18** - UI 框架
|
||
- **TypeScript** - 类型安全
|
||
- **Vite** - 构建工具
|
||
- **Ant Design 5** - UI 组件库
|
||
- **Zustand** - 状态管理
|
||
- **React Router** - 客户端路由
|
||
- **Axios** - HTTP 客户端
|
||
- **Recharts** - 数据可视化
|
||
|
||
---
|
||
|
||
## 扩展阅读
|
||
|
||
- [FastAPI 文档](https://fastapi.tiangolo.com/)
|
||
- [React 文档](https://react.dev/)
|
||
- [Ant Design 文档](https://ant.design/)
|
||
- [智谱 AI 文档](https://docs.bigmodel.cn/)
|
||
- [Zustand 文档](https://zustand-demo.pmnd.rs/)
|
||
- [Vite 文档](https://vitejs.dev/)
|