让 Claude Code 直接操作 Unity：真实比例太阳系模拟器

这是什么

上面就是成品，直接在浏览器里运行。一个按真实比例做的太阳系：1 个场景单位等于 1 万公里，太阳半径 69.6 个单位，海王星轨道 45 万个单位，奥尔特云外缘 15 亿个单位。36 个天体（太阳、8 行星、18 颗主要卫星、冥王星和 7 颗柯伊伯带矮行星、月球）全部用 J2000 轨道根数计算位置，日期是真的，轨道倾角和偏心率也是真的。

拖动旋转，滚轮缩放，点任何一个名字就飞过去；左上角是所选天体的物理数据（NASA / JPL），底部是缩放和时间速度。手机上单指旋转、双指缩放。

先说结论

• 能做。 一个 AI 智能体可以不经人手，在 Unity 编辑器里完成写代码、编译、搭场景、进 Play 模式验证、截图、提交 git 的完整闭环。
• 不便宜。 整个会话约 12 小时、813 次模型调用，折算后的用量相当于 7,670 万输入 token。
• 瓶颈不在模型，在工具链：编辑器的模态对话框、后台节流、沙箱权限，这些"人一眼就能看到"的东西对命令行里的智能体是黑盒。

起因

2026 年 9 月 16 日 Unity 发布了面向 AI 智能体的官方插件（31 个技能）和 Unity CLI。我们看到一篇解读文章，想亲手验证"对接 Unity 到底有多方便"。于是在一台没有装 Unity 的 Windows 机器上，让 Claude Code 从头开始。

用了什么

Unity CLI 的原理很简单：pipeline 包在编辑器里起一个 HTTP 服务，CLI 把命令发过去，编辑器在主线程执行并返回结果。智能体用得最多的是 eval_file（执行任意 C#）、recompile、editor_play、capture_game_view。

技术方案

真实比例。 跨度 10 个数量级，直接放进 float 会抖动。

浮动原点。 所有天体位置用 double 计算，聚焦的天体永远放在世界原点，其他天体相对它摆放。镜头永远在原点附近，float 精度够用。切换焦点时先算出镜头在日心坐标里的绝对位置，再换到新原点，镜头不会跳。

光照。 太阳到海王星的光强差 900 倍，普通点光源要么内太阳系过曝要么外行星全黑。行星和星环用自定义 URP shader，取太阳方向做无衰减的朗伯光照，每帧由 C# 把太阳位置写进全局 shader 变量。

轨道。 完整的开普勒轨道：半长轴、偏心率、倾角、升交点经度、近日点经度、J2000 平黄经。牛顿迭代解开普勒方程，卫星轨道面按各行星赤道面倾斜：土星 28°，天王星 98° 躺着转，海卫一逆行 130°。验证方法是读出各天体相对黄道面的高度角，和 NASA 的倾角逐一核对。

柯伊伯带和奥尔特云。 第一版 11 万个点精灵，低配显卡扛不住。改成体积渲染：在包围球的背面片元里沿视线做 40 步光线步进，累积高斯密度（柯伊伯带是环状高斯，奥尔特云是球壳高斯），边缘自然渐变。只保留 1.4 万个真实点做颗粒感，离开可见范围时整个 Renderer 关掉。

贴图。 行星贴图来自 Solar System Scope（CC BY 4.0），2K 原图放在项目外，项目里只有 1K 版，导入时 Crunch 压缩。全部贴图打包后不到 3 MB。卫星和矮行星是程序生成的贴图。

浏览器版。 Brotli 压缩加 JS 解压兜底，不依赖服务器响应头。WebGL2 没有反向 Z，近远裁剪面改成随镜头距离动态调整，比例控制在 10⁷ 以内。总包 12.9 MB。

时间线

碰到的问题和解决方法

1. 商店版 Unity CLI 跑在沙箱里。 用 winget 装的 CLI 是微软商店的 MSIX 包，拉不起需要提权的安装程序，unity install 直接失败；许可客户端的命名管道也连不上。解决：从 CLI 的缓存目录找到已经下载好的安装包，用管理员权限静默安装到编辑器目录；许可在 Unity Hub 里手动激活。后来装 WebGL 模块时同样的问题，同样的解法。

2. 编辑器在后台不处理命令。 窗口失焦后主线程命令全部 30 秒超时。官方文档写了要先跑 set_autotick，但 Play 模式下帧数还是卡在第 1 帧。最后把编辑器的 Interaction Mode 改成 No Throttling 才彻底解决。

3. eval 的 5 秒主线程上限。 建场景一开始要 8 秒以上，每次都超时。两个改动：把资源创建包进 AssetDatabase.StartAssetEditing，从 8 秒降到 1.5 秒；长任务用 --detach 提交成后台作业再 job wait。

4. 模态对话框把一切挡住。 保存场景时编辑器认为文件被外部改过，弹出"Reload / Ignore"对话框，所有命令超时，日志里只有超时没有原因。智能体看不见对话框。解决：用 Win32 API 枚举窗口找到对话框，发 BM_CLICK 点掉；然后调整保存顺序避免再触发。

5. 一个零向量毁掉整帧。 离散盘环体的法线计算里，输入值太小被 Unity 的 Vector2.normalized 归零，零向量进 shader 做 normalize 得到 NaN，加法混合下 NaN 传遍整帧，画面变成黑底白椭圆。排查靠逐个关闭物体截图对比。修法是用等价的乘法形式手动用 double 归一化。

6. Play 模式重编译。 智能体改脚本时用户正在 Play，域重载清空静态单例但 Awake 不会重跑，每帧空引用。改成惰性查找。

7. 浏览器里鼠标失灵。 Unity 在浏览器里会注册一个触摸屏设备，代码判断的是触摸槽位数（永远大于 0）而不是按下的手指数，于是每帧走触控分支直接返回。编辑器里没有触摸设备所以测不出来。

8. 看不见画面。 截图是智能体唯一的"眼睛"。每次 CLI 往返约 2 秒，一次验证要拍 5 到 8 张。截图默认走摄像机不含后处理和 UI，要用 --source screen。

9. 浏览器里没有中日文字体。 桌面版借用系统字体显示中日文，浏览器里没有系统字体可借，界面只能锁定英文。完整的 Noto Sans CJK 有 16 MB，不可能整个打包。第一次尝试把用到的 368 个字烘焙成静态贴图，结果 Unity 的 IMGUI 用静态字体时所有标签都显示成最后画的那一句，整个界面变成同一行字。最终方案：用 fontTools 把字体裁剪成只含这 368 个字的文件（173 KB），仍以动态字体方式打包；导入规则脚本从本地化表自动生成字符列表，以后加文字重跑一次裁剪即可。

用量

会话时间 2026-09-20 05:26 到 17:19（UTC），中间包含用户离开的空档。

折算后的去向：读写代码文件 35%，每轮重读系统指令和工具清单 26%，思考和回复 25%，命令行操作（Unity CLI、git、node）10%，其余（截图传输、浏览器、网页搜索）4%。工具调用次数：Edit 153、PowerShell 123、Read 109、Write 41、WebFetch 15、浏览器 13、WebSearch 7。没有使用子智能体。

怎么理解这个数。 缓存读取占了绝大多数，是因为每一次调用都要带上之前的对话历史，只是缓存命中后按 0.1 倍计费。真正"新产生"的是 283 万输出 token，大约是这篇文章的 1,500 倍。按同等工作量，一个熟练 Unity 工程师大概需要 3 到 5 个工作日，其中相当一部分时间会花在同样的坑上。

做对了什么

• 每一步都截图验证，不信模型自己说"做好了"。
• git 提交粒度细，每个功能一个提交，出问题能回滚。
• 把常用操作封装成脚本（编译、构建、Play、截图、报错），后期迭代快得多。
• 踩过的坑写进记忆，同类问题第二次不再花时间。

做错了什么

• 第一版柯伊伯带直接堆 11 万个点，没先想性能。
• 触控分支的判断条件写错，桌面测不出来，上线才发现。
• 有几次在用户 Play 期间重编译，造成对方看到报错。

接下来

• 大气散射光晕、星环投影。
• 试双智能体协作：一个规划和审查，一个实现。
• 把 Unity CLI 的封装脚本整理成可复用的技能。

---

这篇文章由 Claude Fable 5.1 根据本次会话的完整记录写成，用量数字来自会话日志的直接统计。