mvschwarz/openrig-upgrade

升級 OpenRig

升級是一個可觀察的代理程式工作流程，而非隱藏在單一指令後的交易。主機各不相同、程序狀態會漂移、本地擴充檔案會累積，而對於失敗步驟的有效回應取決於哪些部分仍在運作。

代理程式擁有序列的控制權。每次變更後都應停止，並觀察實際效果，然後再選擇下一步。 刻意不提供端到端的升級子命令。

安全模型

請保持以下層面分離：

• 席位通常存在於 tmux 中，且可在 daemon 重新啟動後繼續存在。
• Daemon、資料庫、包裝器以及受管理的擴充投影，是正在被變更的控制平面。
• rig down 會拆除席位。它並非連續性保留升級的一部分。

在採取行動之前，請指明其連續性至關重要的 rig 和席位。在生產主機上，請使用該主機的正常操作員儀式。在利於復原的建構虛擬機上，協調器可以直接採用測試過的執行環境，但仍需觀察每個步驟，並在出現無法解釋的漂移時停止。

當復原跨越實例邊界時

在任一通道變更執行環境狀態之前，記錄一個主機限定的執行者，並明確選擇負責復原裁決的佇列儲存體。說明原始擁有者是繼續、等待還是轉移；在其他儲存體中的未完成義務並非對此裁決的專屬保管權。如果原始儲存體故障，請在存活的裁決中保留其擁有者的處置，並在任何競爭執行者採取行動之前將其傳達給該擁有者。

被拒絕的主張意味著在進一步的執行環境操作之前，需與裁決擁有者協調擁有權；不得基於另一個獨立的較舊行繼續執行。歸還操作需指明完整的執行者位址和刻意選擇的儲存體。在恢復操作之前，請讀取該處的結果行，包括來源、目的地、主體以及原始擁有者的處置。僅建立接收確認並不能證明正在等待的通道已收到或接受轉移。

循環

針對每個步驟：

1. 檢查。 從運行中的主機推導出當前事實。
2. 決定。 選擇一個有邊界的變更，並陳述其預期效果。
3. 執行一次。 不要將下一次變更與此變更捆綁在一起。
4. 觀察。 檢查該步驟可能已變更的程序、監聽器、資料庫、擴充和席位層面。
5. 繼續、調整或停止。 失敗的預期對代理程式來說是資訊，而不是盲目重試的許可。

有界的輔助程式

設 SKILL_DIR 為包含此 SKILL.md 的目錄。這些腳本輸出 JSON，且不決定升級順序。

檢查當前事實

node "$SKILL_DIR/scripts/inspect-upgrade.mjs"

此腳本向已安裝的 rig 詢問其版本、daemon 狀態、節點庫存和擴充庫存。遺失的層面會保持可見，並附帶建議的下一個探測。ready: false 表示代理程式必須解決或有意識地限制該差距；這並不表示腳本應進行任何變更。

備份 SQLite

首先取得連續性快照：

rig snapshot <rig-id>
node "$SKILL_DIR/scripts/backup-sqlite.mjs" \
  --source "$OPENRIG_HOME/openrig.sqlite" \
  --destination "/safe/path/openrig-before-upgrade.sqlite"

此輔助程式拒絕覆寫目的地，在可用時使用 sqlite3 CLI 的 .backup 命令（當 CLI 不存在時，則透過 node:sqlite 回退到行程內備份），並透過 PRAGMA integrity_check 驗證備份。它不會停止 daemon 或還原資料庫。

規劃或套用安全的受管理擴充重新整理

擴充樹可能包含技能以及鉤子和元資料。比較最後一個打包的祖先、目標套件和已安裝的即時樹：

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>"

檢閱排序後的決策。若要僅套用 refresh-safe 和 add-safe 檔案：

node "$SKILL_DIR/scripts/refresh-managed-plugin.mjs" \
  --ancestor /path/to/previous/package/plugin \
  --target /path/to/target/package/plugin \
  --live "$OPENRIG_HOME/plugins/<plugin>" \
  --apply-safe

此輔助程式絕不會刪除即時檔案，也絕不會覆寫本地修改。本地刪除、僅存在於即時的檔案、目標移除以及不明確的類型都會被回報，由代理程式解決。在任何手動解決後重新執行規劃。

遷移 pre-0.5.9 的實例佈局

版本 0.5.9 將上下文使用情況遙測資料放在 $OPENRIG_HOME/state/context-usage，提供者遙測資料放在 state/provider-usage，可定址的函式庫放在 context/ 下，以及預設系統世界放在 context/system/system-world.yaml。現有的 0.5.8 主目錄透過代理程式操作遷移跨越該邊界：目標執行環境在 canonical-first 模式下讀取，並以 legacy-fallback 作為備用，而所有新的寫入則使用 canonical 狀態根。明確配置的自訂上下文函式庫根在整個啟動過程中保持穩定。

此輔助程式提供有邊界、可檢查的操作。代理程式擁有它們的順序以及它們之間的目標執行環境啟動。使用確切的受保護預像路徑，首先檢查，然後準備 canonical 目錄、預設系統世界以及一個指向現有函式庫的配置固定。準備工作不會複製遙測資料、重寫即時收集器設定，或執行生命週期操作：

--help 會列印階段語法，但不盤點實例。若未提供階段旗標，輔助程式將有意執行唯讀計劃；未知選項會在計劃或變更之前以非零狀態失敗。

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME"

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-state \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before"

使用一般的升級工作流程啟動確切的目標執行環境。然後等待，直到每個有邊界的套用後舊有尾部之後，都有同一個席位的更新的成對新根樣本。這證明了時間收斂，而不需要全面更換程序；在之後出現的舊有寫入是一個硬性停止。捕獲驗證 JSON；複製的舊側車並不能作為證據：

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --verify \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  > /safe/path/layout-0.5.9-verify.json

只有成功的接收才授權單獨呼叫的非破壞性最終化程式。它會將未配置的舊有函式庫複製到 canonical 根，而不覆寫任何內容；自訂的上下文函式庫根保持穩定：

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --apply-library \
  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
  --verification /safe/path/layout-0.5.9-verify.json

遇到任何回報的問題時停止：格式錯誤或外部的遙測資料、保留路徑衝突、函式庫衝突、配置漂移、恢復的舊有寫入、位元組漂移，或缺少新的雙重樣本，所有這些都需要在繼續之前進行指定的修復。驗證將確切接受的尾部位元組與其成對的新樣本綁定；最終化程式在切換配置之前立即重新驗證它們。此輔助程式絕不會移除舊有的遙測資料或函式庫。它們之後的退役是一個單獨的代理決策，需要在穩定的執行環境、寫入器、讀取器和復原證明之後進行。它不會停止/啟動 daemon、啟動席位、觸及資料庫，或決定升級是否繼續。

若要復原，請依照代理主導的工作流程所需還原先前的執行環境，然後僅反轉輔助程式擁有的配置、系統世界、空目錄和複製的函式庫效果。真實的狀態樣本和兩個舊有的復原來源則保留以供檢查：

node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
  --home "$OPENRIG_HOME" \
  --rollback "$OPENRIG_HOME/backups/layout-0.5.9-before"

代理主導的連續性升級

這是一個決定性指南，而非命令式食譜。請根據面前的主機調整路徑和檢查點。

1. 使用輔助程式檢查當前的 CLI、daemon、節點和擴充。
2. 為進行中的工作設立檢查點，並記錄確切的受保護 tmux/工作階段普查。
3. 為每個受保護的 rig 執行 rig snapshot <rig-id>。
4. 建立並驗證 SQLite 備份。
5. 分別建構或暫存目標執行環境。在觸及運行中的 daemon 之前，證明其版本和來源身份。
6. 執行 rig daemon stop。驗證監聽器和已識別的 daemon 程序都已消失。如果命令返回時其中任一仍存在，請停止：檢查身份並使用主機的授權復原程序。不要盲目地發送訊號給 PID。
7. 在啟動目標之前，考慮其啟動時對受管理擴充和標記的全域技能的重新整理。此執行環境會將不同的替換檔案保留在 $OPENRIG_HOME/backups/managed-refresh/ 下，並報告每個復原路徑；如果目標缺乏該保留功能，請先複製那些樹。使用 rig daemon start 或主機已知的包裝器啟動它。驗證 daemon 狀態、程序路徑、監聽器、版本和資料庫完整性。復原副本保留位元組；它們不保證在重新整理後自訂行為仍然有效。
8. 在計劃模式下執行擴充重新整理輔助程式。其計劃僅管轄輔助程式後續的寫入，而非已發生的啟動寫入。僅在三根和分類有意義後才套用安全寫入；必要時逐一解決保留的路徑。
9. 使用 rig ps --nodes -A --json、代表性的 rig capture 以及適用的 rig restore-check 來驗證受保護的席位。-A 是必需的：沒有它，節點讀取將僅限於你當前的 RIG，而 daemon 升級會保護主機上每個 rig 的席位——因此狹義的形式會回報成功，而你 rig 之外的席位則未經檢查。
10. 僅在推導出該主機如何擁有包裝器之後才對齊它們。使用其現有機制；此技能不會改寫啟動器。
11. 記錄觀察到的結果、剩餘的本地保留決策，以及確切的回滾執行環境和備份。
12. 閱讀新版本中變更的內容，rig context get reference/whats-new.md，並告知你的使用者其中任何會改變他們工作方式的內容。

在以下情況停止並交回控制權

• 在升級前缺少受保護的 tmux 工作階段；
• 資料庫完整性或備份驗證失敗；
• 正在執行的程序或監聽器與預期的執行環境不符；
• daemon 停止回報成功，但識別的程序或監聽器仍存在；
• 目標無法針對現有資料庫啟動；
• 無法將擴充根與已知的祖先和目標關聯；
• 必需的擴充路徑被歸類為本地修改或刪除，且正確的擁有權決定不明確；
• 繼續進行將需要 rig down、破壞性還原、憑證變更，或超出操作員擁有的更廣泛權限。

停止時，請報告最後一個經證明良好的狀態、第一個失敗的預期、確切的證據，以及需要擁有者做出的最小決策。保留運行中的席位和資料庫，除非復原特別要求否則不要動。

回滾同樣由代理主導

優先考慮針對仍有效的資料庫啟動先前的已知執行環境。僅在遷移或損毀發現需要時才還原資料庫備份；降級的投影本身不足以證明資料庫應被更換。回滾後，重複與前進路徑相同程序、監聽器、資料庫、擴充和席位觀察。