OpenMontage Backlot 详解：基于磁盘事件驱动的实时制片看板（Living Storyboard）

OpenMontage Backlot 详解：基于磁盘事件驱动的实时制片看板（Living Storyboard）

【免费下载链接】OpenMontageWorld's 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

Backlot 是 OpenMontage 内置的一个只读、本地、由磁盘状态推导的"活的故事板"（living storyboard）模块：它把正在发生的生产流程实时呈现在浏览器里——流水线各阶段逐一点亮、剧本以分场脚本页呈现、场景计划以胶片条（filmstrip）形式随素材生成而逐步填充，同时展示决策、花费与活动。本文以 backlot/README.md 为核心骨架，结合 服务端实现、状态推导层、事件流 与 检查点协议 的源码细节，完整讲解 Backlot 的启动方式、实时机制、状态来源、看板构成、回放能力与优雅降级策略，读完即可在本地跑起一个实时制片看板并理解其底层原理。

Backlot 看板运行实况（docs/images/backlot/board-live.png）

一、Backlot 是什么：观察而非汇报

Backlot 的全部设计都建立在一个核心契约上：看板上的所有状态都不是 Agent 主动"上报"的，而是从流水线本来就会写入projects/<id>/目录的文件中推导出来的。官方 README 将其概括为：

A read-only local board that shows a production happening: pipeline stages lighting up, the script as a screenplay page, the scene plan as a filmstrip that fills in as assets generate, decisions, spend, and activity — all derived from what the pipeline already writes toprojects/<id>/.

模块包内 backlot/init.py 进一步把设计契约凝练为三条：

1. Observation, not reporting：所有状态都来自流水线本就写入的文件，Agent 永远不需要去更新 UI；
2. Never block, never break：残缺或损坏的状态只会让看板优雅降级，绝不能让它崩溃或阻塞生产；
3. Agent 的唯一职责：在流水线初始化时执行一次python -m backlot open <project>。

也就是说，Backlot 是纯"旁观者"：它读文件、渲染、推送变更，但永远不会写项目目录——这一点在 server.py 的模块注释里被明确声明："The server never writes to project directories."

二、快速开始：三条命令

README 给出了三种典型用法：

python -m backlot open <project-id> # 如无服务则启动，并打开浏览器到该项目的看板 python -m backlot open # 打开库视图（所有项目一览） python -m backlot serve --port 4750 # 前台运行服务

从 backlot/main.py 可以看到命令背后的实际行为：

• open子命令是幂等且非致命的：它先探测http://127.0.0.1:<port>/api/health判断服务是否已在运行；若未运行则以分离的后台进程方式拉起serve（Windows 使用CREATE_NEW_PROCESS_GROUP，POSIX 使用start_new_session），然后轮询健康检查最多 15 秒，最后用webbrowser.open打开http://127.0.0.1:<port>/p/<project-id>（无参数则打开库视图/）。
• 端口默认为4750（定义于 backlot/init.py 的DEFAULT_PORT），可通过环境变量BACKLOT_PORT覆盖。
• 设计上，即使服务启动失败，open也只是打印一条提示并返回非零退出码，但不会抛异常——因为 Agent 在流水线初始化时调用它，生产流程必须继续推进。这正是"never block"的体现。

三、实时性如何保持：watchfiles + SSE 变更推送

README 指出，Backlot 的"live"能力完全不需要 Agent 参与：一个基于watchfiles的 watcher 监听projects/目录，把变更通知通过 SSE（Server-Sent Events）推送给浏览器，浏览器收到后重新拉取看板状态。

这一机制在 server.py 中有完整的源码级实现：

• 监听循环：_watch_projects()在 FastAPI 的 lifespan 中作为后台任务启动（_lifespan负责创建与取消该任务），使用awatch(PROJECTS_DIR, recursive=True, step=400)递归监听，step=400意味着变更事件会先聚合 400ms 再触发一次回调，天然具备防抖效果。
• 变更到项目的映射：热路径_project_of_change()只做纯字符串比较（避免逐路径做文件系统调用），把变更路径归一化后截取projects/根下的第一级目录名作为 project id；同时过滤掉node_modules、.git、__pycache__、.cache这些对看板无意义的噪声路径。
• ChangeHub 扇出：ChangeHub维护订阅者队列与订阅时绑定的 project id（None表示订阅全部项目）。publish(project_id)只把通知投递给匹配的订阅者；每个队列maxsize=64，队列满时直接丢弃——因为队列里只装"这个订阅者真正关心的事件"，满了也意味着必然有一次待消费的唤醒，安全可丢。
• SSE 端点：/api/project/{project_id}/events与/api/library/events分别面向单个项目看板与库视图。两者都先发送{"type":"hello"}握手消息，之后每 15 秒发送一次heartbeat（SSE_HEARTBEAT_SECONDS = 15）以维持连接；收到变更后先排空队列里积压的所有通知（coalesce bursts），再发送一条{"type":"change"}，让浏览器只做一次重拉取——渲染高峰期一次变更批次可能包含成千上万个文件路径，这种合并至关重要。
• 库视图缓存：_cached_summaries()对每个项目的摘要做缓存（全量解析成本高），由 watcher 在对应项目变更时通过_invalidate_summary()失效。

另外值得一提的是响应头：SSE 流设置了Cache-Control: no-cache与X-Accel-Buffering: no，确保 Nginx 等反代不会缓冲事件流；而 UI 页面与/ui/*静态资源则通过一个 HTTP 中间件统一加no-cache，让 UI 修复在普通刷新下即可生效（媒体与缩略图保持常规缓存）。

四、状态从哪来：磁盘文件即状态源

README 中给出了一张"看板元素 ↔ 磁盘来源"的对应表，这是理解 Backlot 的关键，完整列出如下：

下面结合源码逐一深入。

4.1 项目身份与轨道顺序：project.json+ 流水线清单

init_project()（见 lib/checkpoint.py）在创建项目时会写入标准的目录骨架（artifacts/、assets/images|video|audio|music/、renders/）和project.json标记文件，其中记录project_id、title、pipeline_type、style_playbook与created_at，且幂等（重复执行保留原created_at并合并字段）。

load_board_state()（见 backlot/state.py）读取该标记，再通过_load_pipeline_meta()调用 lib/pipeline_loader.py 加载pipeline_defs/<type>.yaml清单，得到每个阶段的名称、门禁标记（human_approval_default）与产出物列表。若清单加载失败，则回退到内置的FALLBACK_STAGES：research → proposal → idea → script → scene_plan → assets → edit → compose → publish。

4.2 阶段状态、门禁与版本：checkpoint_<stage>.json+history/

每个阶段的状态以checkpoint_<stage>.json形式存在于项目根目录，由write_checkpoint()原子写入（先写临时文件再os.replace，防止写一半留下损坏状态）。看板端_collect_checkpoints()扫描所有checkpoint_*.json得到当前状态，_collect_history()则扫描history/checkpoint_*.json得到归档的历史版本。

由此_build_stage_rail()为每个阶段生成轨道条目，包含：

• status：pending/in_progress/awaiting_human/completed/failed；
• gated与human_approved：是否要求人工审批、是否已批准；
• versions：history归档数 + 当前检查点数，前端据此显示v2之类的版本徽标；
• history_entries：按时间排列的状态轨迹（历史 + 当前），这是回放功能的原料；
• gate_skipped：门禁审计——若某个 gated 阶段状态为completed，但历史与当前中从未出现过awaiting_human且没有human_approved，则判定该门禁被跳过，前端会亮出 "⚑ GATE SKIPPED" 徽标。门禁本身在写入端即被 lib/checkpoint.py 强制执行（GATE VIOLATION会直接拒绝写completed），看板端则负责把历史遗留或手工写入的违规暴露出来。

对于清单未声明的"外来"检查点（如旧运行或流水线类型不匹配），轨道依然会为其分配位置——按FALLBACK_STAGES的规范顺序插入（"idea" 应该排在前列而不是吊在 publish 之后），并打上undeclared标记供前端区分。

4.3 剧本卡片：artifacts/script.json

看板的剧本卡片（script card）直接渲染artifacts/script.json：标题、总时长、sections 列表（含起止时间、对白文本text、speaker_directions舞台指示与enhancement_cues增强提示）。前端 board.js 会根据 script 阶段的检查点状态显示 APPROVED / PENDING APPROVAL / DRAFTING 徽标，点击卡片可展开完整剧本弹窗。

4.4 胶片条：scene_plan × script × asset_manifest三表联结

这是 Backlot 最核心的"故事板"逻辑，实现在_build_storyboard()中：

1. 以scene_plan.json的scenes列表为主干，为每个场景生成一张卡片；
2. 场景 ↔ 剧本段落联结（_find_script_section）：优先按script_section_id精确匹配；无该字段时回退到时间窗口重叠最大的启发式匹配——把场景的[start_seconds, end_seconds]与每个剧本 section 的时间窗做交集，取重叠最大者，从而把旁白文本与场景卡片关联起来；
3. 场景 ↔ 素材联结：_asset_entry()将asset_manifest.json中每个 asset 归入其scene_id名下，并按扩展名推断类型（image / video / audio 等）；_resolve_asset_path()兼容三种真实世界路径写法：项目相对路径（assets/images/x.png）、仓库相对路径（projects/<id>/assets/images/x.png）和绝对路径；
4. 可渲染性判定：renderable = exists and ext in (image/video 扩展名)。像 atelier/动画这种指向.tsx合成文件的资产虽然存在于磁盘，但无法缩略图化，会从"takes"中剔除，看板退而显示该场景的逐场景快照（snapshots/<scene_id>.png，见_find_scene_snapshot()）；而文件缺失的栅格/视频资产则保留为 "file missing" 指示；
5. 生成中状态：根据events.jsonl中每个场景最近一次顶层事件推断——start标记为 "generating"，finish/error清除该状态；嵌套（depth>0）的 provider 事件被跳过，因为外层调用的 finish 才是真正完成。前端据此在卡片上显示"生成中"微光与产生该素材的工具名（generating_tool）。

每张场景卡片还携带duration_seconds、hero_moment（高光时刻）、shot_language、shot_intent、framing、movement等镜头语言信息，以及takes（可渲染素材列表）、audio（旁白/音乐/音效列表）。

4.5 活动流：events.jsonl

events.jsonl是只追加的工具事件日志，由 lib/events.py 提供读写能力：

• emit_event()将一条事件（ts+ 工具名、事件类型、场景 id、耗时、花费等）追加到项目目录的events.jsonl，永远不抛异常——可观测性绝不能中断生产；
• infer_project_dir()从工具调用的入参推断归属项目：显式的project_dir/project_path优先，其次在一组路径提示键（output_path、video_path、image_path等）中查找；只有解析到projects/根之下的路径才归属，归属失败就静默不写（"never guess loudly, never fail"）；
• read_events()读取时跳过损坏行（如跨进程追加撕裂的半行），看板端只取最近 250 条。

在 lib/checkpoint.py 的注释与 scripts/backlot_simulate_run.py 的用法中可以看到，工具事件由BaseTool插桩层在工具执行时写入，它同时驱动"生成中微光"与整块活动时间线。

4.6 花费表：检查点cost_snapshot

看板取最新检查点携带的cost_snapshot（按 mtime 排序取最后一个有快照的）；若没有，则回退到asset_manifest.json的total_cost_usd。前端把total_spent_usd与budget_remaining_usd相加得到总预算，渲染出花费数字与进度条（超过 75% 转黄、超过 90% 转红）。

4.7 渲染结果：renders/*.mp4与根目录启发式

_scan_media()扫描renders/目录下的视频文件，外加两个启发式：项目根目录的*.mp4（atelier 交付物惯例）与*.mp3，以及assets/music/与snapshots/、verify/目录下的图片。所有渲染结果按 mtime 倒序排列。此外_find_poster()为库视图挑选最佳封面：优先故事板卡片的图片视觉，其次快照，再按assets/images → assets/frames → exports → assets → .的顺序找图，最后兜底用最新渲染（由/thumb端点抽帧）。

五、媒体服务：缩略图与安全边界

server.py 提供两条媒体端点：

• /media/{project_id}/{file_path:path}：直接以FileResponse返回项目内文件（支持 Range 请求，便于视频拖动播放）；
• /thumb/{project_id}/{file_path:path}：缩略图端点，宽度从(320, 640, 960)三档中就近取整。图片用 PIL 缩放后存 JPEG（quality=82），视频则调用ffmpeg在1.5 秒处抽取一帧作为海报（-ss 1.5 -frames:v 1），再缩到目标宽度。缩略图以sha1(路径|mtime|size|宽度)为键缓存到.backlot/thumbs/，并发未命中时用临时文件隔离写入。对无法抽帧的视频，宁可返回 404 也绝不把原始视频字节喂给<img>消费者（源码注释中的 F-03）。

两条端点都用_safe_project_dir()校验 project id（拒绝含/ \ :的 id 与.、..），并对解析后的目标路径做relative_to检查，防止路径逃逸出项目目录（越界即 403）。

六、看板呈现：阶段轨道、剧本、胶片条与回放

前端是纯原生 JS 的单页应用（board.js + board.css），核心渲染逻辑包括：

• 头部状态条（slate）：流水线类型、场景数/总时长、风格书（style playbook）三个 chip，以及一个活动指示器——有awaiting_human阶段时显示 "◈ AWAITING YOU"，有停滞阶段显示红色 "⚠ STALLED?"，运行中显示 "LIVE"，否则显示 "IDLE · 距上次活动时间"；旁边是花费条。
• 阶段轨道（rail）：每个阶段一个节点，按状态着色（done / active / await / failed），图标与副标题随状态变化（如in_progress且有partial_progress.completed_scene_ids时显示"N scenes done"）。点击节点打开抽屉（drawer），展示该阶段的评审指标（critical / suggestions / nitpicks）、评审摘要与规范产物（如 compose 阶段对应render_report、final_review），未运行的阶段显示 "This stage hasn't run yet."。
• 剧本卡片与胶片条：如前所述，四段折叠展示剧本、按场景渲染胶片条卡片，每张卡片显示时间码、镜头语言、旁白与已生成的 takes。
• 回放（Replay）：README 指出已完成的生产可以从头到尾擦洗（scrub）观看（看板上的 ▶ REPLAY RUN），状态由检查点历史与事件时间戳重建。前端replay = {t0, t1, t, playing}即回放模式的运行状态，回放数据源正是_build_stage_rail()产出的history_entries（按时间排列的阶段状态轨迹）与events.jsonl的时间戳——把两者按时间轴推进，即可重演整条生产线的"点亮过程"。

库视图（index.html + library.js）则是一个项目卡片网格，每张卡片显示标题、流水线类型、封面（poster）、live 状态、活动时间、当前活动阶段、是否在等待人工、完成阶段数、渲染数与场景数。

七、没有真实生产也能体验：模拟运行

README 提供了一条不用跑真实流水线就能体验看板的路：

python scripts/backlot_simulate_run.py # 实时演示运行（约 1 分钟） python -m backlot open backlot-demo-run

scripts/backlot_simulate_run.py 会驱动一个虚构的 "The Last Lighthouse" 电影生产，走完整套真实契约：init_project初始化、write_checkpoint写各阶段检查点（包括awaiting_human门禁、human_approved批准、partial_progress与cost_snapshot）、emit_event写入按场景的工具事件、逐步追加asset_manifest并生成占位图片，让看板真正"活"起来。脚本还支持--fast（压缩等待到约 0.3s，供自动化验证）与--cleanup（结束时清理项目目录）两个参数。

八、优雅降级与健壮性设计

README 明确了两层降级：

1. 无检查点的项目：退化为"watcher 发现了什么就显示什么"的视图——媒体、快照、渲染结果仍然可见。看板端 state.py 的模块注释总结了设计原则："never block, never break"——畸形的 JSON、缺失的产物、写了一半的检查点都只能让看板降级，绝不能让它崩溃。load_board_state()与list_projects()都永不抛异常，解析失败统一返回带error字段的占位摘要。
2. watcher 不可用：_watch_projects()在ImportError（未安装 watchfiles）时直接返回，看板退化为手动刷新（README 与 server.py 均注明这一点）。

健壮性细节还包括：_read_json()以errors="replace"读取并捕获一切异常；事件读取跳过损坏行；检查点in_progress心跳不会进入history/（它不是版本，只是进度心跳，见_archive_superseded_checkpoint()）；停滞检测（state.py 的 F-05 注释）——一个in_progress阶段若超过STALL_WINDOW_SECONDS（10 分钟）没有文件系统活动，会被标记stalled并在前端显式警告，让"卡死的 Agent"可见而非沉默；LIVE_WINDOW_SECONDS（5 分钟）则决定看板读作 "live" 还是 "idle"。

九、测试保障

tests/backlot/目录为该模块提供了成体系的测试覆盖：test_server.py（服务端 API 与 SSE）、test_state.py（状态推导）、test_gate_scenarios.py（门禁场景）、test_ui_bug_bash.py（UI 冒烟）、test_visual_eval.py（视觉评估）与 test_watch_captures.py（watcher 捕获）。从 scripts/backlot_simulate_run.py 可以看到，模拟运行脚本还复用了tests/contracts/test_phase0_contracts.py中的 schema 合法测试夹具来构造产物，说明看板测试与契约测试共享同一套数据契约。

十、总结

Backlot 的价值在于它把"可观测性"的成本降到了极致：不需要 Agent 额外上报、不需要数据库、不需要独立的前后端构建——流水线本来就要写的检查点、产物、事件日志就是全部数据源，一个 watcher 加一组只读 API 就把它变成了实时演进的制片看板。它既是 Agent 与人之间的"交接窗口"（awaiting_human门禁的呈现处），也是事后审计与回放的基础。对想要在自己的流水线系统里构建类似"磁盘即状态、文件变更即事件"式可观测层的开发者，backlot/server.py 的 SSE 扇出设计、backlot/state.py 的多源联结与降级策略，都是可以直接借鉴的范本。

【免费下载链接】OpenMontageWorld's 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