OpenMontage Backlot 活板Living Storyboard完整使用指南一行命令打开生产流程的可视化看板【免费下载链接】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/OpenMontageBacklot 是 OpenMontage 内置的只读实时看板living storyboard它不参与生产只负责把正在进行的视频生产线pipeline以可视化形式呈现在浏览器里——管线阶段逐一亮起、脚本以分镜剧本页展示、场景计划像胶片条一样随着素材生成而逐步填充同时实时呈现决策、花费与活动日志。它的一切数据都源自流水线本就写入projects/id/的检查点、产物、素材与事件日志Agent 与用户都不需要手动维护界面。本文以 .claude/commands/backlot.md 中的 Agent 调用指令为骨架结合 backlot/ 源码模块完整讲解如何打开看板、看板如何保持实时、每个界面元素对应的磁盘数据源以及如何在没有真实生产的情况下体验它。一、本质一个观察者不是报告者Backlot 的核心设计契约记录在 backlot/init.py只有三条Observation, not reporting观察而非上报看板上的所有状态都从流水线已经写入磁盘的文件中推导而来。Agent 永远不会去手动更新 UINever block, never break永不阻塞、永不中断状态文件缺失或损坏时看板优雅降级而不是崩溃Agent 的唯一职责在流水线初始化时执行一次python -m backlot open project。从源码实现看这个契约被严格执行backlot/server.py 的模块注释明确写道The server never writes to project directories——服务端只读项目目录并对外提供状态 APIbacklot/state.py 的 docstring 也强调Everything here is read-only and defensive: a malformed JSON file, a missing artifact, or a half-written checkpoint must degrade the board, never crash it。这一点也直接决定了Backlot 对生产流程的定位是观察者绝不是阻塞器。命令文档特别强调即使open命令失败也要如实上报并继续用户原本的任务。看板只是为了让你看见生产在发生什么而不是生产的依赖项。磁盘目录约定看板监视的根目录来自 lib/paths.py 中定义的单一事实源REPO_ROOT Path(__file__).resolve().parent.parent # 可用环境变量 OPENMONTAGE_PROJECTS_DIR 覆盖默认在仓库 projects/ 下 PROJECTS_DIR Path(os.environ.get(OPENMONTAGE_PROJECTS_DIR) or (REPO_ROOT / projects))检查点、工具事件归属、Backlot 监视都共用这一个根目录保证所有模块看到的项目集合一致。每个项目目录的标准布局由lib.checkpoint.init_project创建同时写入 Backlot 展示项目所需的project.json标记文件大致为projects/id/ ├── project.json # 项目标记title、pipeline_type、style_playbook、created_at ├── checkpoint_stage.json # 每个阶段的当前检查点 ├── history/checkpoint_stage_N.json # 被替换的检查点归档供回放 ├── artifacts/*.json # script.json、scene_plan.json、asset_manifest.json 等规范产物 ├── events.jsonl # BaseTool 插桩写入的追加式工具事件日志 ├── assets/ renders/ snapshots/ verify/ # 媒体与快照 └── decision_log.json # 决策日志也支持放在项目根二、核心命令python -m backlot openBacklot 的 CLI 入口在 backlot/main.py其 docstring 定义了两种命令形式python -m backlot open [project-id] # 必要时启动服务然后在浏览器打开看板 python -m backlot serve [--port N] # 前台运行服务open子命令的行为细节open是幂等且非致命的其完整执行流程在 backlot/main.py 的cmd_open()中可以看到探测端口默认端口为DEFAULT_PORT 4750定义在 backlot/init.py可通过环境变量BACKLOT_PORT覆盖健康检查向http://127.0.0.1:port/api/health发起 1.5 秒超时的请求判断服务是否已在运行未运行则拉起用subprocess.Popen以分离的后台进程方式启动python -m backlot serve --port portUnix 下start_new_sessionTrueWindows 下DETACHED_PROCESS并在 15 秒内轮询等待服务就绪打开浏览器带项目参数时访问http://127.0.0.1:port/p/project_id项目看板页不带参数时访问http://127.0.0.1:port/库视图列出所有项目失败兜底服务起不来或超时打印提示并返回退出码 1——生产流程继续运行不受影响。因此命令文档中的三条规则可以对应到源码不带参数 → 库视图python -m backlot open打开所有项目的总览幂等服务已在运行就直接复用不会重复启动失败不阻塞所有异常都被捕获并打印continuing without the board这正是the board is an observer, never a blocker的实现。serve子命令需要在前台运行服务例如调试或自定义端口时使用python -m backlot serve --port 4750 # 前台运行默认绑定 127.0.0.1cmd_serve()内部通过uvicorn.run(backlot.server:app, host127.0.0.1, portport, log_levelwarning)启动 FastAPI 应用。注意它只绑定本机回环地址不会暴露到局域网。三、看板如何保持实时watchfiles SSE命令文档提到看板从磁盘派生一切而让它保持活的技术机制在 backlot/server.py 中文件监视后台任务_watch_projects()用watchfiles.awatch(PROJECTS_DIR, recursiveTrue, step400)递归监视projects/目录400ms 去抖步长。每次变更批量到达时_project_of_change()用纯字符串前缀匹配把变更路径映射到项目 id并跳过node_modules、.git、__pycache__、.cache等纯噪声目录变更分发映射出的项目 id 通过ChangeHub一个按项目过滤的订阅-发布中心分发给 SSE 订阅者。订阅是按项目过滤的——某个项目的事件洪流不会淹没其他项目的看板队列队列满时直接丢弃因为队列里只有该订阅者关心的 id满队列本身就意味着已经有一次待处理的唤醒浏览器拉取浏览器通过text/event-stream长连接订阅/api/project/id/events每 15 秒心跳一次收到change事件后重新请求板状态接口GET /api/project/id/state从而刷新界面。库视图订阅/api/library/events任一路径变化都会驱动库卡片重排。如果watchfiles未安装看板退回手动刷新模式代码里except ImportError: return同时注释说明watcher unavailable → board still works via manual refresh——这再次印证了never break的设计。四、界面元素 ↔ 磁盘数据源对照表backlot/README.md 给出了看板每个元素与磁盘来源的权威映射。结合 backlot/state.py 的load_board_state()实现这张表可以更具体看板元素磁盘数据源实现要点state.py项目身份 / 阶段轨道顺序project.jsonpipeline_defs/type.yaml_load_pipeline_meta()读取管线清单得到阶段顺序与门禁标志清单未知时回退到FALLBACK_STAGES阶段状态、门禁、版本checkpoint_stage.jsonhistory/_collect_checkpoints()收集各阶段当前检查点_collect_history()读取归档版本_build_stage_rail()合并为阶段轨道并做门禁审计脚本卡片 / 模态框artifacts/script.jsonARTIFACT_FILES映射中 script →script.json胶片条卡片scene_plan × script × asset_manifest三表连接_build_storyboard()按scene_id连接场景计划、脚本分节优先按script_section_id回退按时间重叠与素材清单生成中微光 / 活动events.jsonl由 BaseTool 插桩写入lib.events.read_events()读取场景级start/finish/error事件决定该卡片是否显示generating状态花费仪表检查点cost_snapshot取最新检查点中的cost_snapshot缺失时回退到asset_manifest.total_cost_usd渲染成品renders/*.mp4 根目录 mp4 启发式_scan_media()扫描renders/目录与项目根下*.mp4几个值得注意的细节门禁审计对于human_approval_default: true的带门阶段如果它最终completed却从未经过awaiting_human当前或历史版本_build_stage_rail()会标记gate_skipped: True——被跳过的门禁会在看板上一目了然未声明阶段清单未声明但磁盘上存在的检查点如旧运行、管线不匹配仍会显示在轨道上undeclared: True并按FALLBACK_STAGES中的规范位置插入例如 idea 会被放到轨道靠前的位置而不是挂在末尾素材可渲染性_asset_entry()对每个素材判断exists与renderable——只有真实存在且为位图/视频的文件才能在img/video中展示指向.tsx的 bespoke 合成素材不可渲染胶片条会回退显示snapshots/scene_id.png场景静帧停滞检测in_progress阶段在STALL_WINDOW_SECONDS10 分钟内无任何文件系统活动会被标记stalled并显示停滞分钟数LIVE_WINDOW_SECONDS5 分钟内的活动则决定项目是否标记为live。没有检查点的项目会优雅降级为watcher 找到什么就显示什么的视图——媒体、快照、渲染成品仍然展示只是没有阶段轨道和门禁信息。五、回放Replay擦洗一整条已完成的流水线命令文档没有展开但 README 提到一个关键能力Replay。看板上的 ▶ REPLAY RUN 按钮可以把一条已完成的运行从头到尾擦洗回放——数据从检查点历史history/目录归档和事件时间戳events.jsonl重建。实现基础就是_build_stage_rail()里为每个阶段构建的history_entries历史版本的{status, timestamp}序列加上当前检查点构成阶段状态的完整时间线。这是checkpoint 是流水线的存档点见 skills/meta/checkpoint-protocol.md的直接可视化回报。六、看板为何诚实与 Checkpoint 协议的关系命令文档明确要求保持检查点与产物的诚实看板自然就诚实。看板本身不产生任何数据它只负责把 skills/meta/checkpoint-protocol.md 规定的检查点协议写出的文件渲染出来。几个直接关联点进入阶段先写in_progress检查点这正是在看板上区分进行中与停滞的依据。协议第 4 步要求进入任何阶段先写in_progress检查点——what tells the user (via the Backlot board) that the stage is live rather than stalledmetadata.partial_progress驱动胶片条渐进填充长阶段assets/compose 循环每生成一个场景就更新 partial progress看板的partial_progress字段checkpoint.metadata.partial_progress会随之变化awaiting_human门禁展示需要人工审批的阶段以awaiting_human状态停在看板上审批总结里还会引导用户If the Backlot board is running, point to it: the artifact renders thereinit_project()与project.json标记协议要求流水线初始化时调用init_project()写project.json——the marker the Backlot board needs to show the project before its first checkpoint然后执行python -m backlot open my-project非致命。也就是说只要流水线按协议诚实写盘看板就不需要任何额外维护。七、没有真实生产也能体验模拟运行脚本仓库提供 scripts/backlot_simulate_run.py 来驱动一条真实的磁盘契约init_project、in_progress检查点、带门awaiting_human状态、工具事件、渐进写入的产物让看板实时演示也可以当作 demo 驱动python scripts/backlot_simulate_run.py # 实时演示运行约 1 分钟 python -m backlot open backlot-demo-run脚本参数--project backlot-demo-run # 指定演示项目 id默认 backlot-demo-run --fast # 等待压缩到 ~0.3s用于自动化验证 --cleanup # 结束后删除项目目录脚本走的是真实契约调用init_project、write_checkpoint、emit_event用 PIL 生成占位素材图逐步写入asset_manifest并在每次生成后带cost_snapshot与partial_progress更新in_progress检查点最后在 assets 门禁处awaiting_human等待模拟用户审阅胶片条再审批放行。你可以亲眼看到看板上的阶段依次亮起、胶片条逐步填充、花费表增长——这正是对命令文档所讲看板如何保持 live的最直观演示。八、服务端 API 一览供调试与集成看板前端依赖的 HTTP API 全部定义在 backlot/server.py 的create_app()中如果你要集成或调试可以参考端点说明GET /api/health健康检查open命令即用此探活GET /api/projects库视图所有项目摘要live 优先、按最近活动排序带内存摘要缓存GET /api/project/id/state单个项目的完整板状态GET /api/project/id/eventsSSE 变更流按项目过滤 15s 心跳GET /api/library/eventsSSE 库变更流GET /thumb/project_id/path?w640缩略图/视频海报帧磁盘缓存 JPEG宽 320/640/960 三档视频用 ffmpeg 在 1.5s 处抽帧GET /media/project_id/path媒体文件FileResponse 支持 range 请求GET /与GET /p/project_id库页面与看板页面HTML 静态资源安全设计值得注意_safe_project_dir()拒绝包含/、\、:或./..的项目 id防止路径穿越缩略图与媒体端点都用Path.resolve()relative_to()双重校验文件必须落在项目目录内越界返回 403。九、测试与验证Backlot 的行为有完整的测试覆盖位于 tests/backlot/test_server.pyAPI 形状、路径安全、媒体/缩略图服务、range 请求与宽松性能预算test_state.py板状态推导逻辑含损坏 JSON 优雅降级的防御性行为test_gate_scenarios.py门禁场景含 gate-skipped 审计test_ui_bug_bash.py 与 test_watch_captures.pyUI 冒烟与捕获监视test_visual_eval.py视觉评估辅助。这些测试与--fast模拟脚本结合可以自动化验证看板的全链路行为。十、最佳实践小结结合命令文档与源码使用 Backlot 的正确姿势可以浓缩为几条在流水线初始化时调用python -m backlot open project幂等、非致命失败就上报并继续永远不要手动改 UI——保持检查点与产物诚实看板自然诚实无参数调用看库视图带参数看具体项目用模拟脚本快速体验python scripts/backlot_simulate_run.pypython -m backlot open backlot-demo-run把看板当作审阅面assets 门禁的场景级胶片条审阅按 skills/meta/checkpoint-protocol.md 第 5 步的要求——A bad asset caught here saves a full re-render。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考