AI驱动SketchUp建模：用Ruby脚本实现一句话生成3D模型

很多人第一反应是“AI怎么操作SketchUp”我一开始也以为至少要装一堆插件或者用视觉识别去点按钮。结果折腾了一圈发现最顺的路子根本不是模拟鼠标而是让AI去写Ruby脚本再由命令行驱动SketchUp批处理执行——没错就是让AI直接当建模工程师用它出代码SU跑结果。这套方案我已经在OpenAI Codex、Claude Code上实测跑通了理论上所有能执行命令、能写文件的编程智能体都适用包括Workbuddy、OpenClaw这类Agent框架。这几天我搭了一套“一句话需求 → 自动生成SU模型”的工作流过程中踩了不少配置和脚本的坑正好整理成一篇完整笔记给想玩AI建模、AI辅助设计的朋友做个参考。1. 让Agent驱动SketchUp的整体思路1.1 为什么非要用Ruby API这条链路SketchUp给开发者留了三条自动化的路Ruby API、C/C SDK、UI自动化。很多人第一反应是“既然是AI就让它模拟人操作界面”这个想法看着直接实际用起来非常痛苦。UI自动化需要识别按钮位置、处理弹窗、等待加载SketchUp换个版本可能所有坐标全失效而且速度极慢做一个长方体要好几秒。C/C SDK是做真正的原生插件用的功能强但编译链太长需要装VS、配SDK、处理dll签名Agent很难自己在这个链路里闭环运作。你让Codex写完C代码它没法独自完成编译和环境配置这就不符合“智能体自主执行”的初衷了。剩下就是Ruby API。这是SketchUp开放能力最完整的接口画线、画面、推拉、成组、赋材质、导出格式全部覆盖。Ruby又是简单到几乎没有门槛的语言AI在大规模训练语料里见得多生成的代码质量足够高。更重要的是SU启动时可以直接加载Ruby脚本这意味着Agent写好的脚本可以被SU当成命令行工具一样调用整条链路由机器自动跑完不需要人介入。1.2 四种接入方式对比我为什么选批处理实际测试下来让Agent操作SU有四种常见方式各有适用场景方式原理优点缺点适合场景Ruby批处理脚本Agent写脚本SU启动时自动加载执行稳定可靠可重复执行易于记录每次要启动SU耗时较长日常主流方案Ruby Console粘贴用命令把脚本打进SU控制台实时反馈依赖SU界面已打开自动化难手动调试TCPServer常驻服务SU启动后监听本地端口Agent远程发指令响应快一次启动多次调用需要管理服务生命周期安全性要注意高频迭代建模原生C插件编译成SU插件调用性能最好链路复杂Agent难以闭环生产级工具链我日常用得最多的是第一种批处理脚本。它最稳也最符合Agent的工作模式写文件、执行命令、读结果每个步骤都能被记录和回放。第三种常驻服务在建模迭代特别频繁时很好用我在后面会专门写一段实现思路。1.3 整个闭环是怎么转起来的理解这条链路关键是看数据和指令怎么在Agent和SU之间流动。我把每一步都拆开Agent读入你的自然语言需求比如“生成一个3米乘2米、高1.5米的围墙东南角开一个1.2米宽的门洞”。Agent把需求转化为Ruby脚本写入工作区的脚本文件。Agent执行Shell命令启动SketchUp并指定加载这个脚本。SketchUp启动后按脚本内容建模执行完毕自动保存模型文件并输出一行执行结果。Agent读取结果输出判断是否达到需求没达到就修改脚本再执行一轮。这个循环跑起来之后你基本只需要在开头给需求、结尾验收模型中间全部让AI自己迭代。我实测下来最爽的时刻就是看到AI反复修改脚本、重跑SU、检查结果全程不用我碰建模界面那种感觉像是带了一个干活不需要休息的实习生。2. 环境准备与Agent权限配置2.1 安装和验证Codex CLICodex是OpenAI官方的编程智能体依赖Node.js环境安装方式很常规。装完之后第一件事是执行版本验证确认CLI已经正确进入PATH这一步很多人会忽略导致后面各种启动报错。npm install -g openai/codex codex --version如果系统提示找不到命令八成是npm的全局bin目录没加进PATH。Windows用户在PowerShell里查看npm全局路径macOS用户检查shell配置文件里的PATH设置补上之后重开终端就好了。Codex日常开发会话用的命令是codex直接启动交互模式。但我们要让它自动跑脚本更常用的是codex exec这种非交互执行方式Agent会读取你的任务描述然后自主规划、写代码、执行命令。后面实战案例里我会展示具体用法。2.2 配置config.toml模型、权限、工作目录Codex的配置文件在用户主目录下的.codex文件夹里Windows是C:\Users\你的用户名\.codex\config.tomlmacOS是~/.codex/config.toml。我第一次配的时候踩过一个大坑随便填了一个不存在的模型名结果Codex直接报“模型不支持”然后罢工。这个文件的模型名必须要和你账号实际支持的模型对上。# ~/.codex/config.toml model gpt-5.4-codex # 必须写账号支持的模型名 model_reasoning_effort medium sandbox_mode workspace-write [permissions] allow [ Bash(C:\\Program Files\\SketchUp\\SketchUp 2024\\SketchUp.exe *), Read(D:\\workspace\\**), Write(D:\\workspace\\**), ] deny []权限配置是整个方案安全性的核心。我的原则是“最小权限”只给Agent访问工作目录和SU可执行文件的权限不允许它随便读写整个磁盘。Read(D:\\workspace\\**)表示可以读取该目录下所有文件Write同理Bash里指定SU安装的完整路径这样Agent就只能启动SU不能乱执行系统命令。要特别注意config.toml的编码格式必须是无BOM的UTF-8用记事本另存为时选UTF-8别选带签名的版本否则Codex会直接报“无法加载config.toml”。这个报错我遇到过好几次刚开始以为是配置语法问题排查半天才发现是编码问题。2.3 Claude Code的权限文件与同类Agent的配置思路Claude CodeAnthropic官方CLI的配置方式和Codex大同小异配置文件是一个JSON格式的settings.json通常放在~/.claude/settings.json。核心的白名单配置逻辑完全一样{ permissions: { allow: [ Bash(C:\\Program Files\\SketchUp\\SketchUp 2024\\SketchUp.exe *), Read(D:\\workspace\\**), Write(D:\\workspace\\**) ], deny: [] } }这里有个经验Claude Code对路径中的反斜杠转义处理比较敏感Windows路径建议写成双反斜杠或者干脆正斜杠C:/Program Files/SketchUp/SketchUp 2024/SketchUp.exe实测更稳。至于Workbuddy、OpenClaw这类Agent框架思路也一样——它们本质上是“能写代码、能执行命令”的程序只要在它们的环境配置里开放脚本目录读写权限和SU调用权限就能走完全相同的链路。区别只是权限配置的界面和文件格式不同核心逻辑没变。2.4 联调验证让Agent跑一个最小模型配置完成之后不要急着上复杂需求先让Agent做一个最小验证生成一个边长500毫米的立方体并保存。这一步能同时验证CLI配置、权限白名单、SU批处理调用、Ruby脚本四段链路是否全部打通。我给Codex下的任务是“在D:/workspace/test/下写一个Ruby脚本创建500mm立方体并保存为cube.skp然后调用SketchUp执行”。如果一切正常终端会输出脚本执行成功的消息目标目录下出现cube.skp。看到这个文件说明整条链路已经通了后面就是加大需求复杂度的问题了。3. Ruby脚本驱动SU的核心细节3.1 必学API从画面到推拉到保存SketchUp的Ruby API逻辑和它的建模理念是一致的先在平面上画闭合图形再用推拉工具把它变成立体。核心API其实就那几个掌握了就能覆盖绝大多数建模需求Sketchup.active_model获取当前活动的模型对象一切操作的起点。entities.add_face(points)传入一组三维坐标点生成一个闭合面这是建模的最小单位。face.pushpull(distance)把平面推拉成体块类似你手动点推拉工具往上一拉。Geom::Point3d.new(x, y, z)定义三维坐标点注意SU里Z轴朝上。entities.add_group把多个实体打包成组相当于建群组方便整体移动和管理。face.material给面赋材质配合model.materials.add使用。model.save(path)和model.export(path)保存原文件或导出其他格式。一个最小的建模脚本长这样# build_mini.rb —— 最小可用示例 model Sketchup.active_model ents model.entities # 500mm x 500mm 的底面 pts [ Geom::Point3d.new(0, 0, 0), Geom::Point3d.new(500, 0, 0), Geom::Point3d.new(500, 500, 0), Geom::Point3d.new(0, 500, 0) ] face ents.add_face(pts) face.reverse! # 确保法线朝上 face.pushpull(500) # 向上拉伸500mm得到立方体 model.save(D:/workspace/test/cube.skp) puts SUCCESS entities#{ents.count}这个脚本我建议保存成模板后续让AI写复杂模型时固定结构不动只改坐标、尺寸和推拉高度Agent生成的代码出错的概率会小很多。3.2 单位、坐标系与法线方向三个大坑AI在生成SU脚本时犯的错翻来覆去就那几个但每一个都能让模型看起来莫名其妙。我把最重要的三个坑列出来这些都是我调脚本调出来的经验。第一是单位。SketchUp默认长度单位是英寸如果你脚本里没显式设置AI写一个“墙厚240”SU会当成240英寸——那是6米多直接变成一堵怪物墙。解决办法是在脚本开头统一设置单位。SU的UnitsOptions里LengthUnit有固定枚举值0是英寸1是英尺2是码4是毫米5是厘米6是米。国内项目一般用4毫米。model.options[UnitsOptions][LengthUnit] 4 # 强制毫米第二是法线方向。add_face出来的面方向取决于顶点顺序是顺时针还是逆时针。顺序不对面就是朝下的推拉出来的体块方向也会反。解决方式很简单AI生成的脚本里加一行判断或者直接无条件face.reverse!翻转法线。这种小操作对视觉模型无所谓但对后续要导入别的软件做渲染的场景很关键面朝向错乱会导致渲染阴影全反。第三是坐标基准。AI刚生成脚本时有个坏习惯——从原点附近开始建模倒也算了有时会把模型丢在离原点几千毫米开外的地方后面想对齐坐标就得到处摸黑找模型。我的做法是要求AI在脚本里固定一个ORIGIN Geom::Point3d.new(0, 0, 0)基准点所有坐标都基于这个点偏移模型永远规规矩矩落在原点附近。3.3 一套最小可靠模板直接抄作业为了让Agent输出的脚本更可控我把常用的初始化逻辑固定成一个模板让AI每次建模都基于这个骨架去扩展。模板里包含了单位设置、清空模型、基准点声明、结果输出能覆盖绝大多数基础建模场景。# ai_su_template.rb —— 智能体建模标准入口 model Sketchup.active_model ents model.entities # 1. 统一单位强制毫米 model.options[UnitsOptions][LengthUnit] 4 # 2. 清空当前内容注意这会删除已有模型 ents.clear! # 3. 固定基准点所有建模坐标基于此偏移 BASE Geom::Point3d.new(0, 0, 0) # 4. 把你的建模逻辑写进来AI生成部分 # 下面是一个示例实际由Agent按需求补充 def build_scene(ents, params) # 院子地面 pts [ BASE, Geom::Point3d.new(params[size][0], 0, 0), Geom::Point3d.new(params[size][0], params[size][1], 0), Geom::Point3d.new(0, params[size][1], 0) ] ground ents.add_face(pts) ground.reverse! ground.pushpull(-100) # 向下挖100mm做个下沉庭院 end params { size [6000, 4000] } build_scene(ents, params) # 5. 保存并输出统计结果 model.save(D:/workspace/output.skp) puts DONE entities#{ents.count}这个模板的妙处在于Agent不需要理解SU的初始化细节它只需要在build_scene方法体里填充建模逻辑然后修改params里的参数。固定结构让AI犯错的空间大大缩小输出质量和稳定性都高很多。3.4 进阶玩法让SU常驻监听Agent指令批处理模式有个明显的痛点每次调用都要完整启动一次SketchUp加载插件、初始化UI快则十几秒慢则半分钟。如果你要反复调整模型这个时间成本会非常烦人。解决思路是让SU启动后不退出而是变成一个常驻服务用Ruby的TCPServer开一个本地端口监听Agent发来的指令。Agent只需要向这个端口发一段Ruby代码SU收到后立即执行并返回结果。我测试下来单次指令响应能压到毫秒级迭代速度比批处理快了一个量级。# su_server.rb —— SU常驻服务本机专用勿对外开放 require socket require sketchup.rb model Sketchup.active_model server TCPServer.new(127.0.0.1, 45678) puts SU Agent Server listening on 45678 loop do client server.accept code client.gets begin # 注意eval适合自用调试生产环境请改成白名单动作分发 result eval(code) client.puts(OK: #{result}) rescue e client.puts(ERR: #{e.message}) ensure client.close end endAgent端只需向127.0.0.1:45678发送一段Ruby代码字符串就能实时操作SU。这个方案有几个要注意的地方只监听本机回环地址绝不能监听公网eval执行要谨慎自用调试没问题团队共享时需要改成白名单模式只放行我们预设的建模动作函数。4. 实战让AI自动生成一个庭院模型4.1 需求与首轮生成下面用一次完整的实战来展示整个流程。我给Codex的任务是“在D:/workspace/siteout目录下生成一个庭院模型场地10米乘6米围墙高2.4米、厚240毫米东南角开一个1.2米宽的门洞院内放一个4米乘2.5米的草坪西北角放一个2米乘1米乘0.9米的花池。使用毫米单位模型保存为site.skp。”使用Codex exec非交互模式执行codex exec 根据任务描述生成SketchUp Ruby脚本并执行建模任务见D:/workspace/siteout/task.mdCodex的第一步通常会先写一个脚本文件内容大致包括设置毫米单位、画场地底面、按墙厚和高度生成围墙、开门洞、放草坪和花池。这个过程它会自己查API、写代码我要做的就是等它执行完。4.2 执行与第一次反馈第一轮执行完成后SU输出一行执行结果DONE entities56模型成功保存。但我打开模型一看问题很明显围墙确实建了但门洞的宽度是600毫米而不是需求的1200毫米AI在开门洞时把尺寸算错了。此时不需要我手动去改我直接把问题反馈给Agent“门洞尺寸不对需求是1200毫米脚本里现在是600毫米请修正并重跑。”Agent会去检查自己的代码定位到门洞生成逻辑把参数修正后重新执行。这就是闭环迭代的价值。4.3 修正循环从脚本到模型的迭代第二轮执行之后门洞尺寸修对了。但新的问题又出现了花池的位置贴着围墙看起来像是长在墙里一样。这是因为AI生成花池时只把花池的中心点放在了西北角坐标没有考虑花池本身占用的尺寸范围导致有半个池子嵌进墙里。这次我没直接说怎么改而是给了个模糊指引“花池应该完全在围墙内侧与围墙保持至少200毫米间距。”Agent理解后重新计算了花池的坐标基准把x和y的起点都偏移了足够距离重新执行后模型就正常了。这个“需求→生成→检查→反馈→再生成”的循环是整个工作流最有价值的部分。传统建模是你手动每一步都调整现在你只需要做验收和方向把控细节让AI自己磨。4.4 材质与细节从白模到可展示模型形状确认无误后我给AI追加了一个需求“墙体赋浅灰色材质草地赋绿色材质花池赋红砖材质。”Codex在脚本里增加了材质逻辑# 材质示例 mat_wall model.materials.add(WallGray) mat_wall.color Sketchup::Color.new(180, 180, 180) mat_grass model.materials.add(GrassGreen) mat_grass.color Sketchup::Color.new(90, 160, 90) # 遍历墙体面并赋材质 # AI生成具体遍历逻辑材质赋完之后模型看起来已经像模像样。我又让它导出了一份DAE格式方便预览Agent在脚本末尾加了一行model.export(D:/workspace/siteout/site.dae)几分钟内整个模型从无到有、从白模到可展示全部完成。5. 常见问题与排查速查表5.1 Codex CLI配置与执行报错这几周我反反复复和各种报错打交道很多都是网友们常问的问题我整理成一张速查表报错现象根本原因处理方式模型不支持类似“gpt-5.6-sol is not supported”config.toml里写的模型名不存在或账号不支持改成账号实际支持的模型名别用猜测的编号“无法加载config.toml”文件编码带BOM或语法错误另存为无BOM的UTF-8编码逐行检查字段“无法定位codex CLI二进制”安装不完整或Path没生效重装CLI确认npm全局目录已加入Path上下文用满系统提示room不足单次会话内容太长codex reset清空会话或把大任务拆成多个小任务切换本地服务端点时请求失败本地端口被占用、本机hosts映射异常或本地服务未启动重启CLI检查占用端口把请求超时参数放宽确保本机回环服务正常最后一类报错尤其隐蔽因为它不是脚本逻辑问题而是CLI本地链路的问题。我遇到过一次是某个服务监听端口被其他程序占用了Codex发出去的请求没人接直接报错。处理方式是找一个空闲端口重新绑定重启CLI后再试就好了。5.2 SU执行Ruby脚本时的典型坑SU端执行脚本也有不少坑这些是纯技术层面的跟AU的批处理机制有关批处理启动慢SU启动加载插件需要时间Agent在脚本执行后马上读结果可能读不到。解决方式是脚本执行完写一个标记文件Agent轮询等待标记文件出现。UI.messagebox会卡死批处理Ruby脚本里如果调用了弹窗方法在批处理模式下会一直等着用户点确定整个流程就卡住了。所以给Agent的脚本规范里必须写清楚“禁止使用弹窗”。ents.clear!会清空当前所有模型如果你在已有模型的工程里跑了这个脚本里面内容会全被清掉。安全做法是每次执行前自动备份原文件我让Agent在脚本开头加了复制备份的逻辑从此再也不怕脚本翻车。保存路径目录不存在SU的model.save不会自动创建目录路径不存在就直接失败。脚本里要先Dir.mkdir_p创建目录再保存这个细节AI经常忘我踩过不只一次。5.3 给Agent建模的几条养肥经验这套工作流跑通之后我发现有几个使用习惯能大幅提升成功率一是需求描述里必须写清楚单位。AI默认会用英寸或者不带单位你在自然语言里明确“使用毫米单位”它生成的脚本出错率立刻降一半。二是工作目录里提前放一份模板脚本Agent会被样例格式“带偏”输出的代码稳定很多这是少走弯路最有效的一招。三是敢于让Agent自己检查结果——我一开始担心AI改脚本会越改越乱实际测试下来给它的反馈越具体比如“门洞偏了300毫米”“花池中心往东北移”它二次修改的成功率很高很少把已经对的部分改坏。还有一点尽量用英文路径。Windows下中文路径配上Ruby脚本的编码问题会让AI在排查时多绕很多弯我自己已经把工作目录全部改成了纯英文烦恼少了一大半。结尾这套“Codex调用SketchUp”的工作流跑通之后我最大的感受是AI建模的瓶颈不在AI而在我们是否愿意把需求翻译成它能执行的语言。以前我以为“让AI操作SU”需要什么黑科技结果就是Ruby脚本加命令行批处理技术栈一点都不玄乎但它把“从需求到模型”的效率提升了至少一个量级。我现在的工作方式已经变了建模前先和AI对话理清需求然后让它出脚本、跑模型我负责验收和审美把关。AI擅长的是重复劳动和参数迭代人擅长的是判断“这个模型好不好看、合不合理”两者配合起来刚好互补。这个思路不仅可以做庭院模型室内的户型生成、建筑立面的参数化推敲、甚至景观方案的体块研究都能套用。如果你手边正好装了SketchUp和Codex建议今晚就按文章里的最小模板跑一次“500mm立方体”链路通了之后后面的天地就大了。