# 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/)
