omniverse-usd-performance-tuning

Omniverse USD 性能调优

何时使用

遇到加载缓慢、内存占用高、FPS 低、GPU 崩溃、转换质量排查，或泛泛要求优化 USD 场景等性能问题时，使用此工作流。

说明

1. 除非提示只要求进行静态分类测试，否则在生成调优输出前，先通过强制运行时上下文检查。
2. 将宽泛的优化请求分类为 ready_to_plan；只有当提示明确指出要在规划前执行破坏性操作时，才使用 approval_required。
3. 规划完整的标准流程链，直到 optimization-report；列出里程碑时，保留结构化的里程碑顺序和 profile-stage:baseline / profile-stage:after 标签。对于宽泛的优化请求，默认规划 3 次范围明确的迭代，除非用户选择退出、要求快速处理，或适用停止条件。
4. 只有进入相应阶段时，才调用下游技能主体；将原始运行时产物保留在磁盘上，同时读取精简摘要。

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

输出格式

返回计划或状态摘要，注明所选入口技能；对于通用优化请求，使用 ready_to_plan；包含直到 optimization-report 的完整里程碑链；并将性能分析阶段标记为 profile-stage:baseline 和 profile-stage:after。对于结构化输出，宽泛优化的里程碑子序列为 omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> so-run-validators -> so-interpret-validators -> so-run-operations -> profile-stage:after -> compare-profiles -> optimization-report。端到端执行在运行修改操作时应生成优化后的 stage，并生成符合 optimization-report 参考规范的报告（该参考中的 scripts/optimization-report.schema.json）。默认情况下，宽泛优化应规划 3 次范围明确的迭代；每次迭代都会写入中期报告/更新，后续轮次应复用先前证据，而不是从头重新运行整个工作流。

遇到加载缓慢、FPS 低、内存占用高、GPU 崩溃、转换质量问题，或“优化我的场景”等宽泛性能需求时，使用此工作流。

入口技能规则

只要 Agent 有任何经过验证的途径可以处理宽泛的性能任务，此技能就是指定的入口点。运行时探测的详细信息位于 setup-usd-performance-tuning；此规则只决定哪个技能负责面向用户的性能请求。

• 如果设置探测显示存在任何经过验证的运行时路径——Kit、独立运行环境，甚至 Asset Validator 等部分工具栈——则从此处进入。如果用户要求的工具缺失，应返回具体的 blocked_code（如 blocked_missing_scene_optimizer、blocked_missing_so_operation 等），而不是改用其他工作流。
• 只有在没有任何经过验证的运行时路径，且运行时选择/设置是首个尚未解决的问题时，才从 setup-usd-performance-tuning 进入。
• 对于 omniverse:// 资产，先从 omniverse-authentication 进入。远程资产的身份验证先于设置和排查。

此决策涉及的是职责归属，而不是执行顺序。设置、身份验证和排查都按各自的正常阶段顺序执行；此规则仅规定 Agent 在回复中指定为入口技能的技能。

运行时上下文——会话启动门槛（强制）

在输出任何其他调优内容之前，请遵循 skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md 中规定的强制会话启动门槛。 该参考文件规定了 output_path、规范的 setup-preflight.json 位置、格式 A／格式 B，以及“不要擅自执行无提示探测”这一反模式。

必须达到以下结果：

• 预检缺失或不可读：调用 setup-usd-performance-tuning。
• 预检已存在：打印格式 A，并等待用户选择继续、更改 Kit、切换到独立模式或重新运行探测。
• 同一会话中已确认运行时：后续状态使用精简格式 B。

[Kit: {runtime_context.kit.application} {runtime_context.kit.version}  |  SO: {runtime_context.sceneOptimizer.version}  |  AV: {runtime_context.assetValidator.version}]

运行时产物 Token 预算

读取 Kit 日志、Asset Validator CSV、Scene Optimizer 日志、Tracy CSV 或其他运行时输出之前，请遵循 references/runtime-artifact-token-budget.md。将原始产物保留在磁盘上，先读取摘要 JSON，并使用有界日志快照，而不是完整转储或实时流。

计划时与执行时审批

计划时的 approval_required 仅适用于明确指定破坏性操作的请求。在决定使用 ready_to_plan 还是 approval_required 时，请遵循以下规则：

• 计划时使用 approval_required——用户的请求本身指定了破坏性操作，例如“展平此 stage”“抽稀网格”“合并原型”“删除未使用的 prim”，或任何无法在同一工作流中撤销的具体指定更改。在这种情况下，Agent 的首次回复必须先请求批准并指出该操作，然后才能提交执行该操作的计划。
• 计划时使用 ready_to_plan——用户的请求较为宽泛，例如“优化此场景”“加快加载速度”“减少 GPU 内存”“改善交互性”。Agent 应列出完整计划，包括计划中将调用的任何破坏性操作（例如使用 mergeMaterials 的 so-run-operations），不得隐去计划本身。应在请求批准计划时，一并请求对各项破坏性操作的批准。

两者的区别在于批准计划与批准破坏性操作。宽泛的优化请求授权制定计划，但不授权执行具体的破坏性操作。

对于结构化运行时测试响应及类似的计划摘要：

• 未来的 restructure-decision 提示是计划中的用户决策门槛；对于宽泛的优化请求，不应因此将顶层响应的 decision 设为 approval_required。
• 对于宽泛的优化请求，将 decision 设为 "ready_to_plan"，并在 committed_milestones 和 planned_phases 中包含完整的预期链路，直至 optimization-report。
• gates_observed 可以包含 asks_user_for_restructure_decision，同时顶层 decision 仍为 ready_to_plan。
• 链路提及分析阶段时，必须使用准确标签 profile-stage:baseline 和 profile-stage:after；不得输出含义不明确的裸 profile-stage 标记。
• 结构化里程碑列表必须以作为入口技能的 omniverse-usd-performance-tuning 开头。仅将 setup-usd-performance-tuning 作为额外的 Phase 0 上下文，不得用它替代入口技能里程碑。
• 对于宽泛的优化请求，必须严格保留上述 Output Format 中的里程碑子序列；仅可在不会改变其顺序的位置插入额外分析步骤。
• 在宽泛优化的里程碑摘要中，不得将 so-run-validators 或 so-interpret-validators 列在 restructure-decision 之前。分阶段的验证器路由仍通过 usd-validation-runner 进行；根据结构化计划约定，SO 验证器执行器／解释器里程碑应出现在重组决策路径之后。

输出预期

端到端优化工作应同时生成优化后的 USD stage（执行变更时）和结构化优化报告，且报告须符合 optimization-report 参考中的 scripts/optimization-report.schema.json。HTML 报告必须通过 render_preview.py 根据 references/report-templates/optimization-report.html.template 渲染——切勿手动编写 HTML。仅诊断工作也应以报告或摘要收尾，并明确说明未写入优化后的 stage。

目的

将数字孪生 USD 性能请求路由到正确的诊断和优化工作流，同时在变更前保留证据。

前提条件

• Stage 路径，或足以识别目标资产的上下文。
• 用户目标：仅诊断、验证、性能分析或执行处理器。
• 如果尚未确定，需获取 setup-usd-performance-tuning 提供的运行时可用状态。
• 原位变更与写入单独的优化输出的权限状态。

示例

• “这个 USD 加载很慢；先排查哪些方面？”
• “通过性能工作流处理一个低 FPS 的 CAD 场景。”

分流顺序

0. 运行时门禁。 在验证、性能分析或优化之前，遵循上文规定的强制会话启动门禁。不要在此技能中直接扫描、探测、安装或选择 Kit/standalone 运行时；setup-usd-performance-tuning 负责探测、选择器和安装的调度，并生成此处使用的预检结果。

1. 确定目标问题：

   • 加载时间。
   • FPS 或交互性。
   • GPU 或系统内存。
   • 崩溃或设备丢失。
   • CAD 转换质量。
   • 验证失败。

2. 收集最低限度的上下文：

   • Stage 路径和大小。
   • Stage 位于本地、挂载位置还是 omniverse:// 远程位置。对于远程资产，首次打开前先转到 omniverse-authentication。
   • Kit 或 USD 运行时。
   • 工作负载属于 CAD、VFI、AIF、Isaac，还是通用 OpenUSD。
   • 是否允许原位变更。
   • 用户需要仅诊断还是执行处理器。

3. 路由：

   • USD 合成问题：usd-structure-assessment（合成现已纳入 SA 总体流程；更深入的详情见 skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md）。
   • 验证和内容问题：usd-validation-runner（主路由器；根据意图转到 validate-* 系列或 so-run-validators）。
   • 编辑/输出决策：usd-edit-target-planner（也负责变体/载荷门禁）。
   • 存在重复复制的层级结构或网格数量过多且未使用实例化： usd-hierarchy-dedupe-candidates。
   • 重构决策（单体 Stage、资产边界实体化）：restructure-decision。
   • CAD 转换器设置：阅读 references/cad-conversion/README.md（这是 USD 前的特殊问题；详情见参考文档）。
   • Scene Optimizer：so-run-validators、so-interpret-validators、so-run-operations。

优化顺序

遵循 workflow.md § 操作顺序不变量 中的规范顺序。 高层规则：先处理原型 → 再验证单个资产 → 最后执行 Stage 级操作。 工作流参考文档包含完整的不变量列表（如 meshCleanup 必须在 decimateMeshes 之前执行、先去重再抽稀、存在实例时绝不合并等）以及仅分析操作目录。

规则

• 修改前始终运行构成审计。
• 处理器执行前后始终进行验证。
• 按资产验证前先优化原型。
• 对非常大的 CAD 场景，先检查层级级别的复用，再运行全场景网格去重。
• 没有瓶颈证据时，不要推荐固定的优化方案组合。
• 不要臆造数值阈值或预期收益百分比。
• 优先选择规范的 SO 操作，而不是专用或说明性操作。 references/operations/_curation.json 中的操作筛选将每项操作归类为 canonical、specialty、analysis、documentary 或 deprecated。如果多个操作都可能解决同一问题，应先推荐规范操作，仅在用户明确要求或理由充分时才选择专用操作。具体而言：
  • 对于顶点焊接，优先选择带有明确标志的规范 meshCleanup，而不是独立的 mergeVertices 操作。该独立操作属于旧版／专用接口；进行修改前，应使用上游 usd-optimize 了解操作机制，并遵循本地审批政策。
  • 对于层级去重，推荐使用 usd-hierarchy-dedupe-candidates + apply-restructure（USD 编写的重写路径）。
  • 对于逐网格去重，优先推荐规范的 deduplicateGeometry，而不是分析类的 findCoincidingGeometry（它只生成报告，不会进行更改）。
  • 未经用户明确要求，不要推荐 documentary 状态的操作（例如 boxClip、deletePrims、removeAttributes、removeUntypedPrims，以及超出其狭义的非实例化情形的 merge）。为保持完整性，说明性操作会保留在各自的 references/operations/<key>.md 路由存根中，但不会纳入 Agent 主动发起的推荐。
  • 专用操作 ≠ 说明性操作。 在 _curation.json 中归类为 specialty 的操作要么（a）有验证器发现项作为依据，并被接入 so-interpret-validators 链（例如 sparseMeshes、optimizePrimvars），要么（b）是特定下游情境所需的关键备用方案（例如，当输出必须为 UsdGeomMesh 时使用 primitivesToMeshes，用于实例化切换和材质重新绑定的 utilityFunction，以及用于 so-create-proxy 配方的 pythonScript）。当验证器触发或适用相应下游情境时，应推荐专用操作；上述限制仅针对 documentary 操作。

限制

• 不能替代下游参考资料中的说明；执行前请加载所有必需的参考资料。
• 不会直接安装运行时；缺少依赖时，请遵循设置或安装参考资料中的说明。
• 用户未授权写入时，不得进行修改。

故障排除

• 如果运行时状态不明确，请在分析或验证前运行 setup-usd-performance-tuning。
• 如果报告的问题描述含糊，请收集场景路径、工作负载类型，以及用户要求的是诊断还是执行。
• 如果工作流建议在收集证据前进行修改，请先返回基线分析和构成审计。

参考资料

路由前，请阅读：

• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md — 确定场景所处的管线阶段（提取、结构化或优化）。正确的操作取决于所处阶段。
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md — 了解三大支柱（资产、聚合、动画）和七步结构化模式。

如果可以访问网络，优先使用实时 URL（各参考文件中均有注明），以获取最新版本。

必需的执行流程

阅读 references/workflow.md，了解规范的 Phase 0-7 流程，包括 Kit/独立分支、验证器栈路由、操作顺序、终止条件、时长提示，以及默认的三轮限定范围迭代模式。 根目录的精简映射文件 references/skill-map.md 仅用于将 Agent 路由到此工作流。

不要把后续阶段名称当作普通的检查清单标签。执行每个步骤前，都要加载该阶段的嵌套 README.md 参考文档，并遵循其中的说明。Claude Code 只公开目录中的技能；它不会递归注入 profile-stage、usd-structure-assessment 或其他嵌套参考文档。

最终交付物必须来自 optimization-report：保存结构化 JSON 报告和生成的 Markdown 摘要。不要用临时编写的 SUMMARY.md 或仅在聊天中提供的总结代替优化报告。

如需更深入的子主题指南，请参阅以下参考文档：

• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md、skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md - SA Phase 1 检查清单的子主题详情。
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md - 合并安全性、实例化选择决策树。
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md - 更深入的变体/负载权衡（门槛条件在 usd-edit-target-planner 中内联说明）。
• references/cad-conversion/README.md - CAD 转换器设置。
• references/upstreams/usd-optimize.md - 上游 SO 机制和预构建包解析。
• skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md - SO 验证器基础设施的本地交接说明。
• skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md - 第 1/2/3 级选定探测计划、大型场景防护措施、全量扫描审批，以及场景感知调整。
• skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md - 各阶段都必须填充的数据契约。

有关 Kit 运行时的完整性能分析（FPS、帧时间、Hydra/RTX 指标），请参阅 NVIDIA/omniperf 提供的外部性能分析技能。