SpatialClaw: 重新思考代理空间推理的动作接口

TL;DR SpatialClaw 采用有状态代码执行接口，让 VLM agent 在 Python 内核中按步组合感知与几何原语，灵活解决复杂 3D/4D 空间推理，平均准确率 59.9%，超越现有方法超 11%。

问题

问题背景

视觉语言模型(VLM) 在静态图像理解上已取得突破，但面对涉及 3D/4D 空间关系、物体运动与视角变换的开放推理任务时，仍显力不从心。业界正通过 工具增强代理(tool-augmented agents) 为 VLM 接入专业感知模块（如 SAM3、深度估计），以弥补其空间认知短板。

现有方法局限

当前空间代理的动作接口主要有两种设计，均存在根本灵活性缺陷：

• 单次代码执行(single-pass code)：代理须在上文盲写完整分析策略，执行前无法观测任何中间结果。一旦初始假设错误或场景动态变化，缺乏修正机会，导致复杂任务中鲁棒性极差。
• 结构化工具调用(structured tool-calls)：严格限定参数格式与调用顺序，难以自由组合感知原语或动态构建分析流水线。工具间状态传递困难，常局限于预定义原子操作，无法针对具体任务定制多步推理。 两种方式都将代理束缚在封闭的规划-执行管道中，无法实现“执行-观察-修改”的迭代闭环，在需要假设验证的 3D/4D 场景中表现孱弱。

为什么这个问题难/重要

空间推理是自动驾驶、机器人导航、增强现实等关键应用的基石。技术挑战在于：VLM 本身缺乏精确的度量和几何理解，而工具增强又面临接口设计与代理规划能力深度耦合的难题。一个高效的动作接口须在 可组合性（自由编排多种感知原语）、可观测性（每步检查中间输出）和 适应性（根据反馈动态修正策略）间取得平衡，这直接决定代理的性能上限。工业界与学术界对此高度关注，近年多项工作（如 ReAct、CodeAct）均试图从不同角度突破这一瓶颈。

行业类比

这类似于在数据分析中，用 Jupyter Notebook 的交互式单元执行取代一次性脚本：分析师能够逐步查看结果、调整代码，灵活应对探索性任务；空间代理同样需要这种有状态、可迭代的推理环境，而非黑盒式的一次性推理。

核心洞察

• **有状态代码执行作为空间推理的核心交互范式**：SpatialClaw 将代码接口从单次生成视角提升为持久的 Python 内核，让 VLM 代理能够分步编写、执行并观察中间反馈（包括文本与视觉输出），从而动态调整推理路径。这与单次代码执行（如一次性生成整个分析脚本）或结构化工具调用（缺乏灵活组合与任务自适应能力）形成本质差异，为开放式 3D/4D 空间推理提供了接近人类分析师的灵活性和可调试性。
• **训练无关的接口设计大幅提升现成 VLM 的空间推理上限**：SpatialClaw 无需对 VLM 做任何微调或基准定制，仅通过系统提示、可复用的感知与几何原语以及安全沙箱执行环境，在 20 个广泛的空间推理基准上平均准确率达到 59.9%，较近期专用空间代理高出 11.2 个百分点。这证明 Agent 的能力瓶颈往往不在于模型本身，而在于工具调用接口的合理设计，为工程上低成本拓展 VLM 的应用边界提供了直接方法。

方法

输入与预处理

SpatialClaw 接收多帧图像（静态多视角或视频序列）和文本问题，统一将帧加载到持久 Python 内核中，并对每帧建立类型契约，确保后续工具调用时数据类型一致。

关键模块：持久内核与工具集

• 持久化 Python 内核：维持有状态的执行环境，允许中间变量跨步骤复用，并能捕获执行异常。
• 感知与几何基元工具：包括 tools.Reconstruct（多视图3D重建）、tools.SAM3（视频/图像分割，支持图像与视频模式）、tools.Geometry（空间距离、角度计算）、tools.Mask（掩码操作）、tools.Time（时序分析）、tools.Graph 和 tools.Draw（可视化输出）。
• VLM 代理：作为决策大脑，在系统提示下遵循分阶段的推理纪律。

推理循环

代理运行五阶段迭代：

1. 规划：VLM 将问题分解为子任务，确定所需工具和大致分析路径。
2. 代码生成：根据当前对话历史（含之前所有中间输出），生成一个可执行的 Python 代码块（cell）。
3. 代码执行：内核执行代码，可能返回文本、数值、图像或错误信息。
4. 反馈整合：将执行结果（如分割 Mask、3D 点云俯视图）以序列化形式追加到对话，供下一步决策。
5. 答案提交：当代理认为已收集足够证据，调用 submit_answer 输出最终答案。

整个过程允许观察—修正：代理看到中间可视化后可调整后续步骤，例如在分割失败时启用 tools.SAM3 的提示模式，或改变重建策略。

输出

最终输出为对空间问题的结构化答案，如相对位置、运动轨迹、3D 距离等。

与同类方法的关键差异：现有空间 Agent 或采用单次代码生成（一次性写出全部分析代码，无中间反馈），或使用结构化工具调用（固定的 JSON 调用格式，灵活性受限）。SpatialClaw 用代码作为动作接口但保留有状态的逐步执行，既获得代码的灵活性，又具备根据中间结果动态修正的能力，这是其性能大幅领先的核心原因。

实验

实验设计

SpatialClaw 在 20 个静态与动态 3D/4D 空间推理基准上评估，覆盖物体定位、关系推理、运动分析等任务。实验采用 6 种 VLM 骨干（来自两个模型家族），不针对特定基准或模型调优，以验证泛化能力。对比基线包括：单次代码执行型智能体与结构化工具调用型智能体。

关键发现

SpatialClaw 取得 59.9% 平均准确率，较近期空间智能体提升 +11.2 个百分点，且在所有 VLM 骨架上一致优于基线。维持状态化 Python 内核、分步执行、中间结果反馈的设计，显著增强了复杂、开放式推理的灵活性与成功率。

与基线对比解读

相比单次代码执行（一次性生成完整分析策略，无中间反馈）和结构化工具调用（灵活性受限），SpatialClaw 的分步执行范式允许模型根据每一步的文本与视觉输出调整后续分析，避免了因初始规划偏差导致的整体失败。这一优势在高难度、需多步组合操作的 4D 任务上尤为突出。

行业影响

落地场景

SpatialClaw 所解决的开放域 3D/4D 空间推理问题，直接指向一系列需要精细化空间理解的工业产品：

• 自动驾驶与机器人：动态场景理解、物体轨迹预测、可行驶区域分析，模型需在感知模块输出之上进行灵活组合与推理，而非固定流程。
• AR/VR 与 3D 内容生成：实时理解用户环境，将虚拟物体准确锚定在物理空间中，或根据文本描述生成合理 3D 布局。
• 工业视觉检测与数字孪生：对复杂装配体进行细粒度空间关系校验，或从视频流重建作业空间状态。
• 医疗影像分析：从 CT/MRI 体积数据中定位病灶、分析器官相对位置，需要可解释的多步推理。

商业价值

SpatialClaw 通过 training-free 框架 将现有 VLM 转化为可灵活调用感知原语的 agent，无需为每个新场景标注数据或微调模型，直接降低研发成本与上线周期。

• 降本：避免为不同空间推理任务重复训练专用模型，使用统一的代码动作接口即可适应新问题。
• 增收/体验提升：在自动驾驶中，更准确的意图预测可减少接管率；在电商 3D 商品展示中，自动分析空间关系可生成更符合直觉的交互式浏览，提升用户停留与转化。
• 体验提升：由 agent 产生的推理过程可附带可视化中间结果（如 3D 重建、分割掩码），增强可解释性与用户信任。

与现有产品/工作流的接口

SpatialClaw 以 Python 内核 + 工具 API 的形式天然适配云原生与微服务架构：

• 集成方式：将其部署为独立服务，通过 VLM 调用端点（如 OpenAI 兼容 API）接入现有 agent 编排框架（LangChain、AutoGen 等），或在端侧模拟轻量内核。
• 工具集扩展：tools 模块已定义清晰的接口契约（SAM3、几何计算、绘图等），企业可根据自身传感器和数据格式快速定制新感知原语。
• 安全与资源管理：内核运行于 sandbox 中，支持超时与预算控制，可直接嵌入生产环境的 MLOps 流水线。

具体落地 Use Case

1. 自动驾驶数据标注与校验：标注平台集成 SpatialClaw，对已标注的激光雷达点云序列进行二次校验——agent 根据检测框关系，执行代码检查碰撞时序是否合理、遮挡是否匹配，自动报告可疑标注，将审核效率提升 30% 以上，减少人工逐帧复查。
2. 电商 3D 商品空间装配：在家具电商平台，用户上传房间扫描视频，agent 利用 SAM+3D 重建生成地形图，再根据用户选择的家具尺寸自动计算摆放位置和光照适配性，输出渲染建议，将“虚拟试摆”的交互从静态照片拓至动态视频理解，降低退货率。

局限

• - **依赖底层感知工具**：SpatialClaw 的空间推理质量受限于其集成的感知模块（如 SAM3 与重建工具），这些模块的错误会沿推理链传播，且框架本身不具备端到端微调能力，无法在特定任务上纠正感知偏差。
• - **VLM 能力瓶颈与计算开销**：作为训练无关框架，推理表现严重依赖所选 VLM 主干的理解与代码生成能力，对不同模型增益不一致；循环式执行（Code→Inspect→Revise）增加了推理步数，在简单任务上可能引入不必要的延迟和 token 消耗。
• - **泛化与部署复杂度**：预定义的 Python 内核、工具集与精心设计的系统提示紧密耦合，向新感知模块或新空间推理领域的迁移需要大量手工适配，沙盒安全机制也增加了工程部署的复杂性，限制了即插即用性。