srdf

SRDF

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

此技能适用于在现有且有效的 URDF 基础上编写 MoveIt 语义机器人描述。SRDF 定义规划语义，不定义机器人的物理结构。.srdf 文件是事实来源：直接编写和编辑 XML。不存在 gen_srdf() 契约。

SRDF 的正确性是一个规划语义问题。常见故障并非 XML 无效，而是 SRDF 看起来合理，却让 MoveIt 使用了错误的规划组、工具链接、默认状态、不安全的禁用碰撞矩阵或错误的关节单位。由于语言模型不擅长空间和运动学推理，应根据 URDF 拓扑、MoveIt Setup Assistant 输出、采样碰撞分析或用户明确提供的数据，推导规划组、末端执行器、组状态和禁用碰撞。不要仅凭视觉主题进行推断，也不要凭记忆输入任何链接或关节名称：先提取 URDF 的链接/关节表，再从中复制名称。

设置

通过 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

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

格式边界

• URDF 负责机器人的物理结构：链接、关节、几何体、惯性参数、限位、从动关节、传动装置和机器人状态发布。
• SRDF 负责 MoveIt 语义：虚拟关节、被动关节、规划组、组状态、末端执行器和禁用碰撞对。
• SDF 负责仿真器/世界语义：物理参数、传感器、灯光、插件、世界和仿真专用元数据。

不要在 SRDF 中放置几何体、惯性参数、关节原点、链接位姿、网格引用、物理关节限位、传动装置或 ros2_control 接口。

展示模型

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

• 如果你的工具中包含 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 编码的绝对路径>。如果启动失败，请说明。

将 SRDF 与名称唯一匹配的 URDF 放在一起（机器人名称相同）。 审查规划组、具名状态和关节；视觉审查不能证明规划正确性。

必需工作流

1. 从有效的 URDF 开始。 先使用 $urdf 编写或修复 URDF，并对其进行验证。SRDF 通过文件同目录存放和机器人名称与该 URDF 配对，SRDF 中的每个名称都必须存在于 URDF 中。
2. 提取 URDF 表格。 在编写任何 SRDF XML 之前，列出 URDF 的机器人名称、链接、关节（包括类型、父项、子项、限制和 mimic 标志）。只从此表格复制名称；切勿凭记忆输入。参见 references/srdf-workflow.md。
3. 确定规划任务。 记录目标是机械臂 IK、夹爪控制、移动底座规划、双臂规划、工具使用，还是本地冒烟测试。
4. 创建或更新规划记录。 编写 XML 之前，使用 references/planning-ledger.md；并在 .srdf 中以注释块的形式保留一份精简副本。
5. 通过文件同目录存放与 URDF 配对。 将 .srdf 保存在与 .urdf 相同的文件夹中，并使用相同的 <robot name>——这是唯一的关联机制。验证器和查看器都会扫描文件夹，查找机器人名称匹配的 URDF 来确定配对；每个文件夹中，每个机器人名称只能对应一个 URDF。文件之间没有用于关联的元数据元素。参见 references/authoring-contract.md。
6. 审慎定义虚拟关节和被动关节。 根据机器人模型的需要使用它们。
7. 根据 URDF 拓扑定义规划组。 对于串联机械臂，如果基座和末端在 URDF 树中构成真实的父子路径，应优先使用链式组（验证器会检查这一点）。仅在有明确意图时使用关节、链接或子组定义。
8. 确定组成员关系后再定义末端执行器。 避免末端执行器组与其父组重叠。记录实际的目标链接／TCP 链接。
9. 使用 URDF 原生单位定义组状态。 旋转关节和连续关节的值单位为弧度；移动关节的值单位为米。不要在 SRDF 中存储角度值。值必须处于 URDF 限制范围内，且不得为固定关节或 mimic 关节设置值。
10. 根据证据生成禁用碰撞项。 使用从 URDF 关节表推导出的相邻关系、MoveIt Setup Assistant 采样结果，或用户明确提供的碰撞矩阵。不要凭空编造大范围的禁用列表。参见 references/disabled-collisions.md。
11. 使用 cadgen srdf validate 验证每个新建或修改的 .srdf；该命令会针对配对的 URDF 交叉验证所有名称、链、状态和配对关系。修复发现的问题并重新验证，直到检查通过。
12. 条件允许时运行 MoveIt 冒烟测试。 直接使用 MoveIt Setup Assistant 或项目的 MoveIt 启动项。
13. 报告假设和跳过的检查。 包括未完成的验证、缺少 MoveIt 环境、人工推断的禁用碰撞项，以及推断出的目标链接。

命令

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

验证器格式如下：

cadgen srdf validate path/to/robot.srdf
cadgen srdf validate path/to/robot.srdf --strict
cadgen srdf validate path/to/robot.srdf --json

验证器会解析 SRDF，定位配对的 URDF（同一文件夹中机器人名称匹配的 .urdf；未找到、找到多个或文件无效都会报错），并进行交叉验证：组／关节／链接／子组名称是否存在、链路径是否可解析、子组是否存在循环、虚拟关节／被动关节、末端执行器拓扑、组状态成员关系／限制／完整性、禁用碰撞对（包括 Adjacent 原因是否属实），以及拼写错误的元素。每个阶段都会在一次检查中收集所有发现项（严重级别、代码、XML 路径），但结构错误会中止跨文件检查阶段——每次修复后都要重新运行。每次运行只验证一个文件：--strict 会将警告视为失败；--json 会输出一行 {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"}，其中 element 是 XML 路径。目标文件验证失败时，命令会以非零状态码退出。相对目标路径以当前工作目录为基准解析。

硬性规则

• SRDF 与其 URDF 位于同一文件夹，且共享相同的 <robot name>；只有同文件夹加名称匹配这一种配对机制，并且该文件夹中每个机器人名称只能对应一个 URDF。
• 每个 link、joint、group 和 subgroup 名称都必须来自 URDF 表，或来自同一文件中定义的 group。
• Group state 使用 URDF 原生单位：revolute/continuous 使用弧度，prismatic 使用米。
• 禁用的碰撞对必须注明真实原因和来源。
• 末端执行器 group 不应与其父规划 group 共享 link。
• 目视检查渲染效果很有用，但无法证明规划正确性。

Snapshot 工具

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

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

将 .srdf 文件传给它；工具会按后缀路由，并渲染配对 URDF 的几何体——也就是同一文件夹中 <robot name> 匹配的 .urdf，配对方式与 cadgen srdf validate 完全相同。如果没有匹配项，或匹配项超过一个，工具会在渲染前拒绝执行，并说明查找的机器人名称以及找到的 .urdf 文件。使用 --joint-values 设置机器人姿态——接受 {joint: degrees} JSON；未指定的关节保持 CAD Viewer 打开机器人时的姿态：各关节先使用默认值，然后使用此 SRDF 中声明的 home group state（数据包中的 "jointValues" job 字段含义相同）。快照使用 Viewer 自身的场景绘制机器人，因此显示效果与 Viewer 一致；无法加载的 link 网格会导致操作失败，而不会直接省略该 link。机器人以米为单位建模，系统会根据机器人场景比例自动调整画面取景。

普通快照使用 Solid 模式和 Light 外观。显示模式为 solid（默认）或 parts（每个 link 使用独立颜色），两者各自采用默认值；--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 job 会原样重放：包括其 jointValues、selection.hide（Links 面板中按 id 隐藏的部件）、clip 和 annotation（cadgen snapshot --job <file>）。Quick Edit 可提供内联 JSON 或 .snapshot.json 路径；使用 --job 前，请先将内联 JSON 保存到临时文件。编辑前请检查提供的注释。没有注释时，捕获的视图仅为可选的上下文信息；根据请求需要决定是否渲染。

Link 网格相对于描述文件解析，因此必须确保网格文件存在：未下载内容的 Git LFS 指针会报错 "No link mesh loaded for robot"。请先运行 git lfs checkout <mesh dir>。

SRDF 的几何体来自其配对 URDF，因此 SRDF 没有独立的 snapshot 入口；多态的 cadgen snapshot 会按后缀路由。语法为 cadgen snapshot TARGET [OUT] [flags]，与每种格式入口使用的语法相同。使用 cadgen snapshot --help 查看完整的当前接口。

参考资料

• 编写约定（结构、URDF 配对、标准骨架）：references/authoring-contract.md
• SRDF 工作流（提取 URDF 表、编辑循环）：references/srdf-workflow.md
• 规划台账：references/planning-ledger.md
• 验证与核验流程：references/validation.md
• 末端执行器：references/end-effectors.md
• 禁用的碰撞：references/disabled-collisions.md