AiVideo/ARCHITECTURE.md

AiVideo Architecture Guide

1. 项目目标与当前定位

该项目是一个 AIGC 视频 POC，核心能力是把用户 prompt 转成三分镜短视频，并通过 Node API 流式返回进度与结果。当前实现已经覆盖：

• 分镜生成（script）
• 单分镜润色（refine）
• 视频渲染与合成（render）
• task_id 级别隔离输出（outputs/{task_id}/）
• Docker 内置 ComfyUI + Node + Python 联动
• 启动时自检（Comfy 可达性 + workflow/节点约束）

整体设计是「Node 作为编排/网关，Python 作为生成引擎」。

2. 目录与职责

• server/：Node API + SSE 网关 + 启动自检入口
• engine/：Python 生成引擎（LLM 分镜、TTS、Comfy、MoviePy 合成）
• scripts/：Comfy 连通性和 workflow 约束检查
• configs/config.yaml：运行时配置（Comfy 地址、模型、workflow 映射等）
• docker-compose.yml：aivideo + comfyui 双服务部署
• dev.sh：本地开发启动/日志/重建封装
• outputs/{task_id}/：任务级产物目录（分镜、润色结果、最终视频）

3. 运行架构（容器级）

• aivideo 服务
  • 运行 Node (server/index.js)
  • Node 通过 spawn 调用 Python（python -m engine.main）
  • 对外暴露 3000
• comfyui 服务
  • 默认镜像：jamesbrink/comfyui:latest
  • 对外暴露 8188
  • 挂载 ./ComfyUI/* 到容器 /comfyui/*
• 服务连接
  • aivideo 通过 http://comfyui:8188 访问 ComfyUI API（容器内 DNS）

4. 应用架构（进程级）

4.1 Node 层（server/index.js）

职责：

• 提供 HTTP/SSE 接口
• 统一生成 task_id 并创建输出目录
• 把请求参数透传给 Python 引擎
• 把 Python stdout 协议行转成 SSE 事件
• 启动前执行自检（check_comfy.py + inspect_comfy_node.py）

主要接口：

• GET /api/health
• GET /api/script（SSE）
• POST /api/refine（JSON）
• POST /api/render（SSE）
• GET /api/static/...（输出视频静态托管，禁缓存）

并发策略（当前）：

• 渲染接口使用单全局锁 isBusy（同一时刻只允许一个渲染）

4.2 Python 引擎层（engine/main.py）

职责：

• 解析参数并分发 step：script/refine/render
• 处理全局风格与角色注入
• 与 OpenAI、ComfyUI、TTS、MoviePy 协同
• 按协议输出进度与结构化结果（SCENE_JSON、PROG、RENDER_DONE）

子模块职责：

• engine/script_gen.py：LLM 分镜生成与润色
• engine/audio_gen.py：Edge TTS 合成旁白
• engine/comfy_client.py：提交 workflow、轮询 history、提取产物
• engine/video_editor.py：字幕叠加 + 转场 + 最终拼接
• engine/config.py：YAML 配置读取

5. 核心流程

5.1 Script 生成

1. Node 收到 GET /api/script
2. 生成 task_id，创建 outputs/{task_id}
3. Node spawn Python --step script
4. Python 调 LLM 生成三分镜（无 key 时可 mock fallback）
5. Python 输出多行 SCENE_JSON ...
6. Node 将其转发为 SSE scene 事件

5.2 Refine 润色

1. Node 收到 POST /api/refine
2. 透传当前 scenes/scene 到 Python stdin
3. Python 调 LLM 润色指定分镜
4. 返回 SCENE_JSON，Node 组装 JSON 响应

5.3 Render 渲染

1. Node 收到 POST /api/render（SSE）
2. 全局 isBusy 判定是否可渲染
3. Python 先做 TTS（并发），再逐分镜调 Comfy
4. 收集视频 + 音频，MoviePy 合成 final.mp4
5. Python 输出 PROG 进度与 RENDER_DONE
6. Node 转发 SSE 完成事件

6. 关键设计约束

• task_id 必须贯穿 API 与引擎，保证产物隔离
• 启动自检失败时，服务不启动（fail fast）
• workflow 参数注入基于：
  • 明确 node_id，或
  • class_type fallback 自动定位
• 全局风格/角色必须双重注入：
  • LLM prompt 约束
  • 渲染前 image_prompt 装饰（character + style + scene）

7. 当前架构优势

• 职责拆分清晰：Node 编排、Python 算法，边界明确
• 可观测性较好：SSE 实时进度 + 结构化协议行
• 生产思路正确：自检机制避免“半可用”状态
• 兼容能力强：mock 路径可脱离 Comfy/LLM 快速调通

8. 主要架构风险与优化方向

P0（优先处理）

1. 作业状态只在内存

   • 问题：Node 重启后任务状态丢失，前端不可恢复
   • 建议：引入任务元数据存储（SQLite/Redis），记录状态机（queued/running/succeeded/failed）

2. 单点渲染锁 isBusy

   • 问题：无法扩展并发；请求高峰体验差
   • 建议：升级为队列模型（本地队列或 Redis/BullMQ），支持排队和取消

3. SSE 协议基于字符串前缀

   • 问题：协议演进脆弱，难版本化
   • 建议：统一 JSON line 协议（字段：type, task_id, ts, payload, version）

P1（中期）

4. 配置与环境耦合较松散

   • 建议：增加 config schema 校验（pydantic/JSON schema），启动即检查缺项与类型

5. Comfy 产物识别依赖 history + 文件存在

   • 建议：扩展更稳定的完成判定（WebSocket event 或更严格 history 状态判断）

6. 缺少全链路 trace id

   • 建议：在 Node/Python/Comfy 请求中统一注入 task_id 和 request_id

P2（长期）

7. 引擎内聚度可再提升

   • 建议：把 script/refine/render 拆成独立 use-case 模块，CLI 仅作参数适配

8. 测试体系不足

   • 建议：
   • 单元测试：config、workflow 注入、scene 解析
   • 集成测试：mock 渲染链路
   • 冒烟测试：Docker 启动 + /api/health

9. 推荐重构路线（4 周）

• 第 1 周：任务状态持久化 + API 状态查询接口（/api/tasks/:id）
• 第 2 周：渲染队列化（先单 worker），替换 isBusy
• 第 3 周：统一事件协议（JSON line + version），前后端同时改
• 第 4 周：补测试与可观测（结构化日志、错误码、性能指标）

10. 建议新增接口（便于运维和前端）

• GET /api/tasks/:task_id：任务状态与阶段信息
• POST /api/tasks/:task_id/cancel：取消任务
• GET /api/tasks/:task_id/artifacts：列出产物路径和类型
• GET /api/system/checks：最近一次自检结果

11. 性能优化清单（先易后难）

• TTS 结果按文本 hash 缓存，避免重复合成
• 分镜视频生成支持失败重试与断点继续
• MoviePy 合成参数按场景切换（开发 veryfast，生产 medium/slow）
• 对 outputs/ 增加清理策略（TTL + 最大磁盘占用阈值）

12. 你下一步可以直接做的事

1. 先落地任务持久化和状态查询（收益最大、侵入最小）
2. 再把 isBusy 改为队列（并保留单 worker）
3. 最后统一事件协议，减少前后端耦合与兼容风险

这份文档的目的不是重写现有实现，而是在保留当前可用链路的前提下，把系统逐步推进到可扩展的生产形态。