# Creative Studio

> 基于 **Agent + Skill 架构** 的 AI 剧集创作平台
>
> 集成智谱 AI GLM-4.7 模型，提供完整的自动化剧集创作解决方案

## 项目概述

Creative Studio 是一个创新的 AI 内容创作平台，通过 **可配置的 Skill（技能）** 指导 AI Agent 进行剧集创作。

### 核心特性

| 特性 | 说明 |
|-----|------|
| **Agent + Skill 架构** | 固定的 Agent 工作流 + 可配置的 Skill 行为指导 |
| **参考文件支持** | Skill 可关联参考文件（MD/TXT/JSON/YAML），融入 LLM 上下文 |
| **全局上下文管理** | 世界观、人物小传、场景设定等全局配置 |
| **记忆系统** | 事件时间线、伏笔追踪、人物状态变化记录 |
| **多集一致性** | 自动维护多集内容的一致性 |
| **审核系统** | 多维度质量审核和自动修复建议 |
| **内容管理** | Markdown 渲染预览、编辑、导出（MD/TXT/PDF/DOCX） |

### 技术栈

```
后端: FastAPI + GLM-4.7 + MongoDB + Redis
前端: React 18 + TypeScript + Ant Design + Vite + react-markdown + react-syntax-highlighter
```

## 快速开始

### 前置要求

- Python 3.11+
- Node.js 18+
- MongoDB 7.0+ (可选，默认使用内存存储)
- Redis 7.0+ (可选，用于 Celery 任务队列)
- 智谱 AI API Key

### 1. 克隆项目

```bash
git clone <repository-url>
cd creative_studio
```

### 2. 配置后端

```bash
cd backend

# (推荐) 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
# Windows:
copy .env.example .env
# Linux/Mac:
cp .env.example .env

# 编辑 .env 文件，必须配置以下内容:
# - ZAI_API_KEY: 你的智谱 AI API Key (必填)
# - SECRET_KEY: 随机生成的密钥 (必填)
# 其他配置可以使用默认值

# 启动后端服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

后端服务将运行在 `http://localhost:8000`

API 文档: `http://localhost:8000/docs`

健康检查: `http://localhost:8000/health`

### 3. 配置前端

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端服务将运行在 `http://localhost:5173`

### 常见问题排查

#### 后端启动失败

1. **ModuleNotFoundError**: 确保在虚拟环境中安装了所有依赖
   ```bash
   pip install -r requirements.txt
   ```

2. **编码错误 (Windows)**: 日志中的 emoji 显示警告不影响功能，如需修复请设置终端编码为 UTF-8

3. **环境变量错误**: 确保 `.env` 文件存在且包含必填项 (`ZAI_API_KEY`, `SECRET_KEY`)

#### 前端启动失败

1. **端口占用**: 如果 5173 端口被占用，Vite 会自动选择其他端口
2. **依赖安装失败**: 尝试删除 `node_modules` 后重新安装
   ```bash
   rm -rf node_modules  # Linux/Mac
   rmdir /s node_modules  # Windows
   npm install
   ```

#### 数据库连接失败

如果没有安装 MongoDB 或 Redis，应用仍可正常运行，将使用内存存储。生产环境建议配置数据库。

## 项目结构

```
creative_studio/
├── backend/                    # FastAPI 后端
│   ├── app/
│   │   ├── main.py            # 应用入口
│   │   ├── config.py          # 配置管理
│   │   ├── api/v1/            # API 路由
│   │   │   ├── skills.py      # Skill 管理 API
│   │   │   ├── projects.py    # 项目管理 API
│   │   │   ├── episodes.py    # 剧集内容 API
│   │   │   ├── uploads.py     # 文件上传 API
│   │   │   └── agents.py      # Agent 管理 API
│   │   ├── core/
│   │   │   ├── llm/           # GLM-4.7 客户端（支持参考文件）
│   │   │   ├── skills/        # Skill 管理器（支持 skill-creator 脚本）
│   │   │   ├── agents/        # Agent 执行引擎
│   │   │   ├── memory/        # 记忆系统
│   │   │   └── review/        # 审核系统
│   │   ├── models/            # 数据模型
│   │   └── utils/             # 工具函数
│   ├── skills_storage/         # Skill 文件存储
│   │   ├── builtin_skills/    # 内置 Skills（平台维护）
│   │   │   └── skill-creator/ # Skill 创建工具（用于创建新 Skills）
│   │   └── user_skills/       # 用户 Skills
│   │       ├── consistency_checker/
│   │       └── dialogue_writer_ancient/
│   └── requirements.txt
│
├── frontend/                   # React 前端
│   ├── src/
│   │   ├── pages/             # 页面组件
│   │   │   ├── SkillManagement.tsx
│   │   │   ├── ProjectWorkspace.tsx
│   │   │   ├── ExecutionMonitor.tsx
│   │   │   └── MemorySystem.tsx
│   │   ├── components/        # 通用组件
│   │   │   ├── MarkdownRenderer.tsx    # Markdown 渲染组件
│   │   │   ├── ContentEditor.tsx       # 内容编辑器
│   │   │   └── SkillCreateWizard.tsx   # Skill 创建向导
│   │   ├── stores/            # Zustand 状态管理
│   │   └── services/          # API 服务
│   │       ├── episodeContentService.ts
│   │       ├── uploadService.ts
│   │       └── skillService.ts
│   └── package.json
│
├── docs/                       # 详细文档
│   ├── ARCHITECTURE.md        # 技术架构详解
│   └── API.md                 # API 接口文档
│
├── creative-studio-platform.md # 原始产品规格文档（参考）
└── README.md                   # 本文件
```

## 核心概念

### Agent

Agent 是**固定的工作流框架**，由平台维护，用户不可编辑。

**剧集创作 Agent 工作流**：
1. 结构分析 - 分析场景构成、关键事件
2. 大纲生成 - 生成本集大纲
3. 对话创作 - 使用 Skill 创作剧本（支持参考文件）
4. 一致性审核 - 检查一致性并更新记忆
5. 记忆更新 - 提取事件、伏笔、人物状态

### Skill

Skill 是**可配置的创作能力单元**，通过行为指导影响 LLM 的输出。

**Skill 特性**：
- **行为指导**：指导 LLM 的输出风格和质量
- **参考文件**：可上传 MD/TXT/JSON/YAML 文件作为参考
- **Agent-Skill 生命周期**：注册 → 路由 → 执行 → 反馈
- **skill-creator 标准**：使用 YAML frontmatter 和标准化目录结构

**示例 Skill**：

```markdown
---
name: dialogue-writer-ancient
description: Expert ancient-style dialogue writer for period dramas. Use this skill when creating character dialogue that must match historical settings.
---

## 行为指导

你创作对话时必须遵循以下规则：

1. 使用半文半白的表达，如"何故"、"罢了"、"莫要"
2. 皇室说话威严少语，武将直率简短，文官婉转
3. 愤怒时用动作表达，不要直接说"我很生气"
4. 重要对话一句不超过 15 字
```

### 参考文件

Skill 可以关联参考文件，文件内容会被自动融入 LLM 上下文：

- **支持的格式**：MD, TXT, JSON, YAML
- **文件大小限制**：100KB（默认）
- **融入方式**：格式化后注入到系统提示词中

### 全局上下文

项目级共享设定：

- **世界观设定**: 背景世界描述
- **人物小传**: 角色设定、性格、说话风格
- **场景设定**: 常驻场景描述
- **整体大纲**: 故事线、转折点

### 记忆系统

自动维护一致性：

- **事件时间线**: 已发生的关键事件
- **伏笔追踪**: 新增伏笔、待收线问题
- **人物状态**: 各人物状态的历史变化

### 审核系统

多维度质量检查：

- **人物一致性**: 角色行为是否与设定一致
- **剧情逻辑**: 故事逻辑是否连贯
- **对话质量**: 对话是否自然流畅

## API 使用示例

### 列出所有 Skills

```bash
curl http://localhost:8000/api/v1/skills
```

### 获取 Skill 及其参考文件

```bash
curl http://localhost:8000/api/v1/skills/dialogue-writer-ancient/with-references
```

### 测试 Skill

```bash
curl -X POST http://localhost:8000/api/v1/skills/dialogue-writer-ancient/test \
  -H "Content-Type: application/json" \
  -d '{
    "test_input": "请帮我创作一段古风对话",
    "temperature": 0.7
  }'
```

### 创建项目

```bash
curl -X POST http://localhost:8000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的古风剧集",
    "totalEpisodes": 30,
    "globalContext": {
      "worldSetting": "架空朝代天启朝...",
      "characterProfiles": {...}
    }
  }'
```

### 执行剧集创作

```bash
curl -X POST http://localhost:8000/api/v1/projects/{project_id}/execute \
  -H "Content-Type: application/json" \
  -d '{
    "episode_number": 1
  }'
```

## 主要功能

### Skill 管理

- 查看 Skill 列表（内置 + 用户自定义）
- 使用 skill-creator 向导创建 Skill
- 上传参考文件（MD/TXT/JSON/YAML）
- 测试 Skill 效果
- 编辑 Skill 内容和配置

### 项目管理

- 创建和管理剧集项目
- 配置全局上下文
- 选择使用的 Skills
- 查看项目进度和统计

### 剧集创作

- 单集创作
- 批量创作
- 实时进度监控
- 自动保存到数据库

### 内容管理

- **Markdown 渲染预览**：使用 react-markdown + react-syntax-highlighter
- **在线编辑**：直接编辑剧集内容
- **质量审核**：通过/拒绝、添加审核意见
- **导出功能**：支持 MD/TXT/PDF/DOCX 格式

### 记忆系统

- 事件时间线查看
- 伏笔追踪和管理
- 人物状态变化记录

## 开发路线图

### Phase 1: 基础设施 ✅
- [x] FastAPI 框架搭建
- [x] GLM-4.7 客户端封装
- [x] Skill 管理系统
- [x] 前端框架搭建

### Phase 2: 核心功能 ✅
- [x] Agent 执行引擎
- [x] 项目管理系统
- [x] 记忆系统
- [x] 前端核心页面
- [x] Markdown 渲染预览
- [x] 参考文件 LLM 融入

### Phase 3: 高级功能 ⚠️
- [x] 内容 CRUD API
- [x] 导出功能（基础）
- [ ] 三种执行模式完善
- [ ] Skill Marketplace
- [ ] PDF/DOCX 导出完善

### Phase 4: 优化完善 📝
- [ ] UI/UX 优化
- [ ] 测试覆盖
- [ ] 部署方案
- [ ] 文档完善

## 文档导航

- **[API 文档](docs/API.md)** - 完整的 REST API 接口文档
- **[架构文档](docs/ARCHITECTURE.md)** - 技术架构详细说明
- **[原始产品规格](creative-studio-platform.md)** - 原始产品规格文档（参考）

## 常见问题

### 如何获取智谱 AI API Key？

访问 [智谱AI开放平台](https://open.bigmodel.cn/usercenter/apikeys) 创建 API Key。

### 支持哪些模型？

- `glm-4-flash` - 快速响应模型（推荐）
- `glm-4-plus` - 高质量模型
- `glm-4-0520` - 稳定版本

### Skill 的参考文件是如何工作的？

参考文件会被 SkillManager 加载，格式化后融入 GLM 客户端的系统提示词中，使 LLM 能够参考这些内容进行创作。

### 如何创建新的 Skill？

**方法一：使用前端向导（推荐）**
1. 进入 Skill 管理页面
2. 点击"创建新 Skill"
3. 按照向导步骤填写信息、上传参考文件
4. 预览并保存

**方法二：使用 skill-creator 脚本**
```bash
# 初始化 Skill 模板
cd backend/skills_storage/builtin_skills/skill-creator/scripts
python init_skill.py my-skill --path ../../../user_skills/

# 编辑 SKILL.md 文件
# 添加参考文件到 references/ 目录

# 验证 Skill
python quick_validate.py ../../../user_skills/my-skill

# 打包 Skill（可选）
python package_skill.py ../../../user_skills/my-skill
```

**方法三：手动创建**
1. 在 `backend/skills_storage/user_skills/` 下创建目录
2. 创建 `SKILL.md` 文件，包含 YAML frontmatter：
```markdown
---
name: my-skill
description: 简短描述此 Skill 的用途
---

## 行为指导
你的行为指导...
```
3. 可选：添加 `references/` 目录存放参考文件
4. 重启后端服务自动加载

## 许可证

MIT License

---

**Creative Studio** - 让 AI 创作更简单、更可控