isaac-sim-validator

Isaac Sim Validator

警告： 第 3 级会以你的完整用户权限执行目标脚本。没有容器或沙箱隔离。仅对你完全信任的脚本使用 --confirm-execute。

目的

在所属边界（独立库或 Kit 应用/扩展）拒绝常见的交付缺陷。

第 1–2 级仅执行静态检查。第 3 级会在 timeout 下以调用用户的权限运行目标 Python 脚本。 第 3 级需要明确选择启用 --confirm-execute（或 CONFIRM_EXECUTE=1）；它不是沙箱。

前置条件

• 独立库需要配置好的构建环境或已安装的测试环境。
• Kit 检查需要已构建的 Isaac Sim 目录；只有 GPU 支持的检查才需要 GPU。

限制

• 第 1–2 级无法证明所有工作负载在运行时都正确。
• 第 3 级仅在使用 --confirm-execute 后才会执行不可信的脚本内容；没有容器/firejail 隔离。
• 阈值针对常见的演示/SDG 故障，并不覆盖所有产品功能。

故障排除

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

交付前的最终关卡。拒绝未通过以下检查的输出；不要放宽标准。

对于独立库，需验证常规进程中的公共导入、声明的包/原生依赖闭包、重定位、适用时的 SDK 使用者，以及 isaacsim.common.logging.Logger 诊断信息。不要要求 SimulationApp、渲染或 GPU。

仅适用于 Kit 的验证辅助工具

脚本	用途	参数
scripts/validate_sim.sh	验证仿真	按脚本标头传入位置参数（参见脚本）

运行脚本

对于提供技能执行辅助工具的 Agent 运行时，请使用 run_script() 调用辅助工具：

run_script("scripts/validate_sim.sh", args=[])

在已构建的 Isaac Sim 目录中，从 _build/*/release 使用 ./python.sh（Linux）或 python.bat（Windows）运行同一文件；如果 Shell 辅助工具不需要模拟器，也可以直接执行。

Kit 仿真检查清单

检查项	通过条件	未通过时
脚本路径	存在且可读	拒绝：Script path invalid: <path>
文件大小	> 1 KB	拒绝：Script empty or corrupted
isaacsim 导入	使用 isaacsim.*，而非 omni.isaac.core	拒绝：Use isaacsim.* namespace; omni.isaac.core is deprecated
SimulationApp 配置	明确指定 width 和 height	拒绝：SimulationApp without window args causes swapchain-capture size mismatch
存在灯光	DomeLight（强度 >= 100）且 DistantLight（>= 500）	拒绝：No lighting; render will be black
渲染模式	迭代时使用 RayTracedLighting；仅在英雄镜头中使用 PathTracing	拒绝：PathTracing too slow for iteration; use RayTracedLighting
ACES 色调映射	carb rtx.post.tonemap.op = 4；filmIso 默认为 200 / 深巷场景为 600 / 航拍场景为 400	建议：Enable ACES (op=4) for contrast
最终渲染	>= 150 KB，且 mean_RGB > 30	拒绝：Render is black or low-energy; check lighting
用户路径	不包含 /home/<user>/、硬编码的 C:\path\to\... 或每个 Agent 各自的主目录路径；优先使用 %USERPROFILE%、环境变量或 argparse	拒绝：Hardcoded user path; use $ISAAC_SIM_DIR, $ISAAC_LAB_DIR, $WORKSPACE_DIR, or argparse
网络端点	不包含裸 IP（192.168.x.x、10.x.x.x）或非 localhost 主机	拒绝：Hardcoded endpoint; parameterize via env var or config
输出目录	可配置（环境变量、CLI 或函数参数）	拒绝：Output dir hardcoded; accept as parameter or read $OUTPUT_DIR
VRAM 余量	稳定后 nvidia-smi 显示余量 > 20%	利用率 >90% 时警告；可能存在泄漏或规模问题
是否使用 pkill -f "kit/kit"	检查是否存在杀进程后重新启动的错误	警告：Verify zero kit processes before next launch
仿真时长	物理仿真 >= 3 s	拒绝：Sim ran < 3 s; physics has not settled

文件结构验证（USD 场景）

项目	有效	无效	操作
$ISAAC_LAB_DIR/scripts/	只读参考	在其中写入输出	重定向到 $OUTPUT_DIR 或 $WORKSPACE_DIR/outputs/
get_assets_root_path() -> s3://...	运行时可用	固化在交付的输出中	缓存到本地；通过可配置路径引用
仅支持 MDL 的 Melting / Splat 着色器	原始形式可用	导出时仅支持 MDL	过滤掉；仅支持 MDL 会导致渲染为黑色
RL 的 MakeInstanceable	必需（make_instanceable: true）	缺失	拒绝
表面上的 usdPreviewSurface	必需	缺失	拒绝；建议添加 UsdPreviewSurface
convex_decompose_mesh	false（搭配 clean_sdf_dc）	true	为保证稳定性，建议设为 false
mpu=0.01	适用于仓库外壳（13 m 瓷砖）	用于机器人	拒绝

渲染验证（帧分析）

指标	良好	不佳	操作
文件大小	1–4 MB	~82 KB	82 KB = 黑屏，拒绝
平均 RGB	80–160	< 20	拒绝：Too dark; add lights
最大 RGB	200–250	0	拒绝：No light in scene
像素方差	> 15	< 5	画面平坦 = 缺少阴影；添加强调元素
颜色直方图	多峰	单峰	过曝或光照平坦；调整强度
对象可见性	>= 3 个机器人或 50+ 个资产	可见对象 < 10 个	建议：Scene too sparse; add set dressing
阴影一致性	阴影一致	随机黑块	拒绝：Shadow artifacts; check light cone bounds

视频验证

对于交付的任何 MP4/GIF，至少提取并检查开头、中间和结尾帧。如果开头几帧显示渲染预热、主体被遮挡，或摄像机没有对准任务，则拒绝该演示版本，或重新剪辑。缩短演示片段时，保留完整的源渲染和指标。

RL 训练验证

问题	操作
AppLauncher 不是首个	拒绝：AppLauncher must precede any isaaclab imports
任务的 __init__.py 非空	拒绝：Task __init__.py must be empty; do not import configs
导入 omni.isaac.lab	拒绝：Use isaaclab.*; omni.isaac.lab is deprecated
PhysX 后端（适用 Newton 时）	拒绝：Use Newton; it is the default on Kit 110
缺少 PYTHONUNBUFFERED=1	警告：Set PYTHONUNBUFFERED=1 to see logs in real time
未记录 GPU 内存	建议：Log torch.cuda.memory_allocated()/1e6 to W&B
批次大小超过显存容量	建议：Reduce num_envs (try 2048)
检查点名称错误	拒绝：Must be model_XXXX.zip, not policy.pt
仅有一个随机种子	建议：Run seeds 42, 123, 456 for valid comparison

资源与 Shell 验证

输入	检查项	操作
docker run 命令	为 /workspace/output 添加 -v 挂载	拒绝：Output folder not mounted
启动子 Agent	workdir=$WORKSPACE_DIR	拒绝：Sub-agent workdir hardcoded; use $WORKSPACE_DIR
Blender USD 导出	正确的 mpu、双着色器（UsdPreviewSurface + MDL）、正确的导出类型	任一缺失则拒绝
场景复杂度	在 10 个稳定步骤内完成渲染	拒绝：Scene too complex; simplify assets
残留伪影	清理 /dev/shm/carb-*	拒绝：Use workspace_cleanup.py to clear /dev/shm/carb-*

Kit 决策树

graph TD
    A[Received Output] --> B{Has script?}
    B -->|No| C[Reject: "No script provided"]
    B -->|Yes| D{File size >1KB?}
    D -->|No| E[Reject: "Script empty or corrupted"]
    D -->|Yes| F{Python?}
    F -->|Yes| G{isaacsim.* imports?}
    G -->|No| H[Reject: "Use isaacsim.* not omni.isaac.core"]
    G -->|Yes| I{SimulationApp or --exec?}
    I -->|Neither| J[Reject: "Must use SimulationApp with window args OR isaac-sim.sh --exec"]
    I -->|SimulationApp| K{width and height set?}
    K -->|No| L[Reject: "SimulationApp requires explicit width and height"]
    K -->|Yes| M{Dome + Distant lights?}
    M -->|No| N[Reject: "Add DomeLight and DistantLight (min intensity 100 and 500)"]
    M -->|Yes| O{RayTracedLighting?}
    O -->|No| P[Reject: "Use RayTracedLighting for iteration"]
    O -->|Yes| Q{Render output exists?}
    Q -->|No| R[Reject: "No render output"]
    Q -->|Yes| S{>= 150 KB and mean_RGB > 30?}
    S -->|No| T[Reject: "Render is black, too dark, or corrupted"]
    S -->|Yes| U{Hardcoded user paths or bare IPs?}
    U -->|Yes| V[Reject: "Replace hardcoded user paths/IPs with env vars or args"]
    U -->|No| Y[VALID - deliver]

训练输出

项目	操作
policy_only_XXXX.pt	接受
model_XXXX.zip	接受
log.csv 或 wandb URL	接受
包含 episode 数据的 results.json	接受
无奖励曲线 / 指标	拒绝：Log episode/reward_mean and train/value_loss

回复格式

• 通过：Valid: <one-line summary>
• 未通过：Invalid: <list of failed checks>
• 建议（仅在其他检查均通过时）：Could be improved: <tip>

不要含糊其辞（例如“我认为”“也许”）。不要输出黑帧。

输入来源

• isaac-sim-orchestrator、isaac-sim-rendering、其他生成端技能和子 Agent 输出。
• 在 Isaac Sim 交付物上调用： “validate this Isaac Sim script”、“check this Isaac Sim render”、“review this sim output”。

自动化验证

使用 scripts/validate_sim.sh 从 CLI 运行上述检查：

# Levels 1–2: static only
bash scripts/validate_sim.sh --level <1|2> <script.py> [--output-dir <dir>] [--timeout <seconds>]

# Level 3: EXECUTES the script — requires explicit opt-in
bash scripts/validate_sim.sh --level 3 --confirm-execute <script.py> [--output-dir <dir>] [--timeout <seconds>]
# or: CONFIRM_EXECUTE=1 bash scripts/validate_sim.sh --level 3 <script.py> ...

反馈循环

• 驳回结果会反馈到生成技能的故障模式目录中。
• 反复出现的故障会成为新的验证规则。
• 长期适用的评估标准：references/quality-criteria.md。将每次迭代记录在 references/feedback-log.md 中。