omniverse-cad-to-simready

CAD 到 SimReady

适用场景

当用户需要从源资产到 SimReady 资产或软件包的端到端工作流时，使用此工作流技能。此技能会直接协调现有的转换、创作、验证、符合性检查、渲染和打包参考。不要用单个大型运行器命令替代此工作流。

此技能由文档驱动，不附带 scripts/run.py。它不应依赖仓库检出内容。当某个阶段需要确定性执行时，请运行该阶段参考资料安装目录中的可移植脚本。声明 Shell 是因为此工作流会直接调用已安装的阶段参考脚本；但仍不得添加大型运行器。

前置条件

• 优先先运行 preflight 参考，以完成确定性设置。它会安装或验证本地上游检出内容，写入 cad-to-simready-preflight.json 清单，并为下游参考导出 PHYSICAL_AI_PREFLIGHT_MANIFEST 和 PHYSICAL_AI_REQUIRE_PREFLIGHT=1。
• Python 3.12 和 uv（依据仓库 README.md）。
• 如果要运行本地 Content Agents 部署，则需要 NVIDIA_API_KEY，可从 https://build.nvidia.com 获取。已运行的端点也可以改用显式端点变量和用量令牌，例如 NGC_API_KEY、NVCF_API_KEY 或 CONTENT_AGENTS_*_TOKEN。
• Content Agents 和 OVRTX 阶段需要 Docker、NVIDIA Container Toolkit 和 NVIDIA GPU。
• 如果下游阶段需要上游脚本或规范，则需在 ${PHYSICAL_AI_SKILL_HUB_UPSTREAM_ROOT:-$HOME/.physical-ai-skill-hub/upstreams} 下检出本地上游仓库。

最小可行范围

仅转换也是有效的工作流请求。当用户只要求转换源资产或对源资产转换进行冒烟测试时，将 property_assignment_intent=skip，不要部署 Content Agents，运行 convert-to-usd；如果转换成功，再对生成的 USD 运行 validate-usd-minimum。

不要声称 uv sync 会安装所有源格式转换器运行环境。URDF、MuJoCo/MJCF 和仓库的 Python 依赖由项目环境处理，但基于 NVIDIA 的源格式转换需要安装并验证 NVIDIA-Omniverse/usd-convert-cad 检出内容。如果缺少该运行环境或它不支持源格式，请保留受阻的转换报告及其 install_hint，不要尝试用户未要求的本地构建，也不要换用其他转换器。

首要操作

对于任何宽泛的 CAD/源资产到 SimReady 的请求，除非用户明确要求仅转换、仅验证或不分配材质/物理属性，否则默认设置 property_assignment_intent=run。

在调用转换器、验证、Content Agents、OVRTX、打包或 FET 辅助脚本之前，运行 preflight 参考流程，或验证现有的 PHYSICAL_AI_PREFLIGHT_MANIFEST。将 preflight 视为强制依赖项引导步骤，而不是工作流路由。如果用户明确要求不要部署服务，或要求仅转换/仅验证，请使用 --skip-content-agents。 当设置了 PHYSICAL_AI_REQUIRE_PREFLIGHT=1，且清单中某个必需组件尚未就绪时，下游参考流程必须触发 preflight 防护措施并阻止执行，不得直接重新发现上游组件或服务。

当 property_assignment_intent=run 时，确认源路径并确定意图后的首个实际操作，是验证或部署 Content Agents 服务。此操作必须在资产上下文检查、转换器依赖项检查、转换、验证、一致性检查、渲染、打包或上游源构建之前完成。

如果现有端点可用且健康，请使用这些端点。如果 OVRTX、Material 或 Physics 端点缺失或不健康，请先运行 deploy-content-agents，在共享的独立 OVRTX 渲染器以及独立的 Material 和 Physics 服务容器均已就绪，并通过 CONTENT_AGENTS_*_BASE_URL 导出之前，不得继续。如果请求生成纹理，也要部署 Texture Agent。

如果缺少所需的部署身份验证信息，请向用户索取 NVIDIA_API_KEY 并等待。如果提供的端点需要使用身份验证，则改为索取相应的使用令牌。如果部署无法使服务达到健康状态，请报告 Content Agents 尚未就绪并阻止后续操作，不得继续转换。

说明

1. 确认源资源路径存在，解析 output_root，并将请求分类为端到端、仅转换、仅验证或打包。
2. 在运行任何资源检查、转换器探测、转换、验证、符合性检查、渲染或打包步骤之前，先解析 property_assignment_intent。
3. 为所选工作流目标运行 preflight，除非已配置就绪的 PHYSICAL_AI_PREFLIGHT_MANIFEST。运行下游脚本前，先引入生成的 env 文件。将 preflight 仅视为依赖项设置：它可以使用提供的 --source-asset、--source-format 或 --conversion-tools 值来限定依赖项检查范围，但实际转换支持仍由 convert-to-usd 和上游转换器引用决定。
4. 当 property_assignment_intent=run 时，先验证或部署 Content Agents 服务；如果缺少身份验证信息或服务不健康，则阻止后续操作，不要继续。
5. 阅读 references/workflow.md 和 references/commands.md，然后仅运行当前请求所需的阶段参考。
6. 当可进行 Web 搜索或将运行属性分配时，对原始源资源运行 identify-asset-context。
7. 将源文件交由 convert-to-usd 处理；如果输入已是 USD，则跳过转换，并将源路径视为当前 USD 路径。
8. 在昂贵的下游工作之前运行 validate-usd-minimum。这仅作为可行性关卡：记录单位或配置文件问题，例如 metersPerUnit != 1.0，但如果将运行属性分配，则在 Content Agents 分配之前不要运行 simready-conform-profile、FET001 或任何其他 FET 修复。
9. 根据请求或需要，在转换后且通过最小验证的 USD 上运行 Content Agents 材质、物理属性和可选纹理分配。
10. 属性分配后，在最新的仿真 USD 路径上运行 simready-conform-profile，并保留每份已选 FET 修复报告。
11. 按顺序运行验证关卡：omni-asset-validate、omni-asset-validate-geometry、omni-asset-validate-physics 和 simready-validate。
12. 如果 simready-validate 报告了可修复的要求，则重新运行 simready-conform-profile，然后对最新编写的 USD 重新运行配置文件验证。
13. 如果请求了预览图、缩略图或检查图像，则运行 ovrtx-render-service。如果请求了打包输出，则接着运行 assemble-package-source，从最终 USD 和缩略图创建干净的 deliverable/ 打包源，然后仅针对该交付文件夹运行 nv-core-package-sample 和 nv-core-package-sample-validation。
14. 输出汇总工作流报告，其中包含最终 USD 路径、所有阶段报告、验证结果、重新运行原因和后续工作。

仅当 property_assignment_intent=run 且已完成属性分配后，才使用 simready-conform-profile 参考。它会将功能修复路由至上游 SimReady Foundation FET 技能，例如分支 main 中的 simready-foundation-conform-fet-000-core、simready-foundation-conform-fet-001-minimal、simready-foundation-conform-fet-004-simulate-multi-body-physics 和 simready-foundation-conform-fet-005-simulate-grasp-physics。 如果 simready-validate 在首次符合性检查后报告了可修复的要求，请将结构化要求 ID 反馈给 simready-conform-profile 参考文档，再编写最终结果。特别是，GSP.001 由上游 simready-foundation-conform-fet-005-simulate-grasp-physics 负责；如果视觉能力 Agent 能检查视觉证据，或已提供明确的抓取点，请运行该技能，否则应将 FET005 步骤记录为因缺少视觉能力或抓取点而受阻，而不要将其视为可选的预览任务。 对于 RB.MB.001，请将失败转交给上游 simready-foundation-conform-fet-004-simulate-multi-body-physics。不要假设多个视觉 prim 就是多个刚体；请检查 UsdPhysics.RigidBodyAPI 的应用情况。当 Physics Agent 报告显示已组合拓扑优化，或 USD 中已有组件碰撞体／部件根节点，且配置文件验证器报告 FET004／RB.MB.001 时，FET004 应将这些现有组件提升为刚体，而不创建几何体。只有在确认可复用的刚体候选少于两个后，才能将此门槛标记为不适用。

输出格式

以 Markdown 输出一份汇总工作流报告；如果工作流会写入结构化产物，也请包含 JSON。报告必须包括：

• 总体状态：passed、blocked、failed 或 needs_rerun。
• 请求摘要：源资产路径、检测到的源格式、输出根目录、所选 SimReady 配置文件／版本，以及属性分配意图。
• 按顺序排列的阶段结果：阶段参考、输入产物、输出 USD 或 USDZ 路径、报告路径、状态、阻塞原因，以及适用时的重跑原因。
• Content Agents 就绪情况和属性分配结果，并对服务 URL、令牌和凭据进行脱敏。
• 按门槛、要求 ID、所选 FET 修复参考、修复循环尝试和最终处置分组的符合性与验证结果。
• 最终产物：最终报告的 USD 路径、按需生成的渲染预览路径、打包根目录及打包验证报告（若执行了打包）、Markdown 报告路径、JSON 报告路径（若存在），以及建议的后续工作。

详细参考文档

仅阅读当前请求所需的参考文档：

• references/preflight/README.md：确定性的本地设置、清单／环境变量约定、Linux 和 Windows 封装脚本、Content Agents 部署退出选项，以及防护机制。
• references/workflow.md：输入、源路由、详细工作流、验证策略、输出报告字段、审批节点和后续步骤。
• references/commands.md：各阶段的具体便携式脚本命令模式。
• references/assemble-package-source/README.md：双区打包源组装、规范根 USD 命名、缩略图放置位置，以及自包含交付物检查。

发布布局说明

将 skills/omniverse-cad-to-simready/ 作为此产品仓库中该技能的权威来源。.agents/skills 符号链接是为了兼容本地 agentskills.io 风格发现而设的别名；.codex/skills 和 .claude/skills 是面向特定 Agent 的兼容别名。

Frontmatter 将 version 和 tools 保留在顶层，以兼容 agentskills.io 运行时。NVCARPS 可发现性字段位于 metadata 下。

嵌套的 references/ 树是有意设计的。它既保留了一个公开目录技能，也在工作流下保留了包含脚本的原子阶段参考文档、上游交接说明和路由器文档。不要扁平化这些参考文档，也不要将嵌套的 README 参考文档提升为同级的 SKILL.md 文件，除非仓库的发布模式发生变化。

限制

• 此工作流会协调现有的转换、属性分配、符合性检查、验证、渲染和打包技能；不会用一个单体运行器命令取代它们。
• 除非用户明确要求尽力继续，否则在部署、转换、属性分配或符合性检查编写环节首次失败时停止。
• 上游 simready-foundation-conform-fet-005-simulate-grasp-physics 需要经过视觉审查或提供明确的抓取点，才能编写有意义的抓取向量。

故障排除

症状	原因	修复方法
下游引用报告 cad-to-simready 预检尚未准备好组件	已设置 PHYSICAL_AI_REQUIRE_PREFLIGHT=1，但清单缺失，或所需的运行时/服务未处于 ready 状态	运行 preflight/scripts/preflight.py，加载生成的环境文件，或者仅当 Content Agents 不在范围内时，才使用 --skip-content-agents 显式禁用服务部署。
工作流在 GSP.001 处停止，并将失败报告为未分类	未向 FET005 提供视觉证据或明确的抓取点	只有在具备视觉能力的 Agent 审查过资产后，才运行上游 simready-foundation-conform-fet-005-simulate-grasp-physics；或者传入明确的抓取点。否则，应将 FET005 步骤报告为 blocked，而不是失败。
已生成有意义的 USD 产物，但验证失败	工作流在首次发现验证问题时停止	继续执行其余诊断环节，并将结果标记为 needs_rerun。生成 USD 产物后，不要因验证问题而停止。
属性分配阶段因缺少服务端点而失败	转换前未部署 Content Agents 服务	先运行 deploy-content-agents。如果要执行属性分配，在 Content Agents 就绪前，不要开始资产检查、转换、验证、符合性检查、渲染或打包。
Material Agent 报告修复单位或配置文件后渲染产生了 0 images	在 Material Agent 之前应用了 FET 修复（通常是 FET001 单位规范化），更改了服务所使用的 USD 分层/场景状态	从转换后的/最低有效 USD 重新执行分配：先运行 Material Agent，再运行 Physics Agent，然后在服务生成的最新 USD 上运行 simready-conform-profile 和 FET 修复。
Material 或 Physics Agent 的本地优化路径报告 Permission denied: '/app/.build-resources/scene_optimizer_core/python'	本地 Docker Scene Optimizer 包的权限导致非 root 服务用户无法读取打包的 SO 运行时	使用 docker exec --user root content-material-agent-service chmod -R a+rX /app/.build-resources/scene_optimizer_core 或 docker exec --user root content-physics-agent-service chmod -R a+rX /app/.build-resources/scene_optimizer_core 修复相应的本地容器，然后重新运行相同的优化 Agent 命令。对于实例化/原型资产，不要将无优化器回退视为根本原因。
资产包含许多 prim，但 RB.MB.001 仍然失败	配置文件统计的是 UsdPhysics.RigidBodyAPI prim，而不是可视或碰撞 prim；Physics Agent 可能只在根节点编写一个刚体	转交上游 simready-foundation-conform-fet-004-simulate-multi-body-physics。首先确保 Physics Agent 在适用时使用了组合拓扑优化；然后，如果活动配置文件报告 FET004/RB.MB.001 且无需创建几何体，则提升现有组件碰撞体/部件根节点。

硬性规则

• 优先使用预检清单中的本地上游根目录、转换器可执行文件、SimReady 验证运行时、OVRTX 端点和 Content Agents 服务 URL。当设置了 PHYSICAL_AI_REQUIRE_PREFLIGHT=1 时，不要绕过清单直接发现上游资源。
• 如果将执行属性分配，在 Content Agents 就绪之前，不要运行资产检查、转换器探测、本地上游构建、转换、验证、一致性检查、渲染或打包。
• 直接使用按阶段划分的已安装参考脚本。不要添加或调用单一的 omniverse-cad-to-simready 运行器命令。
• 对于源格式转换，委托给 convert-to-usd 参考；不要使用其他转换器替代 CAD 或网格格式的转换器。
• 对于属性分配，将 Content Agents 参考作为彼此独立的原子步骤使用：先处理材质，再处理物理属性，仅在用户要求时处理纹理。
• 如果将执行属性分配，在 Content Agents 之前，不要运行 simready-conform-profile 或任何 FET 辅助程序。先验证 USD 是否满足最低要求，然后对转换后且满足最低要求的 USD 运行 Content Agents，之后再对服务生成的最新 USD 应用 FET 修复。
• 如果将执行属性分配，在 Content Agents 之前，不要运行 simready-validate 或任何 SimReady 配置文件验证。在调用服务之前，唯一允许的验证关卡是 validate-usd-minimum，它用于检查 USD 的基本可行性。
• 除非用户明确要求尽力继续，否则在部署、转换、属性分配或一致性检查创作关卡首次失败时停止。
• 如果已有有意义的 USD 工件，不要因验证发现的问题而停止。继续执行其余诊断关卡，并将结果标记为 needs_rerun。
• 不要让 GSP.001 配置文件失败成为未分类的最终发现。将其交由上游 simready-foundation-conform-fet-005-simulate-grasp-physics 处理；如果当前 Agent 无法检查渲染结果，或者没有明确的抓取点，则报告 FET005 修复受阻，并提供视觉证据路径或缺少输入的原因。
• 保留每个阶段的报告，并将各报告中具体的输出 USD 路径传递到下一阶段。