sdf

SDF

来源：由 earthtojake/text-to-cad 维护。 运行时以已安装的本地技能文件为准；仓库链接仅用于追溯来源和审查发布版本。

当交付内容为 SDFormat 文档时，请使用此技能。SDFormat 描述模拟器和世界的行为：模型、世界、坐标系、位姿、链接、关节、惯性参数、视觉、碰撞、传感器、灯光、物理、插件、包含项和模拟器元数据。

此技能适用于 SDFormat，不适用于有符号距离场几何。

.sdf 文件是事实来源：直接编写和编辑 XML。没有 gen_sdf() 约定。

设置

通过 uv 运行 cadgen，让此技能的命令与 CAD 应用的服务共用同一套安装及其预热构建守护进程：

• 下文的 cadgen 指 uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.26 cadgen
• 下文的 python 指 uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.26 python

首次运行时会下载该安装包；首次生成快照时会下载其无头浏览器。后续运行会复用这两者。

核心规则

1. 直接编写 .sdf XML，并在报告完成前使用 cadgen sdf validate 验证所有新建或修改的文件。
2. 编辑前先确定目标使用方：Gazebo/libsdformat 版本、其他模拟器、仅用于可视化的工具、模型包，或世界交付目标。
3. 确定文档类型：模型级 SDF、世界级 SDF，或世界中的模型。可复用的机器人/物体导出优先采用模型级 SDF。
4. 除非目标明确要求其他单位，否则使用 SI 单位：米、千克、秒、弧度。
5. 除非目标使用方限制版本，否则新输出优先采用 version="1.12"。
6. 编写位姿、坐标系、关节轴、网格缩放、惯性参数、传感器或插件前，先建立设计记录，并将其作为注释块放在 .sdf 顶部。使用 references/design-ledger.md 和 references/llm-guardrails.md。
7. 为每个非简单位姿和轴显式指定 relative_to / expressed_in。隐式坐标系默认值是 SDF 最常见的失败原因。参见 references/frame-semantics.md。
8. 不要仅凭视觉印象推断空间变换。应根据上游源数据、图纸、模拟器文档、测量值或明确假设推导位姿、轴、缩放、质量、惯性和坐标系名称。切勿凭空编造计算数值——应使用公式或临时辅助脚本（惯性张量、单位换算）。
9. 如果机器人已有 URDF，应从中推导 SDF，而不是重新编写几何；参见 references/interoperability.md。
10. 编辑引用这些资产的 SDF 前，应使用各自所属的工作流重新生成上游几何、网格、机器人描述、渲染、拓扑或包资产。
11. 编写完成后，运行可用的检查：内置验证（只要 gz 在 PATH 中，就会自行运行 gz sdf --check）、模拟器加载、关节运动，以及插件/传感器启动。
12. 报告所作假设、跳过的检查、未解决的资源路径，以及特定于目标的兼容性风险。

范围

将此技能用于 SDFormat 输出。不要将其用于有符号距离场建模、原始几何生成、规划语义，或掩盖错误的上游机器人/源数据；除非任务明确仅涉及模拟器。

显示模型

向用户展示你创建或更改的每个文件，以及他们要求查看的任何文件。快照和验证不能替代这一操作。

• 如果你的工具包含 cad_show（宿主可能会为它添加前缀），请使用它并传入文件的绝对路径，并根据其说明判断何时再次调用。cad_view 会读取用户选中的内容；cad_screenshot 会显示用户看到的内容。二者都不能用于审查你自己的工作。

• 否则，请从任意文件夹运行 CAD Viewer：

  cadgen viewer --host 127.0.0.1 --json --detach
  

  --detach 会在查看器响应请求后返回，并让它在后台继续运行：务必传入此参数，因为前台查看器不会退出（而且通过管道将其输出传给 tail 可能会导致 URL 永远无法显示）。它会启动此机器上的唯一查看器，或复用已有查看器。从它输出的唯一一行 JSON 中读取 url（绝不要猜测端口），并为每个文件返回 url?file=<其 URL 编码后的绝对路径>。如果无法启动，请说明。

检查位置、资源和关节。查看器不会执行模拟器插件或验证动力学；模拟器检查应单独进行。

工作流

1. 定位目标 .sdf 及其使用方。
2. 阅读或创建设计记录注释块。
3. 在编辑任何 <pose>、<frame>、关节轴、relative_to、expressed_in、嵌套作用域、传感器坐标系或插件坐标系之前，先阅读 references/frame-semantics.md。
4. 直接编写 XML，并遵循 references/examples.md 中的示例。
5. 使用 cadgen sdf validate 验证明确指定的目标；将捆绑验证视为防护措施，而非模拟器验证。
6. 在可用时运行目标使用方冒烟测试（references/smoke-tests.md）。
7. 展示结果（显示模型）。静态渲染不会执行 SDF 插件，也不会读取文件编写的运动元数据。
8. 报告已运行的检查、跳过的检查和假设。

命令

按照 Setup 中的定义运行 cadgen。cadgen doctor <skill-dir> 会报告正在使用的安装，并检查它是否与此技能指定的版本一致——使用其他版本时，文档可能会悄然出现偏差。验证本身除了 Python 标准库外无需其他依赖；只有快照需要浏览器。使用 cadgen <verb> --help 查看完整的当前接口。

cadgen sdf validate path/to/model.sdf
cadgen sdf validate path/to/model.sdf --strict
cadgen sdf validate path/to/model.sdf --json
cadgen sdf snapshot path/to/model.sdf review.png

验证器会检查文档结构、名称作用域、位姿/坐标系图、关节、几何体、网格 URI、惯性参数、传感器和插件，并输出检查结果及摘要。每次运行只验证一个文件：--strict 会将警告视为失败，--json 会输出一行 {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"}，其中 element 是 XML 路径。目标验证失败时，命令会以非零状态退出。

默认情况下会执行外部检查：

cadgen sdf validate path/to/model.sdf --gz-check required
cadgen sdf validate path/to/model.sdf --gz-check never

gz sdf --check 是目标使用方验证。默认值 --gz-check auto 表示：如果 gz 位于 PATH 中，就运行检查，并报告 gz_check_passed；如果检查失败，则将工具自身的输出作为错误 gz_check_failed 报告；否则会注明 info: gz_check_unavailable 并继续。缺少可选工具并不能说明文件有问题，因此不会导致干净的文档验证失败，--strict 也不会改变这一点。--gz-check required 会将该工具设为必需——如果缺少 gz，就会报错；--gz-check never 则会直接跳过检查。

必需的报告格式

完成 SDF 任务时，请附上简短报告：

Validated: path/to/model.sdf
Checks run:
- bundled SDF validation: passed
- gz sdf --check: skipped, gz not installed
- simulator load: skipped, target simulator unavailable
- viewer review: live link returned, or explicit launch failure
Assumptions:
- Assumed mesh units are meters.
- Assumed lidar frame is coincident with lidar_link.
Risks:
- Camera plugin filename was not verified in the target simulator environment.

快照工具

cadgen sdf snapshot 会将机器人渲染为 PNG 静态图，使用所有渲染技能共用的 CLI 和无头浏览器运行时，因此快照与 CAD Viewer 中显示的内容一致。

cadgen sdf snapshot path/to/robot.sdf review.png

它仅接受 .sdf（这是格式入口，语法与其他入口相同，均为 TARGET [OUT]）。使用 --joint-values 为机器人设置姿态，格式为 {joint: degrees} JSON；未指定的关节将保持其默认值，也就是 CAD Viewer 打开机器人时的姿态（数据包中的 "jointValues" 作业字段也是如此）。快照使用查看器自身的场景绘制机器人，因此显示效果与查看器一致；若链接网格无法加载，渲染会失败，而不会将该链接省略。机器人以米为单位建模，并会根据机器人场景的比例自动调整取景范围。

普通快照使用 Solid 模式和 Light 外观。显示模式为 solid（默认）或 parts（每个链接使用各自的颜色），两者均使用各自的默认值；--grid 会在机器人下方绘制测量网格，--preview 则会改用 Preview 共用的摄影场景，并采用透视投影。内联显示 JSON 和 JSON 文件均使用 Viewer 的显示对象：mode、grid、appearance（light，默认值，或 dark）、camera（投影方式和焦距）以及 clip。 顶层的 --camera 和 --joint-values 在所有显示模式下都有效。 display.clip 会像查看器的 Clip 一样裁切机器人（{"clip":{"axis":"x","at":0.05}}，at 的单位为米）；exploded、shaded、xray、hidden-line 和 wireframe 用于描述 STEP 模型的 CAD 边和零件，此处会按名称拒绝这些选项。查看器中的 Quick Edit 作业会按原样重放：包括其 jointValues、selection.hide（Links 面板中按 ID 隐藏的零件）、裁切和注释（cadgen snapshot --job <file>）。Quick Edit 接受内联 JSON 或 .snapshot.json 路径；使用 --job 前，请先将内联 JSON 保存到临时文件。编辑前请检查所提供的注释。若没有注释，捕获的视图只是可选参考；仅在有助于完成请求时才渲染它。

链接网格相对于描述文件解析，因此必须确保网格文件存在：未经检出的 Git LFS 指针会导致错误 "No link mesh loaded for robot"。请先运行 git lfs checkout <mesh dir>。

语法为 cadgen sdf snapshot TARGET [OUT] [flags]，与所有格式入口相同。使用 cadgen sdf snapshot --help 查看当前完整接口——机器人无法使用的标志不会出现在帮助中，而不是由命令拒绝。

参考资料

• SDF 工作流：references/sdf-workflow.md
• 示例（标准骨架）：references/examples.md
• LLM 防护规则：references/llm-guardrails.md
• 设计记录：references/design-ledger.md
• 坐标系语义：references/frame-semantics.md
• 验证范围：references/validation.md
• 冒烟测试：references/smoke-tests.md
• 互操作说明（URDF 派生的 SDF、网格、Gazebo）：references/interoperability.md