基于多智能体协作的AI视频创作平台：从架构到部署实战

1. 项目概述：一个由AI智能体驱动的“虚拟制片厂”

如果你曾经尝试过用AI生成视频，大概率会遇到这样的困境：要么是生成的视频人物形象飘忽不定，前一秒还是黑发，下一秒就成了金发；要么是剧情逻辑混乱，场景衔接生硬。这背后的核心问题在于，传统的“单点式”AI工具（比如一个文生图工具接一个文生视频工具）缺乏一个统一的“导演”来统筹全局，导致创作流程是割裂的。今天要聊的 openOii 项目，正是为了解决这个问题而生。它本质上是一个基于多智能体（Multi-Agent）协作的“虚拟制片厂”，通过模拟真实影视剧创作流程中的各个专业角色（如导演、编剧、角色设计师、分镜师等），将你的一个简单故事创意，自动、连贯地转化为一部包含角色、分镜和动态视频的完整“漫剧”作品。

这个项目非常适合两类人：一是对AI视频创作感兴趣，但苦于流程繁琐、效果不稳定的内容创作者；二是希望深入理解多智能体系统如何在实际应用中协同工作的开发者。它不仅仅是一个工具集，更是一个完整、开源的工程实践范例，展示了如何用现代Web技术栈（FastAPI + React）将多个AI服务编排成一个高效、可控的生产流水线。接下来，我会带你深入这个“制片厂”内部，拆解它的核心架构、实操部署的每一个坑，并分享如何根据自身需求定制属于你的AI创作流程。

2. 核心架构与多智能体协作流程拆解

2.1 技术栈选型背后的逻辑

在深入Agent之前，先看看支撑这套系统的技术选型，这决定了项目的稳定性和扩展性。

后端为什么是 FastAPI + SQLModel + PostgreSQL？FastAPI 的异步特性（async/await）是这个项目的生命线。AI API调用、图像处理、视频合成都是高延迟的I/O密集型操作。异步框架能确保在等待一个Agent（例如，等待图像生成）工作时，服务器依然可以处理其他请求或推进其他Agent的任务，极大提升了系统的吞吐量和响应速度。SQLModel 结合了 SQLAlchemy 的强类型和 Pydantic 的数据验证，让数据库模型和API请求/响应模型可以共享同一套定义，减少了大量重复代码和潜在的运行时错误。PostgreSQL 的 JSONB 字段非常适合存储AI生成的非结构化内容，比如角色描述、分镜脚本等。

前端为什么是 React + TypeScript + Zustand？创作过程涉及大量状态：项目信息、多个Agent的生成进度、用户对某个分镜的反馈等。React 的函数式组件和 Hooks 提供了清晰的UI构建方式，而 TypeScript 的静态类型检查在如此复杂的状态流转中至关重要，能在编码阶段就避免许多低级错误。Zustand 是一个轻量级状态管理库，它的API极其简洁，避免了 Redux 的模板代码，非常适合管理这种中等复杂度的应用状态。TanStack Query（原React Query）则优雅地处理了服务器状态（数据获取、缓存、同步），让前端无需手动管理加载和错误状态。

通信为什么是 WebSocket？这是实现“实时反馈系统”的关键。想象一下，你点击“开始生成”后，如果页面一直显示“处理中…”，你完全不知道后台是卡在写剧本了，还是在画角色图，体验会很差。WebSocket 建立了前后端之间的全双工通信通道，后端可以主动将每个Agent的工作进度（如“DirectorAgent：剧本大纲已完成”、“CharacterArtistAgent：正在生成主角形象”）推送到前端，让用户对整个创作流水线的状态一目了然。这比传统的HTTP轮询（Polling）更高效、更实时。

2.2 八大智能体角色与协作链条解析

这是项目的核心灵魂。整个系统被设计成一个高度专业化的流水线，每个Agent都是一个独立的“专家”。

2.2.1 需求分析师：OnboardingAgent这是流程的起点。它的任务不是直接创作，而是理解和澄清用户的模糊意图。用户输入可能只是“一个宇航员在火星上发现了一朵会发光的花”。OnboardingAgent 会与用户进行多轮对话（在后台自动完成），追问细节：故事基调是科幻冒险还是温情治愈？主角宇航员的年龄、性格？那朵花除了发光，还有什么特殊之处？它的目标是产出一份结构化的、富含细节的“创意简报”，为后续所有Agent提供明确、统一的输入。这步至关重要，避免了因初始指令模糊导致的后续环节集体跑偏。

2.2.2 总导演：DirectorAgent拿到创意简报后，DirectorAgent 开始进行宏观规划。它不写具体台词，而是搭建故事的骨架。它的核心产出是：故事的整体节奏、幕次划分（如三幕剧）、关键情节点、以及每个场景的主要冲突和情感基调。例如，它会规划出：第一幕（开端）：宇航员着陆，遭遇沙暴，与基地失联；第二幕（发展）：寻找信号源，发现发光花，产生好奇与警惕；第三幕（高潮与结局）：与花互动，发现其秘密，做出选择。这个规划是所有后续视觉化工作的总纲。

2.2.3 编剧：ScriptwriterAgent在导演规划的框架内，ScriptwriterAgent 负责填充血肉。它的工作非常具体：为每个场景生成详细的描述、角色的具体动作、对话（如果有）、以及最重要的——分镜指示。例如，对于“发现发光花”这个情节点，它会写出：“镜头缓缓推近，宇航员布满灰尘的面罩反射着幽蓝色的光芒。他蹲下身，手套小心翼翼地拨开红色的沙土，一株晶莹剔透、脉络中流淌着光晕的植物显现出来。背景是巨大的火星落日。” 这些描述将成为StoryboardArtistAgent作画的直接依据。

2.2.4 角色设计师：CharacterArtistAgent基于剧本中对角色的文字描述，这个Agent负责生成视觉定妆照。一致性是它最大的挑战。为了确保同一个角色在不同场景、不同角度下看起来是同一个人，项目采用了“角色参考图”机制。它会为首要角色生成一张高质量的“标准肖像”，并在后续生成分镜时，将这张肖像图作为“图生图”的参考输入给图像服务。虽然项目文档提到目前依赖的魔搭平台可能不支持图生图，导致一致性有损，但架构上已经为此预留了接口。更优的方案是使用支持“角色LoRA”或“IP-Adapter”的SD模型，可以更好地锁定角色特征。

2.2.5 分镜师：StoryboardArtistAgent这是将文字剧本转化为视觉草图的关键一步。该Agent根据ScriptwriterAgent提供的每一个镜头的描述，生成对应的“分镜首帧”图像。如果开启了图生图模式，它会把CharacterArtistAgent生成的角色参考图也融入生成条件中，确保画面上的人物形象与定妆照一致。分镜图不需要是精美的最终画面，但必须清晰传达构图、人物位置、基本光影和氛围，是指导视频生成的蓝图。

2.2.6 视频生成师：VideoGeneratorAgent这是将静态画面变为动态影像的环节。它有两种模式：一是“文生视频”，直接使用分镜描述文本生成视频，速度快但可控性差；二是更推荐的“图生视频”模式，将分镜首帧（或结合角色图）作为视觉参考输入给视频生成模型（如豆包的Ark模型），这样生成的视频在构图、主体上会与分镜图高度吻合，大幅提升成片质量。该Agent负责调用视频生成API，并管理生成任务队列。

2.2.7 剪辑师：VideoMergerAgent视频生成API通常有长度限制（如几秒钟）。VideoGeneratorAgent产出的是一段段独立的短视频片段。VideoMergerAgent 的角色就像剪辑师，它使用 FFmpeg 这个强大的命令行工具，将这些片段按照剧本顺序进行拼接，并可以添加简单的转场效果、统一音频（如果生成时带音频）或添加背景音乐，最终输出一个完整的、连贯的成片视频文件。

2.2.8 质量审核员：ReviewAgent这是一个面向用户的交互接口。当用户预览生成的完整作品或中间产物（如某个角色图、某个分镜）不满意时，可以通过界面提出反馈（例如：“主角的表情应该更惊讶一些”）。ReviewAgent 会接收这些反馈，并精准地调度对应的Agent（如CharacterArtistAgent或StoryboardArtistAgent）进行局部重生成，而无需从头开始整个流程。这实现了创作流程的“可纠错”和“可迭代”，大大提升了用户体验和最终作品质量。

这个链条是顺序与并行的结合。例如，在ScriptwriterAgent完成部分剧本后，CharacterArtistAgent就可以开始为已确定的角色生成设计图，无需等待全部剧本写完。整个流程通过一个中央任务调度器（或利用异步编程模式）来协调，并通过WebSocket实时广播状态。

3. 从零开始：本地开发环境部署实操详解

虽然Docker一键部署很方便，但对于想深入了解或进行二次开发的你，走一遍本地部署能帮你彻底理清项目依赖和运行机制。这里我会详细拆解每一步，并附上我踩过坑后总结的注意事项。

3.1 后端环境搭建与配置陷阱规避

首先，把项目代码拉下来：

git clone https://github.com/Xeron2000/openOii.git cd openOii/backend

3.1.1 Python环境与依赖管理项目要求Python 3.10+。我强烈推荐使用uv或pdm这类现代Python包管理器，而不是直接用pip。它们能创建独立的虚拟环境，并拥有更快的依赖解析速度。这里以uv为例（如果你没有安装，可以用pip install uv先安装它）。

# 使用 uv 同步依赖，它会自动创建虚拟环境并安装所有包 uv sync # 或者，如果你想使用传统的 venv + pip python -m venv .venv source .venv/bin/activate # Linux/Mac # .venv\Scripts\activate # Windows pip install -e .

注意：安装过程中，如果遇到psycopg2（PostgreSQL驱动）编译失败，这通常是缺少系统级依赖导致的。在Ubuntu/Debian上，你需要运行sudo apt-get install libpq-dev python3-dev。在Mac上，brew install postgresql通常会包含所需头文件。Windows用户建议直接使用预编译的psycopg2-binary包，可以在requirements.txt或pyproject.toml中指定。

3.1.2 数据库与缓存服务准备你需要一个正在运行的PostgreSQL和Redis。使用Docker是快速启动的方式：

# 启动一个PostgreSQL容器 docker run --name openoii-postgres -e POSTGRES_PASSWORD=yourpassword -e POSTGRES_DB=openoii -p 5432:5432 -d postgres:15 # 启动一个Redis容器 docker run --name openoii-redis -p 6379:6379 -d redis:7-alpine

然后，复制环境变量配置文件并编辑：

cp .env.example .env

打开.env文件，以下配置项是重中之重，每一个都关系到系统能否正常运行：

# 数据库连接字符串。格式为：驱动://用户名:密码@主机:端口/数据库名 # 如果你用上面的Docker命令，主机是localhost，密码是yourpassword DATABASE_URL=postgresql+asyncpg://postgres:yourpassword@localhost:5432/openoii # Redis连接字符串 REDIS_URL=redis://localhost:6379/0 # --- AI服务配置 --- # LLM服务：这是整个系统的“大脑”，负责所有Agent的推理。项目使用Claude Agent SDK，但实际可以对接任何Anthropic API兼容的端点。 # 如果你使用第三方中转服务，这里就填中转服务的地址和密钥。 ANTHROPIC_BASE_URL=https://api.anthropic.com # 或者你的中转服务地址 ANTHROPIC_AUTH_TOKEN=sk-your-anthropic-api-key-here # 图像生成服务：同样兼容OpenAI API格式。国内推荐使用魔搭（modelscope）。 IMAGE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # 魔搭的OpenAI兼容端点 IMAGE_API_KEY=sk-your-modelscope-api-key-here # 视频生成服务：选择提供商，目前支持 `openai` (如Sora API) 或 `doubao` (火山引擎豆包)。 VIDEO_PROVIDER=doubao # 如果选择了豆包，需要配置其API密钥 DOUBAO_API_KEY=your-doubao-ark-api-key-here # 如果使用OpenAI兼容服务，则需要配置VIDEO_BASE_URL和VIDEO_API_KEY # VIDEO_BASE_URL=https://api.openai.com/v1 # VIDEO_API_KEY=sk-your-openai-api-key

关键陷阱1：网络与代理。如果你的开发环境需要通过代理访问外部AI服务（如官方的Anthropic或OpenAI），仅仅在系统设置代理是不够的。Python的httpx/aiohttp库默认不会使用系统代理。你需要在代码中或环境变量里显式配置。一个简单的方法是在启动命令前设置环境变量：export HTTP_PROXY=http://your-proxy:port; export HTTPS_PROXY=http://your-proxy:port。更稳妥的做法是在创建AI客户端时传入proxies参数。项目代码可能已经处理，如果没有，你需要根据所用SDK的文档进行配置。

3.1.3 初始化数据库与启动配置好后，使用FastAPI的启动命令即可。应用启动时会通过SQLModel的create_all自动创建数据表。

uvicorn app.main:app --reload --host 0.0.0.0 --port 18765

--reload参数使得代码修改后服务器会自动重启，非常适合开发。看到Application startup complete.的日志，说明后端服务已经就绪。此时你可以访问http://localhost:18765/docs查看并调试所有API接口。

3.2 前端环境配置与开发服务器启动

打开一个新的终端，进入前端目录：

cd ../frontend

前端使用pnpm作为包管理器，速度比 npm 快很多。如果没有安装，可以用npm install -g pnpm安装。

# 安装项目依赖 pnpm install

这个过程可能会下载数百兆的依赖包，取决于你的网络环境。

安装完成后，通常不需要修改配置，因为前端开发服务器默认代理了后端请求。直接启动：

pnpm dev

Vite 会启动一个开发服务器，并输出访问地址，通常是http://localhost:15173。用浏览器打开这个地址，你应该能看到 openOii 的界面。

关键陷阱2：跨域问题（CORS）。如果前端在localhost:15173，后端在localhost:18765，浏览器会因为同源策略阻止请求。好在项目后端已经配置了CORS中间件，允许来自前端开发服务器的请求。如果你修改了端口，或者从其他地址访问，就需要同步修改后端app/main.py中CORS中间件的origins参数列表。

3.3 首次运行测试：创建一个迷你漫剧

环境跑通后，我们来做一个最简单的端到端测试，验证整个流水线是否工作。

1. 登录/进入界面：打开前端，你应该会看到一个创建项目的按钮或引导页。
2. 创建新项目：点击创建，输入一个简单的故事创意。例如：“一只戴着侦探帽的猫咪，在书房里寻找丢失的毛线球。” 风格可以选择“卡通”、“温馨”。
3. 启动生成：点击开始生成。此时，留意浏览器开发者工具（F12）中的“网络”选项卡，你应该能看到WebSocket连接建立，并不断收到来自后端的不同Agent的进度消息。
4. 观察后台日志：切换到后端服务的终端，你会看到一系列日志输出，清晰地展示了每个Agent被调用、处理、返回结果的过程。
5. 等待结果：根据你的AI服务速度和视频长度，整个过程可能需要几分钟到十几分钟。完成后，前端画布上应该会出现角色卡片、分镜卡片，并最终生成一个视频卡片。点击视频卡片即可播放你的第一部AI漫剧。

如果在这个过程中任何一步卡住或报错，请根据错误信息回溯检查对应的服务配置（LLM、画图、视频的API密钥和地址是否正确，网络是否通畅）。

4. 生产环境部署：Docker Compose方案与网络配置精讲

对于想长期使用或对外提供服务的场景，Docker Compose是最佳选择。它能把所有服务（后端、前端、数据库、Redis）打包管理，一键启停。项目提供的docker-compose.yml文件已经做好了基础配置，但生产环境部署有几个关键点需要特别注意。

4.1 理解Docker网络与服务发现

这是Docker部署中最容易出错的地方。在docker-compose.yml中，所有服务默认共享一个自定义的桥接网络，在这个网络里，服务可以使用容器名作为主机名互相访问。

# 这是项目docker-compose.yml的简化示意 services: postgres: image: postgres:15 container_name: openoii-postgres # 其他配置... redis: image: redis:7-alpine container_name: openoii-redis backend: build: ./backend container_name: openoii-backend depends_on: - postgres - redis environment: - DATABASE_URL=postgresql+asyncpg://postgres:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB} - REDIS_URL=redis://redis:6379/0 # 其他配置...

注意看DATABASE_URL和REDIS_URL：主机部分不再是localhost，而是postgres和redis，这对应着上面定义的container_name。在Docker网络内部，这是正确的访问方式。

4.2 处理外部AI服务与宿主机器服务

问题出在IMAGE_BASE_URL和VIDEO_BASE_URL上。你的图像生成和视频生成服务可能有两种部署方式：

情况一：使用在线SaaS服务（推荐）这是最简单的情况。你直接使用魔搭、豆包等提供的公网API。那么配置无需特殊处理，容器内可以直接访问互联网。

# 在 backend/.env 文件中 IMAGE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 VIDEO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3 # 豆包示例

在docker-compose.yml中，通过environment部分将这些环境变量传入后端容器即可。

情况二：AI服务部署在宿主机上比如你在本机运行了一个Stable Diffusion WebUI（地址http://localhost:7860）。在宿主机上，后端配置IMAGE_BASE_URL=http://localhost:7860是没问题的。但是，当后端运行在Docker容器内时，localhost指向的是容器自己，而不是宿主机。这时就会连接失败。

解决方案：使用特殊的DNS名称host.docker.internal。这个名称由Docker Desktop（Mac/Windows）提供，在Linux上需要额外配置。它解析为宿主机的IP地址。

# 修改 backend/.env 文件，给Docker部署用 IMAGE_BASE_URL=http://host.docker.internal:7860

同时，你需要确保宿主机的服务（如SD WebUI）绑定了0.0.0.0而不仅仅是127.0.0.1，这样才能接受来自Docker容器的连接。

情况三：AI服务也部署在另一个Docker容器/Compose项目中这是更复杂的场景。假设你的图像服务在另一个独立的docker-compose.yml中运行，服务名是sd-webui。

1. 你需要创建一个外部网络，让两个Compose项目共享。

   docker network create ai-network

2. 在两个docker-compose.yml文件中，都声明使用这个外部网络。

   # openOii的 docker-compose.yml services: backend: networks: - default - ai-network networks: ai-network: external: true

   # 图像服务的 docker-compose.yml services: sd-webui: networks: - ai-network networks: ai-network: external: true

3. 在openOii的后端配置中，使用对方容器的服务名和端口进行访问。

   IMAGE_BASE_URL=http://sd-webui:7860

4.3 数据持久化与版本升级

生产环境必须保证数据不丢失。在docker-compose.yml中，已经为数据库和Redis配置了卷（volumes）挂载。

services: postgres: volumes: - postgres_data:/var/lib/postgresql/data redis: volumes: - redis_data:/data volumes: postgres_data: redis_data:

这样，即使你删除并重建容器，数据也会保留在宿主机的Docker卷中。你可以通过docker volume ls查看和管理这些卷。

升级版本流程：

# 拉取最新的代码 git pull origin main # 重新构建后端镜像（如果代码有变） docker-compose build backend # 或者，如果使用了更新的基础镜像，直接up也会重建 docker-compose up -d --force-recreate backend # 执行数据库迁移（如果模型有变更，项目需提供Alembic迁移脚本） docker-compose exec backend alembic upgrade head

如果没有数据库迁移工具，在启动时SQLModel的create_all会尝试修改表结构，但对于已有数据的表，某些修改（如删除列、修改列类型）可能会失败，需要手动处理。因此，对于重要的生产数据，升级前务必备份。

5. 高级配置与调优：让创作更精准、更高效

基础运行只是开始，要让 openOii 真正产出高质量、符合预期的作品，需要对各个AI服务进行精细化的调优。这部分内容通常不会写在基础文档里，却是决定成败的关键。

5.1 提示词工程：为每个Agent注入“灵魂”

每个Agent的核心都是一个LLM调用，其表现很大程度上取决于系统提示词（System Prompt）。项目源码中，每个Agent类里应该都有一个system_prompt属性或类似的结构。理解并微调这些提示词，是定制化创作风格的最有效手段。

以 DirectorAgent 为例，它的默认提示词可能只要求“规划一个三幕剧”。但如果你希望生成的是“抖音风格的快节奏短剧”，你就需要修改其提示词，加入更具体的约束：

你是一位精通短视频节奏的导演。请根据以下创意，规划一个时长在60-90秒、包含3-5个爆点转折的短剧结构。第一幕（前15秒）必须建立强冲突或悬念，直接抓住观众注意力。每一幕的描述请聚焦于视觉冲击力和情绪张力，而非复杂的对话。

以 CharacterArtistAgent 为例，为了生成更一致的角色，可以在提示词中强调：

你是一位角色概念设计师。请根据描述生成该角色的正面半身肖像，用于后续作为视觉参考。务必确保角色特征（如发型、瞳色、脸型、标志性配饰）清晰、突出且易于识别。背景请使用纯色，避免复杂细节干扰主体。

你可以在backend/app/agents/目录下找到各个Agent的源码，直接修改其中的提示词模板。修改后，需要重启后端服务。

5.2 图像与视频生成参数调优

图像和视频生成API通常有大量参数可以调节，直接影响输出质量、风格和速度。

图像生成参数（通常通过IMAGE_API_PARAMS环境变量或配置传递）：

• 模型选择：如果使用魔搭，可以指定不同的模型，如wanx-v1用于真实风格，cogview-3用于二次元风格。在IMAGE_BASE_URL后可能可以指定路径，或通过参数传递。
• 尺寸：分镜图尺寸应与视频生成模型推荐的输入尺寸匹配，否则视频生成时会被拉伸变形。例如，豆包Ark模型推荐1024x576（16:9）。在StoryboardArtistAgent的调用中固定此尺寸。
• 生成张数：角色设计可以生成多张（n=2或4）供用户选择。
• 提示词权重与负向提示词：这是高级技巧。在调用API时，除了正向描述，还可以传递“负向提示词”（如“模糊，丑陋，多只手，文字水印”）来避免常见缺陷。这需要你使用的图像API支持此功能。

视频生成参数（豆包Ark示例）： 豆包的视频生成API参数非常关键。除了基本的prompt（描述），还有：

• cfg_scale：提示词相关性。值越高（如12），生成内容越贴近你的描述，但可能牺牲一些创造性；值低则反之。一般设置在7-12之间调试。
• seed：随机种子。固定一个种子，可以在其他参数不变时生成几乎相同的视频，用于可复现性测试。
• motion_bucket_id：控制画面运动幅度。值越高，运动越剧烈。对于对话、静态场景，可以设低（如40）；对于动作场景，可以调高（如120）。
• fps：输出视频帧率。通常25或30。
• duration_seconds：视频时长。需要与你的分镜规划匹配。

这些参数可以在VideoGeneratorAgent的代码中进行配置。最佳参数组合需要通过多次实验来找到。

5.3 性能优化与成本控制

AI API调用是主要的耗时和成本来源。有几个优化思路：

1. 缓存策略：对于相同的提示词（例如，同一个角色的标准描述），其生成的图像应该是固定的。可以在后端引入一个缓存层（比如用Redis），键为提示词的哈希，值为生成的图像URL或特征。下次遇到相同请求时，直接返回缓存结果，省去一次API调用和生成时间。
2. 队列与异步处理：项目已经使用了异步框架。但对于视频生成这种长任务（可能长达一分钟），最好将其放入一个后台任务队列（如Celery、RQ或Dramatiq），立即返回一个任务ID给前端，前端通过WebSocket或轮询来获取进度和结果。避免HTTP请求长时间挂起。
3. 成本监控：不同AI服务的计费方式不同（按token、按图片尺寸、按视频秒数）。在调用每个服务后，记录下本次消耗的额度或估算成本（例如，Claude的输入/输出token数，生成图片的尺寸和数量）。可以在数据库中添加相关字段，方便后续分析和预算控制。
4. 降级与容错：当首选的高质量视频服务（如豆包）不可用或超时时，可以在VideoGeneratorAgent中实现降级逻辑，比如自动切换到备用的文生视频服务，或者生成一个由静态图片组成的幻灯片视频，保证流程至少能走通，而不是完全失败。

6. 故障排查与常见问题实录

在实际部署和运行中，你一定会遇到各种问题。这里我整理了最常见的一些错误、原因和解决方案，希望能帮你快速排雷。

6.1 启动与连接类问题

问题：后端启动失败，报数据库连接错误。

• 错误信息：sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) could not connect to server: Connection refused
• 原因：PostgreSQL服务没启动，或者连接字符串（DATABASE_URL）中的主机、端口、密码、数据库名不正确。
• 解决：
  1. 确认PostgreSQL正在运行：docker ps或sudo systemctl status postgresql。
  2. 检查连接信息：特别是密码和数据库名。尝试用psql命令行工具手动连接一下。
  3. 如果是Docker部署，确认后端容器和数据库容器在同一个Docker网络中，并且使用容器名（如postgres）而非localhost作为主机。

问题：前端能打开，但创建项目时一直卡住或报“网络错误”。

• 排查步骤：
  1. 打开浏览器开发者工具（F12），切换到“网络”(Network)选项卡，查看失败的请求是什么，状态码是多少（如 500, 502, 404）。
  2. 查看后端日志：这是最重要的信息源。在终端运行docker-compose logs -f backend或直接看你的后端服务输出。
  3. 常见状态码分析：
     • 502 Bad Gateway：通常说明后端服务进程崩溃或根本没启动。检查后端日志。
     • 500 Internal Server Error：后端代码运行时出错。日志里会有详细的Python错误堆栈信息，根据它定位问题。
     • 404 Not Found：前端请求的API路径不对。检查前端配置的API基础地址是否正确，以及后端路由是否匹配。

6.2 AI服务调用类问题

问题：剧本或角色描述生成失败，LLM返回错误。

• 错误信息：可能在日志中看到anthropic.BadRequestError或类似信息。
• 原因：
  1. API密钥错误或过期：检查ANTHROPIC_AUTH_TOKEN是否正确，是否有余额。
  2. 提示词过长或格式错误：某些API对输入token数有限制。检查Agent的提示词是否过于冗长。
  3. 网络问题：无法访问API端点。检查ANTHROPIC_BASE_URL是否可通，以及代理设置。
• 解决：简化提示词进行测试；直接在命令行用curl或Python脚本测试你的API密钥和端点是否有效。

问题：图像生成失败，返回“模型不可用”或“参数错误”。

• 原因：
  1. 不支持的模型：IMAGE_BASE_URL可能指向了一个不提供图像生成服务的端点。
  2. 参数格式不符：不同服务商（OpenAI格式、魔搭、Stable Diffusion API）的参数名和格式有细微差别。项目代码可能只适配了其中一种。
• 解决：查阅你所用图像服务商的API文档，对照backend/app/services/image_generation.py中的请求体格式进行调整。

问题：视频生成时间极长，或一直处于“生成中”状态。

• 原因：视频生成是计算密集型任务，服务端处理需要时间。豆包等服务的异步任务可能排队。
• 排查：
  1. 查看后端日志，确认VideoGeneratorAgent是否已收到任务ID。
  2. 如果是异步任务，检查轮询获取结果的过程是否正常，有没有因为网络超时或API限制而中断。
  3. 在服务商的控制台查看任务队列和状态。
• 解决：增加请求超时时间；实现更健壮的重试和轮询机制；考虑使用WebHook（如果服务商支持）来接收完成通知，而非主动轮询。

6.3 媒体处理与存储问题

问题：视频拼接失败，FFmpeg报错。

• 原因：VideoMergerAgent调用的FFmpeg命令失败。可能因为：
  1. 系统未安装FFmpeg，或Docker镜像中缺少FFmpeg。
  2. 待拼接的视频片段格式不一致（如编码、分辨率、帧率不同）。
  3. 片段文件路径错误或不存在。
• 解决：
  1. 在Dockerfile中确保安装了FFmpeg：RUN apt-get update && apt-get install -y ffmpeg。
  2. 在拼接前，先用FFmpeg命令统一所有片段的格式（这是一个可以增强的预处理步骤）。
  3. 在日志中打印出完整的FFmpeg命令和错误输出，便于调试。

问题：生成的图片或视频文件无法访问或显示。

• 原因：文件存储和访问路径配置问题。项目可能默认将生成的文件保存在服务器本地磁盘。
• 排查：
  1. 文件是否真的生成在了预期的目录？
  2. 后端是否配置了静态文件服务来暴露这个目录？例如，FastAPI的StaticFiles。
  3. 前端访问的URL路径是否与后端静态文件服务的路径匹配？
• 解决：对于生产环境，强烈建议使用对象存储服务（如AWS S3、阿里云OSS、MinIO），并通过CDN分发。这需要修改文件保存和URL生成的逻辑。本地存储仅适用于开发和测试。

7. 扩展思路：打造属于你的专属创作流水线

openOii 提供了一个优秀的、可工作的多智能体框架。但它的真正威力在于其可扩展性。你可以根据自己特定的创作需求，对这个流水线进行“魔改”。

思路一：引入新的专业Agent现有的Agent覆盖了核心流程，但你可以添加更多“专家”：

• 配音Agent：在视频生成后，调用TTS（文本转语音）服务，根据角色对话生成配音，并混入最终视频。
• 字幕Agent：自动识别或根据剧本生成字幕文件（SRT格式），并压制到视频中。
• 特效Agent：在视频拼接前，对某些片段添加简单的视觉特效（如滤镜、转场、文字标题）。
• 音乐推荐Agent：根据剧本的情感基调，从免版税音乐库中推荐并下载背景音乐，交给VideoMergerAgent使用。

添加新Agent的步骤通常是：1) 在后端app/agents/目录下创建新的Agent类，继承基础Agent类；2) 实现其run方法，调用相应的外部服务API；3) 在主流程调度器（可能在app/core/workflow.py中）的合适位置插入这个新Agent的调用。

思路二：替换或升级底层AI模型项目通过抽象层（如ImageGenerationService,VideoGenerationService）来调用AI服务。这使得替换模型变得相对容易。

• 图像模型：如果你想从魔搭切换到本地部署的Stable Diffusion，只需实现一个新的服务类，遵守相同的接口，并在配置中切换。
• LLM模型：除了Claude，你可以接入GPT-4、DeepSeek、GLM等。需要确保新模型的API格式与Claude Agent SDK兼容，或者修改Agent的底层调用代码。
• 视频模型：除了豆包和OpenAI，可以接入Pika、Runway等。同样，需要适配新的API接口。

思路三：实现更复杂的交互与反馈循环目前的ReviewAgent处理的是用户对单次生成结果的反馈。你可以设计更复杂的交互：

• 多轮创意碰撞：让OnboardingAgent与用户进行更深入的对话，生成多个故事方向供选择。
• A/B测试：对于关键分镜，让StoryboardArtistAgent生成2-3个不同构图或风格的版本，让用户选择。
• 风格迁移：用户上传一张参考图（如某位画师的风格），让整个生成流程（角色、分镜）都向该风格靠拢。这需要在调用图像生成API时，将参考图作为风格控制条件输入。

思路四：优化工作流与并行化分析整个流程的耗时瓶颈。通常，视频生成是最慢的。是否可以优化？例如，在生成前几个分镜的视频时，是否可以并行生成后续分镜的图像？或者，对于不需要严格顺序的环节（如生成不同角色的设计图），是否可以并行执行？这需要对任务调度逻辑进行更精细的设计，可能引入像asyncio.gather这样的并发工具或更专业的任务队列。

这个项目的开源价值，不仅在于它实现了一个可用的AI漫剧生成器，更在于它清晰地展示了一个复杂多智能体系统的架构模式。你可以把它看作一个“元项目”，它的框架可以用来构建其他领域的多AI协作应用，比如自动生成营销文案与配图、生成交互式教育内容、甚至辅助代码开发和测试。理解其设计思想，比单纯使用它更为重要。