LiteReality-Agent笔记: 从一次扫描到可交互的房间
内容提要
LiteReality-Agent项目通过手机扫描房间，端到端生成可编辑、可交互的三维场景。其核心是将确定性流水线与agentic编辑分离，房间以Python代码表示，agent通过闭集工具修改代码，并用纯几何检查把关。项目强调工程纪律，如可恢复状态、显式分层、防静默失效，展示了将LLM安全嵌入复杂系统的范式。
延伸解读
工程纪律：把LLM关进笼子
项目最值得借鉴的不是三维重建本身，而是将LLM安全嵌入复杂系统的工程范式。通过可恢复的确定性流水线、代码化的场景表示、闭集工具集、纯几何终检以及对降级路径的强制可见性，LLM被限制在“看图、改代码、迭代”的范围内，无法越界。这种“笼子”设计，为其他涉及LLM的复杂系统提供了可复制的模板。
代码化场景表示的优势
将房间表示为Python代码而非JSON或usdz，是项目最聪明的决策。这使agent编辑场景退化为编辑代码，直接复用LLM在代码生成与修改上的强项，无需设计专门的场景编辑DSL。同时，代码化表示便于版本控制、调试和复用，也使得确定性流水线与agentic编辑的分离更加自然。
防静默失效的实践
项目多处体现对静默失效的警惕：python-fcl作为可选依赖会导致碰撞闸门静默失效，因此被设为必需；不烘焙材质会导致导出后渲染错误，因此publish时显式调用烘焙；测试使用--strict-markers防止标记拼写错误；配置错误在组合边界即被捕获，避免在付费session中失败。这些实践提醒开发者，验证通道自身的可靠性至关重要。
harness与model的正交设计
项目将agent harness（循环、工具、权限）与model（决策大脑）解耦，并显式建模harness之间的非功能等价性。每个harness声明supports集合，调用方据此分支处理，缺失能力在日志中可见。这种设计避免了因假设harness功能一致而导致的静默降级，为多后端支持提供了清晰架构。
Q&A
LiteReality-Agent项目是如何将手机扫描的房间转换为可交互的三维场景的？
LiteReality-Agent通过手机扫描房间，端到端生成可编辑、可交互的三维场景。其核心是将确定性流水线与agentic编辑分离：首先通过确定性流水线（ingest、reconstruct、seed）生成种子房间，然后由agent通过闭集工具修改房间的Python代码表示，最后通过纯几何检查把关，确保场景正确。
LiteReality-Agent中房间的表示形式是什么？为什么选择这种形式？
房间的源是一个Python程序（Room.py），而不是JSON或usdz。这种选择使得agent编辑场景退化为编辑代码，直接复用LLM在代码编辑上的强项，无需发明专门的场景编辑DSL。
LiteReality-Agent中agent有哪些能力工具？它们的作用是什么？
agent的能力工具是闭集，包括fetch_material（获取PBR材质）、select_views（选择最佳采集帧）、render（渲染对比图）、grid（测量米制坐标）、critic（VLM打分）、check_collisions（碰撞检测）。这些工具确保agent能准确获取关键信息，避免猜测。
LiteReality-Agent如何确保agent的修改不会破坏场景的物理正确性？
项目在流水线末尾设置了一道纯几何的AABB检查（room_qc），用于检测物体穿地、穿墙、互相穿插等问题，并通过白名单化正确的重叠（如嵌入式烤箱）来避免误报。这道闸门不依赖模型，确保最终场景的物理合理性。
LiteReality-Agent如何处理agent运行时的预算限制？
项目设计了step budget和step_reserve机制：在预算末尾的step_reserve步内关闭能力工具，迫使agent将剩余步骤用于最终编辑，避免硬停导致工作丢失。对于不支持hooks的harness（如Codex），则退化为硬停，并在日志中明确标注。
LiteReality-Agent中harness和model的区别是什么？为什么说它们不是功能等价的？
harness是agent循环（如Claude Code、Codex），model是循环中的大脑（如HARNESS_MODEL）。它们不是功能等价的，因为不同harness支持的能力不同（如hooks、工具白名单、成本报告等），项目通过supports集合显式建模这些差异，并在日志中显示缺失能力，避免静默降级。
LiteReality-Agent在工程实践上有哪些值得借鉴的纪律？
项目强调工程纪律，包括：可恢复的流水线（状态原子写、级联失效）、显式分层（确定性与agentic分离）、防静默失效（如python-fcl必须为必需依赖、烘焙材质）、配置错误在组合边界暴露、测试默认离线且快、依赖方向由测试执法、唯一副本由测试钉死等。
LiteReality-Agent项目有哪些已知的局限性？
项目版本为Alpha，依赖agent CLI登录态，成本不透明（authoring部分未计量），Codex是二等公民（无hooks、无工具白名单、不报成本），物体精修仅支持Claude。这些局限在文档中明确标注。
