多維計算實驗狀態管理器

多維管理器

一個自足技能，為長時間執行的多維計算實驗帶來秩序。您的計算外掛負責數學計算；這個技能管理周圍的混亂：迭代、快照、稽核和回滾。

這個技能僅負責編排。它永遠不會自行計算結果——每個數字都來自您的外掛。

使用時機

• 工作流程需要在參數空間（維度的笛卡兒網格）中執行多回合，且每回合的狀態需要被記錄下來。
• 在每回合前後，需要對宣告的關鍵檔案進行快照。
• 每回合必須保留完整的稽核軌跡（參數、雜湊、時間戳記、狀態）。
• 使用者必須能夠非破壞性地回滾到任何過往回合。
• 典型情境：縱向研究、參數掃描，或呼叫外部求解器（Mathematica、GAP、SymPy、自訂腳本）的符號/數值掃描。

強制工作流程

依賴引導（首次使用時執行）

首次執行前，檢查此技能的執行時期依賴：

• 核心：純標準函式庫 — 無需安裝。
• 可選：PyYAML（僅當設定檔是 .yaml 時需要；JSON 設定檔只需標準函式庫即可）。

如果缺少 PyYAML 且使用者的設定是 YAML，則告訴使用者並詢問是否要 pip install pyyaml；只在使用者確認後才安裝。未經明確同意，絕對不要在全局環境中安裝。

無論使用者要求執行、檢查或恢復多維實驗，請依序遵循下列步驟：

1. 載入設定。 讀取實驗設定檔（config.example.yaml 為範本）。確認 param_space.dimensions、critical_paths 和 plugin.command 都存在。如果使用 YAML，必須安裝 PyYAML；否則使用 JSON。
2. 展開空間。 列舉所有維度的笛卡兒乘積。在開始執行前向使用者報告總回合數。
3. 偏好乾執行。 執行 python scripts/run.py dryrun --config <cfg>，讓使用者看到完整計畫（每個參數組合）而不產生任何副作用。只有在使用者確認後才繼續執行。
4. 執行掃描。 執行 python scripts/run.py run --config <cfg>。對每回合，依序：之前 快照宣告的關鍵路徑，呼叫外掛，之後 快照，並附加一條稽核記錄。
5. 正確應對失敗。 如果某回合的外掛以非零狀態碼退出，記錄其狀態（failed/error）。啟用 auto_rollback 時，將上一成功回合的執行後狀態恢復到工作目錄，以便後續回合從乾淨狀態開始；這個恢復過程本身也會被稽核。不要因為單一錯誤組合而停止整個掃描。
6. 總結。 掃描完成後，技能會在輸出目錄下寫入 results_summary.csv、results_summary.md、report_draft.md 和 run_metadata.json。將這些檔案指向給使用者。
7. 按需恢復。 要恢復過往回合，執行 python scripts/run.py rollback --config <cfg> --round <N>。預設情況下，它會將內容恢復到一個新目錄；只有當使用者明確想要覆寫目前的工作目錄時，才加上 --force。

硬性限制

• 絕對不要自行計算結果。 所有領域數學都屬於使用者外掛。這個技能僅呼叫它並記錄合約結果。
• 僅快照宣告的關鍵路徑。 永遠不會複製完整的工作目錄；內容以雜湊位址儲存，因此不變的檔案不會產生額外成本。
• 回滾預設為非破壞性。 沒有 --force 時，目前的工作目錄永遠不會被修改；恢復的狀態會放置在新的目錄中。每次回滾（手動或自動）都會被寫入稽核日誌。
• 確定性是用戶的承諾。 這個技能保證編排是可複現的（相同的參數 -> 相同的記錄計畫，相同的雜湊）。它無法保證一個非確定性外掛變成確定性的；請參閱限制。

使用範例

# 列出完整回合計畫而不產生任何副作用（請始終先執行此步驟）。
python scripts/run.py dryrun --config config.example.yaml

# 執行掃描。
python scripts/run.py run --config config.example.yaml

# 恢復過往回合（除非加上 --force，否則會恢復到一個新目錄）。
python scripts/run.py rollback --config config.example.yaml --round 7

# 重新生成總結，或驗證某回合的結果。
python scripts/run.py summary --config config.example.yaml
python scripts/run.py verify --config config.example.yaml --round 7

外掛合約

管理器每回合啟動一個 shell 命令：

python your_plugin.py --params {PARAMS} --out {OUT}

• {PARAMS} - 一個 JSON 檔案的路徑，包含該回合的參數組合。
• {OUT} - 外掛必須將其結果 JSON 寫入的路徑。
• 退出碼：0 成功，1 斷言失敗/檢查失敗，2 錯誤或跳過。

任何外部求解器（Mathematica、GAP、Python LMM 腳本）都應被封裝以遵守這個合約：它讀取參數檔案並寫入結果檔案。技能不在意計算了什麼。

失敗處理

• 外掛以 1 退出的回合被標記為 failed；2 為 error。兩者都會保留在稽核日誌中；掃描會繼續。
• config 錯誤（缺少空間、格式錯誤的 YAML、缺少 {OUT}）會在產生任何副作用之前中止，並列印清晰的訊息（退出碼 2）。
• 對從未記錄、或沒有執行後快照的回合進行 rollback，會因明確的錯誤而失敗，而不是破壞狀態。

限制

• 確定性僅限於編排層。 管理器會記錄雜湊並為相同參數重播相同的計畫，但它無法強制外掛是確定性的。如果外掛涉及網路、使用亂數種子或讀取系統時鐘，相同的輸入可能產生不同的輸出。請在外掛中自行宣告此類非確定性。
• 關鍵路徑必須預先宣告。 未列在 critical_paths 中的檔案永遠不會被快照，因此也無法回滾。
• 黃金輸出驗證是 v0.2。 目前的驗證器只檢查外掛合約（exit 0 + 結果檔案存在）。與已知預期輸出的比較功能已規劃但尚未實作。
• YAML 設定需要 PyYAML。 JSON 設定僅需標準函式庫即可。