Yuanhao Feng

返回

第二篇介绍了 CubeMuse 的 Agent 建造循环:模型使用一组工具逐步建造体素建筑,并在每一步决定接下来做什么。工具列表里有 inspect,能读到方块数量、包围盒、材质分布和 lint 结果。单靠这些文本信息,模型能判断的内容有限。inspect 能告诉模型”屋顶用了 120 块红色方块”,却无法判断”屋顶比例失调”或”墙面和屋顶的配色不搭”。模型需要图像来判断轮廓、比例和色彩搭配。

CubeMuse 用两条路径把视觉信息接入建造过程。第一条是 look:Agent 在建造过程中主动调用,服务端软渲染器为当前 Grid 生成四张截图,视觉模型据此描述外观,描述随后进入 Agent 的上下文。第二条是 critique:用户在建造完成后点击评审,浏览器截取标准四视图,经过结构检查和视觉评审后返回分数和修订建议。

建造中的视觉观察#

在一次苏州园林的建造过程中,Agent 根据视觉反馈调整了后续操作。Agent 在第 19 步调用 look,视觉模型指出作品的垂直层次不足。第 20 步,Agent 执行 add_ops,新增了塔楼、廊顶、花卉和红色装饰四个命名构件。这次视觉观察的结果进入了下一次操作的上下文,Agent 据此调整了建造内容。

look 要求视觉模型返回一个 description 字段,内容是两到四句外观描述。解析器优先提取该字段,失败时保留原始文本,正文最多保留 700 个字符。这段描述作为工具结果进入建造模型的后续上下文,建造模型根据描述决定是否需要修改。

建造模型和视觉模型是两种独立的模型调用。视觉模型接收图片并返回文字,建造模型根据文字继续生成 DSL。两种模型不共享上下文窗口,视觉观察通过文字描述传递。

服务端软渲染#

look 在服务端执行,没有 GPU 可用。CubeMuse 用一个纯 CPU 的软渲染器生成截图。

渲染过程分四步。先把 Grid 包围盒内的体素复制到一个稠密三维数组。然后对每条射线,将其裁入包围盒,沿体素网格用 DDA 算法步进,寻找首个非空体素。命中后按方块家族基色和面朝向的明暗系数着色。最后把像素缓冲编码成 PNG data URL。

软渲染器每次输出四张 384×240 的 PNG 图像,与浏览器截图共享 16:10 的画框比例和四个标准视角。两端的相机位姿、标签和取景距离来自同一个纯几何模块 poses.ts,后面会详细讲。

软渲染用平色和面方向明暗表达体量,楼梯等非整方块也按整方块处理,透明材质会在首个非空体素处结束射线。这意味着 look 主要观察体量和轮廓,材质细节和非整方块形状需要浏览器图像补充。

指标look 软渲染critique 浏览器截图
输出4 张 384×240 PNG4 张 640×400 JPEG
环境Node 服务端,无 GPU浏览器,Three.js
着色面方向平色贴图 + 顶点 AO
非整方块整方块近似完整几何

浏览器在截图前临时关闭雾效,将绘制缓冲切到目标尺寸并重设相机比例。finally 块还原雾、缓冲尺寸、DPR 和比例,正常完成后还原相机位置与旋转,再渲染一帧。这保证截图不受当前视口状态的影响。

观察时机与调用额度#

look 的调用时机需要兼顾当前进度和剩余步数。太早调用,模型看到的只是一堆散落的方块,难以据此判断该怎么修改。太晚调用,剩余的建造步数不够做修改。

提示词建议在主体量形成后、大约三分之一预算处首次调用 look。如果实际建造步数过半且 Agent 尚未尝试 look,循环会追加一次提醒。

look 的调用次数有上限,按 ScalePlan 档位分配。

ScalePlanlook 上限共享侦察额度
S24
M26
L38
XL410

look 与 search_library、get_entry、inspect 共用侦察额度。侦察额度用完后,look 继续消耗建造步。模型因此可以根据需要,在侦察和实际建造之间分配预算。

空场景会拒绝 look 调用。渲染或视觉模型调用失败时返回明确说明失败的观察结果,本次尝试仍占一次 look 额度,Agent 可以继续建造。

以 S 或 M 档为例,一次完整的建造加评审最多产生 3 次视觉调用、12 张图:2 次 look 加 1 次 critique。前提是用满 look 额度、用户触发一次评审且 lint 检查通过。

成品评审与修订#

建造完成后,用户可以在版本卡上点击评审,触发 critique 流程。

look(建造中) critique(成品评审) Agent 建造循环 软渲染器 4× 384×240 PNG 视觉模型 → 外观描述(文字) 回喂 Agent 上下文 用户点击评审 浏览器截图 4× 640×400 JPEG 类别 lint warn 修订单 (0 VLM) info VLM 评审 分数 + findings accept ≥75 / revise poses.ts 位姿 · 标签 · 画框 16:10 — 软渲染器与浏览器截图共读

评审接口先重放建造程序并运行类别感知的 lint。如果 lint 发现 warn 级别的问题,直接生成结构修订单,不调用视觉模型。只有 lint 结果全部为 info 级别时,才继续视觉评审。这样可以先处理结构性问题,再消耗视觉 token。

如果结构检查通过但视觉模型不可用,接口返回 vlmSkipped: true 和零用量,明确说明视觉评审已跳过。

视觉评审同时接收用户意图、结构摘要、可编辑的 group id、类别标准和目标尺寸。视觉模型返回一个 0 到 100 的分数和 accept 或 revise 的判定,以及带有 target、issue、fix 三个字段的修订建议。修订建议可以交给 Agent 修改已有的建造程序。

75 分是评审提示词中的接受线,缺少 verdict 时,也用这个阈值推导判定。解析器优先保留模型给出的合法 verdict,分数限制在 0 到 100 并取整。如果模型没有返回分数,accept 补 85,revise 补 55。

界面默认最多允许两轮评审修订。

人工抽查覆盖了钟楼、龙和庭院三件作品的评审结果。三件作品共有 7 条 findings,三例 verdict 均为 accept,分数在 82 到 85 之间。钟楼的两条 findings 在比对南立面截图后得到确认:阶梯式塔顶的形状和正面白色方盘的位置都与截图吻合。这批结果说明视觉评审能发现可见的缺陷,但缺陷召回率和修订后的质量提升还没有系统测量。

四视角覆盖#

我在生成测试中发现,AI 建造的猫正面和背面都画了脸。猫的原始程序没有留存,沿 z 轴镜像是否导致了背面的第二张脸,仍无法确认。可以确认的是,旧的四视图全部位于模型中心的南侧或上方,北面的覆盖数为零。三台位于地面的相机从东南、西南、正南三个方向拍摄,没有一台能观察到北面。视觉模型看不见北面,自然无法发现北面的问题。

修复方案是把索引 1 的西南轴测改为西北轴测。改动后,东、西、南、北和顶面五个法向均满足覆盖条件。

旧视图 现行视图 N S E W 建筑 0: 东南轴测 1: 西南轴测 2: 南立面 3: 俯视 三台相机均在南侧 北面覆盖: 0 台 ✗ N S E W 建筑 0: 东南轴测 1: 西北轴测 2: 南立面 3: 俯视 北面覆盖: 1 台 ✓ 俯视 (3) 两组相同;相机位置按 poses.ts 的 viewPoses,坐标系 +X 东 / +Z 南 / +Y 上

覆盖条件的判据是:至少一台相机的”中心到相机”单位向量与目标面法向的点积达到 0.3。0.3 的阈值用来排除相机以极度倾斜的角度观察该面的情况。俯视机位的 z 偏移为 0.01,这个微小偏移让俯视图只通过顶面的覆盖检查,而不会因为浮点精度被算作覆盖了南面。

面旧视图覆盖数现行视图覆盖数
东11
西11
南32
北01
顶33
底00

北面由新加入的西北轴测覆盖。底面被有意省略,因为体素建筑的底面通常没有可观察的特征。

测试用两种方式验证覆盖。几何测试检查每个标准视角的法向覆盖条件,包括历史错误位姿的回归用例。像素探针测试在石盒北侧放一块红石,检查西北轴测图中出现红色占优的像素。把红石埋入封闭盒内时,所有视图均不应出现红色像素,验证遮挡行为正确。

这次修复仍使用四张图,图数和调用额度的增量均为零。

统一取景规格#

软渲染器和浏览器截图需要用同一组相机位姿。如果两端使用不同的坐标,浏览器和视觉模型就会从不同角度观察作品,评审结果也就难以对照。

相机位置、标签、取景距离和画框比例集中在纯几何模块 poses.ts 里。服务端软渲染和浏览器截图都导入这个模块。poses.ts 不依赖 node:zlib 等 Node 专属模块,浏览器可以直接使用。取景距离按包围盒最长边计算,公式是 d = 1.6m + 5,其中 m 是最长边长度。

critique 的视图说明由实际图像标签生成,look 使用通用描述提示,传输层在每张图片前附上实际视角标签。两条路径都从 poses.ts 读取标签,保证文字描述和图片内容对应。

统一画框也解决了过去截图尺寸不固定的问题。在引入 captureSize 之前,浏览器截图的高度取决于当前工作台的布局。同一份作品在两种窗口尺寸下分别输出 640×1252 和 640×446,像素量相差 2.8 倍。当前的 captureSize 从宽度按 16:10 的固定比例计算高度,截图尺寸独立于工作台布局。

封面取景#

封面截图复用了与视觉评审相同的截图入口,取景方式则由触发条件决定。

触发条件机位来源适用情形
缺省标准视图索引 0(东南轴测)大多数建筑
门朝向投票门所在的包围盒侧面,平票依次选南、东、北、西有门的建筑
当前视角保留用户的相机位置和朝向用户手动选择正面

用户选择当前视角做封面时,截图保留相机位置和朝向,并按统一画框调整水平取景。用户可以借此为雕塑、动物等没有固定正面的作品选择合适的展示角度。

CubeMuse 的视觉反馈
https://me.yuanhaofeng.com/blog/cubemuse-visual-feedback
作者 Yuanhao Feng
发布于 2026年10月6日