usd-editor

USD Editor 是一个面向 USD 文本级编辑与命令行工作流的技能指南，适用于对 USD 或 USDA 做最小化、文本层面的编辑，以及命令行下的检查、转换、打包、渲染与校验。其核心原则是保持改动尽量小，并在任务未明确要求时保留既有组合结构。

用途与定位

该技能用于最小的文本级 USD 或 USDA 编辑，以及命令行的 USD 检查、转换、打包、渲染和验证。当场景、几何体、变换、动画或材质由已创作的 Reality Composer Pro 或 USD 内容持有时，应保持该创作内容作为事实来源；使用 Swift 和 RealityKit 仅加载或调整运行时状态，除非请求明确为程序化生成，否则不要在 Swift 中重建已创作的 USD 内容。

相关技能路由

• 若 Swift 代码需要用 USDStage、USDPrim 或 USDLayer 在进程内打开、编辑、观察或导出 stage，则转至 $usdkit-runtime-developer。
• 若改动是针对 RealityKit 的材质或着色器相关，则优先使用 shadergraph-editor。

参考资料的加载时机

技能按需加载以下参考文件：

• usd-syntax：需要复习 .usda 语法、值和路径格式时。
• prims-properties：添加或编辑 prim、属性或关系时。
• composition-variants：涉及子层、引用、载荷或变体集时。
• transforms-units：编辑变换、xformOps，或 stage 单位与上轴元数据时。
• time-samples：修改动画或带时间采样的属性时。
• command-line-tools：需要常用 USD 命令行工具的速查参考时。
• usdcat：转换、展平或检查 USD 文件时。
• usdchecker：校验 USD 或 USDZ 资产（含面向 RealityKit 的检查）时。
• usdrecord：从 USD 文件渲染图像时。
• usdtree：检查 USD 文件的 prim 层级时。
• usdzip：创建或检查 USDZ 包时。
• usdedit：需要官方文本编辑工作流处理 USD 可读文件时。
• visionos-runtime-loading.md：关注已创作的 USD 或 USDZ 在 visionOS 应用中实际加载与表现时。
• apple-runtime-boundaries.md：需要判断是编辑已创作的 USD / Reality Composer Pro 内容、通过 RealityKit 加载，还是为 Apple 平台做校验时。

工作流程

1. 识别归属：已创作的 USD / Reality Composer Pro 资产、包资源，还是仅运行时的 Swift 生成内容。
2. 编辑前根据风险程度，用 usdtree、usdcat --loadOnly 或 usdcat --flatten 检查 stage。
3. 定位持有该 opinion 的精确 prim 路径与 layer。
4. 有意识地选择 over、def 或列表编辑。
5. 应用所需的最小改动。
6. 复查被触及的路径、变换或组合边界。
7. 运行与改动匹配的最窄验证工具，随后对用于发布的 visionOS USDZ 资产运行 usdchecker --arkit。

限制与护栏

• 当 over 才是正确编辑方式时，不要用 def 替换 prim。
• 除非明确要求，避免修改组合弧。
• 若 RealityKit 应用通过 Entity(named:in:)、Entity(contentsOf:withName:) 或生成的 Reality Composer Pro 内容包加载资产，优先修复已创作资产并校验包/包裹，而不是构建并行的 Swift 场景图。
• 不要就地手工编辑 .usdz 包；应检查或解包它，编辑源 layer，重建包，再校验结果。
• 最终面向 Apple 平台的 USDZ 输出应使用 usdchecker --arkit --strict 校验，而不仅是源 layer 的解析检查。
• 尽可能保留既有格式与注释。

输出期望

应提供：被编辑的 prim 或路径；使用了哪些参考文件；所做的 USD 改动的确切类别；所用的验证步骤；必要时路由至 $usdkit-runtime-developer、shadergraph-editor 或运行时测试。