编写/验证 SDFormat（.sdf）模型与世界并交接模拟…

当交付物是 SDFormat `.sdf` 文档（模型、world、link/joint/inertial/sensor/plugin 等）时，用于直接编写、验证并交接给 Gazebo 等模拟器或查看器。

适用场景

解决思路

1. 以已安装的本地技能文件作为运行时事实来源；仓库链接仅用于来源和发布审查。
2. 安装 cadgen 运行时：运行 `python -m pip install -r requirements.txt`。
3. 渲染/快照额外安装浏览器：运行 `python -m playwright install chromium`。
4. 在安装 requirements.txt 的 Python 环境中运行 `cadgen`；PATH 不独立时用 `python -m cadgen.cli <verb>`。用 `cadgen doctor <skill-dir>` 验证 cadgen 与技能 pin 匹配。
5. 直接编写和编辑 `.sdf` XML，把 `.sdf` 文件作为唯一事实来源；不存在 `gen_sdf()` 契约。
6. 编辑前识别目标消费者：Gazebo/libsdformat 版本、其他模拟器、仅可视化工具、模型包或 world handoff。
7. 决定文档类型：模型级 SDF、world 级 SDF 或 model-in-world；可复用机器人/物体导出优先模型级 SDF。
8. 除非目标明确要求，使用 SI 单位：米、千克、秒、弧度。
9. 新输出优先 `version="1.12"`，除非目标消费者限制版本。
10. 写 poses、frames、joint axes、mesh scales、inertials、sensors、plugins 前建立 design ledger，并作为注释块放在 `.sdf` 顶部；使用 `references/design-ledger.md` 与 `references/llm-guardrails.md`。
11. 每个非平凡 pose 和 axis 显式写 `relative_to` / `expressed_in`，不要依赖隐式 frame 默认值；参考 `references/frame-semantics.md`。
12. 不要仅凭视觉印象推断空间变换；pose、axis、scale、mass、inertia、frame name 来自上游源数据、图纸、模拟器文档、测量值或显式假设；用公式或一次性辅助脚本计算 inertia tensors、unit conversions，不要手填计算数字。
13. 若机器人已有 URDF，从 URDF 派生 SDF，不要重新编写几何；参考 `references/interoperability.md`。
14. 编辑引用上游 geometry、mesh、robot-description、render、topology、package 资产的 SDF 前，先用其所属工作流重新生成这些资产。
15. 编辑任何 `<pose>`、`<frame>`、joint axis、`relative_to`、`expressed_in`、nested scope、sensor frame 或 plugin frame 前，先读 `references/frame-semantics.md`。
16. 按 `references/examples.md` 的 worked examples/golden skeletons 直接编写 XML。
17. 用 `cadgen sdf validate path/to/model.sdf` 验证每个创建或修改的文件，完成前必须验证。一次只验证一个文件。
18. 用 `cadgen sdf validate path/to/model.sdf --strict` 将 warning 视为失败；用 `--json` 输出一行 JSON（含 ok、path、issues、severity、code、message、element、hint、summary 字段，element 是 XML 路径）；目标失败时非零退出。
19. 外部检查默认开启：`--gz-check auto` 默认，在 `gz` 位于 PATH 时运行并报告 gz_check_passed 或 gz_check_failed，否则提示 info: gz_check_unavailable 并继续；`--gz-check required` 使 `gz` 缺失成为错误；`--gz-check never` 跳过。缺失可选工具不应让干净文档失败，`--strict` 也不改变这一点。
20. 把 bundled validation 当作 guardrail 而非模拟器证明；可用时运行目标消费者 smoke tests，参考 `references/smoke-tests.md`。
21. 创作后运行可用检查：bundled validation（`gz` 在 PATH 时会运行 `gz sdf --check`）、模拟器加载、joint motion、plugin/sensor startup。
22. 若安装 `$cad-viewer`，完成创建/修改 `.sdf` 后必须把显式文件路径交给它；`$cad-viewer` 必须启动 CAD Viewer（若未运行）并返回相关创建/更新文件链接；不可用或启动失败时报告，不要静默省略 handoff。静态渲染不执行 SDF plugins 或读取文件内 motion metadata。
23. 完成时按规定 compact report shape 报告：Validated、Checks run、Assumptions、Risks，并列出 bundled SDF validation、gz sdf --check、simulator load、viewer handoff 等状态。
24. 报告假设、跳过的检查、未解决的资源路径、目标特定兼容性风险。
25. 用 `cadgen sdf snapshot path/to/model.sdf review.png` 渲染 PNG 快照；该命令只接受 `.sdf`，语法为 `cadgen sdf snapshot TARGET [OUT] [flags]`。
26. 用 `--joint-values` 以 `{joint: degrees}` JSON 摆姿势；未命名 joint 保持 rest pose；packet 中 jointValues job field 相同。机器人以米为单位创作，并自动按 robot scene scale 取景。
27. 普通快照使用确定性 light CAD 灯光并隐藏 grid/axis guides；传 `--render light` 或 `--render dark`（或 photographic Render JSON 或文件路径）使用共享 Render scene。无 studio 的 envelope 在 CLI 中解析为 Light。在 Render JSON 中设置相机；顶层 `--camera`、`--display`、`--joint-values` 控制普通快照，不能与 Render 组合。Robot link mesh 没有 CAD-edge 或 exploded assembly topology，这些显示组合会被明确拒绝。
28. Link mesh 相对 description 解析，因此必须存在：未 hydrate 的 Git LFS pointer 会失败并提示 No link mesh loaded for robot；先运行 `git lfs checkout <mesh dir>`。
29. 用 `cadgen sdf snapshot --help` 查看完整当前接口；robot 不能作用的 flags 不会出现在帮助中。
30. 用 `cadgen <verb> --help` 查看完整当前接口。
31. 需要细节时阅读：`references/sdf-workflow.md`、`references/examples.md`、`references/llm-guardrails.md`、`references/design-ledger.md`、`references/frame-semantics.md`、`references/validation.md`、`references/smoke-tests.md`、`references/interoperability.md`。

适用边界 · 注意事项

• 不用于 signed-distance-field geometry/modeling；这是 SDFormat，不是 signed-distance-field。
• 不用于 raw geometry generation、planning semantics。
• 不用于掩盖上游机器人/源数据错误，除非任务明确仅限模拟器。