ReelAgent

一句话：把剧本变成短剧。多 LLM 协同、7 阶段全自动 Pipeline、自由对话式 Agent。

演示（Web 前端）

一段视频看懂前端能干什么：新建任务、跑 Pipeline、分镜/视频预览、审核批注、在线剪辑重拼。

https://github.com/user-attachments/assets/36b49224-227f-4453-bbc8-a0ef5994a612

它能做什么

输入一份剧本（txt/docx）或一张参考图，自动产出分集短剧成片或单图小视频：

• 智能摄取：解析剧本 → 分集 + 角色注册表 + 场景表
• 角色/场景生图：多风格底图 + 服装变体 + 场景图
• 逐镜分镜：每集 shot 级视频 prompt，一次请求闭环
• AI 视频生成：Seedance 2.0 系列图生视频，可选新增 Seedance 2.5
• BGM 生成：MiniMax 音乐按情绪分组
• ffmpeg 拼装：视频 + BGM 混音输出 mp4
• AI 审核：成片自动挑硬伤，支持 shot 级重生修复
• Clip Mode：单张参考图直出带原生对白的短视频片段
• 自由对话 Agent：reel 终端里直接聊，自动识图、自动调用工具

Pipeline 是引擎，Agent 是自动驾驶——前者保证稳定产出，后者负责听懂人话并编排。

快速开始

# 1. 安装
pip install -e .

# 2. 配置（可选；AGNES 内置免费 key，可零配置先用）
cp .env.example .env
# 编辑 .env，填入 CLAUDE_API_KEY / KIMI_API_KEY / DEEPSEEK_API_KEY 等

# 3. 启动交互终端
reel

首次启动会引导选择默认 LLM：

🎬 ReelAgent
首次使用，请选择 LLM 模型：
  1. AGNES 2.0 Flash（免费，推荐先用）
  2. Claude Opus 4.7
  3. DeepSeek V4
  4. Kimi K2.6
> 1
已选择：agnes

Web 前端（可视化操作台）

浏览器里完成新建任务、跑 Pipeline、分镜/视频预览、审核批注、在线剪辑重拼、画风/提示词/密钥管理，全程无需碰命令行。

环境要求

• Python 3.10+（后端 FastAPI，已随 pip install -e . 装好）
• Node.js 18+ 与 npm（前端构建）

一键启动（推荐）

run.py 会自动安装前端依赖 + 构建 + 起服务 + 开浏览器，API 和页面同端口：

python run.py                # 首次自动 npm install + 构建，默认 http://127.0.0.1:7788
python run.py --build        # 强制重新构建前端
python run.py --port 9000    # 自定义端口

开发模式（前端热更新 HMR）

前后端分离：后端 7788，前端 Vite dev server 5173（自动代理 /api、/media 到后端）：

python run.py --dev          # 一条命令同时起后端 + vite HMR，浏览器开 http://localhost:5173

手动安装 / 启动前端依赖

若想单独操作前端（例如只装依赖或只跑构建）：

cd web
npm install                  # 安装前端依赖
npm run dev                  # 开发模式（需另起后端：uvicorn server:app --port 7788）
npm run build                # 构建到 web/dist（供 run.py 生产模式托管）
npm run preview              # 本地预览构建产物

后端可单独启动：uvicorn server:app --reload --port 7788。

前端功能一览

技术栈：React 18 + Vite + TypeScript + Tailwind + shadcn/Radix UI；后端 FastAPI，用 SSE 推送 Pipeline 进度与 Agent 流式对话。

REPL 自由对话（推荐日常用）

安装后输入 reel 进入自然语言控制台：

> 帮我做一个韩漫风格的霸总短剧
> 剧本在 story.docx
> 用 C:\ReelAgent\TEST.png 做一段 16:9 小视频，女人说"老公..."
> 只跑 stage 1 摄取剧本
> 把第 2 集的视频重跑一下
> 审核一下并自动修复
> 看下状态
> /open
> /exit

当前 Agent 能力

• 自然语言理解：闲聊、脑暴、跑 Pipeline、查状态、改配置都能听懂。
• 自动识图：消息里带上图片路径（如 C:\ReelAgent\TEST.png），Agent 会自动调用 analyze_image 分析并基于结果回复。
• ReAct 工具调用：需要操作时自动输出 JSON 调用工具，观察结果后再决定下一步。
• 流式输出：最终回复逐字实时打印到终端。
• 技能注入：sys-prompt/*.md 会根据对话主题动态注入到系统提示里（如 clip、角色、场景、分镜等）。
• 会话记忆：~/.reelagent/session.json 保存当前任务、模型、风格、最近 50 轮历史，重启后自动续上。

内置命令

命令参考

pipeline.py（专家模式）

python pipeline.py --scene <任务ID> [选项]

*Stage1 需要 --script，纯跑 Stage4~7 不需要。

agent.py / reel（自然语言 / 交互模式）

# 非交互自然语言
python agent.py --ask "把我新传的都市爱情剧本做成韩漫风格短剧，跑完审核一下"

# 终端交互（推荐）
reel

* --task 与 --ask 至少提供一个。

7 个 Stage

Clip Mode：单图直出小视频

用一张外部参考图直接生成带原生对白的短视频片段，无需完整剧本：

python agent.py --ask "用 C:\ReelAgent\TEST.png 做一段 16:9 的小视频，保持原图风格，女人说\"老公...\"，男人说\"别走\"，最后弹出选项 A.来吧宝贝 B.我想起来还有工作"

• 参考图默认作为角色底图复用
• 对白按 角色名(音色) {中文台词} 格式直接写进 Seedance video_prompt，由模型原生生成口型/对白
• 不再默认 ffmpeg 后期烧字幕（burn_subtitles 仍作为可选工具保留）

常用示例

# 全流程
python pipeline.py --scene my --script story.docx --style 韩漫 --stages 1,2,3,4,5,6

# 只跑视频+拼装+审核
python pipeline.py --scene my --stages 4,5,6,7 --review

# 重跑分镜
python pipeline.py --scene my --stages 3 --force

# 润色粗糙剧本
python pipeline.py --scene my --script rough.txt --polish --style 赛博朋克

# Agent 全自动
python agent.py --task my --script story.docx --style 韩漫

# 自然语言全自动
python agent.py --ask "把我新传的剧本做成韩漫风格短剧"

# 只重跑视频
python agent.py --ask "重跑 my 的视频"

# 审核并自动修复
python agent.py --task my --ask "审核一下，有问题自动修"

# 查看状态
python agent.py --task my --ask "看下状态"

# 终端交互
reel

# Clip Mode
python agent.py --ask "用 C:\\ReelAgent\\TEST.png 做一段 16:9 小视频，保持原图风格，女人说\"老公...\""

# 免费全自动（AGNES 零配置）
python agent.py --task my --script story.docx --llm-provider agnes

LLM / 生图 / 视频 / BGM 供应商

*_BASE_URL / *_MODEL 均可从 .env 覆盖，支持三方代理。

图片与视频模型（2026-11-02 核对）

新模型为新增选项，不替换旧模型或默认配置。新建任务和任务详情中的模型设置均可选择图片/视频模型；任务选择保存到 control.json，重新打开或继续生成时沿用。设置页管理全局模型与 API Key。旧任务不会因为升级代码自动切换模型。

GPT Image 2.5 的参考图上限仍为 16 张，不应按版本号推断容量。OpenAI 编辑会按顺序发送全部参考图；各客户端在请求前拒绝超限输入，不静默截断。图片原始产物保留生成分辨率，Seedance 提交时另行压缩参考图副本，不改写原图。

系统提示词按当前模型和任务时长注入镜头预算、参考图预算；参考图绑定顺序保持一致。Seedance 2.5 的接入覆盖现有图片参考视频流程，音视频参考、视频编辑/延长与 MOV 输出未在本次新增。Seedream 接入单图生成/多图参考编辑，未开放图层拆分；其宽高比按官网档位模式写入提示词，由模型确定最终像素。

使用 OpenAI 时配置 OPENAI_API_KEY 与 GPT_IMAGE_MODEL，提供商选择 openai（旧 gpt-image-2 名称兼容）；使用 Seedream 时配置 SEEDREAM_API_KEY / SEEDREAM_MODEL。Seedance 使用 SEEDANCE_API_KEY。各账户仍需具备所选模型的访问权限。自定义代理模型 ID 不代表已验证能力；需要按供应商实际契约配置。

官方依据：OpenAI 图片接口、图片提示词与参数、Gemini 图片生成、Seedream 5.0、Seedance API、Seedance 2.5 提示词。

风格库

配置在 styleconfig.json，当前内置：韩漫、美漫、日漫、美式厚涂、维多利亚 2D、3D 皮克斯、爱死机、古风 3D、赛博朋克、吉卜力、2D 像素等，可自行增删。

项目结构

ReelAgent/
├── pipeline.py          # 7 Stage 生产引擎 + LLM/生图/视频客户端封装
├── reelagent/           # 新 Agent 实现
│   ├── agent.py         # ReelAgent 主类（ReAct + 流式 + 识图）
│   ├── intent.py        # 自然语言意图解析器
│   ├── planner.py       # 执行计划器（DAG）
│   ├── executor.py      # ReAct 执行引擎 + Tool Registry 桥接
│   ├── tools.py         # Tool Registry 与本地工具实现
│   ├── skills.py        # sys-prompt/*.md 作为 skill 动态注入
│   ├── review_loop.py   # 审核→重生闭环
│   ├── prefs.py         # 用户偏好记忆
│   ├── report.py        # 结构化报告
│   └── repl.py          # 终端自然语言交互 REPL
├── agent_state.py       # AgentState / Tool / ToolStatus
├── agent_core.py        # 兼容层
├── agent.py             # Agent CLI 入口
├── server.py            # FastAPI 后端（任务/Pipeline/Agent/审核/剪辑 API，SSE）
├── run.py               # Web 一键启动（构建前端 + 起服务 + 开浏览器）
├── web/                 # Web 前端（React + Vite + TS + Tailwind + shadcn）
│   ├── src/pages/       # Dashboard / 新建任务 / 任务详情 / 画风 / 提示词 / 设置
│   ├── src/views/       # 摄取/生图/分镜/视频/BGM/成片/剪辑/审核 视图
│   ├── src/api/         # 后端 API 封装
│   └── dist/            # 构建产物（生产模式由 server.py 托管）
├── ai_review.py         # AI 审核
├── styleconfig.json     # 画风库
├── sys-prompt/          # 提示词工程（skill）
├── tests/               # 单元测试（60 passed）
├── .env.example
├── pyproject.toml
└── requirements.txt

记忆系统

设计要点

• 自研 Agent 框架：没有使用 LangChain / AutoGen / LlamaIndex，直接基于 ReAct + Tool Registry 实现。
• 脏标记级联：上游修改自动标记下游阶段失效。
• 多供应商工厂：LLM / 生图 / 视频 / BGM 统一接口。
• 幂等续写：中断后从断点恢复。
• 审核闭环：AI 逐镜审核 + shot 级重生。
• 供应商可观测：每个 shot 记录 task_id / request_id / errors。
• Windows 适配：ffmpeg 路径转义、surrogate 编码清理等针对 Windows 终端做了处理。

Roadmap / TODO

• 开发 Web 前端页面，支持可视化剧本编辑、分镜预览、审核批注、在线剪辑
• 兼容 Claude Code、Cursor、Windsurf 等主流 Agent 编辑器的调用规范
• 多角色/多场景一致性与角色锁定优化
• 视频生成失败自动重试与异地容灾
• 更细粒度的成本/耗时统计面板

License

MIT