# Creative Studio - 开发指南 本文档为开发者提供详细的开发指南，包括架构设计、API 文档、开发环境配置、测试和部署等内容。 ## 目录 - [架构概览](#架构概览) - [技术栈](#技术栈) - [开发环境配置](#开发环境配置) - [后端开发](#后端开发) - [前端开发](#前端开发) - [API 文档](#api-文档) - [测试指南](#测试指南) - [部署指南](#部署指南) - [性能优化](#性能优化) - [安全考虑](#安全考虑) --- ## 架构概览 ### 系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 前端 (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. **"全自动 + 人工审核"** - 自动创作与人工审核相结合 --- ## 技术栈 ### 后端 - **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** - 数据可视化 --- ## 开发环境配置 ### 后端环境 #### 1. 创建虚拟环境 ```powershell # PowerShell python -m venv .venv .venv\Scripts\Activate.ps1 # CMD python -m venv .venv .venv\Scripts\activate.bat # Git Bash / WSL python -m venv .venv source .venv/Scripts/activate ``` #### 2. 安装依赖 ```bash cd backend pip install -e . ``` 或使用 requirements.txt： ```bash pip install -r requirements.txt ``` #### 3. 配置环境变量 ```bash cp .env.example .env ``` 编辑 `.env` 文件： ```env # GLM API Key (必填) ZAI_API_KEY=your_api_key_here # MongoDB (可选) MONGODB_URL=mongodb://localhost:27017 MONGODB_DATABASE=creative_studio # Redis (可选) REDIS_URL=redis://localhost:6379/0 # 模型配置 ZAI_MODEL=glm-4-flash # 日志配置 LOG_LEVEL=INFO DEBUG=True ``` #### 4. 启动开发服务器 ```bash uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` 访问 `http://localhost:8000/docs` 查看 API 文档。 ### 前端环境 #### 1. 安装依赖 ```bash cd frontend npm install ``` #### 2. 配置环境变量 创建 `.env.local` 文件： ```env VITE_API_BASE_URL=http://localhost:8000 ``` #### 3. 启动开发服务器 ```bash npm run dev ``` 访问 `http://localhost:5173` 查看前端应用。 --- ## 后端开发 ### 项目结构 ``` backend/ ├── app/ │ ├── __init__.py │ ├── main.py # 应用入口 │ ├── config.py # 配置管理 │ ├── api/ │ │ ├── __init__.py │ │ └── v1/ │ │ ├── __init__.py │ │ ├── skills.py # Skill API │ │ ├── projects.py # Project API │ │ ├── memory.py # Memory API │ │ └── review.py # Review API │ ├── core/ │ │ ├── __init__.py │ │ ├── llm/ │ │ │ ├── __init__.py │ │ │ └── glm_client.py # GLM 客户端 │ │ ├── skills/ │ │ │ ├── __init__.py │ │ │ └── skill_manager.py # Skill 管理器 │ │ ├── agents/ │ │ │ ├── __init__.py │ │ │ └── series_creation_agent.py # 剧集创作 Agent │ │ ├── memory/ │ │ │ ├── __init__.py │ │ │ └── memory_manager.py # 记忆管理器 │ │ └── review/ │ │ ├── __init__.py │ │ └── review_manager.py # 审核管理器 │ ├── models/ │ │ ├── __init__.py │ │ ├── skill.py # Skill 数据模型 │ │ ├── project.py # Project 数据模型 │ │ ├── memory.py # Memory 数据模型 │ │ └── review.py # Review 数据模型 │ ├── schemas/ │ │ ├── __init__.py │ │ └── ... │ ├── db/ │ │ ├── __init__.py │ │ └── ... │ └── utils/ │ ├── __init__.py │ └── logger.py # 日志配置 │ ├── skills_storage/ # Skill 文件存储 │ ├── builtin_skills/ # 内置 Skills │ └── user_skills/ # 用户 Skills │ ├── tests/ # 测试 │ ├── __init__.py │ ├── conftest.py # Pytest 配置 │ ├── test_skills.py # Skill 测试 │ ├── test_projects.py # Project 测试 │ └── test_api.py # API 测试 │ ├── requirements.txt # Python 依赖 ├── setup.py # 安装配置 ├── .env.example # 环境变量模板 └── README.md # 后端文档 ``` ### 核心模块说明 #### GLM Client (`app/core/llm/glm_client.py`) 封装智谱 AI GLM-4.7 API，提供核心 LLM 调用能力。 **核心方法**： ```python async def chat_with_skill( skill_behavior: str, # Skill 的行为指导 user_input: str, # 用户输入 context: Dict, # 上下文信息 temperature: float = 0.7 ) -> str: """使用 Skill 行为指导进行对话""" ``` #### Skill Manager (`app/core/skills/skill_manager.py`) 管理 Skill 的加载、解析、缓存和 CRUD 操作。 **核心方法**： ```python async def load_skill(skill_id: str) -> Skill: """加载 Skill""" async def list_skills(skill_type: str = None, category: str = None) -> List[Skill]: """列出 Skills""" async def create_user_skill(skill_data: SkillCreate) -> Skill: """创建用户 Skill""" ``` #### Memory Manager (`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]: """更新人物状态""" ``` #### Review Manager (`app/core/review/review_manager.py`) 管理剧集的审核流程，提供多维度质量检查。 **核心方法**： ```python async def review_episode( episode: Episode, project: SeriesProject, config: ReviewConfig ) -> ReviewResult: """执行完整审核流程""" ``` ### 添加新的 API 端点 1. 在 `app/api/v1/` 下创建路由文件 2. 定义路由和处理器 3. 在 `app/main.py` 中注册路由 示例： ```python # app/api/v1/my_feature.py from fastapi import APIRouter, Depends from app.schemas.my_feature import MyRequest, MyResponse router = APIRouter(prefix="/my-feature", tags=["My Feature"]) @router.post("/", response_model=MyResponse) async def create_my_feature( request: MyRequest ): """创建我的功能""" # 实现逻辑 pass ``` ### 添加新的 Skill 1. 在 `skills_storage/user_skills/` 或 `skills_storage/builtin_skills/` 下创建目录 2. 创建 `SKILL.md` 文件 3. 按照模板编写内容 **Skill 模板**： ```markdown # Skill: Skill 名称 ## 基础信息 - **ID**: skill-id - **版本**: 1.0.0 - **作者**: 你的名字 - **分类**: 分类名称 ## 行为指导 (核心) 这里是 Skill 的核心内容，描述这个 Skill 如何指导 Agent 的行为。 ### 具体规则 1. 规则 1 2. 规则 2 3. ... ### 输出格式 描述期望的输出格式 ### 注意事项 其他需要注意的事项 ``` --- ## 前端开发 ### 项目结构 ``` frontend/ ├── src/ │ ├── main.tsx # 应用入口 │ ├── App.tsx # 根组件 │ ├── index.css # 全局样式 │ │ │ ├── pages/ # 页面组件 │ │ ├── HomePage.tsx # 首页 │ │ ├── SkillManagement.tsx # Skill 管理 │ │ ├── AgentManagement.tsx # Agent 管理 │ │ ├── ProjectList.tsx # 项目列表 │ │ ├── ProjectCreate.tsx # 创建项目 │ │ ├── ProjectDetail.tsx # 项目详情 │ │ ├── ExecutionMonitor.tsx # 执行监控 │ │ ├── MemorySystem.tsx # 记忆系统 │ │ ├── ReviewConfig.tsx # 审核配置 │ │ └── ReviewResults.tsx # 审核结果 │ │ │ ├── components/ # 通用组件 │ │ ├── Layout/ │ │ │ ├── Header.tsx │ │ │ ├── Footer.tsx │ │ │ └── Sidebar.tsx │ │ ├── SkillCard.tsx │ │ ├── EpisodeCard.tsx │ │ └── ... │ │ │ ├── stores/ # Zustand 状态管理 │ │ ├── skillStore.ts │ │ ├── projectStore.ts │ │ ├── memoryStore.ts │ │ ├── reviewStore.ts │ │ └── index.ts │ │ │ ├── services/ # API 服务 │ │ ├── api.ts # Axios 配置 │ │ ├── skillService.ts │ │ ├── projectService.ts │ │ ├── memoryService.ts │ │ ├── reviewService.ts │ │ └── index.ts │ │ │ ├── hooks/ # 自定义 Hooks │ │ ├── useSkills.ts │ │ ├── useProjects.ts │ │ └── ... │ │ │ ├── types/ # TypeScript 类型 │ │ ├── skill.ts │ │ ├── project.ts │ │ ├── memory.ts │ │ ├── review.ts │ │ └── index.ts │ │ │ └── utils/ # 工具函数 │ └── ... │ ├── index.html # HTML 模板 ├── package.json # NPM 依赖 ├── vite.config.ts # Vite 配置 ├── tsconfig.json # TypeScript 配置 ├── tailwind.config.js # Tailwind CSS 配置 └── README.md # 前端文档 ``` ### 状态管理 (Zustand) 使用 Zustand 进行轻量级状态管理。 示例： ```typescript // stores/skillStore.ts import { create } from 'zustand'; import { Skill } from '@/types'; interface SkillStore { skills: Skill[]; loading: boolean; error: string | null; fetchSkills: () => Promise; createSkill: (skill: Partial) => Promise; updateSkill: (id: string, skill: Partial) => Promise; deleteSkill: (id: string) => Promise; } export const useSkillStore = create((set, get) => ({ skills: [], loading: false, error: null, fetchSkills: async () => { set({ loading: true, error: null }); try { const skills = await skillService.listSkills(); set({ skills, loading: false }); } catch (error) { set({ error: error.message, loading: false }); } }, // ... 其他方法 })); ``` ### API 服务 使用 Axios 进行 HTTP 调用。 示例： ```typescript // services/skillService.ts import api from './api'; import { Skill, SkillCreate, SkillUpdate } from '@/types'; export const skillService = { async listSkills(params?: { skill_type?: string; category?: string }) { const response = await api.get('/skills', { params }); return response.data; }, async getSkill(id: string) { const response = await api.get(`/skills/${id}`); return response.data; }, async createSkill(data: SkillCreate) { const response = await api.post('/skills', data); return response.data; }, // ... 其他方法 }; ``` ### 添加新页面 1. 在 `src/pages/` 下创建页面组件 2. 在 `src/App.tsx` 中添加路由 3. 在导航菜单中添加链接 示例： ```typescript // src/pages/MyPage.tsx import React from 'react'; export const MyPage: React.FC = () => { return (

My Page

{/* 页面内容 */}
); }; // src/App.tsx import { MyPage } from '@/pages/MyPage'; // 添加路由 } /> ``` --- ## API 文档 完整的 API 文档请参考 [docs/API.md](docs/API.md)。 ### 主要 API 端点 #### Skill 管理 | 端点 | 方法 | 描述 | |-----|------|------| | `/api/v1/skills` | GET | 列出所有 Skills | | `/api/v1/skills/{id}` | GET | 获取 Skill 详情 | | `/api/v1/skills` | POST | 创建新 Skill | | `/api/v1/skills/{id}/test` | POST | 测试 Skill | | `/api/v1/skills/{id}` | PUT | 更新 Skill | | `/api/v1/skills/{id}` | DELETE | 删除 Skill | #### 项目管理 | 端点 | 方法 | 描述 | |-----|------|------| | `/api/v1/projects` | GET | 列出项目 | | `/api/v1/projects` | POST | 创建项目 | | `/api/v1/projects/{id}` | GET | 获取项目详情 | | `/api/v1/projects/{id}` | PUT | 更新项目 | | `/api/v1/projects/{id}` | DELETE | 删除项目 | | `/api/v1/projects/{id}/execute` | POST | 执行剧集创作 | | `/api/v1/projects/{id}/execute-batch` | POST | 批量执行 | #### 记忆系统 | 端点 | 方法 | 描述 | |-----|------|------| | `/api/v1/projects/{id}/memory` | GET | 获取项目记忆 | | `/api/v1/projects/{id}/memory/timeline` | GET | 获取事件时间线 | | `/api/v1/projects/{id}/memory/threads` | GET | 获取待收线问题 | | `/api/v1/projects/{id}/memory/threads` | POST | 添加待收线问题 | | `/api/v1/projects/{id}/memory/threads/{thread_id}` | PUT | 更新待收线问题 | #### 审核系统 | 端点 | 方法 | 描述 | |-----|------|------| | `/api/v1/projects/{id}/review-config` | GET | 获取审核配置 | | `/api/v1/projects/{id}/review-config` | PUT | 更新审核配置 | | `/api/v1/projects/{id}/episodes/{ep_num}/review` | POST | 执行审核 | --- ## 测试指南 ### 后端测试 使用 pytest 进行测试。 ```bash # 运行所有测试 pytest # 运行特定测试文件 pytest tests/test_skills.py # 查看覆盖率 pytest --cov=app tests/ ``` ### 前端测试 使用 Vitest 进行测试。 ```bash # 运行所有测试 npm run test # 运行特定测试文件 npm run test -- SkillCard.test.tsx # 查看覆盖率 npm run test -- --coverage ``` --- ## 部署指南 ### 后端部署 #### Docker 部署 ```dockerfile # Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] ``` 构建和运行： ```bash docker build -t creative-studio-backend . docker run -p 8000:8000 --env-file .env creative-studio-backend ``` #### 传统部署 ```bash # 使用 Gunicorn gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 ``` ### 前端部署 ```bash # 构建生产版本 npm run build # 输出在 dist/ 目录 ``` 使用 Nginx 服务静态文件： ```nginx server { listen 80; server_name your-domain.com; root /path/to/frontend/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api { proxy_pass http://localhost:8000; } } ``` --- ## 性能优化 ### 后端优化 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. **错误处理**: 不暴露敏感信息 5. **SQL 注入防护**: 使用参数化查询 6. **XSS 防护**: 前端使用 React 的内置防护 --- ## 扩展阅读 - [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/) --- ## 许可证 MIT License