OmniverseUSD性能调优Skill omniverse-usd-performance-tuning

名称	omniverse-usd-performance-tuning
描述	“顶层工作流技能，用于USD性能诊断与优化。处理加载缓慢、内存占用高、FPS低以及大规模场景优化请求；将认证/运行时设置委托给阶段0负责人。”
版本	“0.4.1”
开源协议	Apache-2.0 tools: - Read - Shell - Write compatibility: > 编排器技能。下游阶段可能要求由 setup-usd-performance-tuning 选择的 Kit、Usd Optimize、usd-validation-nvidia、USD Python、可写输出路径以及 omniverse:// 认证。 metadata:
作者	NVIDIA Omniverse tags: - 分类排查 - 性能 - usd - 性能分析 domain: ai-ml languages: - python

Omniverse USD 性能调优

范围

用于广泛的USD性能工作：缓慢加载、低FPS/交互性、高GPU或系统内存、GPU崩溃/设备丢失、验证失败、CAD/转换质量排查、性能分析或优化场景的请求。本技能掌握用户面向的工作流；设置、认证、性能分析、验证、修改和报告在到达阶段引用时由它们执行。

Frontmatter 将 version 和 tools 保留在顶层以兼容 agentskills.io；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/subsets）时变为内联引发 — 其容差或数据保留参数必须现在回答。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 作为阶段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；它拥有阶段0-7流、Kit/独立分支、验证器路由、操作排序、终止条件、时长提示和默认三遍模式。
• 不要将嵌套阶段名称视为检查标签。执行阶段前，加载该阶段的嵌套 README.md 或引用并遵循。仅当阶段到达时才调用下游技能体。
• 如果提供了本地工作区指令或帮助命令，检查并用于创建、验证或渲染必需工件。如果文件/工具不可用，报告观察到的阻塞器而不是捏造完成。
• 对于二进制或大型资产，不要打印原始内容。使用有界元数据、校验和、大小、验证/配置文件摘要、压缩事实或工具报告。
• 在读取Kit日志、usd-validation-nvidia CSV、Usd Optimize日志、Tracy CSV或其他运行时输出前，遵循 references/runtime-artifact-token-budget.md：保持原始工件在磁盘上，先读摘要JSON，使用有界快照而非完整转储或实时流。

要收集的最小上下文：目标阶段、问题/目标、本地/挂载/远程位置、运行时、工作负载类型（已知时）、仅诊断 vs 修改，以及写入的权限/输出目标。除非明确允许，绝不覆盖源；修改时优先使用单独的优化输出。不要编造阈值、百分比胜利、指标或运行时证据。

路由图

• 组合、结构、层健康、实例化就绪：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 操作。
• 顶点焊接：在独立 mergeVertices 上优先使用显式标志的规范 meshCleanup；在修改前遵循上游 usd-optimize 机制和本地批准策略。
• 层级去重：对于阶段2下降，优先使用 usd-hierarchy-dedupe-candidates 加 apply-restructure（它拥有清单/身份契约）；独立批准链去重运行直接驱动 deduplicateHierarchies，每个边界区域调用（paths + 每区域 maxDepth）。
• 每网格去重：优先使用规范 deduplicateGeometry；findCoincidingGeometry 仅为分析/报告。
• 除非明确请求，否则不要代理启动 documentary 操作，如 boxClip、deletePrims、removeAttributes、removeUntypedPrims 或宽 merge，除其狭窄的非实例化情况外。
• 当验证器证据将其接入 usd-optimize-interpret-validators 或下游上下文要求时允许 specialty 操作，如 sparseMeshes、optimizePrimvars、primitivesToMeshes、utilityFunction 或 pythonScript 配方。

可交付物和最终响应

当修改运行且报告 optimization-report 报告时，端到端优化必须产生优化的USD阶段。仅诊断工作也必须以报告或摘要结束，说明没有写入优化阶段。

报告要求：

• 结构化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、schema/验证判决、存在时的分数和 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。