决定做这个 AI 智能体共建仓库的起因是半年前我亲眼看着一条短剧生产线被各种文档、素材、生成脚本和模型配置搅成一锅粥。短剧生产是典型的内容密集型业务而团队里每个人都把中间产物存在自己的电脑和聊天记录里编剧、剪辑、导演和那几个 AI 智能体各自为战最终交付全靠微信互传压缩包。为了把大伙从这种状态里捞出来我用三个月时间搭了一个开源项目把短剧生产涉及的全部文本、画面、音频、提示词和数据处理任务沉淀进一个共建仓库再让多个 AI 智能体通过仓库完成交接最后用一套可视化看板展示各个环节的进展。这篇文章就是整个过程的实操复盘适合正在做多智能体协作、想做内容生产数字化或者单纯想了解开源项目怎么落地到具体业务场景的人读。1. 立项思路短剧生产为什么会需要一个“智能体共建仓库”1.1 短剧的生产链路拆解每一步都在产生中间产物很多人以为短剧就是批量生成短视频但实际上短剧更接近“单元剧集”每集三五分钟总共几十集剧情连续、角色固定、场景复用率高。我按团队实际过程拆过一遍链路大致是选题报审、人物小传、单集剧本、分集大纲、分镜脚本、角色一致性设计、单帧画面生成、场景视频生成、配音与字幕、粗剪精剪、成片质检、平台分发。这条链路上的每一步都会生成新的中间产物选题阶段产生策划文档剧本阶段产生文本稿分镜阶段产生表格和示意图画面生成阶段产生角色设定图和场景图剪辑阶段产生工程文件和成片素材。每经过一个人工或者智能体都会产生一批“临时资产”。这些资产如果不放到统一的地方就会直接变成团队内部互相传文件、改文件名、覆盖版本的无底洞。表格可以看得很清楚生产环节主要产物过去的管理方式进入仓库后的管理方式选题策划故事梗概、竞对分析在线文档散落统一命名 元数据标签剧本单集剧本、台词稿Word 版本号混乱Git 文本版本管理分镜设计表格、示意图、调度说明表格发群结构化 JSON 图片关联画面生成角色设定图、场景素材相册/网盘对象存储 内容哈希视频合成片段、粗剪、精剪本地工程文件大文件仓库 清单索引质检审核合规报告、技术复检人工截图反馈审核智能体自动写入结论如果没有统一仓库这些中间产物永远只是个人经验的一部分有仓库之后它们才变成可以被任意一个智能体消费的输入。这也是我后来反复和团队强调的一句话多个 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.jsonjson 里的每个场次、对白都要符合统一的 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 短剧业务真正要盯的核心指标我梳理了团队最常用的看板指标不是大家熟悉的那种千篇一律的“生成总数”而是围绕短剧生产的六类指标指标计算方式业务含义单集平均生产周期从剧本进入仓库到成片审核通过的时间反映整体效率各节点平均等待时长任务从 ready 落到 running 的时间差寻找流程断点画面生成一次通过率无人工修改直接入库的画面数 / 总生成画面数衡量 prompt 与模型质量素材重复引用率同一角色/场景素材被重复生成的次数发现资产复用问题Agent 任务成功率成功任务数 / 全部执行任务数稳定性核心单集生成成本各 Agent 成本字段汇总控制预算这四个小时段里我们最在意的其实是“各节点平均等待时长”。最开始经常出现一种情况某 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 智能体共同处理真实业务时模型能力只是下限真正决定上限的是交接规范、产物定位和过程透明。这套从短剧生产到可视化看板的开源实践能落地不是因为我写的某个智能体效果多惊艳而是因为我愿意把仓库看作一个“会呼吸的数据库”让每一步变化都被记录、被展示、被复盘。后续我还会继续完善资产层的通用化设计让它能复用到更多剧情类内容生产场景。