ASPIRE 代码实现原理:生成式 Python 运行时如何安全注入与沙箱化工具 API?
ASPIRE 代码实现原理:生成式 Python 运行时如何安全注入与沙箱化工具 API?
ASPIRE(Agentic /Skills Discovery for Robotics)让大模型把机器人技能写成一段普通 Python 代码,再由一套生成式 Python 运行时在沙箱约束下执行。本文拆解它的代码实现原理:工具 API 如何被安全注入、代码如何被审查、结果如何被脱敏——帮你读完 src/cap_harness/runtime.py 之前先建立完整心智模型。
一、为什么"直接写代码"要配一套安全运行时?
ASPIRE 的核心理念:不训练模型权重,而是"训练"一个技能仓库——每个技能就是一段 Python 程序。例如 examples/libero/close_microwave.py 里,"关微波炉"技能只调用了 get_robot_state()、move_to_pose()、open_gripper() 等工具函数,没有任何 import。
但大模型生成的代码本质上是不可信的:它可能 import os 去读文件,可能试图读取仿真器的 qpos、reward 来偷看"答案"。ASPIRE 的解法是把执行环境收窄成"只有工具箱,没有世界":
- 不注入 NumPy、文件系统、网络、原生仿真器句柄;
- 只注入白名单工具函数 + 六个契约构造器(
Pose、RobotAction等); - 每次工具调用的返回值都经过脱敏。
完整的工具清单与边界划分见 docs/api-reference.md 的 "Surface boundaries" 一节。
二、四层防护:工具 API 的注入与沙箱
2.1 第一层 · 注册表白名单(registry.py)
所有想暴露给生成代码的函数都必须先进 ToolRegistry 并标记 public=True,名字还要通过双重审查:
| 审查项 | 规则 |
|---|---|
| 共享工具 | 必须属于 SHARED_PUBLIC_TOOL_NAMES(step、move_to_pose、segment_text 等 24 个) |
| 扩展工具 | 必须以认可的具身前缀开头(libero. / robosuite. / behavior. / yam_real.),且在对应 allowlist 内 |
| 特权名拒绝 | 名字含 reward、success、qpos、sim_state、mujoco 等敏感词一律禁止公开 |
CapApi.register_tools()(api.py)只注册这 24 个公共方法与若干元数据扩展;适配器生命周期方法(reset、check_success、原生环境句柄)永不注入。
2.2 第二层 · AST 静态审查:先审查,后执行
ProgramExecutor.execute_program() 在 exec 之前先用 _ProgramValidator 遍历语法树,直接拒绝:
import除math外的任何模块(import os→ 报错);from ... import全面禁止;- 类定义、
with、await、global、nonlocal、del、异步函数; - 一切下划线开头的名字或属性——这一条封死了
obj.__globals__、func.__closure__之类的自省逃逸。
有意思的是 lambda 被有意允许(排序 key 等场景需要),因为真正的防线在名字/属性守卫上,它们会递归进 lambda 函数体。这些边界规则由 tests/test_runtime.py 逐条钉死,防止未来改动悄悄放权。
2.3 第三层 · 受限命名空间:精简内置函数
程序在一个全新命名空间里执行,__builtins__ 被替换为 _SAFE_BUILTINS:只保留 abs、len、sorted、print 等约 25 个常用内置函数——没有 open、eval、exec。__import__ 同样被换成只放行 math 的受限版本。
与此同时注入六个契约构造器(Pose、RobotAction、ArmCommand、Trajectory、SynchronizedTrajectory、MotionStrategy),让生成代码能合法地"拼动作"而无需 import 任何模块。工具函数本身被包进 _ToolNamespace——一个只读命名空间,任何赋值尝试都会抛 AttributeError,层级名(如 libero.get_task_metadata)也自动构建成只读子树。
2.4 第四层 · 输出净化与调用追踪
工具调用的返回值会经过 _public_value() 净化:
- 键名命中
reward、success、qpos、raw_observation、ground_truth等敏感词的字段被直接剔除——防止技能代码"作弊"或泄露评测信息; StepResult/ExecutionResult只对外返回public_view();- 数组只读;
stdout落盘前还要经redact()(artifacts.py)二次脱敏。
同时每次调用都被记入一条 CallTrace:工具名、耗时、成败、provider(如 sam3、curobo);而参数和结果只保留形状摘要(shape、dtype、点数),不保留图像、mask、关节角数值——既可供事后调试,又不泄漏内容。
三、一次完整执行长什么样?
串起来看 run.py 中 run_program_with_api 的主线:
- 读入生成的
program.py源码; - 按 benchmark 选择扩展白名单,构建
ToolRegistry; api.register_tools(registry)只注入公共工具;ProgramExecutor.execute_program(source):AST 审查 → 受限exec→ 收集CallTrace;- 无论成败,源码、结果、stdout、trace 全部落盘为可审计的 episode 制品(见 docs/run-artifacts.md)。
一个真实技能程序(examples/libero/close_microwave.py)的核心逻辑,没有任何 import:
state = get_robot_state()
above = move_to_pose(
Pose((0.39, 0.04, 0.254), downward, state.base_frame),
tolerance=0.05, max_steps=400,
)
result = {"above_ok": above.ok}
四、边界说明:它不是真正的安全沙箱
⚠️ 官方在 README 中明确警告:
"ASPIRE executes language-model-generated Python with full import access. Trial processes and watchdogs are not a security sandbox."
运行时代码注释也写着 "process isolation is still required for untrusted code"。也就是说,AST 审查防的是无意越界与偷懒作弊(读 reward、调私有 API),而非恶意攻击。生产实践建议:
- 在隔离主机上运行生成代码:不放凭据、不挂载敏感目录、限制网络;
- 仿真 agent 绝不授予物理硬件访问权;真机任务需要独立的 operator 授权流程(见 docs/system2.md)。
五、这套架构跑出了什么结果?
白名单 + 脱敏让"让模型直接写技能"既安全又可规模化:
在 LIBERO-Pro、Robosuite、BEHAVIOR-1K 上,Claude Opus 5.5 在全部任务上达到 97–100% 成功率;成功率随底层模型能力上升(15% → 99%),且最强模型不一定最贵——成功率与 API 成本的权衡图见 README "Model Scaling" 一节的 success vs. API cost 动画。
六、关键文件索引
| 关注点 | 文件 |
|---|---|
| 沙箱执行器、AST 校验、受限命名空间 | src/cap_harness/runtime.py |
| 工具注册与白名单审查 | src/cap_harness/registry.py |
| 公共工具注册入口 | src/cap_harness/api.py |
契约类型与 public_view 脱敏 |
src/cap_harness/contracts.py |
| 运行编排与制品录制 | src/cap_harness/run.py、docs/run-artifacts.md |
| 安全边界回归测试 | tests/test_runtime.py |
| 工具 API 完整清单 | docs/api-reference.md |
一句话总结:ASPIRE 用"注册表白名单 → AST 审查 → 受限命名空间 → 输出脱敏"四层递进,把大模型生成的 Python 关进一个"只有工具箱"的房间——这正是生成式 Python 运行时能够安全注入并沙箱化工具 API 的全部秘密。

