Micro-Drama Agent

Micro-Drama Agent 是一个将“用户故事/剧情梗概”自动转化为“角色一致的短剧视频内容”的多阶段 Agent 工作流。它把长链路的视频生成拆解为可控、可复用、可调试的原子环节：剧情理解与结构化规划（上游 Agent）+ 生成执行（下游工具/模型），并通过统一的 JSON Schema 在各阶段之间传递标准化数据，从而降低信息幻觉、提升链路稳定性与执行确定性。

本仓库聚焦于当前可运行的工程代码与演示资产。体积巨大的本地模型权重默认不纳入版本控制（见 .gitignore）。

项目核心功能概览

• Agent 流程编排（多阶段 Workflow）：将输入逐步转化为故事摘要、子剧本拆分、场景规划、镜头设计、角色画像、首帧生成、视频生成与拼接等关键环节，确保在“镜头/分镜”原子粒度上的指令遵循度与可复现性。
• Prompt 工程（结构化多阶段提示词体系）：上游负责剧情理解与规划，下游负责执行与生成；使用明确的 JSON Schema 作为 Agent 间标准输入输出，便于调参与定位问题。
• 人物一致性（系统级能力）：通过角色画像 Agent 产出结构化 Profile，并预生成多视角全局参考资产；在镜头首帧生成中进行角色身份注入，并引入一致性校验与自动重试，形成“生成 → 校验 → 修正”的闭环。

流程概览（Pipeline Overview）

整体链路以阶段化方式运行：

1. 输入阶段
   • 支持 --user_story（自然语言故事）或 --script_path（已有剧情 synopsis JSON）。
2. 脚本拆解（Script Decomposition）
   • 生成/读取 synopsis，并进一步拆成结构化子剧本（Sub-Script）。
3. 场景规划（Scene Planning）
   • 对每个子剧本生成场景列表与场景描述。
4. 镜头设计（Shot Design）
   • 对每个场景生成镜头（Shot）级别的结构化描述与拍摄要素。
5. 角色画像（Character Profiles）
   • 生成 Step_0_character_profiles.json，沉淀可复用的角色身份/服饰信息。
6. 角色库与多视角参考资产（CharacterBank）
   • 根据角色 Profile 生成并维护多视角 identity 参考图（front/side/back 等）。
   • 说明：这里的 CharaConsist 主要用于“根据文字 Profile 生成角色多角度参考资产 / 构建 CharacterBank”，它不是最终镜头图像生成的主流程模型。
7. 镜头首帧生成（Keyframe / First-frame）
   • 使用 InstantCharacter 在镜头级首帧生成时执行“角色身份注入”（把 CharacterBank 的参考身份稳定注入到指定 bbox 区域），以保证跨镜头/跨场景一致性。
8. 一致性校验与重试（可选）
   • 对注入区域做相似度量化检查，低于阈值自动触发“注入-重生成”。
9. 图生视频与拼接（I2V + Final）
   • 将首帧送入图生视频后端（如 HunyuanVideo_I2V / CogVideoX 等）得到分镜视频片段，并可选拼接为最终视频。

Demo

Visual Assets

Character reference example:

Generated examples:

Other Video Demos

Repository Structure

Micro-Drama Agent/
├── microdrama_agent/       # 主流程代码（Agent 编排 + 工具调用）
├── imgutils-main/          # 图像工具/依赖（工程内 vendored 版本）
├── show/                   # README 展示用资产
├── requirements.txt        # Python 依赖
└── .gitignore              # 忽略本地权重/缓存/运行产物

Installation

创建 Python 环境并安装依赖：

pip install -r requirements.txt

如果想直接使用捆绑的图像工具源代码，请保留 imgutils-main/ 目录。

Quick Start

主入口是：microdrama_agent/run.py

• 从自然语言故事生成：

python microdrama_agent/run.py \
  --user_story "A short emotional reunion story between two old friends." \
  --character_photo_path ./characters \
  --LLM deepseek-v3 \
  --gen_model InstantCharacter \
  --Image2Video CogVideoX

• 从已有 synopsis JSON 运行：

python microdrama_agent/run.py \
  --script_path ./path/to/story.json \
  --character_photo_path ./characters \
  --gen_model InstantCharacter \
  --Image2Video HunyuanVideo_I2V

• 仅生成首帧（跳过图生视频，便于调试一致性与 prompt）：

python microdrama_agent/run.py \
  --script_path ./path/to/story.json \
  --character_photo_path ./characters \
  --gen_model InstantCharacter \
  --images_only

Key Arguments

• --user_story: natural-language story input.
• --script_path: path to a prepared synopsis JSON.
• --character_photo_path: reference character image folder.
• --gen_model: keyframe generation backend.
• --Image2Video: video generation backend.
• --images_only: generate keyframes only, skip video rendering.
• --resume: reuse existing intermediate stage outputs.
• --start_from: resume from script, scene, shot, video, or final.
• --only: run a specific shot, such as "Scene 2,Shot 1".

Notes

• 本仓库默认不包含大型本地模型权重（见 .gitignore）。
• 运行时优先使用 microdrama_agent/models/ 下的本地路径（如已放置）。
• 仓库内可能包含部分第三方工程的子目录，仅保留当前集成所需的代码与配置。

Acknowledgement

This project integrates multiple open-source components and model backends to build a practical micro-drama generation workflow.