很多 agent demo 的叙事是：用户一句话，软件立刻动起来。

这个叙事适合演示，但不适合架构。对一个要长期维护的本地 agent harness 来说，更可靠的路径是先生成 Bridge Trace，再调用 SketchUp。

Bridge Trace 是 live execution 之前的显式操作计划。它让系统先回答“我准备做什么”，再去执行“我已经做了什么”。

Trace 是 planning 和 execution 的分界线

SAH 的 plan_project_execution 会从当前 design_model.json 生成项目级 bridge trace。这个动作不需要打开 SketchUp。

Trace 可以包含：空间边界生成墙体操作，explicit walls 和 hosted openings 生成带开口的 wall operations，component instances 生成 placement operations，lighting 生成 component placement 或 fallback，以及最后的 scene info 查询。

这一步的价值不是“提前算一遍”。它是把 project truth 编译成宿主应用可执行的中间表示。

有了这个中间表示，系统可以在 live SketchUp 之前检查：

  • 有没有对象无法转换成 operation；
  • 每个 operation 是否有稳定 id；
  • payload 是否完整；
  • rollback 行为是否明确；
  • 是否需要 clean replay；
  • 这次执行是否应该拒绝 partial execution。

Headless planning 是开发者的朋友

如果每次验证都必须打开 SketchUp，开发速度会非常慢，CI 也会困难。

Bridge Trace 让很多问题可以 headless 检查：初始化项目是否能形成有效 truth，truth 是否能生成完整 execution trace，schema 变更是否破坏 trace generation，component metadata 是否足以生成 placement operation，imported wall/opening 是否能被重放。

Live SketchUp integration 仍然重要，但它不应该承担所有验证。更合理的策略是：大部分逻辑 headless，少量关键路径 live。

Partial execution 不能静默发生

如果一个项目里有 20 个对象，其中 3 个无法转换成 bridge operation，系统可以选择继续执行 17 个。

这在工程上看似宽容，但在设计工具里很危险。

用户看到的 scene 可能看起来“执行成功”，但实际漏了墙、灯、开口或组件。后续 screenshot、保存、视觉审阅都会基于错误结果。

所以 SAH 的方向是默认拒绝这种 silent partial execution。除非 agent 明确告诉设计师哪些对象被省略，并且有意继续，否则不应该把缺失 truth 伪装成成功模型。

这是产品质量边界，不是异常处理细节。

Clean replay 防止旧几何污染判断

重复执行是另一个常见问题。

如果每次执行都向 SketchUp 添加一批新对象，而不清理旧的 generated geometry，scene 会越来越脏。视觉上你看到的是叠加结果，不是当前 truth 的结果。

Bridge Trace 搭配 clean replay 可以缓解这个问题：先清理 harness 管理的层或对象，再根据当前 design_model.json 重放。对于 import replay，还可以扩大清理范围，并在执行后检查是否还有不应存在的 scene contamination。

这样才能保证 visual review 看的是当前 truth，而不是历史残留。

Operation id 是调试坐标

每个 operation 都需要稳定 id。

没有 operation id，失败只能描述为“SketchUp 执行失败”。有了 operation id，系统可以说清楚：哪个 placement 失败、哪面 wall 未生成、哪个 opening 的 host wall 不存在、哪个 component fallback 被使用、哪一步 rollback 失败。

对 agent 来说，这些信息可以转成下一步修复动作。对开发者来说，这些信息可以进入测试、日志和 regression。

Feedback 不是日志，是下一轮 truth

Bridge Trace 执行完后，返回结果不能只存在执行报告里。

如果成功，entity ids 和 operation metadata 要回写 design_model.json。如果失败，失败信息应该足够结构化，能定位到 operation 和 rollback 状态。

这让下一轮 agent 调用可以基于当前 truth 继续工作，而不是重新猜 SketchUp scene 的状态。

好的 agent harness 应该让 execution feedback 参与状态更新，而不是只把它当成 console output。

为什么这篇不写成 tutorial

Bridge Trace 是架构层概念，不是一个单独命令本身。具体命令和示例应该在产品 repo 验证后再写成 tutorial。

这篇文章先固定 developer mental model：live host execution 不应该是第一层可检查对象。trace 才是。

如果一个本地 agent 产品没有 trace 或类似中间表示，它的调试会很快进入黑箱：LLM 说了什么、tool 做了什么、host app 真实做了什么，很难分清。

Source trace