内容
# RealReel
一个生成针对ICP（理想客户画像）的产品营销视频的AI代理，通过一个自我改进的循环，即参考挖掘、生成、自我批评和持续学习，使其在每次运行中都变得明显更好。
在[AI Engineer World's Fair 2026](https://www.ai.engineer/worldsfair/2026)黑客马拉松上构建，由[Cerebral Valley](https://cerebralvalley.ai/e/aiewf-hackathon-2026)组织。
## 问题
创建产品营销视频很慢，很昂贵，且千篇一律。大多数工具都产生一种通用输出，不能与任何特定受众产生共鸣。没有反馈循环——你发布视频，希望它有效。
## 解决方案
RealReel是一个围绕**自我改进循环**构建的视频生成代理。给定一个产品网址和理想客户画像（ICP），它：
1. **挖掘** - 通过[Exa](https://exa.ai)语义搜索发现已经引起ICP共鸣的高性能参考内容，并通过YouTube Data API的真实参与度数据对其进行排名。
2. **提取模式** - 将参考语料库输入Gemini以构建`ResonanceProfile`：哪些钩子有效，理想的节奏，字幕密度，视觉主题和需要避免的内容。
3. **生成** - 捕获您的产品（使用Playwright），使用Gemini图像生成创建标题/行动号召卡，使用Veo 3.1生成B卷，并使用FFmpeg将所有内容组合成特定平台的格式（TikTok/Reels，YouTube，LinkedIn等）。
4. **自我批评** - 批评代理根据ICP派生的评分标准（钩子强度，静音可读性，节奏，共鸣，行动号召清晰度等）评估输出，并发出有针对性的再生操作。
5. **迭代** - 重新生成弱组件，重新组合并重新评分，直到视频达到质量阈值或达到迭代上限。
6. **学习** - 将参考资料，共鸣配置文件，生成结果和批评分数持久化到MongoDB Atlas（使用Voyage嵌入），以便为同一ICP的未来运行从学习到的最佳模式开始提供冷启动。
结果：运行#20比运行#1产生更好的有针对性的视频，而无需进行任何手动调整。
## 架构
```
ICP Profile
│
▼
[1] 参考挖掘（Exa + YouTube API）
│
▼
[2] 模式提取（Gemini）→ 共鸣配置文件
│
▼
[3] 生成（Playwright捕获 + Gemini卡片 + Veo B卷 + Lyria音乐）
│
▼
[4] FFmpeg合成（每个平台的渲染配置文件）
│
▼
[5] 自我批评（Gemini批评代理）
│
├── 低于阈值 → 重新生成弱组件 → 返回[3]
│
▼ （通过）
[6] 输出 + 内存（MongoDB Atlas + Voyage嵌入）
```
## 渲染配置文件
视频针对每个目标平台使用相同的源资产进行合成：
| 配置文件 | 分辨率 | 比例 | 平台 | 时长 |
|---|---|---|---|---|
| `social_vertical` | 1080x1920 | 9:16 | TikTok, Reels, Shorts | 15-30秒 |
| `feed_portrait` | 1080x1350 | 4:5 | Instagram, LinkedIn feed | 15-30秒 |
| `square` | 1080x1080 | 1:1 | 旧版feed，广告单元 | 15-30秒 |
| `landscape` | 1920x1080 | 16:9 | Twitter, LinkedIn, 网页 | 20-45秒 |
| `youtube` | 1920x1080 | 16:9 | YouTube 观看页面 | 30-60秒 |
## 设置
### 先决条件
- Docker
- API密钥（见下文）
### 环境变量
在项目根目录下创建一个`.env`文件：
```env
GEMINI_API_KEY=您的gemini_api_key
EXA_API_KEY=您的exa_api_key
YOUTUBE_API_KEY=您的youtube_data_api_v3_key
# 可选 - 启用跨运行学习
MONGODB_URI=mongodb+srv://用户:密码@集群/数据库
VOYAGE_API_KEY=您的voyage_api_key
```
**获取密钥：**
- **Gemini API密钥** - [Google AI Studio](https://aistudio.google.com/apikey)
- **Exa API密钥** - [Exa Dashboard](https://dashboard.exa.ai)
- **YouTube Data API密钥** - [Google Cloud Console](https://console.cloud.google.com) → APIs & Services → 启用“YouTube Data API v3” → 创建凭证 → API密钥 → 选择“公共数据”
- **MongoDB Atlas** （可选）- [MongoDB Atlas](https://cloud.mongodb.com) 免费层
- **Voyage AI** （可选）- [Voyage AI](https://www.voyageai.com)
### 构建和运行
```bash
# 构建Docker镜像
docker build -t product-video-factory .
# 运行服务器
docker run --rm --env-file .env -p 8000:8000 -v "$(pwd)/output:/app/output" product-video-factory
```
MCP服务器在`http://localhost:8000/mcp`启动，使用Streamable HTTP传输。
### 连接MCP客户端
将以下内容添加到您的MCP客户端配置中（例如`.mcp.json`适用于Claude Code）：
```json
{
"mcpServers": {
"video-factory": {
"type": "streamable-http",
"url": "http://localhost:8000/mcp"
}
}
}
```
## 用法
### MCP工具
**`launch_video_generation`** - 启动视频生成作业。
```json
{
"url": "https://您的产品.com",
"video_prompt": "显示仪表板，创建新项目，演示AI功能",
"icp": {
"name": "种子阶段的技术创始人",
"persona": "成为创始人的工程师；信任实时产品视频和同行信号。",
"pains": ["手动GTM占用构建时间", "通用演示不显示实际产品"],
"desired_outcomes": ["在没有营销人员的情况下发布营销内容", "证明工具在20秒内有效"],
"platforms": ["youtube", "linkedin"],
"seed_accounts": [],
"seed_reference_urls": ["https://youtube.com/watch?v=示例"],
"keywords": ["产品演示开发工具", "创始人启动视频"],
"tone": "构建者到构建者，快速，技术性，无废话",
"banned_styles": ["企业语音", "库存镜头", "缓慢的标志介绍"]
},
"profiles": ["social_vertical", "landscape"],
"max_iterations": 3
}
```
立即返回一个`job_id`。作业在后台运行。
**`monitor_job_status`** - 轮询正在运行的作业。
```json
{
"job_id": "a1b2c3d4"
}
```
返回完整的作业状态，包括日志、每次迭代的批评分数和输出文件路径。
### MCP资源
**`factory://dashboard`** - 所有作业的Markdown摘要。
## 项目结构
```
realreel/
├── server.py # FastMCP服务器 + 作业协调器
├── loop.py # 自我改进循环控制器
├── icp.py # ICP + ResonanceProfile数据类
├── mining.py # Exa + YouTube参考挖掘
├── resonance.py # Gemini模式提取
├── pipeline.py # Playwright捕获 + Gemini卡片 + Veo + Lyria
├── critic.py # 针对ICP评分标准的自我批评
├── compose.py # FFmpeg图构建器
├── profiles.py # 渲染配置文件定义
├── memory.py # MongoDB Atlas + Voyage持续学习存储
├── publish.py # 封闭发布 + 参与度拉取
├── templates/ # 设备框架PNG用于模拟合成
└── output/ # 生成的工件（卷挂载）
```
## 自我批评的工作原理
批评者根据7个维度（0-10）评估每个视频：
| 维度 | 测量内容 |
|---|---|
| 钩子强度 | 落在目标窗口内，与ICP相关 |
| 静音可读性 | 完全静音（自动播放现实） |
| 节奏 | 剪辑节奏与共鸣配置文件目标相比 |
| ICP共鸣 | 匹配钩子/主题/基调模式以适应此ICP |
| 安全区域合规性 | 平台UI叠加层下无关键内容 |
| 行动号召清晰度 | CTA清晰且无歧义 |
| 品牌一致性 | 整个片段中类型/颜色/标志一致 |
评分低于7.0的视频会触发有针对性的再生 - 仅重建弱组件，不会重建整个视频。
