一句创意，一部短剧。
AI Director 是一个多 Agent 协作的 AI 漫剧创作平台：用户输入一句创意（或剧本、分镜），由 14 个专业 Agent 按确定性管线协作，完成从安全审查、故事架构、剧本、角色、分镜、视频提示词到成片组装的全流程创作。
- 多 Agent 确定性编排：14 个专业 Skill 按前置依赖图调度，调度决策由纯函数引擎给出，不依赖 LLM 自主路由
- 产物契约与血缘：每个 Skill 输出经技能名 + 语义化契约版本双重校验，所有产物版本化、可追溯，用户源素材不可变
- 安全门禁：Safety Guardian 在创作入口与视频生成前两次审查；AUTO 模式下角色视觉确认与生成前终审仍强制执行
- 修改计划（Change Plan）：修改已有产物前必须先确认影响范围，受保护镜头自动排除，生产进行中冻结调度
- 安全工程：PostgreSQL 行级安全（RLS + FORCE）与应用层归属断言双保险，DB 层滑动窗口限流与并发租约，全链路令牌哈希存储
- 视频作业状态机：幂等提交、失败语义分类（可重试 / 结果未知禁止自动重提，防重复计费）、供应商结果转存私有素材库
flowchart TD
SAFETY[SAFETY_GUARDIAN<br/>创作入口安全审查] --> PLANNER[DIRECTOR_PLANNER<br/>导演规划]
PLANNER --> ARCH[STORY_ARCHITECT<br/>故事架构]
ARCH --> SCR[SCREENPLAY_WRITER<br/>结构化剧本]
ARCH --> CHAR[CHARACTER_DESIGNER<br/>角色设定]
SCR --> CONSIS
CHAR --> CONSIS[CHARACTER_CONSISTENCY<br/>跨镜头角色一致性]
CONSIS --> CONT[CONTINUITY<br/>剧情连续性]
CONT --> BOARD[STORYBOARD_PLANNER<br/>分镜规划]
BOARD --> CINE[CINEMATIC_DIRECTOR<br/>镜头语言方案]
BOARD --> VOICE[VOICE_AND_SUBTITLE<br/>配音与字幕]
CINE --> STYLE[VISUAL_STYLE<br/>视觉执行方案]
STYLE --> PROMPT[VIDEO_PROMPT_ENGINEER<br/>视频提示词简报]
PROMPT --> FINAL[SAFETY_GUARDIAN<br/>生成前安全终审]
FINAL --> VIDEO[视频生成<br/>Seedance]
VIDEO --> QC[QUALITY_CONTROL<br/>质检]
- 三种创作模式：灵感创作（IDEA_CREATION）/ 剧本导演（SCREENPLAY_DIRECTOR）/ 专业分镜（PRO_STORYBOARD）
- 两种执行策略：AUTO（门禁通过自动推进）/ PROFESSIONAL（关键节点需用户确认）
- 9 个用户审批点：导演设定、故事架构、剧本草案、角色视觉、分镜、镜头语言、视觉风格、预视频、配音字幕
┌────────────────────────────────────────────────────────┐
│ Next.js App Router（全栈） │
│ ┌────────────┐ ┌──────────────────────────────────┐ │
│ │ 页面/组件 │ │ API Routes（35 个端点） │ │
│ └────────────┘ └──────────┬───────────────┬───────┘ │
│ │ │ │
│ ┌────────────▼───┐ ┌────────▼───────┐ │
│ │ API 守卫 │ │ Agent 实现 │ │
│ │ 频控/并发租约 │ │ 11 个 Skill │ │
│ └────────────┬───┘ └────────┬───────┘ │
│ │ │ │
│ ┌────────────▼───────────────▼───────┐ │
│ │ Director Runtime │ │
│ │ contracts / orchestrator / │ │
│ │ validation / character-lineage │ │
│ └──────────┬───────────────┬─────────┘ │
│ │ │ │
│ ┌────────────▼────┐ ┌───────▼─────────┐ │
│ │ Qwen 适配器 │ │ Seedance 适配器 │ │
│ │ （LLM 调用） │ │ （视频生成） │ │
│ └────────────────┘ └─────────────────┘ │
│ │ │ │
│ ┌────────────▼───────────────▼─────────┐ │
│ │ PostgreSQL（原生 SQL + RLS） │ │
│ └──────────────────────────────────────┘ │
└────────────────────────────────────────────────────────┘
- Director Runtime 是自研的编排核心：调度引擎（
evaluateDispatch）以纯函数形式校验前置依赖、安全门禁、审批点与锁定保护，每次 Skill 调用前后均执行 - 模型只负责起草：调度顺序、产物版本、用户确认节点与安全决策全部由应用代码管控，模型输出经过契约校验后才可持久化
| 层 | 技术 |
|---|---|
| 全栈框架 | Next.js 15（App Router）+ React 19 |
| 语言 | TypeScript（strict） |
| 数据库 | PostgreSQL（pg 原生驱动，无 ORM，RLS 行级隔离） |
| LLM | 通义千问 Qwen（OpenAI 兼容接口，JSON 模式） |
| 视频生成 | 即梦 Seedance（Volcengine Ark Content Generation） |
| 媒体处理 | FFmpeg（本地成片渲染） |
| 测试 | Node.js 原生 test runner |
- Node.js 20+
- PostgreSQL 14+
# 1. 安装依赖
npm install
# 2. 配置环境变量
cp .env.example .env.local
# 编辑 .env.local，至少填写 QWEN_API_KEY、QWEN_BASE_URL、QWEN_MODEL、DATABASE_URL
# 3. 执行数据库迁移
npm run db:migrate
# 4. 启动开发服务器
npm run dev
# 打开 http://localhost:3000| 变量 | 必填 | 说明 |
|---|---|---|
QWEN_API_KEY |
✅ | 通义千问 API Key |
QWEN_BASE_URL |
✅ | 兼容 OpenAI 接口的 API 地址（须 HTTPS） |
QWEN_MODEL |
✅ | 模型名 |
QWEN_REQUEST_TIMEOUT_MS |
否 | 请求超时，默认 170000（上限受路由 180s 限制） |
QWEN_ENABLE_JSON_MODE |
否 | JSON 输出模式，默认 true |
QWEN_ENABLE_THINKING |
否 | 思维链输出，默认 false |
SEEDANCE_API_KEY |
否 | 视频生成 API Key（不配置则视频作业只入队不派发） |
SEEDANCE_BASE_URL |
否 | 默认 https://ark.cn-beijing.volces.com/api/v3 |
SEEDANCE_MODEL |
否 | 视频生成模型 |
SEEDANCE_REQUEST_TIMEOUT_MS |
否 | 默认 60000 |
DATABASE_URL |
✅ | PostgreSQL 连接串（仅服务端使用） |
DATABASE_SSL_CA_PATH |
否 | SSL 模式下的 CA 证书路径，默认 certs/rds-ca.pem |
ASSET_STORAGE_PROVIDER |
否 | 默认 LOCAL_PRIVATE |
ASSET_LOCAL_ROOT |
否 | 私有素材根目录，默认 .asset-storage |
TRUST_PROXY_HEADERS |
否 | 仅在可信反代后置 true（信任 X-Forwarded-For 做限流分桶） |
所有凭据仅允许服务端环境变量，代码会在检测到 NEXT_PUBLIC_ 前缀的敏感变量时直接报错。
├── app/ # Next.js 页面与 API 路由
│ ├── api/ # 35 个 API 端点（认证/项目/AI 管线/视频作业/素材/后期）
│ └── app/ # 创作空间（项目工作台、回收站）
├── components/ # React 组件（认证/项目/原型存储/基础 UI）
├── lib/
│ ├── agent/ # 11 个 Agent 实现（prepare → LLM → finalize）
│ ├── director-runtime/ # 自研编排核心：契约、调度引擎、结果校验、角色血缘
│ ├── qwen/ # Qwen 适配器（调用、配置、Prompt 加载）
│ ├── seedance/ # Seedance 适配器（提交/轮询/结果转移）
│ ├── projects/ # 仓储层（repository.ts，全部工作流持久化）
│ ├── api/ # 请求校验、守卫（限流/并发租约）、响应约定
│ ├── auth/ # 会话认证（scrypt 密码哈希、不透明令牌）
│ ├── db/ # PostgreSQL 连接池与事务封装
│ ├── assets/ # 私有素材存储与上传策略
│ └── post-production/ # 后期制作时序校验
├── db/migrations/ # 数据库迁移（10 个，含 RLS 策略）
├── docs/ # 设计文档（状态机、数据协议、记忆架构、Prompt 契约）
├── scripts/ # 迁移执行、库验证、本地渲染、离线 TTS、集成测试
└── certs/ # 数据库 CA 证书（不入库，见 .gitignore）
| 命令 | 说明 |
|---|---|
npm run dev |
启动开发服务器 |
npm run build |
生产构建 |
npm run lint |
ESLint 检查 |
npm run typecheck |
TypeScript 类型检查 |
npm run test:runtime |
运行时单元测试（调度引擎、契约校验、适配器、资源策略等） |
npm run test:integration |
API 集成测试（需本地服务运行在 3000 端口） |
npm run db:migrate |
执行数据库迁移 |
npm run db:verify |
数据库验证（表结构、RLS 隔离、限流原子性、并发租约） |
架构与设计决策见 docs/：
- 产品状态机 — 项目生命周期、产物、作业、审核四维状态机
- 核心数据协议 — 项目聚合、产物版本化与血缘模型
- Agent 记忆架构 — 权威项目记忆、派生上下文卡与检索
- Seedance 视频作业 — 供应商契约、失败语义与防重复计费
- API 安全 — 限流、并发租约、RLS 与凭据防护
- Prompt 注册表 — 14 个 Skill Prompt 与运行时协议
- 创作管线（故事架构 → 视频提示词）、视频作业状态机、私有素材库、后期编排草案均已实现
- 本地无费用子集已落地：FFmpeg 本地成片渲染、Windows 离线语音合成
- 真实 Seedance 付费调用尚未执行：供应商适配层与作业语义已按契约实现并测试，端到端视频生成待合同验证
- Agent 记忆架构 Phase A（数据表与 RLS）已落地，Phase B（记忆卡填充与上下文构建器）未实现