编写或校验 MoveIt2 SRDF 规划语义时，用…

在已有有效 URDF 上创建、修改、检查或验证 `.srdf` 文件，并确保 MoveIt 规划组、虚拟/被动关节、末端执行器、组状态和禁用碰撞对正确且可验证。

适用场景

解决思路

1. 安装 cadgen 运行时：`python -m pip install -r requirements.txt`。
2. 安装渲染所需浏览器：`python -m playwright install chromium`。
3. 将已安装的本地技能文件作为运行时事实源；仓库链接仅用于溯源和发布审查。
4. 在已有有效 URDF 之上使用该技能；SRDF 只定义 MoveIt 规划语义，不定义物理结构；直接编辑 `.srdf` XML，不要寻找 `gen_srdf()` 契约。
5. 将 SRDF 正确性视为规划语义问题：重点防止规划组、工具链接、默认状态、禁用碰撞矩阵或关节单位看似合理但实际错误。
6. 不要仅凭视觉主题推断规划组、末端执行器、组状态或禁用碰撞；由于语言模型空间/运动学推理弱，应从 URDF 拓扑、MoveIt Setup Assistant 输出、采样碰撞分析或用户明确数据中推导。
7. 不要凭记忆输入任何链接或关节名；先提取 URDF 的 link/joint 表并从中复制名称。
8. 遵守格式边界：URDF 负责 links、joints、geometry、inertials、limits、mimic joints、transmissions、robot-state publishing 等物理结构。
9. SRDF 负责 MoveIt 语义：virtual joints、passive joints、planning groups、group states、end effectors、disabled collision pairs。
10. SDF 负责仿真/世界语义：physics、sensors、lights、plugins、worlds、simulation-specific metadata。
11. 不要将 geometry、inertials、joint origins、link poses、mesh references、physical joint limits、transmissions、`ros2_control` interfaces 放入 SRDF。
12. 完成创建或修改 `.srdf` 的工作后，若安装了 `$cad-viewer`，必须始终把显式文件路径交给 `$cad-viewer`。
13. `$cad-viewer` 必须启动 CAD Viewer（若尚未运行），并返回相关创建/更新文件的链接。
14. 如果 `$cad-viewer` 不可用或启动失败，报告该情况，不能默默省略交接。
15. 从有效 URDF 开始：先用 `$urdf` 编写或修复 URDF 并验证；SRDF 通过同目录放置和机器人名称与该 URDF 配对，SRDF 中每个名称都必须存在于其中。
16. 在写任何 SRDF XML 前，提取 URDF 表：列出 robot name、links、joints（type、parent、child、limits、mimic flags）；只从该表复制名称，绝不凭记忆输入；参考 `references/srdf-workflow.md`。
17. 识别规划任务：记录目标是 arm IK、gripper control、mobile base planning、dual-arm planning、tool use 还是 local smoke testing。
18. 在写 XML 前创建或更新规划账本：使用 `references/planning-ledger.md`，并在 `.srdf` 中保留一个紧凑副本作为注释块。
19. 通过同目录放置与 URDF 配对：把 `.srdf` 与其 `.urdf` 保存在同一文件夹，并使用相同 `<robot name>`；这是唯一链接机制。
20. 校验器和查看器都通过扫描文件夹中机器人名称匹配的 URDF 来解析配对；每个机器人名称在每个文件夹中必须恰好一个 URDF；没有元数据元素链接文件；参考 `references/authoring-contract.md`。
21. 按机器人模型需要，刻意定义 virtual joints 和 passive joints。
22. 从 URDF 拓扑定义规划组；对于串联机械臂，当 base/tip 在 URDF 树中形成真实 parent-to-child 路径时，优先使用 chain group（校验器会验证）；只有在有意时才使用 joint/link/subgroup 定义。
23. 在组归属已知后定义 end effectors；避免 end-effector group 与其 parent group 重叠；记录实际 target/TCP link。
24. 用 URDF 原生单位定义 group states：revolute 和 continuous 用弧度，prismatic 用米；不要在 SRDF 中存角度；值必须在 URDF limits 内，且不得设置 fixed 或 mimic joints。
25. 基于证据生成 disabled collisions：使用从 URDF joint 表推导的 adjacency、MoveIt Setup Assistant 采样，或用户明确提供的 collision matrices；不要编造宽泛禁用列表；参考 `references/disabled-collisions.md`。
26. 对每个创建或修改的 `.srdf` 运行 `cadgen srdf validate`；它会针对配对的 URDF 交叉验证所有名称、chains、states 和 pairs；修复发现并重新验证直到干净。
27. 当可用时运行 MoveIt smoke tests：直接使用 MoveIt Setup Assistant 或项目 MoveIt launch。
28. 报告假设和跳过的检查：包括不完整验证、缺少 MoveIt 环境、手动推理的 collision disables、推断的 target links。
29. 从安装 `requirements.txt` 的 Python 环境运行 `cadgen`（等价 PATH 无关命令：`python -m cadgen.cli <verb>`）；运行 `cadgen doctor <skill-dir>` 验证已安装 cadgen 匹配该技能的 pin，避免文档因不匹配安装而静默漂移。
30. 验证本身只需要 Python 标准库；只有 snapshots 需要浏览器；使用 `cadgen <verb> --help` 查看完整当前接口。
31. 使用校验器形状：`cadgen srdf validate path/to/robot.srdf`、`cadgen srdf validate path/to/robot.srdf --strict`、`cadgen srdf validate path/to/robot.srdf --json`。
32. 理解校验器行为：解析 SRDF，解析配对 URDF（同文件夹中 robot name 匹配的 `.urdf`；没有、多个或无效都是错误），并交叉验证 group/joint/link/subgroup 名称存在性、chain path 可解析性、subgroup cycles、virtual/passive joints、end-effector topology、group-state membership/limits/completeness、disabled-collision pairs（包括 Adjacent-reason truthfulness）以及拼写错误元素。
33. 每个阶段一次收集其所有发现（severity、code、XML path），但结构性错误会停止跨文件阶段；每次修复后重新运行；一次运行只验证一个文件。
34. `--strict` 将 warnings 视为 failures；`--json` 打印一行 JSON，字段包括 `ok`、`path`、`issues`（每项含 `severity`、`code`、`message`、`element`、`hint`）、`summary`，其中 `element` 是 XML path；目标失败时退出码非零；相对目标从当前工作目录解析。
35. 硬性规则：SRDF 必须与其 URDF 同文件夹并共享 `<robot name>`；这种同目录加名称匹配是唯一配对机制；文件夹中每个机器人名称只能有一个 URDF。
36. 硬性规则：每个 link、joint、group、subgroup 名称必须来自 URDF 表或同一文件中定义的 group。
37. 硬性规则：group states 使用 URDF 原生单位：revolute/continuous 用弧度，prismatic 用米。
38. 硬性规则：disabled collision pairs 需要真实原因和 provenance。
39. 硬性规则：end-effector groups 不应与其 parent planning group 共享 links。
40. 硬性规则：视觉渲染审查有用，但不能证明规划正确性。
41. Snapshot：使用 `cadgen snapshot path/to/robot.srdf review.png` 将机器人渲染为 PNG 静帧；它使用共享 CLI 和无头浏览器运行时，因此快照与 CAD Viewer 显示一致。
42. 交给它 `.srdf`；它按后缀路由并渲染配对 URDF 的几何。
43. 使用 `--joint-values` 摆姿势：传入 `{joint: degrees}` JSON；未命名的 joints 保持在 rest pose；packet 中的 `"jointValues"` job 字段含义相同；机器人以米为单位创作，并自动按机器人场景尺度取景。
44. 普通 snapshot 使用确定性 light CAD 光照，并隐藏 grid 和 axis guides；传入 `--render light` 或 `--render dark`（或 photographic Render JSON 或文件路径）使用共享 Render 场景；没有 `studio` 的 envelope 在 CLI 中解析为 Light。
45. 在 Render JSON 内设置相机；顶层 `--camera`、`--display`、`--joint-values` 控制普通 snapshots，不能与 Render 组合；机器人 link meshes 没有 CAD-edge 或 exploded assembly 拓扑，因此这些显示组合会被明确拒绝。
46. Link meshes 相对于 description 解析，因此必须存在：未水合的 Git LFS pointer 会失败为 `No link mesh loaded for robot`；先运行 `git lfs checkout <mesh dir>`。
47. SRDF 的几何来自其旁边的 URDF，因此它没有自己的 snapshot door；多态 `cadgen snapshot` 按后缀路由；语法是 `cadgen snapshot TARGET [OUT] [flags]`，与其他格式 door 相同；使用 `cadgen snapshot --help` 查看完整当前接口。
48. 参考文件：按需查阅 `references/authoring-contract.md`、`references/srdf-workflow.md`、`references/planning-ledger.md`、`references/validation.md`、`references/end-effectors.md`、`references/disabled-collisions.md`。

适用边界 · 注意事项

• 没有有效 URDF，或任务是在定义机器人物理结构（links、joints、geometry、inertials、limits、transmissions、`ros2_control`）时，不使用 SRDF；先用 `$urdf`。
• 任务属于仿真/世界语义（physics、sensors、lights、plugins、worlds、simulation-specific metadata）时，不使用 SRDF；应使用 SDF skill。
• 需要仅凭视觉渲染/外观主题证明规划正确性，或需要 MoveIt/cadgen/CAD Viewer 环境但缺失时，不应把 SRDF 工作视为已充分验证。