开发者在做设计类 agent 产品时，很容易把宿主软件里的当前画面当成系统状态。SketchUp 已经画出来了，为什么还要维护一个 design_model.json？

答案是：SketchUp scene 是 live execution view，不是适合 agent 长期推理、验证、修复和回放的项目真相。

对 SAH 来说，design_model.json 不是一个导出缓存，而是设计项目的 editable truth。它需要站在 SketchUp scene 前面。

Live scene 不擅长回答工程问题

SketchUp scene 可以展示模型，但它不天然回答这些问题：

  • 哪些对象来自导入图纸，哪些对象来自手工编辑？
  • 某个组件的尺寸、anchor、clearance、来源和授权信息在哪里？
  • 当前模型能不能重新生成同样的 bridge trace？
  • 某次 visual feedback 应该修改哪个空间、墙、组件、规则或材质？
  • 哪些 entity 是上一轮 replay 生成的，哪些已经过时？
  • 如果要比较两个设计版本，应比较像素、scene 文件，还是结构化事实？

这些问题不是展示问题，而是状态管理问题。Agent 需要可读、可校验、可 diff、可 patch 的状态，而不是只看宿主软件当前画面。

Project truth 的文件边界

SAH 的设计项目目录把工作状态拆成几类文件：

  • design_model.json：空间、墙、开口、组件、灯光、语义 anchors、执行 metadata；
  • design_rules.json：项目规则、偏好和约束；
  • component_library.json：项目局部组件语义；
  • assets.lock.json：项目实际引用的组件资产；
  • imports/：导入 source、manifest、evidence、extracted interpretation；
  • snapshots/manifest.json：截图、渲染和 visual feedback 的 provenance；
  • versions/：结构化 truth 的版本快照。

这些文件共同构成 agent 的 operating surface。SketchUp scene 是其中一个执行产物，而不是唯一状态。

为什么 structured truth 更适合 agent

Agent 最需要的不是“看见一个模型”，而是知道能安全改变什么。

design_model.json 让 agent 能够：

  • 用 MCP tool 读取 project state；
  • 校验当前 truth 能否生成完整 execution trace；
  • 明确某个 object 的 provenance；
  • 用结构化方式添加、移动、删除组件；
  • 保存和比较版本；
  • 把 bridge 返回的 entity ids 写回对应对象；
  • 在 visual feedback 被接受后执行结构化修改。

如果这些信息只存在 SketchUp scene 里，agent 就会被迫从几何结果反推设计意图。这通常不可靠。

Snapshots 和 renders 也是 artifact

视觉产物有价值，但它们应该被记录为 review artifact。

SAH 的 visual loop 里，snapshot、render 和 visual feedback 都进入 snapshots/manifest.json，并带上 provenance。它们可以指导设计判断，但不直接替代 design_model.json。

如果用户接受一条视觉建议，agent 应该把它转换成结构化动作：组件变更、灯光变更、材质变更、规则变更、note，或者由专门几何工具执行的模型变更。

这里的关键是：像素不能直接成为几何真相。像素只能触发对 truth 的修改。

Execution metadata 也属于 truth

当 Ruby bridge 执行成功后，返回的 entity ids、operation status、spatial delta 和 operation id 不应该只停留在日志里。

它们需要回到 design_model.json。

这样下一轮 agent 才知道：

  • 哪个 component instance 对应 SketchUp 里的哪个 entity；
  • 哪个 wall side 已经执行；
  • 哪些 hosted openings 已经生成过；
  • 当前 replay 的 bridge operations 是什么；
  • 哪些旧 execution metadata 应该被替换。

如果不把 execution feedback 写回 truth，后续修改就会依赖猜测。Agent 可能重复创建对象，或者操作已经过时的 entity。

Versions 应该比较结构化事实

设计项目会反复修改。版本比较如果只靠 scene 文件或截图，很难告诉开发者具体变化是什么。

结构化 truth 可以比较 spaces、walls、openings、component instances、rules、assets 和 visual artifacts。这类 diff 才适合 agent 解释、回滚和生成下一步操作。

Git 可以管理文件历史，但 domain-level comparison 仍需要基于 design_model.json 这类结构化模型。

这不是把 SketchUp 降级

把 design_model.json 放在前面，不是说 SketchUp 不重要。SketchUp 是专业建模和视觉执行环境。它负责让设计师看到、检查和继续操作真实模型。

但对 agent harness 来说，SketchUp 最适合做 live execution view。它不应该独自承担 project truth、source evidence、runtime memory、version comparison 和 repair planning。

更健康的分工是：

design_model.json owns editable truth
MCP server owns tools, validation, planning
Ruby bridge owns host execution
SketchUp scene owns live visual result
snapshots and renders own review artifacts

如果你要做一个可维护的设计 agent 产品，这个分工比“模型终于画出来了”更重要。

Source trace