Remotion Video — Agent 驱动的视频生成项目服务

从 SRT 字幕到完整 Remotion 视频的端到端工作流。支持 MCP 驱动、多 Provider TTS 语音合成、异步任务队列、实时 Web 控制台。

---

架构

用户 → ZCode / Codex / Claude Code → Skill (SKILL.md)
                                         ↓
                                   MCP Server (17 工具, stdio)
                                         ↓
                                  Domain Service (Express + SSE)
                                         ↓
                             Core (SQLite + Provider + Artifact + Run 队列)
                                         ↓
                           scripts/*.js + tts/*.py + Remotion CLI
                                         ↓
                                    Web 控制台 (React SPA)

四层分离：

层	目录	职责
Skill	SKILL.md + references/	触发条件、工作流编排、质量标准
MCP Server	server/mcp/	17 个 MCP 工具，Agent 通过 stdio 调用
Domain Service	server/api/ + server/core/	Express API + SSE + SQLite + 异步队列 + Worker
Provider	server/core/providers/	封装 scripts/.js / tts/.py / Remotion CLI

快速开始

安装

git clone https://github.com/techdou/remotion-video.git
cd remotion-video

# 安装后端依赖
npm install

# 安装前端依赖
cd web-ui && npm install && cd ..

# 安装模板依赖（首次）
cd template && npm install && cd ..

构建

# 构建后端（TypeScript → dist/）
npm run build

# 构建前端（JSX → app.js）
npx esbuild web-ui/public/app.jsx --bundle --format=iife --jsx=transform \
  --outfile=web-ui/public/app.js

启动

# 启动 Domain Service（API + Worker + Web 控制台）
node dist/index.js
# → http://127.0.0.1:3210

# 启动 MCP Server（另一个终端，供 Agent 调用）
node dist/mcp.js

核心能力

MCP Server（17 个工具）

Agent 通过 MCP 协议调用以下工具，所有长任务异步执行（立即返回 runId）：

工具	用途
get_project_context	获取项目完整上下文（project + runs + artifacts）
get_capabilities	列出 Provider 能力和支持的 run 类型
start_run	提交异步任务（init/render/tts/validate 等）
get_run_status	查询任务状态和进度
cancel_run	取消运行中的任务
list_artifacts	列出项目产物
set_artifact_status	设置产物状态（draft→candidate→selected→final）
test_provider	测试 Provider 连通性
...	完整 17 个工具见 server/mcp/index.ts

异步 Run 队列

• SQLite-backed：任务持久化，进程崩溃不丢失
• Worker Lease + Heartbeat：防止任务被重复执行
• 崩溃恢复：启动时扫描超时 run，自动标记 failed 或重新排队
• AbortSignal：取消信号贯穿 Provider → 子进程 → 下载 → 重试

Provider 系统

三种 Provider 封装现有脚本，通过子进程 spawn 调用（不修改原脚本）：

Provider	包装对象	操作
script	scripts/*.js (CommonJS)	init / storyboard / creators / registry / validate
tts	tts/*.py (Python)	tts（语音合成）/ merge_speech（合并音轨）
render	npx remotion render	render（视频渲染）

TTS 语音合成（3 个 Provider）

Provider	平台	配置
openai (默认)	OpenAI / 硅基流动 / 火山方舟 / OneAPI	TTS_API_KEY + TTS_BASE_URL
mimo	小米 MiMo	MIMO_API_KEY（Chat Completions 格式）
edge	Edge TTS	免费本地，无需 API Key

配置见 .env.example。时间轴策略：SRT 驱动，每段语音放在原始时间点。

Artifact 系统

每个产物记录：ID、类型、状态（draft→candidate→selected→final→archived）、来源 Run、父 Artifact（版本树）。

Web 控制台

多页面 SPA，学者暖色系设计（亚麻 #F5F3EE + 陶杯 #C0785A + 衬线字体）：

• 控制台：项目统计、活跃任务、最近项目
• 项目：项目列表 + 新建
• 项目工作区：Pipeline 步骤 / 产物版本 / 任务记录（三标签页）
• Provider：能力列表 + 连通性测试
• 设置：TTS 配置管理

目录结构

remotion-video/
├── server/                      # TS 业务内核
│   ├── core/
│   │   ├── types.ts             # 接口定义
│   │   ├── db.ts                # SQLite + WAL + migration
│   │   ├── storage.ts           # CRUD + revision 乐观锁
│   │   ├── run-queue.ts         # 异步队列 + Worker + 崩溃恢复
│   │   ├── artifact-store.ts    # 产物文件存储 + 版本管理
│   │   ├── config.ts            # .env 读取 + 脱敏 + 路径防护
│   │   ├── providers/           # Provider 系统
│   │   │   ├── base.ts          # 接口
│   │   │   ├── script-provider.ts
│   │   │   ├── tts-provider.ts
│   │   │   ├── render-provider.ts
│   │   │   └── registry.ts
│   │   ├── migrations/          # SQL 迁移
│   │   └── tests/               # 34 个测试
│   ├── mcp/index.ts             # MCP Server (17 工具)
│   ├── api/index.ts             # Express API + SSE
│   └── index.ts                 # 主入口
├── web-ui/                      # React 控制台
│   ├── public/
│   │   ├── app.jsx              # 源码（需编译）
│   │   ├── styles.css
│   │   └── vendor/              # React 18 本地化
│   └── ...
├── scripts/                     # 工作流脚本 (CommonJS)
├── tts/                         # TTS Python 子系统
│   ├── generate-speech.py
│   ├── merge-speech.py
│   └── providers/               # openai / mimo / edge
├── template/                    # Remotion 项目模板
├── rules/                       # 40+ Remotion 最佳实践规则
├── references/                  # 工作流协议文档
├── SKILL.md                     # Agent 技能定义
├── .env.example                 # TTS 配置模板
├── tsconfig.json
└── tsup.config.ts

测试

# 运行全部 34 个测试
npx tsx --test server/core/tests/storage.test.ts server/core/tests/advanced.test.ts

覆盖：Project CRUD、Run 生命周期、Artifact 版本树、revision 乐观锁并发、Worker lease/heartbeat、崩溃恢复、Provider 能力探测和错误处理。

安全

• 绑定 127.0.0.1：Domain Service 不暴露局域网
• 路径穿越防护：validateProjectPath 精确匹配项目目录
• API Key 脱敏：GET 返回 sk-abc***，PUT 跳过脱敏值
• CORS 限制：仅允许 localhost
• 配置合并写入：保留 .env 注释，key 格式校验，拒绝换行注入

依赖

依赖	用途
Node.js 18+	运行环境
Python 3.9+	TTS 子系统
ffmpeg	语音合并
better-sqlite3	SQLite 驱动
@modelcontextprotocol/sdk	MCP Server
express	HTTP API
edge-tts (可选)	免费 TTS

License

MIT © 2025 techdou