SDFormat/SDF模型与世界生成、验证及模拟器交接。用于`.sdf`文件、SDFormat XML、Python `gen_sdf()`源码、模型、世界、链接、关节、位姿、框架、惯性、视觉/碰撞几何体、网格URI、传感器、灯光、物理、插件、包含、Gazebo、静态SDF审查或模拟器特定元数据。不用于符号距离场几何体。
SDF
来源：维护于earthtojake/text-to-cad。
使用本地安装的技能文件作为运行时的事实来源；仓库链接仅用于来源追溯和发布审查。
当交付物为SDFormat文档或Python gen_sdf()源码时使用此技能。SDFormat描述模拟器和世界行为：模型、世界、框架、位姿、链接、关节、惯性、视觉、碰撞、传感器、灯光、物理、插件、包含和模拟器元数据。
此技能用于SDFormat，而非符号距离场几何体。
核心规则
- 将定义
gen_sdf()的Python文件视为事实来源。将配置的.sdf文件视为生成的工件，除非用户明确要求直接编辑XML。 - 在编辑前确定目标消费者：Gazebo/libsdformat版本、其他模拟器、仅可视化工具、模型包或世界交接。
- 确定文档类型：模型级SDF、世界级SDF或模型在世界中。对于可复用的机器人/对象导出，优先使用模型级SDF。
- 除非目标明确要求其他单位，否则使用SI单位：米、千克、秒、弧度。
- 除非目标消费者限制版本，否则新输出优先使用
version="1.12"。 - 在编写位姿、框架、关节轴、网格缩放、惯性、传感器或插件之前，建立设计日志。使用
references/design-ledger.md和references/llm-guardrails.md。 - 不要仅凭视觉印象推断空间变换。从上游源数据、图纸、模拟器文档、测量值或明确假设中推导位姿、轴、缩放、质量、惯性和框架名称。
- 优先使用辅助函数和命名常量，而非大型XML字符串字面量。隐藏数字是常见的SDF失败模式。
- 仅使用
scripts/sdf或仓库现有的SDF启动器生成明确目标。不要运行目录范围的生成。 - 在重新生成引用上游几何体、网格、机器人描述、渲染、拓扑或包资产的SDF之前，先使用其所属工作流重新生成这些资产。
- 生成后，运行可用的检查：捆绑验证、可选的
gz sdf --check、模拟器加载、关节运动以及插件/传感器启动。 - 报告假设、跳过的检查、未解决的资源路径以及目标特定的兼容性风险。
范围
使用此技能处理SDFormat输出和生成器。不要用于符号距离场建模、原始几何体生成、规划语义，或掩盖不正确的上游机器人/源数据，除非任务明确仅限模拟器。
CAD查看器交接
完成创建或修改.sdf的SDF工作后，如果安装了$cad-viewer技能，必须始终将明确的文件路径交给$cad-viewer。$cad-viewer必须启动CAD查看器（如果尚未运行），并返回相关创建或更新文件的链接；如果$cad-viewer不可用或启动失败，则报告该情况，而不是静默省略交接。
工作流
- 定位
gen_sdf()源码和预期的.sdf输出。 - 读取或创建设计日志。
- 在编辑任何
<pose>、<frame>、关节轴、relative_to、expressed_in、嵌套作用域、传感器框架或插件框架之前，阅读references/frame-semantics.md。 - 编辑生成器源码，而非生成的XML。
- 当可选的构建辅助函数能使生成的结构更清晰时使用它们；仍然允许使用原始ElementTree。
- 重新生成明确目标。
- 将捆绑验证视为护栏，而非模拟器证明。
- 当可用时，运行目标消费者的冒烟测试。
- 报告已运行的检查、跳过的检查和假设。静态渲染不执行SDF插件或读取文件编写的运动元数据。
命令
使用项目或工作区的Python环境运行。将示例中的python视为解释器占位符；如果裸python不可用，则替换为python3、项目虚拟环境解释器或配置的解释器路径。
python scripts/sdf path/to/source.py
python scripts/sdf path/to/source.py -o path/to/output.sdf
python scripts/sdf path/to/a.py=out/a.sdf path/to/b.py=out/b.sdf
纯Python目标会在其源文件旁边生成同名的.sdf文件。-o / --output仅对单个纯目标有效。SOURCE.py=OUTPUT.sdf支持自定义多目标输出路径。
如果运行时支持可选的外部检查：
python scripts/sdf path/to/source.py --gz-check auto
python scripts/sdf path/to/source.py --gz-check required
python scripts/sdf path/to/source.py --gz-check never
gz sdf --check是可选的消费者验证。当不可用时应报告为已跳过，除非明确要求。
必需的报告格式
完成SDF任务时，包含一个简洁的报告：
生成：path/to/model.sdf 来自 path/to/model.py
已运行的检查：
- 捆绑SDF验证：通过
- gz sdf --check：跳过，未安装gz
- 模拟器加载：跳过，目标模拟器不可用
- 查看器交接：`$cad-viewer`链接已返回
假设：
- 假设网格单位为米。
- 假设激光雷达框架与lidar_link重合。
风险：
- 相机插件文件名未在目标模拟器环境中验证。
参考资料
- 生成命令：
references/gen-sdf.md - 生成器契约：
references/generator-contract.md - SDF工作流：
references/sdf-workflow.md - 构建辅助函数：
references/builder-helpers.md - LLM护栏：
references/llm-guardrails.md - 设计日志：
references/design-ledger.md - 框架语义：
references/frame-semantics.md - 验证范围：
references/validation.md - 冒烟测试：
references/smoke-tests.md - 互操作性说明：
references/interoperability.md - 示例：
references/examples.md - 运行时说明和当前限制：
references/implementation-notes.md
