isaac-sim-orchestrator

Isaac Sim 编排器

用途

将已确定的目标或约定转化为经过验证的库、Kit 集成或可运行的仿真，方法是梳理功能并按顺序执行专门技能。像“叉车演示的范围已确定并获批；请构建它并给我视频”这样的请求，可直接进入以下四个阶段。只有在交付物或验收标准仍需确定范围时，才先使用 isaac-sim-workflow。

专业技能归属

以避障为重点的机械臂演示归 motion-generation 负责，包括绕杆进行抓取放置，并提供物理仿真和视频。如果先加载了此编排器，应在实施前移交给 motion-generation，并将其保留为主要技能。编排可协助组合与交付。

如果有原生技能调用工具，应使用该工具调用专业技能；通过 shell 读取其说明或脚本不能替代调用。如果运行时仅支持基于文件的技能加载，则使用该机制，并准确说明追踪方面的限制。

前提条件

• Kit 集成：需要已构建的 Isaac Sim、受支持的 NVIDIA GPU，以及下方的 shell 环境。
• 独立库基础：需要已配置的 source/libraries 构建，或已安装的 wheel/SDK；Kit 和 GPU 并非普遍必需。

限制

• 除非某一节另有说明，Kit 相关指南以 Isaac Sim 6 / Kit 110 为目标。
• 无法替代 NVIDIA 官方文档来处理不受支持的边缘情况。

故障排除

错误 / 症状	原因	解决方案
找不到扩展	$ISAAC_SIM_DIR 错误或 Kit 构建过期	将环境变量指向 _build/linux-x86_64/release，或重新构建
画面全黑或为空	缺少灯光，或渲染模式非 RTX	添加穹顶光/关键光；确认 RTX / PathTracing 设置
加载场景或首次渲染时卡住	MDL 编译或场景过大	按照 isaac-sim-troubleshooting 中的隔离步骤操作

环境约定

Kit 路由的技能使用以下变量；独立库工作则使用其已配置的构建/安装环境：

变量	用途	示例
$ISAAC_SIM_DIR	Isaac Sim 安装根目录或已构建的仓库路径	$HOME/IsaacSim（安装版）或 <this-repo>/_build/linux-x86_64/release（源码构建）
$ISAAC_LAB_DIR	Isaac Lab 检出目录	$ISAAC_SIM_DIR/IsaacLab
$WORKSPACE_DIR	每个 Agent 的输出、临时文件和缓存	默认未设置；选择项目本地路径或 ~/.cache/<repo>
$CIP_ROOT（Windows）	内容管线安装目录（CIP/WRAPP）	C:\_Data

在进行 GPU 仿真或渲染前运行 nvidia-smi，以确定 num_envs 的大小并选择 RT2 或 PathTracing。对于仅使用 CPU 的库工作流，不要要求运行此命令，也不要硬编码 GPU 型号。

执行模式

运行代码前，先选择负责的工作面：

工作面	执行方式
独立库	使用已配置的模块构建、已安装的 wheel/SDK，或 source/examples/examples.sh；不要创建 SimulationApp
Kit 演示/控制器	除非用户明确要求进行独立验证，否则在独立交接/录制前，通过 isaac-sim-remote 迭代并验证
其他 Kit 扩展或适配器	优先通过 isaac-sim-remote 使用实时 Python 服务器进行迭代；使用 python.sh 进行独立 Kit 交接测试
在 Kit 中暂存的库	先在常规进程中验证该库，再在 Kit 中测试其 wheel 暂存和生命周期适配器

扩展到库的重写流程

当既定契约要求将可复用行为从扩展迁出时：

1. 清点并分类旧 API、实现、适配器、打包方式、依赖项、测试、导入项和版本相关内容。
2. 在 source/libraries 中保留唯一实现；保留受支持的导入方式，并验证其公共门面无需 Kit 即可运行。
3. 将构建好的 wheel 和 SDK 暂存到精简的 Kit 扩展中，该扩展仅保留 Kit 生命周期或转换行为。
4. 使用 isaac-sim-validator 分别验证库和 Kit 路径，包括各自独立的版本决策。

按照 isaac-sim-remote 中的启动流程启动启用服务器的模拟；不要在此处重复其命令。 在迭代 Kit 控制器之前，必须先收到成功的健康检查响应，然后通过客户端发送场景设置、调优和验证探测。保留这些响应作为执行证据。如果无法让服务器正常运行，请报告工作流验证受阻；不要悄悄改为反复启动 SimulationApp，也不要根据成功的视频声称工作流已完成。 在线迭代后如需正常关闭，请通过本地主机客户端调用远程技能的关闭辅助脚本。

任务分解

对于任何请求，都要执行全部四个阶段。每个阶段中的具体步骤取决于目标；先识别能力，再逐项独立验证，最后进行组合。

阶段 1 — 验证基础

1a. 功能／技能映射（编写任何代码之前）：

• 如果演示仍缺少交付物或验收标准，请加载 isaac-sim-workflow 来定义这些内容，然后返回这些阶段。如果请求已明确主题、行为、约束和输出（例如，交付一段 20 秒、无碰撞地穿过过道的视频），则直接采用该契约；不要重复范围界定流程。
• 对照 Isaac Sim 已记录的功能和 API 检查请求。
• 针对每项能力，查找现有技能：
  • 技能存在 -> 加载该技能并遵循其流程。
  • 技能不存在 -> 直接构建。将其 frontmatter 的 status 标记为 draft，在 skill-distillation 中将其标记为 HIGH PRIORITY，提前告知用户，并缩短迭代周期（分享中间结果，尽早提出有针对性的问题）。
• 在进入 1b 之前，将功能 -> 技能映射写入任务的 WORKLOG.md。

1b. 基础验证（逐项能力验证）：

• 列出任务所需的每项能力（资产、物理、机器人控制、传感器、渲染等）。
• 逐项独立验证：能否加载，能否正常运行。
• 所有基础项均通过后才能继续。

阶段 2 — 渐进式集成

每次只组合一个已验证的基础项。每增加一项后，都要重新运行稳定性／正确性检查。每次失败都只能有一个新变量。

阶段 3 — 润色与交付

• 通过视觉或程序方式验证输出。验证任务是否成功，而不只是脚本是否执行完毕。
• 添加输出特定的要求（写入器、标注、视频捕获、DR）。
• 打包并移交，附上简短摘要。

阶段 4 — 提炼（必需）

• 列出迭代、失败和变通方案。
• 记录用户的纠正意见。
• 对每条经验分类：新技能、技能更新、流程修正或 MEMORY.md 事实。
• 遵循 skill-distillation，判断可复用经验是否值得修改技能。用户已授权时，应用范围明确的修改；否则，先记录或提出补丁，再进行写入。如果没有可复用经验，也要记录这一结论。

完整流程请参阅 skill-distillation。阶段 4 不可省略，即使无需更改任何文件也必须执行。

子 Agent 规则

• 每个阶段都可以由拥有独立 WORKLOG.md 的子 Agent 执行。
• 子 Agent 应在逻辑检查点提交，绝不提交未完成的内容。
• 生成大型脚本时，应逐步写入文件。不要试图在一轮中生成 200 行以上的内容。
• 如果子 Agent 超时，WORKLOG.md 会保留，供后续接续任务使用。

路由技能

技能	适用场景
isaac-sim-remote	Kit 开发中的实时 Python 服务迭代与验证
motion-generation	障碍物感知型机械臂控制器和抓取放置的主要负责人，包括物理和视频演示
urdf-mjcf-to-usd-conversion	将 URDF/MJCF 机器人描述导入 USD，并配置物理 API 和关节结构
physx-to-newton-conversion	将现有的仅含 PhysX 的 USD 机器人转换为支持 Newton 的变体包
usd-pipeline	资产插入、缩放、材质、无头渲染兼容性
usd-composition-architecture	分层 USD 资产（根层 + 物理层 + 外观层）
usd-articulation	多连杆关节结构、关节层级、Robot Schema 覆盖层
physics-simulation	PhysicsScene 配置、单个 prim 设置、接触材质、Newton 与 PhysX
isaac-sim-sensor	RTX/物理传感器（相机、LiDAR、IMU、接触）、渲染产品、标注器
isaac-sim-rendering	无头 Kit 110 捕获、RT2/PathTracing、ACES
isaac-sim-validator	交付前的最终 QA 检查
有关 Kit 引导流程以及它与独立库导入的区别，请参阅
references/api-cheatsheet.md。

多机器人车队参考

示例机器人

机器人	起始 Z	驱动方式	备注
Nova Carter	0.0	差速	车轮半径 0.14 m，轮距 0.499 m；阻尼 100K
VSVXL	0.0	差速	最可靠；车轮半径 0.15 m，轮距 1.52 m
Spot	0.75	全向轮	bbox 最小 Z = -0.69；需要离地间隙
FR3	0.0	固定底座	仅末端执行器，不可移动

场景设置

• sim_warehouse_v4.usda 模式：shell + lights + racks + PhysicsScene + 地面碰撞体。
• 外壳（sm_warehouse_mega.usd）的单位是 cm；机器人和设备的单位是米。
• 离线移除环境资产中的物理配置。在大型场景中，运行时移除会导致核心转储。

PhysicsScene

from pxr import UsdPhysics, PhysxSchema

physics_scene = UsdPhysics.Scene.Define(stage, "/World/PhysicsScene")
physics_scene.CreateGravityDirectionAttr().Set((0, 0, -1))
physics_scene.CreateGravityMagnitudeAttr().Set(9.81)

physx_scene = PhysxSchema.PhysxSceneAPI.Apply(physics_scene.GetPrim())
physx_scene.CreateEnableCCDAttr().Set(True)
physx_scene.CreateEnableStabilizationAttr().Set(True)
physx_scene.CreateSolverTypeAttr().Set("TGS")
physx_scene.CreateTimeStepsPerSecondAttr().Set(60)
physx_scene.CreateGpuMaxNumPartitionsAttr().Set(8)   # 10+ robots

网格放置

import math

def place_robots_grid(stage, robot_usd_path, prefix, count, spacing=3.0, start_z=0.0):
    cols = math.ceil(math.sqrt(count))
    robots = []
    for i in range(count):
        row, col = divmod(i, cols)
        x, y = col * spacing, row * spacing
        prim_path = f"/World/Robots/{prefix}_{i}"
        ref = stage.OverridePrim(prim_path)
        ref.GetReferences().AddReference(robot_usd_path)
        from pxr import UsdGeom, Gf
        xform = UsdGeom.Xformable(ref)
        xform.ClearXformOpOrder()
        xform.AddTranslateOp().Set(Gf.Vec3d(x, y, start_z))
        robots.append(prim_path)
    return robots

间距

• 移动机器人：中心之间至少间隔 2 m。
• 关节机械臂：至少为工作半径的 1.5 倍。
• 空中机器人：高度错开至少 2 m。

碰撞组

from pxr import PhysxSchema

def create_collision_group(stage, group_path, robot_paths):
    group = PhysxSchema.PhysxCollisionAPI.Apply(stage.DefinePrim(group_path))
    for path in robot_paths:
        prim = stage.GetPrimAtPath(path)
        collision_api = PhysxSchema.PhysxCollisionAPI.Apply(prim)
        collision_api.GetCollisionGroupsRel().AddTarget(group_path)

缩放限制（按 VRAM）

限制大致随可用 VRAM 线性变化。超过以下阈值会有 CUDA OOM 风险。

指标	12 GB	24 GB	48 GB	96 GB	备注
prim 总数	~12K	~25K	~50K	~100K	线性扩展
机器人数量	<= 2	<= 5	<= 10	<= 20	取决于复杂度
每个机器人上的活动刚体	~200	~200	~200	~200	每个机器人恒定
关节结构（多自由度）	<= 2	<= 5	<= 10	<= 20
渲染分辨率	1280x720	1600x900	1920x1080	2560x1440	单个视口

优化：

• 在 URDF 的 config.yaml 中设置 make_instanceable: true（共享网格数据）。
• 对远处的机器人切换 LOD。
• 禁用活动区域之外机器人上的物理功能。

导航

差速驱动运动学：

vL = (vx - omega * tw/2) / wheel_r
vR = (vx + omega * tw/2) / wheel_r

PD 转向默认值：KP=2.5、KD=1.2、MAX_W=1.5，航点容差为 4.0 m。越界条件：|Z| > 50 或 |X|/|Y| > 500 -> 标记为失效。

相机

跟随相机：位于后方 12 m，最小高度 2.5 m，限制在仓库边界内，使用平滑插值 alpha = min(1.0, DT*2.0)。动态抬高相机以避开货架遮挡。

视图模式（每 4 s 切换）：跟随、俯视（z=50 m）、巷道（平视）、广角（z=20 m，yaw=0）。

照明（仓库默认值）

参数	值
filmISO	100-120（200 会过曝，80 会使巷道过暗）
DomeLight	强度 150，颜色 (0.85, 0.88, 0.95)
Fill SphereLights	强度 1200，颜色 (1.0, 0.95, 0.85)，高度 8-9 m
RectLights	安装在天花板上，与巷道对齐

渲染

• RayTracedLighting（RT2），1920x1080。
• 使用 hideUi=1 的 320x240 窗口以节省 GPU 资源。
• 始终设置 DISPLAY=:0；复杂区域的无头视口初始化会失败。
• maxBounces=7、aovs=none。

计时

DT = 1/60
Settle: 200-500 frames after timeline.play()
Capture: every 4th step (15 fps)

工作流：多机器人仿真

1. 接收请求（例如：“在仓库中部署 6 台 Nova，仓库有 100 个货架”）。
2. 构建场景：加载仓库 USD，通过 place_robots_grid 放置机器人。
3. 如有需要，创建碰撞组。
4. 使用 usd-pipeline 验证网格缩放和着色器。
5. 在持久会话中运行：通过 isaac-sim-remote（Python 服务端）实时迭代，或使用 isaac-sim.sh --exec script.py 运行独立任务或交接任务。
6. 每 100 步运行一次渲染脉冲循环。
7. 使用 isaac-sim-validator 验证渲染结果。
8. 交付视频和最终场景。

工作流：Physical AI 端到端流水线

适用于涉及资产导入、物理、传感器和验证的任务的路由链（例如：“导入一台 Franka 机械臂，模拟抓取，采集 LiDAR + RGB 数据并进行验证”）。

流水线阶段

┌─────────────────────────┐     ┌──────────────────────┐     ┌───────────────────┐     ┌─────────────────────┐
│ 1. Asset Import         │────▶│ 2. Physics Setup     │────▶│ 3. Sensor Attach  │────▶│ 4. Validate & Ship  │
│                         │     │                      │     │                   │     │                     │
│ urdf-mjcf-to-usd-conv  │     │ physics-simulation   │     │ isaac-sim-sensor  │     │ isaac-sim-validator │
│ usd-pipeline            │     │ usd-articulation     │     │ isaac-camera      │     │ isaac-sim-rendering │
│ usd-composition-arch    │     │                      │     │ isaac-sim-remote  │     │                     │
└─────────────────────────┘     └──────────────────────┘     └───────────────────┘     └─────────────────────┘

阶段 1 — 资产导入

输入	技能	输出约定
URDF/MJCF 文件	urdf-mjcf-to-usd-conversion	包含 IsaacRobotAPI、IsaacLinkAPI、IsaacJointAPI 和碰撞网格的 USD
USD 环境资产	usd-pipeline	经过测量、着色器分类并已放置，且包含边界框偏移的资产
多层组合	usd-composition-architecture	根层 + 物理层 + 外观层

交接至阶段 2：磁盘上已有 USD 文件，已知 prim 路径；对于 RL 工作负载，设置 make_instanceable: true。

阶段 2 — 物理设置

输入	技能	输出约定
已导入的 USD stage	physics-simulation	PhysicsScene（重力、求解器、时间步长、CCD）、每个 prim 的 RigidBodyAPI/CollisionAPI/MassAPI、接触材质、关节驱动
多自由度机器人	usd-articulation	Articulation 根节点、关节层级、驱动刚度/阻尼

阶段 1 的先决条件：

• 机器人 USD 的根节点必须具有 IsaacRobotAPI（由导入器应用）。
• 静态环境 prim 只需要 CollisionAPI（不需要 RigidBodyAPI）。
• 即使导入器已应用各关节属性，也始终在此处创建 PhysicsScene。

交接至阶段 3：仿真运行时不会崩溃，机器人在重力作用下保持姿态 200 帧。

阶段 3 — 传感器挂载

输入	技能	输出约定
稳定的仿真 stage	isaac-sim-sensor	挂载在机器人连杆下的传感器 prim，以及带标注器的渲染产品
相机内参	isaac-camera	已配置镜头模型和焦距参数的 USD 相机
运行时验证	isaac-sim-remote	实时推送传感器配置并验证数据流非零

安装点约定：传感器挂载在机器人连杆下的 Xform prim 上。如果导入的 URDF 缺少安装连杆，请创建一个：

mount = UsdGeom.Xform.Define(stage, f"{robot_path}/{link_name}/sensor_mount")

交接至阶段 4：至少获得一帧非零传感器数据（深度值 > 0、点云非空、IMU 报告重力）。

阶段 4 — 验证并交付

输入	技能	检查项
完整仿真脚本	isaac-sim-validator	无已弃用的导入、无硬编码路径、存在灯光、渲染结果非黑屏
渲染帧	isaac-sim-rendering	帧质量、ACES 色调映射、分辨率
运行时行为	（手动或脚本化）	物理：机器人保持着地，无 NaN。传感器：数据流符合预期范围

验证器是交付的门槛，但不涵盖运行时物理或传感器正确性。进行运行时检查时，请验证：

1. RigidBodyAPI.GetVelocityAttr() 在整个仿真时段内始终为有限值。
2. 传感器标注器数据的形状与配置的分辨率/通道一致。
3. Articulation 关节位置保持在驱动限位范围内。

端到端流程

1. 阶段 1a — 将请求中的功能映射到上述流水线阶段。
2. 阶段 1b — 单独验证各个阶段：
   • 导入：USD 加载时无错误，基元数量与 VRAM 容量相符。
   • 物理：机器人保持姿势，timeline.play() + 200 帧运行稳定。
   • 传感器：在简化场景中，一个传感器即可生成有效数据。
3. 阶段 2 — 逐步集成（导入 → 物理 → 传感器），每次添加后重新检查稳定性。
4. 阶段 3 — 运行 isaac-sim-validator，捕获最终输出并交付。
5. 阶段 4 — 按照 skill-distillation 提炼经验。

调试协议

渲染

问题	操作
黑帧	确保存在 DomeLight + DistantLight；强制设置 settings.set("/rtx/rendermode", "RayTracedLighting")；检查 nvidia-smi
颜色失真	使用 ACES 色调映射（/rtx/post/tonemap/op=4）；仓库场景将 filmISO 设为 600；移除 PathTracing
卡顿	设置 DT=1/60；设置 setTimeStepsPerSecond=60；调整显示帧率，而非物理帧率
破裂	检查网格完整性；降低凹凸／法线贴图分辨率；使用低分辨率碰撞网格
关节运动异常	设置 SolverType=TGS（fabric）；设置 maxPositionIterations >= 6；设置 make_instanceable: true
OOM 崩溃	运行 pkill -f "kit/kit"；清理 /dev/shm/carb-*；减少 num_envs

资产加载

问题	操作
资产渲染为黑色	使用 UsdPreviewSurface 或双着色器；使用相对路径（./meshes/asset.usd）；在有效时确认其为可实例化
变换错误	检查 mpu（默认值为 1.0）；放置前应用偏移；使用 measure_asset() 验证
网格缺失	路径区分大小写；使用绝对路径；通过 stage.GetPrimAtPath() 验证

训练

问题	操作
损失为 NaN	降低 LR；将奖励裁剪到 [-5, 5]；检查发散的遥操作基准
奖励始终为 0	添加密集型塑形奖励；将奖励缩放降低 50%；添加输入噪声以便探索
价值发散	提高目标网络更新频率；使用优先经验回放；增大批次

操作规则

• 永远不要删除工作文件夹；应重复使用并创建分支。
• 始终保存 .usd 文件；不要假设它只存在于内存中。
• 验证每次渲染；绝不交付黑帧。
• 每个长时间运行的进程都必须可终止（使用 pkill 或 pidfile）。
• 生成的脚本中不得直接使用 ~/；应展开为 $HOME 或 $ENV_VAR。
• 所有 RL 机器人都设置 make_instanceable: true。
• 切换摄像机后调用 simulation_app.update() 5 次。
• 在 timeline.play() 之前绝不要导入 torch。
• 每个 epoch 都记录 GPU 内存。
• 延迟加载 HoD 资产（按需解压）。
• 在任务结束时运行 skill-distillation（请求循环的第 5 步）。将经验记录在相关的 SKILL.md 中，而不是临时记忆中。