AI Skills
sdf

sdf

熱門

SDFormat/SDF 模型與世界生成、驗證及模擬器交接。用於 `.sdf` 檔案、SDFormat XML、Python `gen_sdf()` 原始碼、模型、世界、連結、關節、姿態、框架、慣性、視覺/碰撞幾何、網格 URI、感測器、光源、物理、插件、包含、Gazebo、靜態 SDF 審查或模擬器特定中繼資料。請勿用於符號距離場幾何。

8286星標
946分支
更新於 2026/7/11
獲取技能源代碼

相關技能

systematic-literature-review8萬context-window-management4.6萬roundup-setup3.8萬
SKILL.md
唯讀
名稱
sdf
描述

SDFormat/SDF 模型與世界生成、驗證及模擬器交接。用於 `.sdf` 檔案、SDFormat XML、Python `gen_sdf()` 原始碼、模型、世界、連結、關節、姿態、框架、慣性、視覺/碰撞幾何、網格 URI、感測器、光源、物理、插件、包含、Gazebo、靜態 SDF 審查或模擬器特定中繼資料。請勿用於符號距離場幾何。

SDF

來源：維護於 earthtojake/text-to-cad。
使用已安裝的本機技能檔案作為執行階段的真實來源；
儲存庫連結僅供來源追溯與版本審查使用。

當交付項目為 SDFormat 文件或 Python gen_sdf() 原始碼時，使用此技能。SDFormat 描述模擬器與世界行為：模型、世界、框架、姿態、連結、關節、慣性、視覺、碰撞、感測器、光源、物理、插件、包含以及模擬器中繼資料。

此技能適用於 SDFormat，而非符號距離場幾何。

核心規則

  1. 將定義 gen_sdf() 的 Python 檔案視為真實來源。除非使用者明確要求直接編輯 XML，否則將已配置的 .sdf 檔案視為產出成品。
  2. 在編輯前確認目標消費者：Gazebo/libsdformat 版本、其他模擬器、僅視覺化工具、模型套件或世界交接。
  3. 決定文件類型：模型層級 SDF、世界層級 SDF 或模型置於世界中。對於可重複使用的機器人/物體匯出，優先使用模型層級 SDF。
  4. 除非目標明確要求其他單位，否則使用 SI 單位：公尺、公斤、秒、弧度。
  5. 除非目標消費者限制版本，否則新輸出優先使用 version="1.12"。
  6. 在撰寫姿態、框架、關節軸、網格縮放、慣性、感測器或插件之前，先建立設計記錄。使用 references/design-ledger.md 和 references/llm-guardrails.md。
  7. 不要僅憑視覺印象推斷空間轉換。姿態、軸、縮放、質量、慣性及框架名稱應來自上游來源資料、圖紙、模擬器文件、量測值或明確假設。
  8. 優先使用輔助函式與命名常數，而非大型 XML 字串字面值。隱藏數字是常見的 SDF 失敗模式。
  9. 僅透過 scripts/sdf 或儲存庫現有的 SDF 啟動器產生明確目標。不要執行目錄範圍的生成。
  10. 在重新產生參照上游幾何、網格、機器人描述、渲染、拓撲或套件資產的 SDF 之前，先以對應的工作流程重新產生這些資產。
  11. 產生後執行可用的檢查：內建驗證、選擇性 gz sdf --check、模擬器載入、關節運動以及插件/感測器啟動。
  12. 回報假設、跳過的檢查、未解析的資源路徑以及目標特定的相容性風險。

範圍

此技能用於 SDFormat 輸出與產生器。請勿用於符號距離場建模、原始幾何生成、規劃語義，或掩蓋不正確的上游機器人/來源資料，除非任務明確僅限於模擬器。

CAD 檢視器交接

完成建立或修改 .sdf 的 SDF 工作後，若 $cad-viewer 技能已安裝，你必須將明確的檔案路徑傳遞給 $cad-viewer。$cad-viewer 必須啟動 CAD 檢視器（若尚未執行）並回傳相關已建立或修改檔案的連結；若 $cad-viewer 不可用或啟動失敗，則回報此情況，而非默默省略交接。

工作流程

  1. 找到 gen_sdf() 原始碼與預期的 .sdf 輸出。
  2. 讀取或建立設計記錄。
  3. 在編輯任何 <pose>、<frame>、關節軸、relative_to、expressed_in、巢狀範圍、感測器框架或插件框架之前，先閱讀 references/frame-semantics.md。
  4. 編輯產生器原始碼，而非產生的 XML。
  5. 當建構輔助工具能使產生的結構更清晰時，可選擇使用；仍允許使用原始 ElementTree。
  6. 重新產生明確目標。
  7. 將內建驗證視為防護措施，而非模擬器保證。
  8. 若可用，執行目標消費者煙霧測試。
  9. 回報已執行、已跳過的檢查以及假設。靜態渲染不執行 SDF 插件，也不讀取檔案中的運動中繼資料。

指令

使用專案或工作區的 Python 環境執行。將範例中的 python 視為直譯器佔位符；若裸 python 不可用，請替換為 python3、專案虛擬環境直譯器或已配置的直譯器路徑。

python scripts/sdf path/to/source.py
python scripts/sdf path/to/source.py -o path/to/output.sdf
python scripts/sdf path/to/a.py=out/a.sdf path/to/b.py=out/b.sdf

純 Python 目標會在其原始碼旁寫入同層級的 .sdf 檔案。-o / --output 僅在單一目標時有效。SOURCE.py=OUTPUT.sdf 支援自訂多目標目的地。

若執行環境支援選擇性外部檢查：

python scripts/sdf path/to/source.py --gz-check auto
python scripts/sdf path/to/source.py --gz-check required
python scripts/sdf path/to/source.py --gz-check never

gz sdf --check 是選擇性的目標消費者驗證。當不可用時應回報為已跳過，除非明確要求。

必要報告格式

完成 SDF 任務時，請包含簡潔報告：

Generated: path/to/model.sdf from path/to/model.py
Checks run:
- bundled SDF validation: passed
- gz sdf --check: skipped, gz not installed
- simulator load: skipped, target simulator unavailable
- viewer handoff: `$cad-viewer` link returned
Assumptions:
- Assumed mesh units are meters.
- Assumed lidar frame is coincident with lidar_link.
Risks:
- Camera plugin filename was not verified in the target simulator environment.

參考資料

  • Generation command: references/gen-sdf.md
  • Generator contract: references/generator-contract.md
  • SDF workflow: references/sdf-workflow.md
  • Builder helpers: references/builder-helpers.md
  • LLM guardrails: references/llm-guardrails.md
  • Design ledger: references/design-ledger.md
  • Frame semantics: references/frame-semantics.md
  • Validation scope: references/validation.md
  • Smoke tests: references/smoke-tests.md
  • Interoperability notes: references/interoperability.md
  • Examples: references/examples.md
  • Runtime notes and current limitations: references/implementation-notes.md