# 03 · 三开源项目对比与吸收

## 1. 三个项目一句话画像

| 项目 | 路径 | 定位 | 最大亮点 |
|------|------|------|----------|
| **Toonflow-app** | `Toonflow-app/` | Electron 桌面 AI 短剧工程 | **三层 Agent 协作 + Skill 外化 + 可编程供应商系统** |
| **AIComicBuilder** | `aibuildvideo/AIComicBuilder/` | Next.js 漫剧 Web 全栈 | **角色一致性双轨制 + 12 个提示词插槽化管理 + 首尾帧+视频插值** |
| **waoowaoo** | `waoowaoo/` | Next.js 企业级 AI 视频 SaaS | **BullMQ 任务队列 + 余额冻结计费 + 多租户 + 国际化 + 代码卫士** |

## 2. 功能矩阵

| 维度 | Toonflow | AIComicBuilder | waoowaoo | 吸收到我们项目 |
|------|----------|----------------|----------|----------------|
| 剧本解析 | ✓ 事件图谱驱动 | ✓ 四步导入流水线 | ✓ | **四步导入 + 事件提取**(AICB+Toonflow) |
| 自动分集 | ✓ 前 10 集黄金结构 | ✓ | ✗ | **采用 Toonflow 的付费卡点策略**(10/30/50/70/90%) |
| 角色四视图 | ✗ | ✓ 正面/3/4侧/侧/背 | ✗ | **必做,AICB 方案** |
| 角色参考图注入 | ✓ | ✓ Gemini 参考图 | ✓ | **必做,用通义万相参考图模式** |
| 角色关系图 | ✗ | ✓ characterRelations 表 | ✗ | **必做,影响构图和视线** |
| 分镜智能规划 | ✓ 导演 Agent | ✓ 非常细致 | ✓ | **合并 Toonflow 导演手册 + AICB shot-split** |
| 首尾帧+视频插值 | 部分 | ✓ 主力模式 | ✗ | **主力模式采用** |
| 多模态参考模式 | ✓ | ✓ Veo 3.1 | ✗ | **Pro 用户可选** |
| 三层 Agent | ✓⭐⭐⭐ | ✗ | LangGraph | **采用 Toonflow 三层架构** |
| Agent 记忆 | ✓ 向量+摘要 | ✗ | ✗ | **用 Redis Stack (RediSearch) 实现** |
| Skill 文件外化 | ✓ 159 个 .md | ✓ 12 个提示词 | ✗ | **采用 Markdown Skill 库 + 插槽化编辑** |
| 提示词版本管理 | ✗ | ✓ 完整 | ✗ | **采用 AICB 方案** |
| 可编程供应商 | ✓ VM 沙盒 | ✗ | ✓ 配置化 | **用 Spring 策略模式 + SPI** |
| 资产版本 | ✗ | ✓ shot_assets 表 | ✓ MediaObject 哈希去重 | **合并: 版本表 + 哈希去重** |
| 任务队列 | Socket.IO 简单 | 自研 | ✓ BullMQ + 4 队列 | **采用 RabbitMQ/Kafka + 队列分型** |
| 任务心跳/重试 | 部分 | ✗ | ✓ 完整 | **必做** |
| 多租户 | ✗ | ✗ | ✓ userId 隔离 | **强化: tenantId + Spring Security** |
| 计费系统 | ✗ | ✗ | ✓⭐⭐⭐ 余额冻结 | **直接采用 waoowaoo 方案** |
| 幂等性 | ✗ | ✗ | ✓ idempotencyKey | **必做** |
| 审计日志 | ✗ | ✗ | ✓ 结构化+脱敏 | **必做** |
| 国际化 | ✓ 7 种 | 4 种 | 2 种 | **中英双语起步** |
| 代码卫士 | ✗ | ✗ | ✓ 10+ 守护脚本 | **必做** |
| 测试分层 | ✗ | 部分 | ✓ 单元/集成/系统/回归 | **必做** |
| 可观测性 | ✗ | ✗ | ✓ Bull Board | **Prometheus + Grafana + Spring Actuator** |
| FFmpeg 合成 | ✓ | ✓ 字幕/转场/BGM | ✓ Remotion | **采用 AICB FFmpeg 方案** |
| TTS | 框架 | 未集成 | ✓ FAL/百炼 | **必做: 百炼 Qwen TTS** |
| 口型同步 | ✗ | ✗ | ✓ | **Pro 功能** |

## 3. 各项目核心亮点详述

### 3.1 Toonflow 亮点(架构启发)

**三层 Agent 协作体系** — 这是 Toonflow 最大的技术遗产,值得完整移植:

```
决策层 Agent
  ├─ 理解用户意图
  ├─ 任务拆解
  ├─ 调度执行/监督层
  └─ 质量把关(最终通过/驳回)
执行层 SubAgent (6 个)
  ├─ 故事骨架搭建(三幕 + 付费卡点)
  ├─ 改编策略制定
  ├─ 剧本编写
  ├─ 衍生资产分析
  ├─ 导演规划
  └─ 分镜生成
监督层 Agent
  └─ 审核执行层产出,反馈修订
```

**Skill 文件外化**: 159 个 Markdown 文件分别存储提示词、艺术手册、导演约束,运行时动态加载,改动无需重启。

**艺术风格手册**: `art_skills/2D_90s_japanese_anime/` 下有完整的角色/场景/道具约束文档,包含鹅蛋脸、6-6.5 头身、樱桃唇等具体描述 —— 直接复用!

**跨会话记忆**: 基于 ONNX all-MiniLM 做向量化,按项目 ID 隔离,支持 RAG 召回。我们改用 Redis Stack(RediSearch,HNSW + COSINE)+ 通义 embedding,Spring AI `RedisVectorStore` 直连,未来超过 64GB 再迁 Milvus(接口零改动)。

### 3.2 AIComicBuilder 亮点(工程细节)

**角色一致性双轨制**:
1. 视觉轨道: 四视图参考图 → 每次生成首尾帧时作为 reference image 注入
2. 文字轨道: 分镜拆分时强制使用完整角色名,禁止缩写和代词

**12 个提示词 + 插槽化编辑**:
- script_generate / script_parse / script_split
- character_extract / import_character_extract / character_image
- shot_split
- frame_generate_first / frame_generate_last / scene_frame_generate
- video_generate / ref_video_prompt_generate

三层优先级: **项目级覆盖 > 全局级覆盖 > 代码默认值**,且支持**版本历史+一键回滚**。

**shot_assets 统一资产表**: 一张表存 first_frame/last_frame/reference/keyframe_video/reference_video 五种类型,配合 assetVersion + isActive 实现版本管理,这个设计直接搬过来。

**四步剧本导入**: 文本抽取 → 角色提取(AI 去重) → 智能分集 → 一键创建,每步可视化、可修改、可回退。

### 3.3 waoowaoo 亮点(SaaS 基础设施)

**余额冻结机制**(核心借鉴):

```
Task 提交 → prepareTaskBilling → 估算成本 → 冻结金额(BalanceFreeze)
Task 执行 → withBilling 包装 → 收集实际用量
Task 完成 → settleTaskBilling → 解冻 + 扣费 + 写 BalanceTransaction
Task 失败 → rollbackTaskBilling → 解冻,不扣费
```

- **原子性**: 冻结即锁定余额,防止超支
- **幂等性**: idempotencyKey 防重复扣费
- **可追溯**: 每笔扣费都有 Transaction 流水
- **自动清理**: 过期冻结自动释放

**MediaObject 统一媒体管理**: 单一媒体表 + sha256 内容哈希 + 40+ 种关系,DRY 原则。

**代码卫士(Guards)**:
- `check:api-handler` — API 签名规范
- `check:prompt-i18n` — 提示词本地化
- 禁止 LLM 直接写在 API(必须走 worker)
- 禁止模型配置硬编码

**测试分层**: 单元 + 集成 + 系统 + 回归 + 并发 + 合约,CI 守护质量。

## 4. 我们的吸收策略

### 4.1 直接搬运(少改)

- AIComicBuilder 的 `shot_assets` 表设计
- AIComicBuilder 的 12 个提示词分类 + 插槽化编辑 + 版本历史
- AIComicBuilder 的四步剧本导入 UX
- AIComicBuilder 的角色四视图生成提示词
- waoowaoo 的 `UserBalance` / `BalanceFreeze` / `BalanceTransaction` 三表结构
- waoowaoo 的 `MediaObject` 统一媒体表
- Toonflow 的 `art_skills/` 艺术手册全套 Markdown 文件
- Toonflow 的故事骨架提示词(三幕 + 付费卡点)

### 4.2 架构移植(Node → Java)

- Toonflow 三层 Agent → Spring AI Alibaba + Tool Use + 多 Chain
- Toonflow 供应商 VM 系统 → Java SPI + Strategy Pattern + `@Component`
- Toonflow Agent Memory → Redis Stack(RediSearch)+ 通义 embedding + Spring AI `RedisVectorStore`
- waoowaoo BullMQ → RabbitMQ/Kafka + Spring AMQP + 多队列(image/video/voice/text)
- waoowaoo NextAuth → Sa-Token(Redis 会话)+ Sa-Token-OAuth2
- waoowaoo Prisma → MyBatis-Plus + Flyway
- waoowaoo next-intl → Spring MessageSource + i18n

### 4.3 自研强化

- **多租户**: 强化到 tenantId + RLS(行级安全)或租户库分库
- **订阅支付**: 集成支付宝/微信/Stripe,waoowaoo 只做了按量
- **权限模型**: RBAC + ABAC,细到分镜级别
- **可观测性**: Prometheus + Grafana + SkyWalking 链路追踪
- **资产市场**: 社区分享+付费购买资产(差异化功能)

## 5. 明确不用的设计

- ❌ Toonflow 的 SQLite — 直接上 MySQL
- ❌ Toonflow 的 Electron 打包 — 我们是 Web SaaS
- ❌ Toonflow 的 VM2 供应商系统 — 安全隐患,改 Java SPI
- ❌ waoowaoo 的 Remotion — 用 FFmpeg 够了,Remotion 是 React 依赖
- ❌ AIComicBuilder 的 SQLite + Drizzle — 同上
- ❌ 三个项目的单机部署 — 我们要分布式
