jinghui/creative_studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
creative_studio/DEVELOPMENT_GUIDE.md
BuildTools d0e11aef1b Init commit.
2026-01-25 19:27:44 +08:00

20 KiB
Raw Permalink Blame History

Creative Studio - 开发指南

本文档为开发者提供详细的开发指南，包括架构设计、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
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. 安装依赖

cd backend
pip install -e .

或使用 requirements.txt：

pip install -r requirements.txt

3. 配置环境变量

cp .env.example .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. 启动开发服务器

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

访问 http://localhost:8000/docs 查看 API 文档。

前端环境

1. 安装依赖

cd frontend
npm install

2. 配置环境变量

创建 .env.local 文件：

VITE_API_BASE_URL=http://localhost:8000

3. 启动开发服务器

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 调用能力。

核心方法：

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 操作。

核心方法：

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)

管理项目的记忆系统，包括事件时间线、伏笔追踪等。

核心方法：

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)

管理剧集的审核流程，提供多维度质量检查。

核心方法：

async def review_episode(
    episode: Episode,
    project: SeriesProject,
    config: ReviewConfig
) -> ReviewResult:
    """执行完整审核流程"""

添加新的 API 端点

  1. 在 app/api/v1/ 下创建路由文件
  2. 定义路由和处理器
  3. 在 app/main.py 中注册路由

示例：

# 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 模板：

# 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 进行轻量级状态管理。

示例：

// 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 调用。

示例：

// 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. 在导航菜单中添加链接

示例：

// 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。

主要 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 进行测试。

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_skills.py

# 查看覆盖率
pytest --cov=app tests/

前端测试

使用 Vitest 进行测试。

# 运行所有测试
npm run test

# 运行特定测试文件
npm run test -- SkillCard.test.tsx

# 查看覆盖率
npm run test -- --coverage

部署指南

后端部署

Docker 部署

# 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"]

构建和运行：

docker build -t creative-studio-backend .
docker run -p 8000:8000 --env-file .env creative-studio-backend

传统部署

# 使用 Gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

前端部署

# 构建生产版本
npm run build

# 输出在 dist/ 目录

使用 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 的内置防护

扩展阅读

许可证

MIT License