BackboneNeo/ai-skills-cad-engineering

CAD 工程工作流程

將儲存庫指示與儲存庫擁有的驗證器視為權威來源。使用此技能使工作系統化；切勿以通用假設取代專案特定需求。

1. 建立合約

1. 在開始撰寫前，閱讀所有適用的 AGENTS.md、完整的專案指南、現行圖紙快照以及請求的 Issue。
2. 識別不可變的基線標籤、CAD 路徑、SHA-256、座標系統、單位系統、當前元件清單、預期可列印實體以及釋出目標。
3. 如果真相來源相互衝突或基線無法驗證，請在編輯前停止。
4. 將請求的結果與相關 Issue 的上下文分開。不要將待辦事項吸收到任務中。
5. 選擇由 Issue、儲存庫政策或用戶宣告的釋出軌道：數位 CAD/圖紙或實體合格產品。圖紙釋出並不表示產品合格。
6. 根據該權威合約，將每個驗收標準分類為計算、視覺、實體或僅操作員。對於圖紙軌道，諸如配合、安裝、移除、夾持、致動、佈線或存取等用語，除非合約明確要求製造樣品或實際測試，否則意味著數位幾何/路徑驗證。切勿將通用工程風險提升為強制關卡，也切勿僅憑幾何資料就報告實體標準已通過。

選擇或驗證基線時，請閱讀 baseline-and-source-truth.md。修復現有失敗候選版本前，請閱讀 failure-patterns.md。

2. 修改前檢查

1. 開啟現有的原生 CAD 文件，檢查其樹狀結構、物件類型、表達式、屬性、位置、群組、實體、可見性以及重新計算狀態。

2. 記錄機器可讀的基線報告。當 FreeCAD 可用時，執行：

   python scripts/run_inspect_fcstd.py --freecad FreeCADCmd.exe --file <baseline.FCStd> --output <baseline-report.json>

3. 不要從網格、STEP、螢幕截圖、快照或引導產生器重建現有的原生文件。

4. 除非任務明確要求那些確切變更，否則不要覆寫用戶儲存的位置、顏色、可見性、表達式或手動編輯。

5. 當儲存庫規則使歷史版本不可變時，請在新的版本化路徑中工作。

3. 實作最小的完整工程變更

1. 使用精確、固定的元件來源。一起保留可編輯來源、確切的匯入工件、來源修訂版與 SHA-256。
2. 將外部元件放置在儲存庫的嵌入式來源群組中，並從驗證過的模型推導安裝幾何。
3. 在其原生上游特徵處取代舊幾何。切勿透過將修補片、板、插頭、蒙皮、填料或共面修復融合到下游完工實體中，來隱藏廢棄的孔、凹坑、減料或安裝特徵。
4. 如果無法恢復原生前特徵實體或可編輯的建構鏈，請停止並設定為阻塞。不要為了獲得請求的最終輪廓而替換為添加性修復幾何。
5. 當儲存庫要求基於草圖的控制時，保持控制幾何可編輯且完全約束。
6. 透過可檢查的依賴鏈或順序布林鏈，將每個控制特徵連接到最終的可列印實體。草圖或切割器的存在並不證明已整合。
7. 更換元件時，移除廢棄的特定元件切割、減料、標籤、活動的嵌入式來源以及下游殘留物。
8. 限制附帶變更。保留不相關的元件位置、可列印實體、座標系統、外觀與文件結構。

對於每個更換或調整大小的開口，請閱讀並遵循 native-feature-replacement.md。有關元件工作，請閱讀 component-integration.md；有關原生建模與布林運算，請閱讀 parametric-geometry.md。

4. 分層驗證

在每個有意義的幾何群組之後執行驗證，而不僅是在最後。

1. 重新計算並拒絕文件錯誤。
2. 儲存、關閉、重新開啟、重新計算、儲存，然後再次重新開啟。
3. 確認預期的可列印實體數量、實體數量、邊界、體積與拓撲。
4. 證明請求的功能影響了預期的最終實體。
5. 對於更換，證明受影響的局部實體等於僅套用了新預期操作的原生未修改特徵。拒絕殘留的舊輪廓、添加性修復依賴、額外的共面邊界以及隱藏的填充實體。
6. 分別檢查碰撞與所需接觸。所需安裝接觸不是不必要的碰撞。
7. 在適用的情況下，以數位方式檢查組裝順序、移除路徑、連接器插入路徑、緊固件軸線、工具包絡、端子可及性、接線空間、彎曲半徑、應變消除。將此證據標記為幾何學證據；不要宣稱實際的配合、力或耐久性。
8. 在可拋棄的副本上測試參數化可編輯性，然後恢復原始參數。
9. 匯出所需的 STL 與 STEP 工件，並獨立重新開啟每個匯出檔案。
10. 分別顯示與隱藏元件的特寫渲染，使原生開口與周圍牆壁可供審查。
11. 渲染已儲存的 FCStd，而不是近似的平行模型。
12. 完全按照執行器控制的方式執行每個儲存庫擁有的測試。

使用 run_inspect_fcstd.py 生成候選報告，然後使用以下命令與基線進行比較：

python scripts/compare_fcstd_reports.py --baseline <baseline-report.json> --candidate <candidate-report.json>

閱讀 validation-matrix.md 以了解每個關卡所需的證據。

5. 組裝連貫的釋出候選版本

1. 保持原生 CAD、嵌入式來源、匯出檔案、預覽、佈局、清單、快照、版本說明與活動索引彼此一致。
2. 僅在最終工件生成後重新計算 SHA-256。在任何承載雜湊的檔案變更後重新執行驗證。
3. 透過差異比較或儲存的雜湊值證明歷史基線的不變性。
4. 當專案政策禁止自動生成時，保持僅手動格式為空。
5. 當任何強制關卡未完成時，不要建立或核准標籤或釋出。
6. 當其要求的數位關卡通過時，允許圖紙釋出，即使可選的未來實體合格性尚未執行。切勿將其標記為生產就緒或實體合格。
7. 僅在所需的實際製造、測量、組裝與工程師簽核通過後，從確切的圖紙提交建立產品合格釋出。

閱讀 release-lifecycle.md 以選擇釋出軌道與標籤政策。在宣告完成前，閱讀 release-gate.md。

6. 誠實回報

• 當所選釋出軌道的所有任務要求關卡都通過時，回傳 completed。
• 僅當權威任務或儲存庫來源明確要求完成不完整的實體或操作員關卡時，回傳 blocked，同時保留已完成的候選版本。
• 僅在證明請求的狀態已存在時，回傳 no_change_needed。
• 將未請求的試片、循環、振動、引腳分配、接線或其他實體測試記錄為後續建議，而不是阻塞項目。不要發明驗收標準。
• 分別列出每個阻塞項目，附上證據與一個可行的下一步行動。
• 區分 not_run、failed 和 passed。切勿將缺乏證據轉化為成功。
• 不要在風險或摘要文字中隱藏釋出阻塞項目。