優化交接（核心優化） 是做什麼的？
當目標是將核心推向硬體極限（而非僅進行效能抽查）時，此文件是 Primus-Turbo 與位於 ../../kernel-optimize/SKILL.md 的自動化優化迴圈之間的介面。它提供該迴圈所需的前提資訊。請先閱讀中心樞紐文件 ../SKILL.md。
流程
- 驗證環境 —
pip show primus_turbo；若未安裝則以可編輯模式重新安裝（中心樞紐SKILL.md→ 建置）。 - 閱讀
kernel-optimize/SKILL.md的「前提資訊」 — 了解迴圈需要哪些資訊。 - 收集目標運算元的前提資訊（下表 + 中心樞紐
SKILL.md中的程式碼對應表 / 指令）。 - 交接給
kernel-optimize/SKILL.md；它會依序執行 DEFINE_TARGET → PREPARE_ENVIRONMENT → BASELINE → (ANALYZE → OPTIMIZE → VALIDATE)* → REPORT。 - 驗收 — 回到專案中：執行完整套件
pytest tests/pytorch/ -v，審查報告，確認有乾淨的差異/提交。
在迴圈開始之前，請閱讀 ../../../rules/iteration_rules.mdc：每輪一個假設，正確性門檻優先於效能，接受/回滾譜系，且每個被接受的增益都必須轉移到真實的訓練步驟中（不允許以 id(...) 為鍵的激活/梯度輸出快取，不允許僅限均勻分佈的 GroupGemm 捷徑）。
前提資訊（每個運算元）
| 需求 | 取得位置 |
|---|---|
| 核心原始檔路徑 | 中心樞紐 SKILL.md → 程式碼對應表 |
| 聚焦測試指令 | 中心樞紐 SKILL.md → 測試與基準；例如 pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON" |
| 聚焦基準指令 | ../verify-performance/SKILL.md；例如 PRIMUS_TURBO_GEMM_BACKEND=TRITON python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise |
| 基準輸出格式 / 指標 | ../verify-performance/SKILL.md（Forward/Backward TFLOPS、Check 門檻） |
| 快速驗證工具 | 下方「快速驗證」 |
| 評分規則 | 下方「優化評分」 |
execution_mode + 重建 | 下方「優化環境」 |
優化環境
| 後端 / 語言 | 推薦的 execution_mode | 修改後重建方式 |
|---|---|---|
| Triton (Python) | repo-mode | 無需重建（可編輯安裝） |
| HIP / CK (C++)，小型/參數修改 | repo-mode | GPU_ARCHS=<arch> pip install --no-build-isolation -e . -v |
| HIP / CK (C++)，新核心/大量嘗試錯誤 | workspace-mode | 依照 kernel-optimize/SKILL.md 中的最小堆疊設定 |
優化評分
Check 欄位是硬性門檻 — 任何 FAIL/ERROR 形狀都拒絕該候選。
| 最佳化類型 | primary_metric（匯總 = 所有 PASS 形狀的幾何平均） |
|---|---|
| 計算密集型，僅前向 | Forward TFLOPS |
| 計算密集型，前向 + 反向（訓練） | Combined Step TFLOPS（前向/反向保留作為診斷用） |
| 記憶體密集型（逐元素、量化） | Forward GB/s / Backward GB/s |
合併步驟的推導方式（對於 fwd+bwd GEMM 類運算元為首選）位於 ../verify-performance/SKILL.md。請在 DEFINE_TARGET 階段與使用者確認 primary_metric。
快速驗證
兩種工具，各自獨立角色 — 請勿跨工具比較絕對數值（它們使用不同的計時引擎）：
quick_test_bench.py（此文件夾，會複製到最佳化活動目錄中）是逐輪形狀回歸門控的權威來源。BASELINE（第1輪）以及每個 VALIDATE 輪次都執行此腳本，並比較其--summary-csv輸出。它使用手動實作的time.perf_counter迴圈。- 完整的
bench_<op>_turbo.py（參見../verify-performance/SKILL.md，使用torch.utils.benchmark.Timer）僅用於 (i) 從完整形狀集中選取representative_shapes，以及 (ii) 在最佳化活動結束後進行最終驗收。
兩個驗證層級都透過 quick_test_bench.py 執行，僅 SHAPES 不同：
- 完整驗證（BASELINE + 最終驗收）→
SHAPES= 所有target_shapes。 - 快速驗證（每個 VALIDATE 輪次）→
SHAPES= 3–5 個representative_shapes子集。
representative_shapes：僅取 BASELINE 執行中 Check=PASS 的形狀，涵蓋小規模（啟動開銷）與大規模（計算/記憶體）規模，優先選擇變異數高的形狀。記錄在 manifest.yaml 的 representative_shapes 欄位中。
工具包： 範本 quick_test_bench.py 是規範參考。在 PREPARE_ENVIRONMENT 階段，將其複製到 <campaign_dir>/quick_test_bench.py，SHAPES 設為空值，<target_backend> 設為目標後端；BASELINE 階段將 SHAPES 填入所有 target_shapes，然後在 VALIDATE 輪次中縮小為 representative_shapes。根據目標調整運算元/配置；保留 --summary-csv 寫入器和欄位結構（非 GEMM 運算元請參閱下方的結構範圍說明）。
量測一致性合約： BASELINE（第1輪）與每個 VALIDATE 輪次都透過 --summary-csv 讀取同一個權威 CSV，且所有輪次使用相同的 CSV 讀取器進行一致解析 — 若已配置，可使用選用的 mcp__turbo__parse_bench_csv MCP 輔助工具，否則使用以以下欄位為鍵的直接 csv.DictReader。使用哪個讀取器並不重要，關鍵在於固定資料結構。資料結構必須與以下欄位完全一致（任何偏移都會自動停用逐形狀回歸門控）：
label,B,M,N,K,Check,Forward TFLOPS,Forward TFLOPS_stddev,Backward TFLOPS,Backward TFLOPS_stddev,Forward Time (ms),Backward Time (ms),out_snr,da_snr,db_snr
Check 使用 PASS / FAIL；*_stddev 是該指標單位的絕對標準差。在 manifest.yaml 中將呼叫記錄為 quick_command: "python <campaign_dir>/quick_test_bench.py"；BASELINE 與每個 VALIDATE 輪次都追加 --summary-csv <round_dir>/artifacts/benchmark.csv。
資料結構範圍： 以上欄位是 GEMM 類專用（M,N,K 維度、Forward/Backward TFLOPS、out_snr/da_snr/db_snr）。對於非 GEMM 運算元，保留 label、Check 以及 *_stddev 慣例，但將 GEMM 專用欄位替換為你的 primary_metric 所需的欄位 — 例如記憶體密集型運算元（依「優化評分」）應使用 Forward GB/s / Backward GB/s 取代 TFLOPS，而單一輸出運算元則應以自身的正確性指標取代 out_snr/da_snr/db_snr。無論選擇何種資料結構，請在 BASELINE 階段將其固定，在所有輪次中保持位元組一致，並更新所使用的 CSV 讀取器（若已配置，則更新 mcp__turbo__parse_bench_csv 對應關係；否則更新直接的 csv.DictReader）以匹配 — 逐形狀回歸門控依賴於精確的欄位名稱。