MoveIt2 SRDF 生成、驗證與規劃語意工作流程。適用於建立、編輯、重新產生、檢查或驗證 `.srdf` 檔案、`gen_srdf()` 來源、MoveIt 規劃群組、虛擬關節、被動關節、末端執行器、群組狀態、停用碰撞、URDF 連結的規劃語意，或 SRDF 交接供即時審查。請使用 URDF 技能處理機器人結構，使用 SDF 技能處理模擬器描述，使用 cad-viewer 技能處理渲染、即時審查連結與選用的 MoveIt2 控制。
SRDF
來源：維護於 earthtojake/text-to-cad。
使用已安裝的本機技能檔案作為執行階段的真實來源；
儲存庫連結僅供來源追溯與版本審查。
此技能用於在現有有效 URDF 之上定義 MoveIt 語意機器人描述。SRDF 定義規劃語意；它不定義實體機器人結構。
SRDF 正確性是一個規劃語意問題。常見的失敗並非無效的 XML；而是看似合理的 SRDF 卻提供 MoveIt 錯誤的規劃群組、錯誤的工具連結、錯誤的預設狀態、不安全的停用碰撞矩陣，或錯誤的關節單位。由於語言模型在空間與運動學推理上較弱，請根據 URDF 拓撲、MoveIt Setup Assistant 輸出、取樣碰撞分析或明確的使用者資料來推導規劃群組、末端執行器、群組狀態與停用碰撞。請勿僅憑視覺外觀推斷。
格式邊界
- URDF 負責實體機器人結構：連結、關節、幾何、慣性、限制、模仿關節、傳動裝置與機器人狀態發布。
- SRDF 負責 MoveIt 語意：虛擬關節、被動關節、規劃群組、群組狀態、末端執行器與停用碰撞對。
- SDF 負責模擬器/世界語意：物理、感測器、光源、插件、世界與模擬特定中繼資料。
請勿將幾何、慣性、關節原點、連結姿勢、網格參考、實體關節限制、傳動裝置或 ros2_control 介面放入 SRDF。
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。
