# 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<void>;
  createSkill: (skill: Partial<Skill>) => Promise<void>;
  updateSkill: (id: string, skill: Partial<Skill>) => Promise<void>;
  deleteSkill: (id: string) => Promise<void>;
}

export const useSkillStore = create<SkillStore>((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 (
    <div>
      <h1>My Page</h1>
      {/* 页面内容 */}
    </div>
  );
};

// src/App.tsx
import { MyPage } from '@/pages/MyPage';

// 添加路由
<Route path="/my-page" element={<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
