MoveIt2 SRDF生成、验证和规划语义工作流。用于创建、编辑、重新生成、检查或验证`.srdf`文件、`gen_srdf()`源、MoveIt规划组、虚拟关节、被动关节、末端执行器、组状态、禁用碰撞、URDF关联的规划语义，或用于实时审查的SRDF交接。使用URDF技能处理机器人结构，使用SDF技能处理仿真器描述，使用cad-viewer技能进行渲染、实时审查链接和可选的MoveIt2控制。
SRDF
来源：维护于earthtojake/text-to-cad。
使用已安装的本地技能文件作为运行时真实来源；
仓库链接仅用于来源追溯和发布审查。
此技能用于在现有有效URDF之上定义MoveIt语义机器人描述。SRDF定义规划语义；它不定义物理机器人结构。
SRDF正确性是一个规划语义问题。常见失败不是无效的XML；而是一个看似合理但给MoveIt提供了错误规划组、错误工具链接、错误默认状态、不安全禁用碰撞矩阵或错误关节单位的SRDF。由于语言模型在空间和运动学推理方面较弱，请从URDF拓扑、MoveIt Setup Assistant输出、采样碰撞分析或明确的用户数据中推导规划组、末端执行器、组状态和禁用碰撞。不要仅凭视觉外观推断。
格式边界
- URDF 拥有物理机器人结构：连杆、关节、几何、惯性、极限、模仿关节、传动装置和机器人状态发布。
- SRDF 拥有MoveIt语义：虚拟关节、被动关节、规划组、组状态、末端执行器和禁用碰撞对。
- SDF 拥有仿真器/世界语义：物理、传感器、灯光、插件、世界和仿真特定元数据。
不要在SRDF中放置几何、惯性、关节原点、连杆位姿、网格引用、物理关节极限、传动装置或ros2_control接口。
CAD Viewer 交接
在完成创建或修改.srdf的SRDF工作后，当该技能已安装时，您必须始终将明确的文件路径交给$cad-viewer。$cad-viewer必须启动CAD Viewer（如果尚未运行）并返回相关创建或更新文件的链接；仅在用户需要交互式IK或路径规划审查时，在交接中包含可选的MoveIt2控制。如果$cad-viewer不可用或启动失败，请报告该情况，而不是静默省略交接。
必需工作流
- 从有效URDF开始。 首先生成或修复URDF。SRDF生成器会根据
gen_srdf()提供的源相对.urdf路径进行验证。 - 识别规划任务。 记录目标是手臂IK、夹爪控制、移动底盘规划、双臂规划、工具使用还是本地冒烟测试。
- 创建或更新规划台账。 在编写XML之前使用
references/planning-ledger.md。 - 有目的地定义虚拟关节和被动关节。 当机器人模型需要时使用它们，即使当前轻量级运行时尚未完全盘点它们。
- 从URDF拓扑定义规划组。 对于串联机械臂，当基座/末端形成实际路径时，优先使用链组。仅在有意为之的情况下使用关节/连杆/子组定义。
- 在组隶属关系已知后定义末端执行器。 避免末端执行器组与其父组之间的重叠。记录实际目标/TCP链接。
- 以URDF原生单位定义组状态。 旋转和连续关节值为弧度；移动关节值为米。不要在SRDF中存储度数。
- 基于证据生成禁用碰撞。 使用邻接关系、MoveIt Setup Assistant采样或用户提供的显式碰撞矩阵。不要凭空创建广泛的禁用列表。
- 仅重新生成明确的SRDF目标。 生成在写入前会验证生成的SRDF与关联的URDF。
- 在可用时运行MoveIt冒烟测试。 直接使用MoveIt Setup Assistant或项目MoveIt启动文件。
- 报告假设和跳过的检查。 包括不完整的验证、缺失的MoveIt环境、手动推理的碰撞禁用和推断的目标链接。
命令
使用项目或工作空间的Python环境运行。将示例中的python视为解释器占位符；如果裸python不可用，请替换为python3、项目虚拟环境解释器或配置的解释器路径。
从本技能目录，SRDF启动器形式为：
python scripts/srdf path/to/source.py
python scripts/srdf path/to/source.py -o path/to/robot.srdf
python scripts/srdf path/to/a.py=out/a.srdf path/to/b.py=out/b.srdf
相对源目标和CLI输出覆盖从当前工作目录解析。当从本技能目录外部运行时，请为启动器路径添加前缀，以便目标文件仍能从预期工作空间解析。
硬性规则
- SRDF必须引用一个现有的有效URDF。
- SRDF机器人名称必须与URDF机器人名称匹配。
- 组状态使用URDF原生单位：旋转/连续关节为弧度，移动关节为米。
- 禁用碰撞对需要真实原因和来源。
- 末端执行器组不应与其父规划组共享连杆。
$cad-viewer拥有可选的本地moveit2_server指导，用于交互式规划审查。- 视觉渲染审查有用，但不能证明规划正确性。
参考
- 生成命令：
references/gen-srdf.md - 生成器契约：
references/generator-contract.md - SRDF工作流：
references/srdf-workflow.md - 规划台账：
references/planning-ledger.md - 验证范围：
references/validation.md - 末端执行器：
references/end-effectors.md - 禁用碰撞：
references/disabled-collisions.md - 运行时说明和当前限制：
references/implementation-notes.md
对于本地MoveIt2控制，请使用$cad-viewer；在该技能中，阅读references/moveit2-server.md。
