# 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; createSkill: (skill: Partial) => Promise; } export const useSkillStore = create((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/)