ArcReel

graph TD
    A["📖 上传小说"] --> B["🔍 全局角色/线索提取"]
    B --> C["✂️ 分集规划与切分"]
    C --> D["📝 剧本预处理与 JSON 生成"]
    D --> E["👤 生成角色设计图"]
    D --> F["🔑 生成线索设计图"]
    E --> G["🖼️ 生成分镜图 / 宫格图"]
    F --> G
    G --> H["🎬 生成视频片段"]
    H --> I["🎞️ FFmpeg 合成最终视频"]
    H --> J["📦 导出剪映草稿"]

⚠️ 操作系统：Linux / MacOS / Windows WSL2（Claude Agent SDK 及部分依赖仅兼容 POSIX 环境，Windows 原生暂不支持，请使用 Docker Desktop 或 WSL2）

git clone https://github.com/ArcReel/ArcReel.git
cd ArcReel/deploy
cp .env.example .env
docker compose up -d
# 访问 http://localhost:1241

cd ArcReel/deploy/production
cp .env.example .env    # 需设置 POSTGRES_PASSWORD
docker compose up -d

首次启动后，使用默认账号登录（用户名 admin，密码在 .env 中通过 AUTH_PASSWORD 设置；未设置则首次启动时自动生成并回写到 .env），前往 设置页（/settings）完成配置：

1. ArcReel 智能体 — 配置 Anthropic API Key（驱动 AI 助手），支持自定义 Base URL 和模型
2. AI 生图/生视频 — 配置至少一个供应商的 API Key（Gemini / 火山方舟 / Grok / OpenAI），或添加自定义供应商

📖 详细步骤请参考 完整入门教程

• 完整生产流水线 — 小说 → 剧本 → 角色设计 → 分镜图片 → 视频片段 → 成片，一键编排
• 多智能体架构 — 编排 Skill 检测项目状态并自动调度聚焦 Subagent，每个 Subagent 独立完成一项任务后返回摘要
• 多供应商支持 — 图片/视频/文本生成均支持 Gemini、火山方舟、Grok、OpenAI 四大预置供应商，全局/项目级可切换
• 自定义供应商 — 接入任何 OpenAI 兼容 / Google 兼容 API（如 Ollama、vLLM、第三方中转），自动发现可用模型并分配媒体类型，与预置供应商享有同等功能
• 两种内容模式 — 说书模式（narration）按朗读节奏拆分片段，剧集动画模式（drama）按场景/对话结构组织
• 渐进式分集规划 — 人机协作切分长篇小说：peek 探测 → Agent 建议断点 → 用户确认 → 物理切分，按需制作
• 风格参考图 — 上传风格图，AI 自动分析并统一应用到所有图片生成，确保全项目视觉一致
• 角色一致性 — AI 先生成角色设计图，后续所有分镜和视频均参考该设计
• 线索追踪 — 关键道具、场景元素标记为"线索"，跨镜头保持视觉连贯
• 版本历史 — 每次重新生成自动保存历史版本，支持一键回滚
• 多供应商费用追踪 — 图片/视频/文本全部纳入费用计算，按供应商分策略计费，不同币种分别统计
• 费用预估 — 生成前预估项目/单集/单镜头费用，三级下钻展示预估与实际费用对比
• 剪映草稿导出 — 按集导出剪映草稿 ZIP，支持剪映 5.x / 6+（操作指南）
• 宫格模式 — 多个分镜合成为宫格图（grid_4/grid_6/grid_9），自动选格，拆分后作为首尾帧驱动视频生成
• 多 API Key 管理 — 每个供应商支持配置多个 API Key 并切换激活，支持 Google Vertex AI 凭证上传
• 中英文双语 UI — 前端和后端全面国际化，支持中文/英文界面切换
• 项目导入/导出 — 整个项目打包归档，方便备份和迁移

ArcReel 通过统一的 ImageBackend / VideoBackend / TextBackend 协议，支持多个预置供应商和自定义供应商，可在全局或项目级别切换：

除预置供应商外，可接入任何 OpenAI 兼容 或 Google 兼容 API：

• 在设置页添加自定义供应商，填入 Base URL 和 API Key
• 自动调用 /v1/models 发现可用模型，按名称推断媒体类型（图片/视频/文本）
• 与预置供应商享有同等功能：全局/项目级切换、费用追踪、版本管理

供应商选择优先级：项目级设置 > 全局默认。切换供应商时通用设置（分辨率、宽高比、音频等）直接沿用，供应商特有参数保留。

扫码加入飞书交流群，获取帮助和最新动态：

ArcReel 的 AI 助手基于 Claude Agent SDK 构建，采用编排 Skill + 聚焦 Subagent 的多智能体架构：

flowchart TD
    User["用户对话"] --> Main["主 Agent"]
    Main --> MW["manga-workflow<br/>编排 Skill"]
    MW -->|"状态检测"| PJ["读取 project.json<br/>+ 文件系统"]
    MW -->|"dispatch"| SA1["analyze-characters-clues<br/>全局角色/线索提取"]
    MW -->|"dispatch"| SA2["split-narration-segments<br/>说书模式片段拆分"]
    MW -->|"dispatch"| SA3["normalize-drama-script<br/>剧集动画规范化"]
    MW -->|"dispatch"| SA4["create-episode-script<br/>JSON 剧本生成"]
    MW -->|"dispatch"| SA5["资产生成 Subagent<br/>角色/线索/分镜/视频"]
    SA1 -->|"摘要"| Main
    SA4 -->|"摘要"| Main
    Main -->|"展示结果<br/>等待确认"| User

核心设计原则：

• 编排 Skill（manga-workflow） — 具备状态检测能力，自动判断项目当前阶段（角色设计 / 分集规划 / 预处理 / 剧本生成 / 资产生成），dispatch 对应的 Subagent，支持从任意阶段进入和中断恢复
• 聚焦 Subagent — 每个 Subagent 只完成一项任务后返回，小说原文等大量上下文留在 Subagent 内部，主 Agent 只收到精炼摘要，保护上下文空间
• Skill vs Subagent 边界 — Skill 负责确定性脚本执行（API 调用、文件生成），Subagent 负责需要推理分析的任务（角色提取、剧本规范化）
• 阶段间确认 — 每个 Subagent 返回后，主 Agent 向用户展示结果摘要并等待确认，确认后才进入下一阶段

ArcReel 支持通过 OpenClaw 等外部 AI Agent 平台调用，实现自然语言驱动的视频创作：

1. 在 ArcReel 设置页生成 API Key（arc- 前缀）
2. 在 OpenClaw 中加载 ArcReel 的 Skill 定义（访问 http://your-domain/skill.md 自动获取）
3. 通过 OpenClaw 对话即可创建项目、生成剧本、制作视频

技术实现：API Key 认证（Bearer Token）+ 同步 Agent 对话端点（POST /api/v1/agent/chat），内部对接 SSE 流式助手并收集完整响应返回。

flowchart TB
    subgraph UI["Web UI — React 19"]
        U1["项目管理"] ~~~ U2["素材预览"] ~~~ U3["AI 助手"] ~~~ U4["任务监控"]
    end

    subgraph Server["FastAPI Server"]
        S1["REST API<br/>路由分发"] ~~~ S2["Agent Runtime<br/>Claude Agent SDK"]
        S3["SSE Stream<br/>实时状态推送"] ~~~ S4["Auth<br/>JWT + API Key"]
    end

    subgraph Core["Core Library"]
        C1["VideoBackend 抽象层<br/>Gemini · 火山方舟 · Grok · OpenAI · 自定义"] ~~~ C2["ImageBackend 抽象层<br/>Gemini · 火山方舟 · Grok · OpenAI · 自定义"]
        C5["TextBackend 抽象层<br/>Gemini · 火山方舟 · Grok · OpenAI · 自定义"] ~~~ C3["GenerationQueue<br/>RPM 限速 · Image/Video 通道"]
        C4["ProjectManager<br/>文件系统 + 版本管理"]
    end

    subgraph Data["数据层"]
        D1["SQLAlchemy 2.0 Async ORM"] ~~~ D2["SQLite / PostgreSQL"]
        D3["Alembic 迁移"] ~~~ D4["UsageTracker<br/>多供应商费用追踪"]
    end

    UI --> Server --> Core --> Data

• 📖 完整入门教程 — 从零开始的手把手指南
• 📦 剪映草稿导出指南 — 将视频片段导入剪映桌面版进行二次编辑
• 💰 Google GenAI 费用说明 — Gemini 图像 / Veo 视频生成费用参考
• 💰 火山方舟费用说明 — 火山方舟视频 / 图片 / 文本模型费用参考

欢迎贡献代码、报告 Bug 或提出功能建议！请参阅 贡献指南 了解本地开发环境搭建、测试和代码规范。

本地克隆后请务必执行一次：

uv run pre-commit install

安装 pre-commit 钩子（ruff check + format、frontend eslint、workflow tripwire），避免把可被自动修复的问题推到 CI。

AGPL-3.0

如果觉得项目有用，请给个 ⭐ Star 支持一下！