cicd-diagnostics

cicd-diagnostics 技能是一款專門為資深平台工程師設計的工程工具包，用於排查並解決 dotCMS/core 儲存庫中的 CI/CD 管線故障。它提供了一套結構化且基於證據的工作流程，協助從原始故障日誌中釐清根本原因，避免在確認故障是否為已知問題、不穩定測試（flaky test）或基礎架構問題之前，就過早跳入原始碼分析的常見錯誤。

• 自動識別 GitHub Actions 工作流程（包括 PR、合併隊列、主分支及每日運行）中失敗的工作與步驟。
• 執行智慧型日誌分析，提取堆疊追蹤、斷言錯誤及基礎架構錯誤，同時過濾掉來自 'continue-on-error' 步驟的干擾訊息。
• 利用內建診斷腳本，透過 diagnose.py 工具執行預檢、工作區管理及結構化的證據收集。
• 搜尋現有的 GitHub 問題以獲取測試故障的歷史背景，確保在開始深入調查前識別已知問題。
• 透過 evidence.py 提供進階日誌分析，將故障分類為新缺陷、不穩定測試或環境相關的逾時問題。
• 協助比較不同工作流程類型，例如 PR 驗證與完整合併隊列測試套件之間的差異。

使用說明與限制：

• 必須在 dotCMS/core 的有效檢出（checkout）環境中執行。
• 依賴 Python 3.8+ 及已驗證的 GitHub CLI (gh) 環境。
• 應始終優先考慮分類診斷與歷史問題搜尋，再進行深入程式碼分析，以優化 Token 使用量與工程時間。
• 使用提供的子指令（如 --metadata, --logs, --evidence）來逐步收集資料，而非在每個步驟都抓取完整日誌。
• 避免手動臨時解析 JSON 日誌；請使用整合的工具函式，確保資料提取的一致性與準確性。
• 該工具針對識別不穩定測試、基礎架構連線問題及部署/驗證錯誤等特定訊號進行了優化。