OpenMontage Backlot 实战指南：用 `/backlot` 命令打开实时视频制作看板

OpenMontage Backlot 实战指南用/backlot命令打开实时视频制作看板【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage本篇技术指南以 OpenMontage 仓库中的 .cursor/commands/backlot.md 命令文档为核心完整讲解 Backlot「living storyboard活的分镜看板」的打开方式、运行语义与底层实现。读完你将掌握如何通过python -m backlot open project-id一条命令让 Agent 在流水线启动时打开浏览器看板、看板如何从磁盘文件实时派生阶段/脚本/分镜/资产生成状态以及为什么「看板永远只是观察者、绝不阻塞生产」这条设计契约贯穿始终。一、Backlot 是什么一条命令背后的「活分镜看板」Backlot 是 OpenMontage 内置的一个只读本地看板read-only local board它把一次正在进行中的视频制作「演出」呈现为浏览器 UI——流水线阶段依次点亮、剧本以分镜稿screenplay形式呈现、场景计划scene plan以胶片条filmstrip形态随资产生成逐帧填充同时展示决策记录decisions、花费cost与实时活动activity。所有这些内容都不是 UI 自己生成或 Agent 主动上报的而是完全由流水线已经写入projects/id/的磁盘文件派生而来。项目完整说明见 backlot/README.md。从代码结构看Backlot 是一个独立可运行的 Python 模块由四个部分构成文件职责backlot/main.pyCLI 入口open/serve两个子命令backlot/server.pyFastAPI 服务看板状态 API、SSE 变更推送、媒体/缩略图服务backlot/state.py状态派生把项目目录渲染成可展示的 BoardStatebacklot/ui/前端静态资源board.html看板页、index.html库页及配套 JS/CSS默认端口为4750见 backlot/init.py 中DEFAULT_PORT 4750。二、/backlot命令速查三种打开方式.cursor/commands/backlot.md定义了一条 Agent 可直接调用的命令/backlot其核心动作是「为请求的项目打开 Backlot 看板」。底层等价于三个 CLI 用法与 backlot/README.md 一致python -m backlot open project-id # 需要时启动 server然后打开浏览器到该项目看板 python -m backlot open # 无 project id → 打开 library 视图全部项目 python -m backlot serve --port 4750 # 前台运行 server2.1 带项目 id打开指定项目看板python -m backlot open project-id若 server 尚未运行会静默在后台启动随后自动打开浏览器访问http://127.0.0.1:port/p/project-id若 server 已在运行则直接打开对应项目页指定不存在的项目 id 会在浏览器中显示 404/api/project/{id}/state会先做_safe_project_dir校验见 backlot/server.py。2.2 无 project id打开 Library 视图python -m backlot open不带参数时打开http://127.0.0.1:port/即 Backlot 的**项目库library**视图列出projects/下全部项目卡片卡片包含项目类型、场景数、渲染数以及LIVE5 分钟窗口内有磁盘活动或NO MEDIA YET等状态标记。库的排序规则是「live 项目优先其次按最近活动时间倒序」见 backlot/state.py。2.3 前台运行 Serverpython -m backlot serve --port 4750在终端前台以uvicorn运行 FastAPI 应用backlot.server:app便于调试时直接观察请求日志端口可用--port指定也可通过环境变量BACKLOT_PORT覆盖默认值见 backlot/main.py。三、命令行为语义幂等、容错、绝不阻塞/backlot命令文档用三条规则约束了命令行为这三条在 backlot/main.py 中均有对应实现1. 幂等Idempotentopen不会重复启动 server。cmd_open首先通过_server_alive()探测GET /api/health1.5 秒超时只有探测失败才调用_spawn_server()以分离进程方式拉起python -m backlot serve --port N见 backlot/main.py。这意味着多次调用是安全的Agent 可以在流水线初始化、中途重试等任意时刻反复执行。2. 失败不致命non-fatal如果 server 启动失败或在 15 秒内未能就绪cmd_open只打印一行backlot: could not start server (...) — continuing without the board并以状态码 1 返回见 backlot/main.py绝不让一次看板故障拖垮整个视频生产流水线。这正是模块 docstring 中「agents call it at pipeline initialization and must continue the production even if it fails」的设计承诺见 backlot/main.py。3. 观察者不是阻塞器observer, never a blocker看板只负责「看」不参与任何生产决策。它的所有输入都来自流水线已经写好的文件流水线运行完全不依赖看板是否在线。四、看板如何「活」起来观察者模式的数据流Backlot 的「live」不是靠 Agent 主动汇报而是一条完整的磁盘 → 监听 → 推送 → 重取链路见 backlot/server.py 与 backlot/README.md 的 How it stays live监听后台任务_watch_projects()使用watchfiles.awatch递归监听projects/目录以 400ms 为步长聚合变更并通过字符串前缀比较把文件路径归因到具体项目见 backlot/server.py发布ChangeHub是一个变更扇出器fan-out每个订阅队列带maxsize64且按项目过滤——订阅某项目的看板只接收该项目的事件避免无关项目的大批量变更渲染期间可达数千路径挤爆队列见 backlot/server.py推送浏览器通过 SSE 长连接订阅/api/project/{id}/events或/api/library/events收到change事件后重新拉取看板状态连接空闲时每 15 秒收到一次heartbeat心跳见 backlot/server.py重取前端 JS 重新请求/api/project/{id}/state由load_board_state()重新从磁盘派生完整 BoardState。值得注意的是库视图的摘要library summary是全状态解析、开销较高因此server.py用_summary_cache按项目缓存并由 watcher 在文件变化时主动失效见 backlot/server.py。五、状态从磁盘派生projects/id/目录契约Backlot 状态派生的核心原则是「一切状态都来自projects/id/磁盘文件」。/backlot命令文档强调board 从磁盘派生状态绝不手动更新 UI。各看板元素与磁盘源的对应关系如下来自 backlot/README.md看板元素磁盘来源项目身份 / 阶段顺序rail orderproject.jsonpipeline_defs/type.yaml阶段状态、门禁、版本checkpoint_stage.jsonhistory/脚本卡片 / 弹窗artifacts/script.json分镜胶片条卡片scene_plan × script × asset_manifest三表联查生成中微光、活动events.jsonl由BaseTool埋点写入花费计量checkpoint 的cost_snapshot渲染成品renders/*.mp4含项目根目录 mp4 启发式这些约定与 lib/checkpoint.py 中init_project()创建的标准目录布局完全吻合artifacts/、assets/images|video|audio|music、renders/并写入project.json标记文件见 lib/checkpoint.py。5.1 阶段轨Stage Rail与门禁审计_build_stage_rail()见 backlot/state.py以 pipeline manifest如 pipeline_defs/cinematic.yaml声明的阶段顺序为准为每个阶段派生状态pending / in_progress / awaiting_human / completed、review 结论、cost_snapshot、历史版本数以及门禁跳过审计——一个本应经过awaiting_human的 gated 阶段若直接以completed收尾且从未出现awaiting_human版本、也没有human_approvedTrue就会被标记为gate_skipped: true暴露在看板上。值得注意的健壮性设计manifest 未声明的阶段如历史遗留运行的 checkpoint也会被插入阶段轨并按FALLBACK_STAGES的规范位置排序如idea应靠前而不是全部堆在末尾。5.2 分镜故事板三表联查 实时事件_build_storyboard()见 backlot/state.py是看板最「活」的部分每个场景卡片由scene_plan.scenes驱动再与script.sections按script_section_id或时间重叠匹配、asset_manifest.assets联查得到旁白文本、镜头语言、所需资产、候选镜头takes等字段。而「生成中generating」状态则来自事件流某个场景最近的顶层事件若是未完成的start卡片即显示生成微光并标注工具名如flux_imagefinish/error事件会清除该状态嵌套depth0的 provider 事件会被跳过以最外层调用的完成为准。对于无法生成缩略图的 bespoke 资产如.tsx动画合成看板会回退到每场景快照snapshots/scene_id.png保证胶片条永远有视觉内容见 backlot/state.py。5.3 活动、花费与卡死检测活动日志lib/events.py维护追加式的events.jsonl由BaseTool埋点层在每次工具调用时写入事件归属通过显式project_dir/project_path或输入路径推断见 lib/events.py。关键设计是「观测绝不破坏生产」所有公开函数静默吞掉自身错误写失败只丢一条活动记录见 lib/events.py。花费以最新 checkpoint 的cost_snapshot为准缺失时回退到asset_manifest.total_cost_usd见 backlot/state.py。卡死检测in_progress阶段若超过 10 分钟STALL_WINDOW_SECONDS无任何磁盘活动会被标记stalled并显示已停滞分钟数——「卡死的 Agent 必须可见而不是沉默」见 backlot/state.py 与 backlot/state.py。六、保持 Checkpoints 诚实门禁完整性与测试验证/backlot命令文档的最后一条要求是「保持 checkpoints 和 artifacts 诚实Keep checkpoints and artifacts honest」并指向 skills/meta/checkpoint-protocol.md。这是因为看板显示的阶段状态、门禁审计、花费全部依赖 checkpoint 文件——如果 checkpoint 是伪造的看板展示的就是谎言。lib/checkpoint.py在写入端做了三层硬约束门禁强制GATE VIOLATION当 pipeline manifest 声明某阶段human_approval_default: true或调用方显式传入human_approval_requiredTrue时直接以completed写入且未带human_approvedTrue会抛出CheckpointValidationError见 lib/checkpoint.py前置条件强制PREREQUISITE VIOLATIONawaiting_human/completed生命周期推进前会校验前序阶段全部completed且 gated 前序已获批准见 lib/checkpoint.py历史归档被取代的completed/awaiting_humancheckpoint 会复制进history/保留完整版本轨迹script v1→v2、gate 转换均可重建供看板展示版本数与时间线回放见 lib/checkpoint.py。对应测试 tests/backlot/test_gate_scenarios.py 直接验证了看板与 checkpoint 的联动手写一个缺human_approved的completedcheckpoint 后load_board_state()会把该阶段标记为gate_skipped: True而规范的awaiting_human → completed(human_approvedTrue)序列则得到gate_skipped: False且versions 2、history_entries[0].status awaiting_human。七、无真实生产时如何体验模拟一次完整流水线想在不跑真实生产的情况下看到看板的 live 效果仓库提供了模拟驱动脚本见 backlot/README.mdpython scripts/backlot_simulate_run.py # live 演示运行约 1 分钟 python -m backlot open backlot-demo-runbacklot_simulate_run.py并不是一个玩具脚本它驱动的是真实契约通过lib.checkpoint.init_project初始化项目、write_checkpoint写入in_progress → awaiting_human → completed的阶段流转、lib.events.emit_event发射按场景的flux_image生成事件、并渐进式写入script.json、scene_plan.json、asset_manifest.json等产物见 scripts/backlot_simulate_run.py。其参数包括python scripts/backlot_simulate_run.py [--project backlot-demo-run] [--fast] [--cleanup]--fast把等待压缩到约 0.3 秒供自动化验证使用--cleanup结束后删除演示项目目录。模拟结束后浏览器中即可看到阶段轨点亮、脚本门禁待审、逐场景资产生成与花费累计的完整 live 过程。八、进阶媒体服务与回放机制除了状态 APIserver 还提供两类媒体能力保证看板图片/视频可以直出缩略图服务/thumb/{project_id}/{path}图片按目标宽度320/640/960 三档就近取宽降采样为 JPEG 并缓存到.backlot/thumbs/视频则调用ffmpeg在 1.5 秒处抽取单帧作海报缓存键由文件 mtimesize 的 SHA1 构成杜绝并发写同一临时文件见 backlot/server.py媒体服务/media/{project_id}/{path}通过FileResponse提供范围请求支持range requests可直接播放renders/*.mp4等大文件两类接口都对路径做了relative_to校验杜绝穿越项目目录读取任意文件见 backlot/server.py。此外看板的**回放Replay**能力值得一提一个已完成运行可通过看板上的 ▶ REPLAY RUN 从头到尾拖拽回放数据完全由 checkpoint 历史history/与事件时间戳重建无需任何额外录制见 backlot/README.md 的 Replay 段落。九、集成姿势Agent 应在何处调用/backlot.cursor/commands/backlot.md的实际使用场景是作为 Agent 的斜杠命令在流水线初始化时调用/backlot open project-id之后该项目的所有阶段进展会自动出现在浏览器看板中供用户随时查看。需要记住的四条纪律无 project id 时/backlot open打开库视图幂等命令会自行判断 server 是否在运行可安全重复调用失败不阻塞看板打不开就报告并继续生产它只是观察者绝不手动更新 UI看板状态永远派生自projects/id/磁盘文件Agent 只需要诚实地通过init_project/write_checkpoint/emit_event写文件看板自然会如实呈现——checkpoint 协议详见 skills/meta/checkpoint-protocol.md。相关实现与测试还可继续深入阅读backlot/server.py、backlot/state.py、lib/checkpoint.py、tests/backlot/test_server.py 与 tests/backlot/test_state.py。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考