用途
Isaac Sim Validator 是一个面向 Isaac Sim 交付物的交付前质量门禁，目标是拒绝常见交付缺陷，包括黑帧、已弃用导入、硬编码用户路径、缺失灯光、错误渲染模式以及过小的 SimulationApp 配置。它被作为交付前的最终关口使用，对未通过检查的输出予以拒绝，不软化结果。
运行级别与执行风险
Level 1–2 仅做静态检查。Level 3 会在超时约束下、以调用用户的权限运行目标 Python 脚本。Level 3 需要显式传入 --confirm-execute（或 CONFIRM_EXECUTE=1）进行选择确认；它并非沙箱。警告：Level 3 以你的完整用户权限执行目标脚本，没有容器或沙箱隔离。仅对完全信任的脚本使用 --confirm-execute。
前提条件
- 已构建的 Isaac Sim（$ISAAC_SIM_DIR 或 _build/linux-x86_64/release）。
- 安装当前驱动的 NVIDIA GPU（nvidia-smi）。
- 来自 isaac-sim-orchestrator 的 shell 环境契约：$ISAAC_SIM_DIR、$ISAAC_LAB_DIR、$WORKSPACE_DIR。
使用方式
可通过暴露技能执行辅助函数的智能体运行时调用：
run_script("scripts/validate_sim.sh", args=[])
也可在已构建的 Isaac Sim 目录树中，从 _build/*/release 使用 ./python.sh（Linux）或 python.bat（Windows）运行同一文件；对于不需要模拟器的 shell 辅助脚本，可直接执行。
命令行运行：
# 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> ...
主要检查能力
通用检查清单覆盖：脚本路径是否存在且可读；文件大小是否大于 1 KB；isaacsim 导入是否使用 isaacsim.* 而非已弃用的 omni.isaac.core；SimulationApp 配置是否显式指定 width 和 height；是否包含灯光（DomeLight 强度 >= 100、DistantLight >= 500）；渲染模式是否为迭代用的 RayTracedLighting；ACES 色调映射（carb rtx.post.tonemap.op = 4 及 filmIso 建议值）；最终渲染是否 >= 150 KB 且 mean_RGB > 30；是否避免硬编码用户路径；是否避免裸 IP 或非 localhost 主机；输出目录是否可配置；VRAM 余量；pkill -f "kit/kit" 使用情况；仿真时长是否 >= 3 秒物理时间。
USD 场景文件结构校验覆盖：$ISAAC_LAB_DIR/scripts/ 只读引用、get_assets_root_path() 的 s3:// 缓存处理、Melting/Splat MDL-only 着色器过滤、RL 用的 MakeInstanceable、表面 usdPreviewSurface、convex_decompose_mesh 取值、mpu=0.01 的适用性。
渲染帧分析覆盖文件大小、Mean RGB、Max RGB、像素方差、颜色直方图、物体可见数量、阴影一致性。视频校验要求对交付的 MP4/GIF 至少抽取并检查起始/中间/结束帧。RL 训练校验覆盖 AppLauncher 顺序、Task init.py 为空、isaaclab.* 导入、PhysX 后端（Newton 适用时）、PYTHONUNBUFFERED=1、GPU 内存日志、批次大小、checkpoint 命名、随机种子多样性。资产与 shell 校验覆盖 docker 挂载、子智能体 workdir、Blender USD 导出、场景复杂度、ghost 清理。
另有决策树流程从“是否提供脚本”逐步判断至“VALID - deliver”。
适用场景
用于 Isaac Sim 交付物，触发语句如“validate this Isaac Sim script”“check this Isaac Sim render”“review this sim output”。输入来源包括 isaac-sim-orchestrator、isaac-sim-rendering、其他生产者技能及子智能体输出。
限制
- Level 1–2 无法证明每个工作负载的运行时正确性。
- Level 3 仅在 --confirm-execute 后执行不受信任的脚本内容；没有容器/firejail 隔离。
- 阈值针对常见 demo/SDG 失败，并非覆盖全部产品功能。
故障排查
- 扩展或导入未找到：$ISAAC_SIM_DIR 错误或构建陈旧；将环境变量指向 _build/linux-x86_64/release 或重新构建。
- 黑帧或空帧：缺失灯光或非 RTX 渲染模式；添加 dome/key 灯光并确认 RTX/PathTracing 设置。
- 在 stage 加载或首次渲染时挂起：MDL 编译或 stage 过大；遵循 isaac-sim-troubleshooting 中的隔离步骤。
回复格式
通过：Valid: <one-line summary>；失败：Invalid: <list of failed checks>；建议（仅在否则有效时）：Could be improved: <tip>。不要含糊其辞，不要交付黑帧。
反馈循环
拒绝结果会回流到生产技能的失败模式目录；反复出现的失败会成为新的校验规则。固定评分标准见 references/quality-criteria.md，每次迭代记录在 references/feedback-log.md。