LiteReality-Agent笔记: 从一次扫描到可交互的房间
内容提要
LiteReality-Agent项目通过手机扫描房间，端到端生成可交互三维场景。其核心设计采用确定性流水线与agentic分层，将房间表示为可编辑Python代码，agent通过闭集工具修改代码。项目强调工程纪律，包括可恢复流水线、纯几何终检、显式建模harness差异及防静默失效，并记录架构决策与教训。
延伸解读
确定性流水线与agentic分层
项目将流水线明确分为scene_init（确定性）和realism_authoring（agentic）两个阶段，前者不依赖模型做布局决策，后者通过agent修改代码来迭代。这种分层让调试时能清晰定位问题：布局歪了是seed的问题，材质不对是agent的问题。许多将LLM塞入流水线的项目因分界模糊而难以维护，此设计值得借鉴。
代码化场景表示的优势
房间源被表示为可编辑的Python代码（Room.py），而非JSON或usdz，使得agent编辑场景退化为编辑代码，直接复用LLM的代码能力。这种表示还支持可恢复流水线：磁盘上的Room.py可作为事实来源，即使状态文件丢失也能恢复。同时，代码化表示便于版本控制和差异比较，提升了工程可维护性。
防静默失效的工程实践
项目多处强调防止静默失效：缺失FCL时碰撞闸门会变成空操作，因此将其设为必需依赖；未烘焙材质会导致渲染白色，故在publish时显式调用bake_room()。此外，配置错误在组合边界即失败，避免在付费session中才暴露。这些实践提醒我们，验证通道自身失效是最难发现的bug，需通过显式检查和日志来确保降级可见。
harness与model的正交设计
项目将agent harness（循环控制）与model（推理大脑）解耦，并显式建模harness差异：每个harness声明supports集合，调用方据此分支。例如，Claude支持hooks优雅收尾，而Codex只能硬停。这种设计避免了假设功能等价，并通过describe()打印差距，确保缺失能力在日志中可见，防止降级运行看起来像正常。
Q&A
LiteReality-Agent项目的主要目标是什么？
LiteReality-Agent项目通过手机扫描房间，端到端生成可编辑、可渲染、可交互的三维场景，强调与真实房间的对应而非仅合理外观。
LiteReality-Agent如何表示房间场景？为什么选择这种表示？
房间表示为可编辑的Python代码（Room.py），而非JSON或usdz。这样agent编辑场景退化为编辑代码，复用LLM的代码能力。
LiteReality-Agent的流水线分为哪两个阶段？各自的特点是什么？
分为scene_init（确定性阶段）和realism_authoring（agentic阶段）。scene_init读扫描、检测、生成物体，同样输入出同样输出；realism_authoring由agent修改代码直到与照片对上。
LiteReality-Agent中agent有哪些能力工具？其中哪些工具的设计特别巧妙？
能力工具包括fetch_material、select_views、render、grid、critic、check_collisions。select_views和grid将易猜错的量（帧号、米制坐标）转为工具调用，避免agent猜测。
LiteReality-Agent如何保证最终场景的几何正确性？
通过纯几何终检（AABB算术）检查物体是否穿出地板、天花板、墙等，并白名单正确的重叠（如台下式水槽）。该检查不含模型，快速且精确。
LiteReality-Agent如何处理harness之间的差异？
每个harness声明一个supports集合，调用方分支判断。例如Claude Code支持hooks、inproc_tools、cost报告等，而Codex不支持。差异通过providers.describe()打印到日志，确保缺失能力可见。
LiteReality-Agent中step budget的优雅落地机制是什么？
通过step_budget和step_reserve字段，在预算耗尽前预留一段步数，关闭能力工具，迫使agent用剩余步数完成编辑。支持hooks的harness原生实现，否则硬停。
LiteReality-Agent如何实现可恢复的流水线？
状态原子写（先写.tmp再replace），force级联失效下游，磁盘状态可认领内存状态（如直接跑stage author时，若磁盘有Room.py则标记REUSED）。
LiteReality-Agent中物体重建的复杂度路由是怎样的？
classify_complexity.py根据物体类型路由：椅子、沙发等有机形状用TRELLIS神经生成静态GLB；规则盒体、家电用procedural（Blender原语+PBR），并手写每类物体的规格（几何、材质、运动方式）。
LiteReality-Agent有哪些静默失效的教训？
两个教训：python-fcl不能作为可选依赖，否则碰撞检测闸门会静默失效；程序化材质未烘焙会导致渲染白色，且难以发现。修法是显式烘焙。
