编写/校验 URDF 机器人描述文件时：如何处理坐标系…

创建、编辑、检查、校验或调试 `.urdf` 文件（link、joint、limit、inertial、visual/collision 几何、mesh 引用、坐标系约定）时使用。

适用场景

解决思路

1. 安装运行时：在技能目录执行 `python -m pip install -r requirements.txt`（该 cadgen 分发包含 Python 构建运行时及其执行的 JavaScript）。
2. 需要渲染时另装浏览器：`python -m playwright install chromium`（pip 无法提供浏览器）。
3. 把 `.urdf` 文件本身当作唯一事实源：直接编写和编辑 URDF XML，不要为它搭 Python 生成流水线，不存在 `gen_urdf()` 这类契约。
4. 在编写或修改 URDF XML 之前，先建立机器人的坐标系、关节、几何、单位与假设台账（design ledger），并以注释块形式嵌在 `.urdf` 文件顶部（见 `references/design-ledger.md`）。
5. 严格按 URDF 坐标系语义使用：joint origin、link frame、joint axis、visual/collision/inertial origin 各自参考的坐标系不同（见 `references/frame-semantics.md`）。
6. 不要从含糊的自然语言里推断空间变换、mesh 单位、手性、轴或关节正负号；改用 CAD 变换、带尺寸图纸、实测值、已有源数据或明确记录的假设。
7. 凡属计算结果的数值——惯量张量、质心、跨多 link 的单位换算、镜像变换——绝不手写估计：用基本体闭式公式计算，或写一次性辅助脚本求 mesh 推导值（见 `references/inertials.md`）。
8. 对物理 link，在目标消费方需要时分别建模 `inertial`、`visual`、`collision`；纯坐标系 link 可以有意省略质量与几何。
9. 每个创建或修改过的 `.urdf`，在报告完成前都要用 `cadgen urdf validate` 校验（见 `references/validation.md`）。
10. 辅助脚本可用于计算且被鼓励，但只是脚手架、不是工件的事实源；对复杂或真正参数化的模型，可（可选）把模型局部辅助脚本与相关源码（如 STEP 生成源）放在一起并在台账中注明；签入的 `.urdf` 始终是权威。
11. URDF 工作完成后（创建或修改了 `.urdf`），只要 `$cad-viewer` 已安装，就必须把明确文件路径交给 `$cad-viewer`；`$cad-viewer` 未运行时要先启动并返回相关新建/更新文件的链接；若 `$cad-viewer` 不可用或启动失败，要如实报告，不能悄悄跳过交接。
12. 先确定目标 `.urdf` 文件及其消费方：RViz、robot_state_publisher、Gazebo/Ignition、MoveIt、真实机器人驱动或另一个仿真器。
13. 在改动坐标系、origin、轴、mesh 缩放、limit 或 inertial 之前，先读取或创建设计台账，并把台账作为注释块保留在 `.urdf` 内部。
14. 若 link 引用 mesh，先准备 mesh 资产：每个 link 一个 mesh，并由负责的 CAD/mesh 流程在**该 link 的坐标系**下导出（见 `references/meshes.md`）。
15. 直接编写或编辑 URDF XML，结构、元素顺序与命名按 `references/authoring-contract.md` 执行。
16. 惯量及其它派生数值一律计算、绝不猜测（见 `references/inertials.md`）。
17. 用 `cadgen urdf validate` 校验，修复发现的问题并反复校验直到干净。
18. 执行 `references/validation.md` 中的验证配方：有外部工具时先用（`check_urdf`），再做一次视图审查，扫过每一个关节。
19. 报告时说明仍然存在的假设、未核实的空间数据和验证缺口。
20. 在该技能 `requirements.txt` 所安装到的 Python 环境里运行 `cadgen`（不依赖 PATH 的等价写法是 `python -m cadgen.cli <verb>`）；`cadgen doctor <skill-dir>` 用来确认已安装的 cadgen 与技能 pin 一致（版本不匹配时文档会静默漂移）。
21. 完整的当前接口用 `cadgen <verb> --help` 查看。
22. 校验器调用形式：`cadgen urdf validate path/to/robot.urdf`，可加 `--strict`、`--json`、`--packages robot_description=/path/to/pkg`；以及 `cadgen urdf snapshot path/to/robot.urdf review.png`。
23. 校验器一次收齐所有发现（严重级别、代码、XML 路径），覆盖 XML 结构、树拓扑、关节语义（limit、mimic、dynamics）、几何、mesh 引用、材质、惯量物理与拼写错误的元素，并打印摘要。
24. 一次运行只校验一个文件；`--strict` 把 warning 当失败；`--json` 输出一行 `{"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"}`（其中 `element` 是 XML 路径）；`--packages NAME=PATH` 解析 `package://` mesh URI 且可重复以指定多个根；目标不合格时退出码非零；相对路径从当前工作目录解析，因此要在拥有这些文件的工作区里运行。
25. 记住校验只是护栏、不是空间证明：URDF 可能通过全部结构检查，关节位置却仍然放错——这正是需要台账和视图扫描的原因。
26. 用 `cadgen urdf snapshot path/to/robot.urdf review.png` 把机器人渲染成 PNG 静帧（与其他渲染技能共用同一 CLI 与无头浏览器运行时，因此与 CAD Viewer 所见一致）。
27. snapshot 只接受 `.urdf`；用 `--joint-values` 摆姿态，值为 `{joint: degrees}` 形式的 JSON，未点名的关节停留在 rest pose（数据包中的 `jointValues` 字段等同）。
28. 机器人以米为单位建模，渲染时自动按机器人场景尺度取景。
29. 普通快照使用确定性的 light CAD 光照并隐藏网格与坐标轴辅助；要共用 Render 场景就传 `--render light` 或 `--render dark`（或摄影级 Render JSON / 文件路径）；不带 `studio` 的 envelope 在 CLI 中解析为 Light。
30. 相机在 Render JSON 内设置；顶层 `--camera`、`--display`、`--joint-values` 控制普通快照，不能与 Render 组合使用。
31. 机器人 link mesh 没有 CAD 边线或爆炸装配拓扑，这类显示组合会被明确拒绝。
32. link mesh 相对描述文件解析，所以必须实际存在：未 hydrate 的 Git LFS 指针会以 "No link mesh loaded for robot" 失败，先执行 `git lfs checkout <mesh dir>`。
33. snapshot 语法为 `cadgen urdf snapshot TARGET [OUT] [flags]`，与其它格式入口一致；机器人用不到的参数不会出现在 `--help` 中，而不是被拒绝。

适用边界 · 注意事项

• 不适合处理 MoveIt2 语义组与 IK/路径规划语义（改用 SRDF 技能）。
• 不适合生成或处理 STEP/STL/3MF/DXF/GLB 等 CAD 输出（改用 CAD 技能）。