urdf

URDF

来源：在 earthtojake/text-to-cad 中维护。 请将已安装的本地 skill 文件作为运行时事实来源； 仓库链接仅用于来源追溯和发布审核。

请将此 skill 用于 URDF 机器人描述输出。URDF 工作应视为受约束的运动学建模，而不只是编写 XML。主要的正确性风险包括坐标系放置、关节轴语义、单位一致性、网格缩放和惯性数据。

设置

通过 uv 运行 cadgen，这样此 skill 的命令就能与 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. .urdf 文件是事实来源。直接编写和编辑 URDF XML；不要为此构建 Python 生成流程。没有 gen_urdf() 约定。
2. 编写或更改 URDF XML 之前，应先明确机器人的坐标系、关节、几何、单位和假设清单，并将其作为注释块嵌入 .urdf 文件顶部。参见 references/design-ledger.md。
3. 严格遵循 URDF 坐标系语义。关节原点、连杆坐标系、关节轴以及 visual/collision/inertial 原点使用不同的参考坐标系。参见 references/frame-semantics.md。
4. 不要根据含糊的文字描述推断空间变换、网格单位、左右手系、轴向或关节正负方向。应使用 CAD 变换、带尺寸的图纸、测量值、现有源数据或明确记录的假设。
5. 切勿凭空填写由计算得出的数值——例如惯性张量、质心、多个连杆之间的单位换算、镜像变换。请实际计算：对基本几何体使用闭式公式，或使用临时辅助脚本计算网格衍生值。参见 references/inertials.md。
6. 对于物理连杆，如果目标使用方需要，应分别建模 inertial、visual 和 collision。仅包含坐标系的连杆可以有意省略质量和几何。
7. 报告完成前，必须使用 cadgen urdf validate 验证每个新建或修改过的 .urdf。参见 references/validation.md。
8. 允许并鼓励使用辅助脚本进行计算，但脚本只是脚手架，不是工件的事实来源。对于复杂或确实需要参数化的模型，可以将模型专用辅助脚本保存在相关源代码（例如 STEP 生成器源文件）旁边，并在清单中注明；这是可选的，已签入的 .urdf 仍是规范版本。

展示模型

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

• 如果你的工具包含 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. 确定目标 .urdf 文件及其使用方：RViz、robot_state_publisher、Gazebo/Ignition、MoveIt、真实机器人驱动程序或其他模拟器。
2. 编辑坐标系、原点、轴、网格比例、限制或惯性参数前，先阅读或创建设计台账。将台账作为注释块保留在 .urdf 文件中。
3. 如果链接引用了网格，先准备网格资源：每个链接一个网格，由负责该链接的 CAD/网格工作流在链接坐标系下导出。请参阅 references/meshes.md。
4. 直接编写或编辑 URDF XML，并遵循 references/authoring-contract.md 中的结构、顺序和命名要求。
5. 计算惯性参数和其他派生数值，切勿猜测。请参阅 references/inertials.md。
6. 使用 cadgen urdf validate 进行验证；修复发现的问题并重新验证，直到没有问题。
7. 按照 references/validation.md 中的验证流程操作：先使用可用的外部工具（check_urdf），然后在查看器中逐个检查所有关节。
8. 报告剩余的假设、未经检查的空间数据以及验证缺口。

命令

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

验证器的形式如下：

cadgen urdf validate path/to/robot.urdf
cadgen urdf validate path/to/robot.urdf --strict
cadgen urdf validate path/to/robot.urdf --json
cadgen urdf validate path/to/robot.urdf --packages robot_description=/path/to/pkg
cadgen urdf snapshot path/to/robot.urdf review.png

验证器会在一次运行中收集所有问题，并显示严重程度、代码和 XML 路径，涵盖 XML 结构、树拓扑、关节语义（限制、mimic、动力学）、几何、网格引用、材质、惯性物理和拼写错误的元素，同时打印摘要。每次运行只验证一个文件：--strict 会将警告视为失败；--json 会输出一行 {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"}，其中 element 是 XML 路径；--packages NAME=PATH 会解析 package:// 网格 URI，并针对多个根目录重复解析。如果目标验证失败，命令会以非零状态码退出。相对目标路径以当前工作目录为基准解析；请从包含这些文件的工作区运行命令。

验证是一道防护措施，并不能证明空间数据正确：URDF 即使通过所有结构检查，也可能把关节放在错误的位置。因此需要设计台账和查看器检查流程。

Snapshot 工具

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

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

它仅接受 .urdf。使用 --joint-values 设置机器人的姿态，格式为 {joint: degrees} JSON；未指定的关节保持默认值。这与 CAD Viewer 打开机器人时的姿态相同（数据包中的 "jointValues" 作业字段也表示同一内容）。快照使用 Viewer 自己的场景来绘制机器人，因此显示效果与 Viewer 一致；无法加载的连杆网格会导致渲染失败，而不会被略过。机器人以米为单位建模，并会根据机器人场景的比例自动调整取景框。

普通快照使用 Solid 模式和 Light 外观。显示模式为 solid（默认）或 parts（每个连杆使用独立颜色），各自采用对应的默认设置；--grid 会在机器人下方绘制测量网格，--preview 则会改用 Preview 共用的摄影场景，并以透视方式显示。内联显示 JSON 和 JSON 文件都采用 Viewer 的显示对象格式：mode、grid、appearance（light，默认值，或 dark）、camera（投影方式和焦距）以及 clip。 顶层的 --camera 和 --joint-values 在所有显示模式下仍然有效。 display.clip 会像 Viewer 的 Clip 功能一样裁切机器人 （{"clip":{"axis":"x","at":0.05}}，at 的单位为米）；exploded 以及 shaded、xray、 hidden-line 和 wireframe 描述的是 STEP 模型的 CAD 边和零件，此处会按名称拒绝这些选项。Viewer 中的 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 urdf snapshot TARGET [OUT] [flags]，与所有格式入口相同。使用 cadgen urdf snapshot --help 查看当前完整接口——机器人无法使用的标志不会出现在帮助中，也不会被拒绝。

参考资料

• 建模约定（结构、顺序、标准骨架）：references/authoring-contract.md
• 设计记录：references/design-ledger.md
• 坐标系语义：references/frame-semantics.md
• 网格准备与参考资料：references/meshes.md
• 惯性参数（公式、脚本、合理性检查）：references/inertials.md
• URDF 编辑工作流：references/urdf-workflow.md
• 验证与确认流程：references/validation.md