Toonflow（通流）产品需求文档

1. 产品概述

1.1 产品定位

Toonflow（通流）是一款 AI 短剧/漫剧创作工具，核心定位是"AI短剧工厂"。它利用人工智能技术，将小说文本自动转化为剧本，并结合 AI 生成的图片和视频，实现高效的短剧内容创作。

1.2 目标用户

• 短视频内容创作者
• 小说影视化改编从业者
• AI 文学改编爱好者
• 剧本开发人员与快速原型制作者
• 视频素材生成需求者

1.3 核心价值主张

"动动手指，小说秒变剧集！AI剧本 x AI影像 x 极速生成"

将传统需要数周的人工改编流程压缩至数小时，通过 AI 自动化完成剧本拆解、角色设计、分镜生成和视频合成。

2. 核心功能模块

2.1 三层 Agent 协作体系

项目采用独特的 决策层 → 执行层 → 监督层 架构：

ScriptAgent（剧本 Agent）

• 决策层：分析小说结构，制定整体改编策略
• 执行层子 Agent：
  • 故事骨架生成：提取核心情节脉络
  • 改编策略制定：确定叙事节奏与风格
  • 剧本生成：输出结构化剧本内容
• 监督层：质量校验与一致性审查

ProductionAgent（生产 Agent）

• 决策层：统筹资产生产与分镜规划
• 执行层子 Agent：
  • 衍生资产分析：识别角色/场景/道具需求
  • 资产图片生成：调用 AI 绘画接口生成素材
  • 导演规划：制定镜头语言与视觉风格
  • 分镜图生成：将剧本转化为可视化分镜
  • 分镜面板写入：组织分镜到面板
  • 分镜表构建：生成分镜时间表
• 监督层：视觉一致性与质量把控

2.2 无限画布生产工作台

以类无限画布形式组织创作内容：

• 剧本内容节点
• 角色/场景/道具资产卡片
• 分镜面板
• 视频轨道与素材节点

2.3 持久化 Agent 记忆系统

• 基于本地 ONNX 向量检索（all-MiniLM-L6-v2）
• 三层记忆架构：
  • 短期消息：当前会话上下文
  • 长期摘要：历史会话的压缩记忆
  • 语义召回 (RAG)：基于向量相似度的知识检索
• 支持跨会话记忆连续性

2.4 可编程供应商系统

• 支持在设置中心直接编写 TypeScript 供应商逻辑
• 使用 vm2 沙箱执行供应商代码
• 无需修改源码或重启服务即可接入新模型

2.5 章节事件图谱驱动改编

• 自动提取原著章节事件并结构化存储
• 剧本改编按事件图谱精准调用上下文
• 确保改编忠实于原著情节

2.6 Skill 文件化配置

• Agent 核心提示词外化为 Markdown Skill 文件
• 支持在线编辑与快速调优
• 预置多种画风技能：2D/3D/真人风格等 10+ 种

2.7 主要业务模块

3. 系统架构

3.1 整体架构图

+------------------+     +------------------+     +------------------+
|   Electron 桌面   |     |   Web 浏览器     |     |   Docker 容器    |
|     客户端        |     |   (前端 SPA)     |     |   服务端部署      |
+------------------+     +------------------+     +------------------+
         |                       |                       |
         +-----------------------+-----------------------+
                                 |
                    +------------v------------+
                    |    Express 5 服务端     |
                    |  (REST API + Socket.IO) |
                    +------------+------------+
                                 |
         +-----------------------+-----------------------+
         |                       |                       |
+--------v--------+   +----------v----------+   +--------v--------+
|   Agent 引擎     |   |   业务路由层        |   |   媒体处理层    |
| (Script/Prod)   |   |  (153+ API 接口)    |   |  (Sharp/FFmpeg) |
+-----------------+   +---------------------+   +-----------------+
         |                       |                       |
         +-----------------------+-----------------------+
                                 |
                    +------------v------------+
                    |      数据持久化层        |
                    |  SQLite + 本地文件存储   |
                    +-------------------------+

3.2 关键架构设计

文件系统即路由

src/routes/ 目录下的文件自动映射为 API 路由，无需手动注册，开发效率高。

Skill 驱动架构

Agent 行为完全由外部 Markdown 文件定义，无需改代码即可调优提示词策略。

供应商热插拔

通过 vm2 沙箱执行 TypeScript 供应商代码，支持动态添加 AI 提供商，无需重启服务。

Electron + Web 双模式

同一套后端代码同时支持桌面客户端和 Web 服务部署。

4. 技术栈

4.1 运行时与语言

4.2 后端架构

4.3 AI 集成层

4.4 桌面客户端

4.5 图像与媒体处理

4.6 部署方式

• 本机安装：直接下载安装包
• Docker 部署：基于 node:24-bookworm-slim
• 云端部署：PM2 + Node.js 服务器
• 开发模式：nodemon + tsx

5. 视频生成模块（深度架构）

5.1 视频生成整体流程

+-------------------+     +-------------------+     +-------------------+
|   分镜/资产选择    | --> |  视频提示词生成    | --> |   AI 视频生成     |
| (storyboard/assets)|     | (LLM 结构化提示词) |     | (供应商 API 调用) |
+-------------------+     +-------------------+     +-------------------+
                                                          |
+-------------------+     +-------------------+          |
|   视频轨道管理     | <-- |   本地文件存储     | <--------+
| (workbench/edit)  |     |   (OSS 抽象层)    |
+-------------------+     +-------------------+

5.2 视频生成 API 端点

POST /api/production/workbench/generateVideo

接收参数：

异步处理流程：

1. 查询 o_project 获取 videoRatio（16:9 或 9:16）
2. 从 o_storyboard 或 o_assets 查询关联图片路径
3. 通过 u.oss.getImageBase64() 转为 base64
4. 插入 o_video 记录，状态设为"生成中"
5. 异步调用 u.Ai.Video(model).run({...}, taskRecord)
6. 生成成功后 aiVideo.save(videoPath)，更新状态为"生成成功"

5.3 视频提示词生成引擎

POST /api/production/workbench/generateVideoPrompt

核心逻辑：

1. 接收 trackId、projectId、info（素材/分镜列表）、model
2. 拆分 assets 和 storyboard 数据
3. 从 o_prompt 表加载 videoPromptGeneration 类型的提示词模板
4. 通过 u.getArtPrompt(artStyle, "art_skills", "art_storyboard_video") 获取视觉风格约束
5. 调用 u.Ai.Text("universalAi").invoke() 生成视频提示词
6. 结果保存到 o_videoTrack.prompt

5.4 视频生成模式体系

5.5 视频提示词模板体系（4 种模式）

模式一：通用多参模式（MVL 多模态融合）

适用模型：KlingOmni、可灵 v3-omni 等支持多图引用的模型

格式：

[References]
@图1 : [角色A参考图]
@图2 : [角色B参考图]
@图3 : [场景参考图]
@图4 : [分镜图1]

[Instruction]
Based on the storyboard from @图4 to @图5 :
@图1 {动作/状态描述（英文）},
@图2 {动作/状态描述（英文）},
set in the {场景描述（英文）} of @图3 ,
{镜头/运镜描述（英文）},
{情感基调（英文）},
{台词描述（英文）/ No dialogue},
{音效描述（英文）}.

核心规则：

• MVL 多模态融合：自然语言 + 图像引用在同一语义空间
• 分镜图序列负责动作/时间轴/构图，场景参考图负责环境一致性
• 所有资产和分镜图统一用 @图N 引用
• 台词不可缺失，区分 dialogue / inner monologue OS / voiceover VO

模式二：通用首尾帧模式（纯文本五维度）

适用模型：Seedance 1.5 Pro、不支持多参引用的模型

格式：

[Visual]
{主体A名}: {外观简述}, {站位/姿态}, {说话状态 speaking/silent}.
{主体B名}: {外观简述}, {站位/姿态}, {说话状态}.
{场景描述}, {道具描述}.
{视觉风格标签}.

[Motion]
0s-{X}s: {主体A名} {动作描述段1}.
{X}s-{Y}s: {主体B名} {动作描述段2}.

[Camera]
{镜头类型}, {运镜方式}, {全程单一连贯镜头描述}.

[Audio]
{Xs-Ys}: "{台词内容}" — {说话者名} ({dialogue / inner monologue OS / voiceover VO}), {lip-sync active / silent lips}.
{音效描述}.

[Narrative]
{情节点概述}, {叙事位置}.

核心规则：

• 纯文本提示词，不使用任何 @图N 引用
• 五维度结构：Visual / Motion / Camera / Audio / Narrative
• 全程单一连贯镜头，从头到尾不切镜
• 每个主体必须标注说话状态：speaking / silent / speaking simultaneously

模式三：Seedance 2.0（结构化 12 维编码）

适用模型：火山 Seedance 2.0

格式：

画面风格和类型: {风格}, {色调}, {类型}

生成一个由以下 {N} 个分镜组成的视频:

场景:
分镜过渡: {全局过渡描述}

分镜1<duration-ms>{毫秒数}</duration-ms>: 时间：{日/夜/晨/黄昏}，场景图片：@图{场景编号} ，镜头：{景别}，{角度}，{运镜}，@图{角色编号} {动作/表情/视线朝向/站位描述}。{台词与音色描述（如有）}。{背景环境补充}。{光影氛围}。{运镜补充}。

核心规则：

• 中文提示词
• 结构化 12 维编码
• 毫秒级时长控制（秒 × 1000）
• 音色参数 9 维度精细描述（有台词时必填）：性别、年龄音色、音调、音色质感、声音厚度、发音方式、气息、语速、特殊质感
• 台词类型标注：普通对白「说：」、内心独白「内心OS：」、画外音「画外音VO：」

模式四：Wan 2.6（叙事式英文提示词）

适用模型：阿里万相 Wan 2.6

格式：

{风格基调一句话定性},
{主体名} {外观简述}, {具体动作/姿态描述}, {情绪/表情用动作暗示}.
{场景背景主体}, {具体环境物件}, {空间感}, {时间/天气}.
{光线方向/色温} {质感描述}, {情绪暗示光影}.
{台词描述（如有，含 dialogue/OS/VO 标注）/ No dialogue}.
{音效描述}.
{拍摄方式}, {景别}, {视角}, {运镜方式}.

核心规则：

• 叙事式英文提示词，像写小说一样描写画面
• 三段式结构：风格基调 → 主体动作+场景环境+光线氛围 → 镜头收尾
• 不使用 @图N 引用，纯文本描述
• 禁止标签堆砌（不写 4K, cinematic, high quality）
• 情绪用动作暗示，不直接陈述「他很悲伤」

5.6 视频提示词模式路由规则

5.7 景别 → 镜头标签映射

5.8 运镜 → 镜头标签映射

5.9 艺术风格注入体系

每个画风 Skill 在 art_prompt/art_storyboard_video.md 中定义视频提示词风格标签：

示例（真人古风）：

示例（3D 动漫渲染）：

5.10 视频供应商适配器架构

所有视频供应商通过统一的 VideoConfig 接口接入：

interface VideoConfig {
  duration: number;           // 视频时长（秒）
  resolution: string;         // 分辨率（720p/1080p）
  aspectRatio: "16:9" | "9:16"; // 宽高比
  prompt: string;             // 视频提示词
  referenceList?: ReferenceList[]; // 参考素材（图片/视频/音频 base64）
  audio?: boolean;            // 是否生成音频
  mode: VideoMode[];          // 生成模式
}

type VideoMode =
  | "singleImage"
  | "startEndRequired"
  | "endFrameOptional"
  | "startFrameOptional"
  | "text"
  | (`videoReference:${number}` | `imageReference:${number}` | `audioReference:${number}`)[];

供应商代码执行流程：

1. getVendorTemplateFn("videoRequest", modelName) 从 o_vendorConfig 加载供应商代码
2. 使用 sucrase 实时转译 TypeScript → JavaScript
3. vm2 沙箱执行供应商代码
4. 沙箱内暴露：AI SDK 提供商、axios、sharp 工具、pollTask 轮询函数等
5. 供应商代码调用外部 API，返回 base64 视频数据
6. AiVideo.save() 写入本地 OSS

5.11 预置视频供应商

可灵 AI（klingai.ts）

• 版本：2.0
• 认证：JWT（HS256，accessKey + secretKey）
• 接口：https://api-beijing.klingai.com
• 视频模型：
  • kling-video-o1（Omni，支持多参）
  • kling-v3-omni（Omni，支持多参）
  • kling-v3（标准/专家）
  • kling-v2-6（标准/专家）
  • kling-v2-5-turbo（标准/专家）
  • kling-v2-1（标准/专家/Master）
  • kling-v1-6（标准/专家，支持多图参考）
  • kling-v1-5（标准/专家）
  • kling-v1（标准/专家）
• 模式支持：text / singleImage / startEndRequired / endFrameOptional / startFrameOptional / 多参数组
• 音频：部分模型支持 sound: on/off
• 接口分类：
  • Omni 模型：/v1/videos/omni-video
  • 多图参考：/v1/videos/multi-image2video
  • 文生视频：/v1/videos/text2video
  • 图生视频：/v1/videos/image2video

Vidu（vidu.ts）

• 认证：API Key（Token 格式）
• 接口：https://api.vidu.cn/ent/v2
• 视频模型：ViduQ3 turbo/pro、ViduQ2 pro/fast/turbo、ViduQ1/Q2、Vidu2.0
• 模式支持：singleImage / startEndRequired / text
• 音频：全部支持音频生成
• 特色：支持图片生成（viduq1/viduq2 for image）

火山引擎/豆包（volcengine.ts）

• 版本：2.3
• 认证：Bearer Token
• 接口：https://ark.cn-beijing.volces.com/api/v3
• 视频模型：
  • Seedance-2.0（音画同生，支持多参）
  • Seedance-2.0-Fast
  • Seedance-1.5-Pro（音画同生）
  • Seedance-1.0-Pro/Fast/Lite
• 模式支持：text / startFrameOptional / 多参数组（imageReference:9, videoReference:3, audioReference:3）
• 音频：optional（Seedance 2.0/1.5）
• 接口：/contents/generations/tasks

MiniMax/海螺（minimax.ts）

• 版本：2.1
• 认证：Bearer Token
• 接口：https://api.minimaxi.com
• 视频模型：
  • 海螺 2.3（标准/极速版）
  • 海螺 02
• 模式支持：text / singleImage / startEndRequired
• 音频：不支持
• 接口：/v1/video_generation

5.12 视频生成自动化流程设计参考

阶段 5 分镜面板写入模式决策：

视频生成完整自动化流水线：

阶段1: 衍生资产分析
  ↓
阶段2: 衍生资产生成（可选，用户确认）
  ↓
阶段3: 导演规划（需监督层审核）
  ↓
阶段4: 构建分镜表（需监督层审核）
  ↓
阶段5: 分镜面板写入（确定多参/首尾帧模式）
  ↓
阶段6: 分镜图生成（异步）
  ↓
视频提示词生成（根据模型选择4种模式之一）
  ↓
视频生成（异步调用供应商 API）
  ↓
视频保存到轨道

关键约束：

• 分组累计时长不得超过 15 秒
• 仅可使用分镜面板中的真实分镜 ID 发起生成
• 图片内容需与分镜描述一致
• 阶段3、4、5、6 只能使用资产库中已存在的资产

6. 提示词体系（完整提取）

6.1 系统提示词模板

事件提取提示词（eventExtraction）

• 用途：逐章提取小说结构化事件信息
• 输出格式：单行 7 字段表格，以 | 开头结尾
• 字段：章节 | 涉及角色 | 核心事件 | 主线关系 | 信息密度 | 预估集长 | 情绪强度
• 约束：完整回复只有一行，无前缀后缀，不输出表头

剧本资产提取提示词（scriptAssetExtraction）

• 用途：从剧本提取角色、场景、道具资产
• 输出：必须通过 resultTool 工具返回，禁止纯文本输出
• 字段：name / desc / prompt / type（role/scene/tool）
• 规则：忠于剧本、视觉优先、精简实用、分类准确

视频提示词生成（videoPromptGeneration）

• 用途：根据分镜信息生成模型特定的视频提示词
• 模式：通用多参 / 通用首尾帧 / Seedance 2.0 / Wan 2.6
• 输入：资产信息 + 分镜 <storyboardItem> XML 列表
• 输出：单个完整的视频提示词文本

6.2 Agent Skill 提示词文件

6.3 艺术风格 Skill（10+ 种画风）

目录结构：

data/skills/art_skills/
├── {style_name}/
│   ├── prefix.md                    # 全局美学规则、色彩板
│   ├── art_prompt/
│   │   ├── art_character.md         # 角色生成提示词
│   │   ├── art_scene.md             # 场景生成提示词
│   │   ├── art_prop.md              # 道具生成提示词
│   │   └── art_storyboard_video.md  # 分镜/视频提示词风格约束
│   └── driector_skills/
│       ├── director_planning_style.md   # 导演规划风格
│       └── director_storyboard.md       # 分镜导演风格

预置画风：

6.4 故事风格 Skill（12 种叙事类型）

目录：data/skills/story_skills/

每个包含：

• director_planning_narrative.md — 导演规划叙事风格
• director_storyboard_table_narrative.md — 分镜表叙事风格

7. 开源组件与依赖

7.1 核心生产依赖

7.2 预置 AI 模型提供商

7.3 开源许可证

• 主项目：Apache-2.0
• 附带协议：补充商业协议（含分发限制条款）

8. 数据模型

8.1 核心实体

8.2 视频相关数据表

9. 核心架构模式与设计

9.1 三层 Agent 协作体系

决策层 (Decision Layer)
    ↓ 派发任务
执行层 (Execution Layer) — 多个子 Agent
    ↓ 输出结果
监督层 (Supervision Layer) — 质量校验

• ScriptAgent：故事骨架 → 改编策略 → 剧本生成
• ProductionAgent：衍生资产 → 生成资产 → 导演规划 → 分镜表 → 分镜面板 → 分镜图生成

9.2 文件系统即路由

使用 fast-glob 扫描 src/routes/**/*.ts，自动生成 src/router.ts。文件路径自动映射为 API 路由，共 153 条路由。

9.3 Skill 驱动架构

• Skill 文件位于 data/skills/
• 支持 YAML frontmatter 元数据
• 通过 parseFrontmatter() 和 useSkill() 加载
• 提供 activate_skill 和 read_skill_file 工具给 AI Agent

9.4 供应商热插拔系统

• 供应商代码为 TypeScript 文件，存放于 data/vendor/
• 通过 vm2 沙箱执行，隔离环境
• 使用 sucrase 实时转译 TypeScript → JavaScript
• 暴露 AI SDK 提供商、sharp、axios、FormData、jsonwebtoken 等给沙箱

9.5 持久化 Agent 记忆系统

• 3 层记忆架构：短期消息 / 长期摘要 / 语义召回 (RAG)
• 使用 all-MiniLM-L6-v2 ONNX 模型进行本地嵌入
• deepRetrieve()：深度检索，结合向量搜索 + AI 相关性判断

9.6 XML-Based Agent 输出

Agent 通过 XML 标签向工作区写入数据：

• <scriptItem> — 剧本条目
• <storyboardItem> — 分镜条目
• <storyboardTable> — 分镜表
• <scriptPlan> — 剧本计划

9.7 本地对象存储 (OSS)

• 基于本地文件系统的对象存储抽象
• 路径安全校验（is-path-inside 防止目录遍历）
• 支持：文件读写、图片 base64 转换、缩略图自动生成（Sharp 512px）

10. 非功能性需求

10.1 性能要求

• API 响应时间：普通接口 < 200ms，AI 接口依赖外部服务
• 本地嵌入推理：单次 < 500ms（CPU）
• 图片生成：依赖外部 API，支持异步队列

10.2 可扩展性

• 供应商系统支持热插拔新模型
• Skill 文件化支持无代码调整 Agent 行为
• 模块化路由设计便于功能扩展

10.3 安全性

• JWT 认证保护 API
• vm2 沙箱隔离供应商代码执行
• 本地数据存储，不上传用户原创内容

10.4 兼容性

• 支持 Windows 10+ / macOS 12+ / Linux
• 支持 Docker 容器化部署
• 支持现代浏览器访问 Web 端

11. 路线图（Roadmap）

12. 自动化流程设计参考（技术提取）

12.1 剧本改编流水线（ScriptAgent）

项目初始化（确认参数）
  ↓
阶段1: 故事骨架
  - 输入：事件表（get_novel_events）
  - 处理：三幕分割、按项目配置分集、删减决策、钩子设计
  - 输出：planData.storySkeleton
  - 审核：监督层审核 → 用户确认
  ↓
阶段2: 改编策略
  - 输入：事件表 + storySkeleton
  - 处理：提炼改编原则、确定删减依据、世界观呈现策略
  - 输出：planData.adaptationStrategy
  - 审核：监督层审核 → 用户确认
  ↓
阶段3: 剧本编写
  - 输入：事件表 + storySkeleton + adaptationStrategy
  - 处理：逐集编写，每次一集，单次上限5集
  - 输出：SQLite 剧本记录
  - 循环调度，静默执行，完成后一次性通知

12.2 视频生产流水线（ProductionAgent）

阶段1: 衍生资产分析
  - 输入：剧本 + 已有资产
  - 输出：衍生资产清单（或"无需衍生"）
  - 用户确认后进入阶段2（或跳过）
  ↓
阶段2: 衍生资产生成（可选）
  - 输入：用户确认的资产清单
  - 输出：图片生成启动（异步）
  ↓
阶段3: 导演规划
  - 输入：剧本 + 资产库
  - 输出：导演拍摄计划
  - 审核：监督层审核 → 用户确认
  ↓
阶段4: 构建分镜表
  - 输入：剧本 + 导演计划 + 资产库
  - 输出：结构化分镜表
  - 审核：监督层审核 → 用户确认
  ↓
阶段5: 分镜面板写入
  - 根据模型参数`多参`决定写入模式
  - 模式：纯文本多参 / 分镜图辅助多参 / 首位帧模式
  - 约束：分组累计时长不得超过15秒
  ↓
阶段6: 分镜图生成
  - 输入：分镜面板
  - 输出：分镜图片（异步）
  ↓
视频提示词生成
  - 根据模型名称路由到4种提示词模式之一
  - 输出：模型特定格式的视频提示词
  ↓
视频生成
  - 调用供应商 API（异步）
  - 轮询获取结果
  - 保存到本地 OSS

12.3 关键技术提取

AI 抽象层设计：

• AiText：封装 generateText / streamText
• AiImage：封装图片生成，支持 referenceList
• AiVideo：封装视频生成，支持多种 mode
• AiAudio：封装 TTS 生成
• 统一通过 resolveModelName() 从 o_agentDeploy 查询配置
• 统一通过 getVendorTemplateFn() 动态加载供应商代码

供应商沙箱设计：

• 输入：TypeScript 代码字符串
• 处理：sucrase 转译 → vm2 沙箱执行
• 输出：暴露 textRequest / imageRequest / videoRequest / ttsRequest 函数
• 沙箱内可用：axios、sharp 工具函数、pollTask、所有 AI SDK 提供商创建函数

任务追踪设计：

• 所有 AI 调用通过 withTaskRecord() 包裹
• 自动创建 o_tasks 记录
• 成功/失败自动更新状态
• 支持 projectId 级别的任务追踪

文档版本：v2.0
最后更新：2026-04-21
产品：Toonflow（通流）AI 短剧创作平台