AI智能体共建仓库：短剧生产协作的开源实践

决定做这个 AI 智能体共建仓库的起因，是半年前我亲眼看着一条短剧生产线被各种文档、素材、生成脚本和模型配置搅成一锅粥。短剧生产是典型的内容密集型业务，而团队里每个人都把中间产物存在自己的电脑和聊天记录里，编剧、剪辑、导演和那几个 AI 智能体各自为战，最终交付全靠微信互传压缩包。为了把大伙从这种状态里捞出来，我用三个月时间搭了一个开源项目：把短剧生产涉及的全部文本、画面、音频、提示词和数据处理任务沉淀进一个共建仓库，再让多个 AI 智能体通过仓库完成交接，最后用一套可视化看板展示各个环节的进展。这篇文章就是整个过程的实操复盘，适合正在做多智能体协作、想做内容生产数字化，或者单纯想了解开源项目怎么落地到具体业务场景的人读。

1. 立项思路：短剧生产为什么会需要一个“智能体共建仓库”

1.1 短剧的生产链路拆解：每一步都在产生中间产物

很多人以为短剧就是批量生成短视频，但实际上短剧更接近“单元剧集”：每集三五分钟，总共几十集，剧情连续、角色固定、场景复用率高。我按团队实际过程拆过一遍，链路大致是：选题报审、人物小传、单集剧本、分集大纲、分镜脚本、角色一致性设计、单帧画面生成、场景视频生成、配音与字幕、粗剪精剪、成片质检、平台分发。

这条链路上的每一步都会生成新的中间产物：选题阶段产生策划文档，剧本阶段产生文本稿，分镜阶段产生表格和示意图，画面生成阶段产生角色设定图和场景图，剪辑阶段产生工程文件和成片素材。每经过一个人工或者智能体，都会产生一批“临时资产”。这些资产如果不放到统一的地方，就会直接变成团队内部互相传文件、改文件名、覆盖版本的无底洞。

表格可以看得很清楚：

如果没有统一仓库，这些中间产物永远只是个人经验的一部分；有仓库之后，它们才变成可以被任意一个智能体消费的输入。这也是我后来反复和团队强调的一句话：多个 AI 智能体协同做生产，本质上不是让模型更聪明，而是让每一步的产物都有标准化归属。

1.2 多个 AI 智能体协作时的三种典型失控模式

我们团队在项目早期其实已经引入了文本生成智能体、图像生成智能体和配音合成智能体，但使用效果并不理想。复盘了将近两周，我发现失控集中在三种模式上。

第一种是“文件漂移”。A 智能体生成的分镜脚本输出到本地目录，B 智能体却监听另一个目录，结果两边永远对不上。第二种是“上下文断裂”。剧本智能体生成一个故事设定，画面生成智能体的 prompt 完全没有引用之前的设定信息，导致角色外貌每集都变。第三种是“不可重试”。某个生成环节一旦失败，如果原始输入和模型参数没有被记录，整个子任务只能从头再来，想定位是哪一步出错都费劲。

这三种模式有一个共同根源：智能体之间没有稳定、可查询、可回溯的“交接空间”。视频生成工具开会可以开在一块白板前，AI 智能体协作也需要一块公有白板，而这块白板在设计上最合适的形式就是仓库。

1.3 为什么我坚持叫它“仓库”，而不是平台或流水线

立项时有人建议直接做一个内部 AI 平台，把所有智能体封装成服务，再写一个编排后台。我没有采纳，原因是平台改造成本太大，而且一旦做成平台，团队就很难把草稿、素材、失败产物都留存下来。还有人建议把它设计成严格的流水线，每一步按固定顺序执行。我也没采纳，因为短剧生产经常需要回退重试：导演看完画面觉得角色情绪不对，要回到上一步重新描述；运营看完分镜如果觉得节奏不对，得改动剧本再生成一次。固定顺序的流水线在这种内容创意场景里会频繁卡壳。

“共建仓库”刚好在两者之间。它本质上是一个共享的存储空间加一套元数据约定，既有 Git 对文本版本的控制力，又有对象存储对多媒体文件的承载能力，同时允许每个智能体按照自己的节奏消费和产出。智能体不需要知道上游工具是谁，只要按约定的 schema 向仓库写入产物，再读取下游需要的输入，就能完成一次工作交接。仓库天然留痕，也为故障排查和回溯提供了路径。这个理念后来成了整个开源项目的地基。

2. 仓库里到底放什么：内容资产与代码资产的分层设计

2.1 四类资产和对它们的物理存储方案

一个能真正支撑短剧生产的仓库，不能只装代码。我最初犯过的错误是让所有 AI 智能体代码和生成图片挤在同一个 Git 仓库里，结果克隆一次要几分钟。后来我把仓库拆成了逻辑上的四层，物理存储也各归各位。

第一类是人类产出的策划文案和剧本，体量小但版本价值高，放进 Git 仓库做逐字对比。第二类是图片、视频、音频等大文件，不适合进 Git，放进 MinIO 兼容的对象存储，把对象地址与哈希存进数据库。第三类是智能体运行时的模型配置、Prompt 模板、Agent 技能包配置，这些会频繁迭代，但本质是小型文本文件，也放进 Git 仓库，并按版本打 tag。第四类是生产过程中产生的结构化元数据，包括任务状态、产物依赖关系、调用链日志，统一写入 PostgreSQL。

最终长期保存的目录结构大致是这样：

drama-hub/ ├── agents/ # 各智能体的技能包与配置 │ ├── script-writer/ │ ├── shot-list/ │ └── asset-render/ ├── content/ # 人类生产与智能体生产的内容资产索引 │ ├── projects/ │ │ └── drama_xxx/ │ │ ├── synopsis/ # 梗概与人物设定 │ │ ├── episode_01/ # 每集的剧本、分镜、成片包 │ │ └── assets/ # 共享角色与场景资产 ├── schemas/ # 输入输出 JSON Schema ├── workflows/ # 串并行编排配置 ├── dashboard/ # 可视化看板前端代码 └── docker/ # 镜像构建文件

2.2 AI 智能体在仓库中的“技能包化”

在我接触过的很多开源多智能体项目里，智能体都被理解成一个又一个的 Python 文件或者 API 调用。但在短剧生产这种需求快速变化的场景里，我更建议把每个智能体定义成“可发布的技能包”。一个技能包里包含输入 schema、输出 schema、一份依赖模型的配置、一份 Prompt 模板、一个最小可运行的 Dockerfile，以及一个 README 说明它的职责边界。

例如剧本智能体技能包的 README 里会明确规定：它只负责处理“故事梗概 -> 单集剧本”的转换，不负责分镜设计；它必须从仓库读取synopsis.json，并向仓库输出episode_01.json，json 里的每个场次、对白都要符合统一的 schema。分镜智能体只能消费同一个剧集目录下最新版本的episode_01.json。这种边界可以让外部贡献者很容易判断自己的改动影响面：如果改了分镜的 schema，画面生成技能包的输入字段也要同步升级，否则 PR 的 CI 校验就能拦住。

技能包版本管理沿用 Git 的 tag，比如script-writer/1.4.0。每个智能体运行时都会把自身版本号写进产物清单，后期如果发现某个生成结果不符合预期，能精确查出是哪一版 prompt 和哪一版模型权重产生了该结果。

2.3 用元数据约定替代智能体之间的点对点调用

多智能体协作最常见的反模式，就是让 Agent A 直接去调 Agent B 的 API。一旦链路长起来，任何一步失败都得写很复杂的异步回滚；而且 A 调用 B 时如果带着对话上下文，上下文很容易被循环放大，最终导致输入 token 爆炸，产出反而偏离大纲。

所以我们约定：所有智能体都不允许直接调用另一个智能体的内部接口。它们只和仓库通信。流程是这样的：智能体启动后，监听自己负责的输入目录或任务队列；一旦发现新的或状态变化的 manifest 文件，就开始执行任务；执行完成后把产物写入仓库，并更新 manifest 中的状态字段。

一次任务完成后写出的 manifest 大概长这样：

{ "task_id": "ep01_scene_004_shotlist", "agent": "shot-list-generator", "agent_version": "2.1.0", "status": "done", "inputs": [ "content/projects/drama_ep01/episode_01.json" ], "outputs": [ "content/projects/drama_ep01/scenes/scene_004/shotlist.json" ], "created_at": "2025-06-18T10:20:33Z", "cost_usd": 0.083 }

这个设计让整个系统具备非常强的可观测性。只要看 manifest 里的状态字段，就能知道当前工序是在排队、执行中、已完成还是出了问题；只要把 manifest 里的 input、output 关系做成图，就能还原整部短剧的生产链路。可视化看板后期之所以能快速上线，靠的正是这套从第一天就定好的元数据规范。

3. 多智能体之间的工作交接：从串行流水线到可插拔状态机

3.1 工作流不是一个大脚本，而是一张可查询的状态表

智能体之间的交接逻辑如果写进 Python 脚本里，最爽的是当下，最痛的是升级。短剧业务经常会调整生成顺序：有时候要先把人物定妆图做好再写后续剧本，因为剧情必须贴合角色；有时候则要先有完整剧本再批量生成角色引用图。这时候工作流不能写死，所以我们在仓库里维护了一张“工作流点表”，本质上是一个带优先级的状态机。

状态机涉及的节点包括：pending（等待被上一个节点触发）、ready（输入齐备可执行）、running（智能体正在处理）、blocked_for_review（等待人类审批）、done（成果已入库）、failed（执行失败，允许重试）。整部短剧从选题到成片，就是把这些节点在仓库元数据表里不停地从一个状态推进到下一个状态。

比如一个典型串行批次：

pending -> ready -> running -> done -> ready -> running -> done

自动化的核心不是“调谁”，而是用任务表驱动。每个智能体执行后只做两件事：更新自身的任务状态、确认下游任务是否已经变为ready。这种模式让我很好地避开了“中心调度器”这个维护噩梦，即便某个 Agent 进程崩溃，重启后在任务表中找到所有ready状态的任务继续执行即可。

3.2 一期实现：用事件加队列处理的串行编排

一期开源版本里，我们选择了一套最简单、也能跑通的方案：监听仓库文件系统事件并推送到消息队列，队列中每个消息对应一个任务。监听器拿到新增的 manifest 后，读取任务表，动态判断下一步应该触发哪个 Agent。这里最关键的一步是“动态判断”，判断逻辑基于 manifest 中的outputs和后继技能的 schema 依赖关系，所以每增加一个新智能体，只需要在技能包配置文件里注册输入依赖。

为什么这么设计的一期能快速交付？因为串行链路不需要考虑复杂的并发冲突，可以先验证流程闭环。我也建议任何团队刚开始做多智能体生产时，不要一上来就设计很复杂的并行编排，先把串行跑通，再做扩展。串行版本跑了一周后，我们发现单集生成效率大概提升了 60%，仍然不够，原因是角色资源准备和单集剧本撰写没有并行，而正好剧本撰写过程并不会用到全部定妆图，只要核心角色图先拿到，画面智能体就可以跟着推进部分场景。

3.3 二期演进：增加并行分支和人工审批节点

二期版本里，我们把工作流点表升级成有向无环图 DAG 来表达。DAG 的好处是可以定义并行子任务，比如“单集剧本产出后，可以同时生成 A 场景和 B 场景，同时启动配音稿生成”。如果某个节点需要人类判断创意方向，任务状态就会被置为blocked_for_review，看板上会立刻出现一条“等人审”的提示。

为了让人工审核不会变成瓶颈，我们在仓库里预置了“审批建议摘要”。例如剧本智能体完成一集后，会附带生成一个 200 字以内的剧情概述和人物行为动机说明；画面生成 Agent 输出角色候选图后，会附带 prompt 和参照图。审核人员不需要打开十几个文件，直接在可视化看板的待办卡片里就能做决定。这一步虽然简单，却实实在在提高了人工介入的效率，也让整体流程在“自动生成”和“人类把控”之间找到了平衡。

4. 可视化看板：让仓库每天的“心跳”清晰可见

4.1 看板数据从哪里来：仓库事件流加持续汇总的指标表

可视化看板不能只展示当前目录里有多少文件，那没有业务价值。真正有用的看板，必须回答这些问题：今天哪个环节在堆积？哪一集已经到了审查阶段？一共生成了多少次废图？各模型的调用成本是多少？

我们用的是仓库事件流加指标表的方式。每个智能体执行完成时，都会向事件中心发送一条标准化事件，事件内容包括任务类型、执行状态、耗时、模型版本、成本等。后台有一个聚合任务每隔五分钟把这些事件按剧集、环节、Agent 类型分组，写入一张production_metrics表。看板的图表全部直接查询这张表。

这样做的好处是查询速度很快。就算短剧规模增加到几百集，也不需要实时扫描全部 manifest；同时因为保留的是标准化事件，指标怎么展示可以随时调整，不必反推历史数据。做埋点设计时一定要牢记：宁可多保留一个字段，也不要等看板需求明确后再回去补。我们后期就在改版时吃过亏，有一个版本因为没有记录画面生成的模型耗时，导致后来想做成本优化时只能靠猜。

4.2 短剧业务真正要盯的核心指标

我梳理了团队最常用的看板指标，不是大家熟悉的那种千篇一律的“生成总数”，而是围绕短剧生产的六类指标：

这四个小时段里，我们最在意的其实是“各节点平均等待时长”。最开始经常出现一种情况：某 Agent 的排队队列已经堆了几十条，而旁边的推理卡完全空闲。团队成员只要看到等待时长变红，就会去调整队列分发逻辑，这比任何进度汇报都直观。

4.3 技术选型与落地效果：不是套个 Dashboard 就算完

技术选型时，我们考虑过直接部署 Grafana 或者 Superset。这些开源可视化工具本身很好，但短剧生产看板不可能只展示几个数值，还需要展示图片缩略图、带有人工审批状态的待办卡片、能直接点击查看分镜预览的富交互组件。让业务人员每天在两个系统之间跳来跳去并不现实，所以看板前端最终选择了自研的低代码方案，后端只暴露一组只读 REST API。

我们项目中的看板主要分成三块。第一块是“流程总览”，展示每一集处于哪个环节，用泳道形式列出各节点任务数量。第二块是“素材池”，按项目名称、角色、场景维度展示图片与视频资产，支持按使用次数排序。第三块是“问题追踪”，集中展示failed和blocked_for_review状态的任务，以及最近一次报错信息。自研工作不大，却能贴合业务需要。如果项目前期没有数据规范，就算接入再漂亮的 BI 工具，也依然只能看到一堆冷冰冰的数字。

5. 开源仓库的工程化细节：大文件、镜像、依赖、CI/CD 一网打尽

5.1 Git 仓库不放视频：大文件存储与索引分离

任何从单体仓库折戟的项目都知道，视频素材、图像集放进 Git 后，仓库体积会快速膨胀，团队协作会寸步难行。我们的处理方式是在 Git 仓库内只保存一份.file_index.json索引，索引中记录大文件在对象存储中的相对路径、文件大小、SHA-256、生成时间和所属任务。普通接入者不需要真的有大文件存储也可以跑通流程，因为文档结构里提供了 mock 入口。

对于有完整资源上传需求的团队，开源代码里提供了三个同步命令：上传作品包、删除过时资源、校验哈希。所有命令都要求先写索引再传文件，顺序反过来会导致短暂的索引空窗。如果你也在做类似项目，建议把“对象存储 + 文件索引 + 内容哈希校验”这三点从一开始就钉死，否则数据膨胀后迁移成本会非常痛苦。

5.2 让 Agent 运行环境可复现：容器镜像与镜像仓库

短剧生产涉及文本模型、图像模型、音频模型，不同智能体可能依赖不同版本的 PyTorch、Transformers 或者 ffmpeg。如果只是靠 requirements.txt 锁定版本，也很难完全排除系统库差异。我们为每个智能体写了单独 Dockerfile，基础镜像锁定到python:3.11-slim和node:20-bullseye-slim等具体标签，绝不使用latest。

构建好的镜像统一推送到私有镜像仓库，比如 Harbor 或 Docker Registry，并在发布 Agent 配置时记录镜像 digest 而不是 tag。因为同一个 tag 可以被重复推送覆盖，而 digest 不可变，能保证任何一次执行都使用完全相同的运行环境。这个小细节在和外部贡献者协作时特别有价值：他们从仓库拉取代码后，只需要按照docker-compose.yml拉取对应镜像，就能复现和我们完全一致的生产链路。

5.3 多语言依赖管理的统一实践：从 Maven 到 PyPI 的镜像与锁文件

短剧仓库里并不只是 Python，前端看板用 Node.js，部分格式解析工具链用 Java，因此依赖管理很容易变成一团乱麻。我们在根目录分别维护了python-requirements.lock、package-lock.json以及 Java 侧的pom.xml，并搭建了一个私有的 Nexus 制品仓库，对 PyPI、npm、Maven Central 都做了代理缓存。

这里有个很实际的经验：如果是国内团队协作，记得在构建配置里正确配置公共镜像仓库。以 Java 构建为例，最省心的方法是不要在每个项目里散落配置 mirror，而是统一在 Maven 的settings.xml中配置 Nexus 镜像地址，让 Nexus 去代理远程仓库。这样既能获得速度，又能保留版本追溯。针对依赖版本，CI 中加入依赖扫描步骤，防止某个组件包被替换成不兼容的新版本导致夜间自动化任务静默失败。

5.4 用 CI/CD 把仓库变成“自动生产线”

当仓库的设计稳定之后，CI/CD 就不只是测试代码，而是直接驱动生产。我们配置了几条流水线：第一条，每当有 Pull Request 涉及某个智能体的 schema 时，自动执行结构校验并跑一组最小样本，确保不会破坏下游 Agent 的输入输出约定。第二条，当发布一个新的 Agent 技能包版本时，自动构建镜像，执行单元测试，再上传到镜像仓库。第三条以定时任务方式运行，将仓库里新增的元数据事件同步到指标表并刷新演示看板。

这种做法能让外部贡献者获得很强安全感：任何一个改动都不会在合并后才被发现问题。我记得第一次有外部开发者提 PR 给剧本智能体新增了语气选项，CI 自动校验时发现生成结果与分镜阶段 schema 不兼容，系统直接拒绝合并并把原因列得一清二楚。这种“仓库驱动生产”的方式，正是整个开源实践最接近工业级工程的地方。

6. 开源共建机制与真实踩到的坑

6.1 让外部贡献者最快跑起来的 QuickStart

开源项目最怕的是文档说“很简单”，实际跑起来各种环境问题。为了让更多人能复现完整流程，我们单独维护了一个sample-drama示例集，里面只有三集迷你短剧所需的全部文本，所有中间产物用精简版 mock 数据代替。Docker Compose 文件只需要启动三个核心 Agent、一个对象存储、一个 PostgreSQL 实例和一个看板容器。只要硬件允许，外部贡献者执行三条命令就能看到一集短剧从梗概到分镜再到画面提示词的完整生产演示。

文档里我还强制写了一个“半小时入门路径”：第一步，先打开看板，理解有哪些阶段；第二步，运行一个已经配置好的串行任务，观察 manifest 状态变化；第三步，修改一段 prompt，重新触发某个 Agent，看看产物差异在仓库中如何呈现。这个路径能让新手快速体验“多 Agent 不是互相调 API，而是共享仓库状态”的核心设计。

6.2 我们踩过的那些数据、版本和状态相关的深坑

开源过程不等于顺风顺水。自己跑团队内部场景和开放给社区使用是完全不同的复杂度。我在这里把几个影响最深刻的坑分享给大家，希望后来者不用踩第二遍。

第一个坑是多个 Agent 并行执行时，都往同名目录写文件导致相互覆盖。解决办法是每个任务的任务 ID 必须全局唯一，并在写入目录中加入任务 ID 前缀。现在我们的产物结构永远是tasks/{task_id}/output/...，不会再出现两个 Agent 抢一个目录的问题。

第二个坑是 prompt 模板变更之后没有任何版本关联，导致回滚旧任务时无法复现。我们把 prompt 模板也纳入 Git 仓库，并在 manifest 中记录模板的 commit hash，同时记录模型权重文件的 sha256。这样即使后来模型升级了，审计历史时也能准确知道当时到底用什么生成出来的。

第三个坑发生在可视化看板开发晚期：之前有不少 Agent 只发布结果，没有发布统一格式的事件。等我们要统计失败原因时，只能用粗糙的日志字符串去匹配。补埋点的成本比想象中高得多。所以后来我们强制要求所有 Agent 的事件发布必须使用仓库中统一的 schema，并且把这条要求写进开源贡献指南里。这也是我看板项目最笨但也最正确的决定。

6.3 AI 生成内容的版权与合规边界处理

最后这块看着不起眼，实际对短剧项目开源影响很大。短剧涉及大量生成内容，不同地区对肖像、声音、音乐版权的合规要求不一样，开源仓库不能默认用户可以随意生成真人肖像或知名歌手音色，所以我们在流程中加了一道“合规审核 Agent”。它不是简单用提示词做安全检查，而是会读取生成物的元数据：如果是人物画面，检查参考图中是否带有“真人肖像授权”标签；如果是音频，检查模型名称是否在授权白名单内；所有最终进入成片阶段的物料，必须携带来源素材 ID 和生成配置哈希，方便出现争议时能走完问责与下架流程。

关于内容取向，我们也在技能包的提示词规范里加入了正向引导设定，避免模型被恶意提示词劫持生成低俗化内容。这个审核 Agent 本身也可以被社区替换和增强，整个模块在开源仓库中独立维护。说句实话，内容安全不是锦上添花的插件，而是让短剧生产能走得更远的一道保险。谁在搭建这类生产链路时忽略它，后期一定会付出更多补救成本。

等到项目真正对外开源，我才更清楚这套方案的边界在哪里。如果现在让我重新设计一遍，我会把所有指标埋点从第一天就定义为“协议”的一部分，让它不是事后加上的功能，而是每个智能体必须遵守的接口。多个 AI 智能体共同处理真实业务时，模型能力只是下限，真正决定上限的是交接规范、产物定位和过程透明。这套从短剧生产到可视化看板的开源实践能落地，不是因为我写的某个智能体效果多惊艳，而是因为我愿意把仓库看作一个“会呼吸的数据库”，让每一步变化都被记录、被展示、被复盘。后续我还会继续完善资产层的通用化设计，让它能复用到更多剧情类内容生产场景。