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 模型提供方密钥；如果使用已运行的端点，则需要显式的端点变量和使用令牌。完整列表请参见 references/preflight/README.md。
• Content Agents 和 OVRTX 阶段需要 Docker、NVIDIA Container Toolkit 和 NVIDIA GPU。
• 如果某个阶段需要上游脚本或规范，则需在 ${OMNIVERSE_CAD_TO_SIMREADY_UPSTREAM_ROOT:-$HOME/.omniverse-cad-to-simready/upstreams} 下提供本地上游检出项。

首要操作

对于任何范围较广的 CAD/源资产到 SimReady 请求，除非用户明确要求仅转换、仅验证或不进行材质/物理属性分配，否则应假定 property_assignment_intent=run。 对于仅转换请求，设置 property_assignment_intent=skip，不要部署 Content Agents，运行 convert-to-usd；如果转换成功，再对生成的 USD 运行 validate-usd-minimum。对于仅验证请求，设置 property_assignment_intent=skip，验证用户提供的 USD，不要重新运行转换。

在运行任何转换器、验证、Content Agents、OVRTX、打包或 FET 步骤之前，先运行 preflight（或验证现有的 PHYSICAL_AI_PREFLIGHT_MANIFEST）；将其视为依赖引导，而非工作流路由。对于仅转换/仅验证请求，使用 --skip-content-agents。

当 property_assignment_intent=run 时，在确认源路径并确定意图后，立即验证或部署 Content Agents 服务；此操作必须先于资产上下文检查、转换器依赖检查、转换、验证、符合性检查、渲染、打包或上游源代码构建。明确提供且健康的端点应视为由用户管理；否则运行 deploy-content-agents，它会按顺序部署共享的独立 OVRTX 渲染器、Material、Physics 和可选的 Texture 服务容器。

Instructions

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. 当可进行网络搜索或将运行属性分配时，对原始源资产运行 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 路径、所有阶段报告、验证结果、重新运行原因和后续工作。

Output Format

以 Markdown 格式输出合并后的工作流报告；如果工作流写入了结构化产物，还需包含 JSON。将总体状态报告为 passed、blocked、failed 或 needs_rerun。所需的 Markdown 和 JSON 报告字段见 references/workflow.md。

Detailed References

仅阅读当前请求所需的参考资料：

• references/preflight/README.md：确定性的本地设置、清单／env 契约、包装脚本、部署退出选项和防护机制行为。
• references/workflow.md：输入、源路由、详细工作流、验证策略、输出报告字段和后续步骤。
• references/commands.md：具体且可移植的脚本命令模式。
• references/assemble-package-source/README.md：双区域打包源组装、根 USD 命名、缩略图放置和交付检查。
• references/troubleshooting.md：症状／原因／修复表，以及 FET（GSP.001／RB.MB.001）修复路由详情。
• references/publishing-layout.md：此技能自身文件树的 frontmatter 兼容性字段说明和布局理由。

发布布局说明

使用 skills/omniverse-cad-to-simready/ 作为此产品仓库技能的事实来源。.agents/skills 符号链接是供本地 Agent 按 agentskills.io 风格发现技能的兼容别名，嵌套的 references/ 目录树是有意设置的。别名列表、frontmatter 字段位置和扁平化规则请参阅 references/publishing-layout.md。

限制

• 此工作流会协调现有的转换、属性分配、符合性检查、验证、渲染和打包技能；它不会用单个整体式运行器命令取代这些技能。

故障排查

仅当特定阶段或验证关卡失败时，才阅读 references/troubleshooting.md；该文件包含症状／原因／修复表格和 FET 修复路由。

硬性规则

• 对于本地上游根目录、转换器可执行文件、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 路径传递给下一阶段。