omniverse-usd-performance-tuning

Omniverse USD 性能调优

范围

适用于广泛的 USD 性能工作：加载缓慢、FPS／交互性低、GPU 或系统内存占用过高、GPU 崩溃／设备丢失、验证失败、CAD／转换质量分诊、性能分析，或优化场景的请求。本技能负责面向用户的工作流；达到相应阶段后，由阶段参考执行设置、身份验证、性能分析、验证、修改和报告。

为兼容 agentskills.io，Frontmatter 将 version 和 tools 保留在顶层；NVCARPS 字段位于 metadata 下。

必需的会话启动关卡

除仅进行静态分类的回答外，在输出任何调优内容前，请遵循 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 并等待用户回答。选项由该参考规定；此处不要重述或自行编造选项。
• 本次会话中已确认运行时：使用精简格式 B：

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

对于独立／usd-optimize 软件包，运行时证据必须包含软件包／哨兵检查以及共享库或导入／加载验证，不能仅凭 Python 可执行文件／版本。对于 omniverse:// 资产，请先经由 omniverse-authentication，再进行设置、分诊或首次打开。

入口技能与决策规则

• 只要验证了任何运行时路径：Kit、独立运行，或仅包含 usd-validation-nvidia 之类的部分技术栈，就将 omniverse-usd-performance-tuning 命名为入口技能。如果缺少所请求的工具或操作，则返回特定的阻塞代码，例如 blocked_missing_usd_optimize 或 blocked_missing_usd_optimize_operation；不要改用其他工作流。
• 仅当尚未验证任何运行时路径，且运行时选择／设置是首个未解决问题时，才将 setup-usd-performance-tuning 命名为入口技能。
• 这是职责归属，不是阶段顺序：身份验证、设置和分诊仍按正常顺序进行。

规划决策——根据响应的形式推导 decision，绝不能根据请求是否指定了破坏性操作来判断（测试框架会强制校验形式不变量）：

• ready_to_plan——此响应中没有需要用户处理的事项；committed_milestones 等于 planned_phases。这是通用优化的默认值：无损的规范操作链，加上主动执行的 auto-within-tolerance 有界损失处理——对过度细分且在视觉容差范围内的目标，按其保守的逐目标范围进行精简，并通过一行提示告知用户，而不是先询问。
• approval_required——此响应在当前呈现的关卡处暂停；committed_milestones 是 planned_phases 的严格前缀，且 approval_required_reason 指明该关卡。触发条件是 Agent 必须先呈现一个尚未解决的决策，才能规划该操作，而不是操作具有破坏性。对于适合拟合的场景（例如 BIM／CAD 管线和风管），使用默认参数运行 fitPrimitives 进行基本图元拟合，是标准且预期有效的优化，仍属于 ready_to_plan；审批关卡设在执行阶段。只有在以下情况下，有界损失操作（decimateMeshes、fitPrimitives）才会要求当场确认——必须现在回答其容差或数据保留参数：操作将超出保守范围、目标需要功能精度（articulated／物理／仿真就绪／计量／包含变体），或用户明确要求保留数据（用户要求保留 UV／displayColors／子集）。如果 decimateMeshes 请求未说明容差，则必须通过一个预先提出的 mm_tolerance 问题要求当场确认。响应当前呈现的 restructure-decision 也属于 approval_required，原因相同。有关操作的授权类别，请参阅 usd-optimize-run-operations/references/operation-safety.md。
• blocked——适用 blocked_code。
• 真正会在后续触发的关卡——尚未到达的下游 restructure-decision，以及为第 7 阶段的自选菜单收集的身份验证关卡操作——应归入 gates_observed，绝不能归入 decision。

规范计划约定

对于广泛优化，结构化计划／状态摘要必须：

• 以 omniverse-usd-performance-tuning 开始里程碑列表；仅在相关时，将 setup-usd-performance-tuning 作为 Phase 0 背景信息纳入。
• 对通用优化，将顶层 decision 设为 ready_to_plan。
• 在 committed_milestones 和 planned_phases 中都包含直到 optimization-report 的完整链路。
• 使用准确的配置文件标签 profile-stage:baseline 和 profile-stage:after；绝不输出不带限定词的 profile-stage。
• 严格保留以下子序列；仅可在不改变其顺序的位置插入可选分析：

omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> usd-optimize-run-validators -> usd-optimize-interpret-validators -> usd-optimize-run-operations -> profile-stage:after -> compare-profiles -> optimization-report

有两个里程碑是有条件必需的——触发条件成立时，它们必须在此位置作为已提交里程碑出现，而不能仅仅被路由到：

• usd-hierarchy-dedupe-candidates——在 usd-structure-assessment 之后、restructure-decision 之前；当阶段显示存在重复复制的层级、网格数量很多但实例化很少或没有，或存在单体根节点时，必须纳入。未执行此步骤前，不得得出 hierarchy_dedupe.recommended: false 的结论。
• usd-edit-target-planner——在 apply-restructure 之后、Usd Optimize 验证器／操作链之前；当阶段由引用或载荷构成，且每个目标都必须作为自己的根层进行优化时，必须纳入。

在广泛优化的里程碑摘要中，不要将 usd-optimize-run-validators 或 usd-optimize-interpret-validators 列在 restructure-decision 之前。验证器仍需在 usd-validation-runner 内按阶段进行路由。

除非用户选择退出、要求快速处理，或满足停止条件，否则广泛优化默认进行三轮有明确范围的迭代。每轮都会写入中期报告／更新；后续轮次复用已有证据，而不是从头重跑完整工作流。

执行规范

• 端到端执行前，加载 references/workflow.md；该文件规定 Phase 0-7 流程、Kit／独立运行分支、验证器路由、操作顺序、终止标准、时长提示和默认三轮模式。
• 不要将嵌套阶段名称视为检查清单标签。执行某个阶段前，加载该阶段的嵌套 README.md 或参考文档并遵循其说明。只有到达相应阶段时，才调用下游技能的具体执行内容。
• 如果提供了本地工作区说明或辅助命令，请检查并使用它们来创建、验证或渲染所需产物。如果文件／工具不可用，请报告实际观察到的阻碍，不要伪造已完成状态。
• 对于二进制或大型资源，不要输出原始内容。使用有限的元数据、校验和、大小、验证／配置文件摘要、精简事实或工具报告。
• 在读取 Kit 日志、usd-validation-nvidia CSV、Usd Optimize 日志、Tracy CSV 或其他运行时输出前，遵循 references/runtime-artifact-token-budget.md：将原始产物保留在磁盘上，先读取摘要 JSON，并使用有限快照，而不是完整转储或实时流。

必须收集的最低限度上下文：目标阶段、问题／目标、本地／挂载／远程位置、运行时、已知时的工作负载类型、仅诊断还是要修改，以及写入权限／输出目标。除非获得明确许可，否则绝不覆盖源文件；修改时优先输出到单独的优化结果。不得虚构阈值、性能提升百分比、指标或运行时证据。

路由图

• 组合、结构、层健康状况、实例化准备情况：usd-structure-assessment。
• 验证／内容问题：usd-validation-runner，它会根据需要路由至 validate-* 或 Usd Optimize 验证器。
• 编辑目标、变体、负载和输出决策：usd-edit-target-planner。
• 重复复制的层级结构／网格数量多但未实例化：usd-hierarchy-dedupe-candidates。
• 单体阶段或资产边界物化：先运行 restructure-decision，获批后再运行 apply-restructure。
• CAD 转换器设置：references/cad-conversion/README.md。
• Usd Optimize 执行：usd-optimize-run-validators、usd-optimize-interpret-validators、usd-optimize-run-operations。
• FPS、帧时间、Hydra／RTX 指标等完整 Kit 运行时分析：使用外部 NVIDIA／omniperf 分析技能。

在路由大型工作前，如果管线阶段和工厂级结构决策很重要，请先阅读 usd-structure-assessment 的权衡参考资料。

变更与操作规则

遵循 references/workflow.md#operation-ordering-invariants。高级别不变量：先处理原型 -> 再进行每资产验证 -> 最后执行阶段级操作。

始终：

• 变更前运行组合审计。
• 处理器执行前后都要验证。
• 在每资产验证前优化原型。
• 对超大型 CAD 场景，在整个阶段进行网格去重前，先检查层级级别的复用情况。
• 根据瓶颈证据提出建议；没有调查结果时，不要推荐固定的操作组合。
• 不允许写入时，不得授权变更。

Usd Optimize 筛选：

• 多项操作都可能解决同一项调查结果时，优先选择 references/operations/operations.json 中的 canonical 操作。
• 顶点焊接：优先使用带明确标志的标准 meshCleanup，而不是独立的 mergeVertices；变更前遵循上游 usd-optimize 机制和本地审批政策。
• 层级去重：对于 Phase 2 下行处理，优先使用 usd-hierarchy-dedupe-candidates 加 apply-restructure（它负责清单／身份契约）；独立的已批准链式去重运行会直接驱动 deduplicateHierarchies，并按前沿区域调用（使用 paths + 每个区域的 maxDepth）。
• 每网格去重：优先使用标准 deduplicateGeometry；findCoincidingGeometry 仅用于分析／报告。
• 除非收到明确请求，否则不得由 Agent 主动发起 documentary 操作，例如 boxClip、deletePrims、removeAttributes、removeUntypedPrims，或狭义非实例化场景以外的广泛 merge。
• 如果验证器证据将 specialty 操作接入 usd-optimize-interpret-validators，或下游上下文有此需要，则允许使用这些操作，例如 sparseMeshes、optimizePrimvars、primitivesToMeshes、utilityFunction 或 pythonScript 配方。

交付物和最终响应

端到端优化在运行变更时必须生成优化后的 USD 阶段和一份 optimization-report 报告。仅诊断的工作仍必须以一份说明未写入优化后阶段的报告或摘要收尾。

报告要求：

• 结构化 JSON 必须符合 optimization-report 的 scripts/optimization-report.schema.json。
• 保存生成的 Markdown 摘要。
• 使用 render_preview.py 从 references/report-templates/optimization-report.html.template 渲染 HTML；不得手动编写 HTML。
• 不得用临时摘要文件或仅在聊天中复述来代替报告产物。

最终运行时响应必须明确列出：

• 选定的入口技能和选定的运行时／预检状态；适用时还要说明独立软件包的哨兵／加载证据；
• 已写入时优化后的 USD 输出路径，或说明未运行变更；
• 源文件未被覆盖／原地变更状态；
• 实际执行的确切操作链，尤其是声称安全／无损时所用的操作链；
• 证据中可用的变更前／变更后验证结果和配置文件指标；
• 已验证的报告 JSON、生成的 Markdown、渲染后的 HTML、架构／验证结论、存在时的评分，以及 workflow_mode。

如果缺少预检、验证／渲染失败、报告产物缺失或未运行变更，必须如实说明，不得用仅在聊天中复述来代替缺失的产物。

限制和参考资料

此技能不会安装运行时、替代下游参考说明、自行验证远程资源的身份、批准未请求的破坏性写入，也不会在缺少证据时保证性能提升。如果运行时状态不明确，请返回设置关卡；如果在获取证据前就开始变更，请先进行基线配置分析和合成审计。

主要参考资料：

• references/workflow.md
• references/briefing-the-skill.md — 请求应说明哪些内容，以及原因。简报内容过于简略时请阅读此文：其中列出了决定策略的四项内容，以及会悄然降低质量的表述方式（指定三角形数量、指定网格数量）。
• references/runtime-artifact-token-budget.md
• references/skill-map.md
• skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md
• 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
• skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md
• skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md
• skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md
• references/upstreams/usd-optimize.md

网络可用且需要了解上游当前行为时，请使用参考文件中注明的实时 URL。