如果只从用户界面看，SketchUp Agent Harness 很容易被理解成“用 Codex 或 Claude 控制 SketchUp”。这个说法没有错，但它对开发者来说太粗了。

更准确的理解是：Codex 和 Claude 只是入口。真正值得讨论的，是中间那套把自然语言、项目状态、工具调用、几何操作、验证结果和 SketchUp 执行连接起来的 harness。

这也是这个项目的核心架构判断：

agent CLI
-> product runtime skills
-> MCP server
-> project workspace / design_model.json
-> bridge execution trace
-> SketchUp Ruby bridge
-> SketchUp scene
-> execution feedback
-> design_model.json

如果你在做一个本地 agent 产品，尤其是要控制专业桌面软件、CAD、建模软件、设计软件或其他宿主应用，这条链路比“模型会不会写 prompt”更重要。

Agent CLI 不应该成为产品核心

SAH 支持 Claude，也支持 Codex。未来如果要支持其他 agent CLI，理想状态也不应该重写产品核心。

原因很直接：不同 CLI 的插件机制、项目规则、skill 目录、会话体验和权限模型都会变，但它们不应该改变一个 SketchUp 模型如何被描述、验证、执行和修复。

所以 SAH 的可复用核心不是某个 CLI，而是：

  • MCP server
  • SketchUp Ruby bridge
  • design_model.json schema
  • component metadata
  • runtime skills
  • project workspace convention
  • protocol and spatial rules

CLI-specific 部分应该是 adapter。它负责把当前 agent 工具接到同一套核心能力上，而不是把产品逻辑写进 Claude-only 或 Codex-only 的路径里。

这个边界对开发者很重要。否则产品一旦从一个 agent CLI 扩展到另一个，就会变成多套行为、多套文档、多套测试和多套运行时分支。

为什么需要 project workspace

一个容易犯的错误，是把产品源码仓库当成用户工作区。

对设计师来说，正常使用 SAH 不应该是 clone 产品 repo、打开源码目录、修改内部文件。更合理的工作面是一个干净的设计项目目录。

这个项目目录承载当前设计任务的事实：

  • design_model.json
  • design_rules.json
  • component_library.json
  • assets.lock.json
  • imports/
  • snapshots/
  • project-local runtime skills
  • model.skp

产品安装在外部，产品 repo 维护 MCP server、Ruby bridge、runtime skill authoring、spec、tests 和 release artifacts。用户项目目录维护当前设计的 working truth、规则、证据、资产和审阅产物。

这个分离不是目录洁癖。它决定了 agent 到底应该读取什么事实。

如果 agent 默认站在产品源码仓库里，它看到的是维护者上下文。如果 agent 默认站在设计项目目录里，它看到的是当前设计上下文。对本地 agent harness 来说，这两者必须分开。

为什么 SketchUp scene 不是真相源

SketchUp 是 live execution view。它很重要，但它不适合作为 agent 的唯一真相源。

原因是 live scene 很难直接回答这些问题：

  • 这个墙体来自用户手工创建、导入图纸，还是某次 agent replay？
  • 这个组件的尺寸、anchor、clearance 和 license 信息在哪里？
  • 当前模型能否从结构化状态重新执行？
  • 如果视觉审阅发现问题，应该改哪条结构化事实？
  • 如果某次执行失败，哪些操作成功，哪些操作被跳过？

所以 SAH 把 design_model.json 放在 SketchUp scene 前面。结构化模型记录 spaces、walls、openings、components、rules、assumptions、imports、execution metadata 和版本信息。SketchUp scene 是这个 truth 的执行结果，而不是唯一事实。

这让 agent 可以做几件更工程化的事情：

  • 在不打开 SketchUp 时检查项目状态；
  • 从同一个 truth 生成可测试的 execution trace；
  • 把 bridge 返回的 entity ids 和 operation metadata 写回 truth；
  • 用结构化 diff、validation 和 repair 处理变化；
  • 在需要时 clean replay，而不是不断叠加旧几何。

MCP server 的职责

MCP server 是这个架构里的共享执行层。它不应该只是把自然语言原样转发给 SketchUp。

它至少承担这些职责：

  • 读取和校验 project workspace；
  • 暴露 agent 可调用的工具；
  • 合并设计规则和项目状态；
  • 生成 bridge execution trace；
  • 在没有 live SketchUp 时进行 headless planning；
  • 在 live bridge 可用时执行项目模型；
  • 将执行反馈写回结构化 truth。

这也是为什么 SAH 的架构不是“LLM 直接操作 SketchUp UI”。专业软件的状态太复杂，不能把所有责任交给一次 prompt。中间层必须把意图变成可检查的项目状态和操作计划。

Ruby bridge 的职责

Ruby bridge 的职责应该更窄：在 SketchUp 侧执行结构化操作，并返回结构化结果。

它不应该承担产品级推理，也不应该理解不同 agent CLI 的差异。它应该关心的是：

  • 当前 SketchUp 是否可执行；
  • 操作 payload 是否有效；
  • 几何是否创建成功；
  • 失败是否能定位到 operation；
  • 是否需要 rollback；
  • 返回哪些 entity ids、spatial delta 和 model revision。

这个分层让 Python MCP server 和 Ruby bridge 之间形成稳定协议边界。对开发者来说，这比“让模型直接写 Ruby 脚本”更可维护。

Runtime skills 是产品表面，不是维护者笔记

SAH 还有一个容易混淆的点：skills。

产品 runtime skills 位于产品的 skills/ authoring source 中，但它们最终应该通过 Claude、Codex 或未来 agent CLI 支持的机制安装到用户可加载的位置。它们是设计师工作流的一部分，比如空间规划、组件搜索、语义定位、导入图纸、视觉反馈和布局验证。

这和维护者在开发过程中使用的 Codex skills 不是一回事。

维护者 skills 服务产品开发。产品 runtime skills 服务设计师使用。项目或会话中动态生成的 runtime skills 服务某个具体设计项目，例如一次图纸导入的符号解释、用户纠正或项目偏好。

这三层混在一起，会导致两个问题：

  • 维护者实现细节泄露到用户运行时；
  • 某个项目的局部记忆被误当成产品通用规则。

所以开发者要把 skill 当成产品架构的一部分，而不是 prompt 文件夹。

验证策略：不要只相信 live demo

如果一个 agent harness 控制的是 SketchUp 这类桌面软件，live demo 很重要，但它不应该是唯一验证方式。

更稳的策略是分层验证：

  • source checkout 下的 unit 和 contract checks；
  • 不打开 SketchUp 的 project initialization、state、validation 和 trace planning；
  • bridge install dry run；
  • live bridge integration；
  • release smoke；
  • installed package smoke。

这背后的判断是：用户不会在维护者源码路径里使用产品。用户会安装 harness、安装 bridge、创建项目目录，再从自己的项目中启动 agent CLI。

所以 source checkout 通过，不等于真实安装可用。runtime skills、bridge files、plugin manifests、templates 和 CLI entry points 都可能在 packaging 边界上出问题。

这个架构模式可以复用到哪里

SAH 的具体宿主应用是 SketchUp，但这个模式不只属于 SketchUp。

任何本地 agent 产品，只要要控制一个复杂宿主软件，都可能需要类似分层：

  • agent CLI 是入口；
  • runtime skills 给 agent 领域工作流；
  • MCP server 或类似工具层暴露可调用能力；
  • project workspace 保存当前任务事实；
  • structured model 保存可编辑 truth；
  • execution trace 连接 truth 和 host app；
  • bridge 执行宿主软件操作；
  • visual or live output 只是执行和审阅产物；
  • verification 覆盖 headless、live 和 installed package。

这就是为什么我认为“agent CLI 只是入口”是 SAH 技术架构系列的第一篇。开发者真正需要理解的，不是 Codex 或 Claude 哪个更会聊天，而是如何把一个专业软件变成可验证、可执行、可修复的 agent harness。

Source trace