Codex 如何驱动 SketchUp 建模：从指令到可验证模型

这篇不是操作教程。

我还不想在 demo 路径完全验证之前，把它包装成“照着做就能跑”的步骤文。更准确地说，它是一篇架构 walkthrough：解释 Codex 或其他 agent CLI 为什么不应该直接“魔法式控制 SketchUp”，而应该通过一组可验证的中间层，把自然语言意图转成可检查、可执行、可修复的项目状态。

以 SketchUp Agent Harness 为例，Claude 和 Codex 都只是入口。真正重要的是中间的结构：

agent CLI
-> runtime skills
-> MCP server
-> structured design model
-> SketchUp Ruby bridge
-> SketchUp scene

这条链路决定了 agent 是在“生成一次结果”，还是在“维护一个设计项目”。

为什么不能让 Codex 直接操作 SketchUp

最直觉的做法是：让 Codex 理解用户的话，然后直接调用 SketchUp。

这个想法很诱人，但会有几个问题。

第一，软件操作太容易变成黑箱。Codex 做了什么、为什么这么做、哪些对象被创建、哪些尺寸来自哪里，如果没有结构化记录，很难追踪。

第二，设计状态会散落在多个地方。部分在聊天里，部分在 SketchUp scene 里，部分在临时脚本里，部分在用户脑子里。下一次继续工作时，agent 很难知道项目真实状态。

第三，错误难以修复。如果结果看起来不对，agent 可能只能在当前场景上补丁式修改，而不是回到来源证据和结构化模型里修正根因。

所以，Codex 不应该直接成为 SketchUp 的手。它更应该成为一个理解意图、调用工具、检查结果、推动修复的 agent 入口。

真正稳定的执行能力应该在工具层和项目状态层。

第一层：agent CLI 理解意图

用户首先表达的是自然语言意图。

例如：

“创建一个 2 米 x 1.8 米的卫生间，包含马桶、洗手台、门、镜子、基础照明，并检查通行距离。”

Codex 的价值不在于把这句话直接变成某段一次性脚本，而在于理解这个请求包含哪些设计动作：

创建空间
设置尺寸和单位
放置组件
应用基础规则
检查清距
生成可执行计划
最后把结果推进到 SketchUp

这里的 Codex 是入口和协调者，不是唯一真相源。

第二层：runtime skills 提供设计任务语境

只理解自然语言还不够。

一个通用 agent 可能知道“卫生间”是什么，但它不一定知道这个产品里如何表达空间、如何登记组件、如何处理设计规则、什么时候应该验证布局、什么时候不该把一次项目里的修正写成全局规则。

这就是 runtime skills 的作用。

在 SketchUp Agent Harness 这样的系统里，runtime skills 应该服务设计任务本身，而不是服务产品维护者。它们可以告诉 agent：

如何创建或打开设计项目
如何处理空间规划
如何导入平面图
如何搜索和放置组件
如何应用设计规则
如何记录视觉反馈
如何把反馈转成结构化修复

这些 skills 不应该混入发布流程、测试流程或维护者内部开发规则。设计师运行时需要的是设计任务能力，不是产品工程上下文。

第三层：MCP server 负责稳定工具边界

如果说 Codex 是入口，runtime skills 是任务语境，那么 MCP server 就是稳定的工具边界。

它应该负责几类事情：

读取项目状态
更新结构化模型
执行验证
生成执行计划
暴露清晰工具接口
把 agent 请求转成产品可控的操作

这层很重要，因为它把“模型会话里的意图”变成了“产品可审计的工具调用”。

没有这层，agent 很容易直接生成脚本、直接修改文件、直接操作软件。短期看很灵活，长期看很难维护。

有了这层，Codex 可以变，Claude 可以变，未来的 agent CLI 也可以变，但中间的项目协议和执行模型保持稳定。

第四层：结构化模型承载项目真相

SketchUp Agent Harness 的核心不是某个聊天入口，而是结构化设计模型。

在这个项目里，design_model.json 承载的是设计项目的工作真相：

空间
尺寸
组件
规则
假设
来源证据
执行计划
后续修复线索

这一步决定了系统是否可靠。

如果没有结构化模型，Codex 可能可以生成一个看起来正确的 SketchUp 场景，但下一次很难稳定继续。

有了结构化模型，系统可以做更多事情：

diff
validation
replay
repair
version compare
source-backed correction

SketchUp scene 是执行结果，design_model.json 才是 agent 可以持续理解的项目状态。

第五层：Ruby bridge 执行到 SketchUp

最终，设计还是要进入 SketchUp。

Ruby bridge 的作用，是把结构化操作发送到 SketchUp，而不是让 agent 直接把所有软件细节塞进对话。

这层应该尽量稳定、可诊断、可失败。

一个好的 bridge 不只是“能创建对象”，还应该能在阻塞时告诉上层发生了什么。例如 SketchUp 没有打开到模型窗口、bridge 没有安装、执行被软件状态阻塞、返回结构不符合预期等。

这类结构化错误很重要。它让 agent 不用猜，也不会把软件状态问题误判成设计问题。

第六层：视觉审阅回到结构化修复

执行到 SketchUp 以后，还需要审阅。

截图、俯视图和渲染图能暴露很多问题：墙体错位、空间方向错误、开口缺失、组件比例不对、材质或灯光不符合意图。

但视觉审阅不能停在“这张图看起来不对”。

如果设计师接受了一个视觉反馈，系统应该把它变成结构化修复：

更新模型 diff
修正来源证据
添加验证规则
记录组件或材料变更
保存项目局部记忆
再次执行或回放

这就是闭环。

Codex 不是只负责生成第一版结果，而是参与发现问题、解释问题、调用工具修复问题。

一个完整链路应该长什么样

抽象来看，一次自然语言建模可以拆成这样：

1. 用户表达设计意图
2. Codex 根据 runtime skills 判断任务类型
3. MCP server 读取或创建项目状态
4. 结构化模型记录空间、规则、组件和假设
5. validator 检查尺寸、清距或结构问题
6. execution plan 转成 SketchUp bridge 操作
7. Ruby bridge 在 SketchUp 中执行
8. 截图或视图成为 review artifact
9. 设计师反馈被写回结构化模型
10. 系统重新验证、修复或回放

这条链路看起来比“输入一句话，生成模型”复杂。

但它解决的是长期可靠性：项目能继续、错误能定位、设计师反馈能追踪、模型能回放。

为什么这不是 Codex 专属架构

这套架构里，Codex 不是唯一核心。

Claude、Codex、未来其他 agent CLI，都可以作为入口。真正应该保持稳定的是：

runtime skills
MCP tool layer
design model schema
SketchUp bridge
protocol docs
validation loop

这意味着 agent 入口可以更换，但产品的项目状态和执行边界不必重写。

这也避免了把某个模型产品的习惯写死到核心系统里。Claude-specific 和 Codex-specific 逻辑应该尽量留在适配层，而不是进入 MCP server 和结构化模型。

当前还不能夸大的地方

也要明确边界。

SketchUp Agent Harness 仍是 early-development open-source project，不应该被包装成成熟的商业设计平台。

当前能讨论的是架构方向和已经形成的产品边界：自然语言入口、MCP server、Ruby bridge、结构化模型、runtime skills、协议和验证思路。

如果要把这篇变成真正的教程，还需要一条经过验证的 public-safe demo path：用公开安全的输入，完整跑通从自然语言目标到 SketchUp 执行、审阅和修复的过程。

在那之前，这篇文章只讨论架构，不承诺读者照着步骤一定能复现。

结论

Codex 驱动 SketchUp 建模，关键不在于让 Codex 直接控制软件。

关键在于中间层。

自然语言只是入口，SketchUp scene 只是执行结果。真正让系统可持续的是 runtime skills、MCP server、结构化设计模型、Ruby bridge 和视觉审阅闭环。

如果没有这些层，AI 建模很容易变成一次性输出。

如果这些层成立，agent 才可能从“帮我画一个东西”走向“帮我维护一个设计项目”。