維護正式環境的 AI Agent 時，最棘手的問題往往不是服務直接當機報錯，而是「程序明明順利啟動，實際運作的行為卻完全變了」。
升級 Hermes Agent 之後，定時排程可能看似正常觸發，它卻悄悄換了一套預設參數、改變輪詢節奏、莫名漏掉某個重要工具呼叫，甚至在輸入完全相同的 Prompt 時，產出格式不符的資料。這類非崩潰型的隱性問題如果直接發生在線上環境（Production），很難在第一時間判斷究竟是業務邏輯改壞、設定被新版預設值覆蓋，還是模型適配器與外掛套件版本不相容。
遇到這種狀況，千萬不要慌張地把所有套件一口氣全部降版。最穩健的處理原則，是先將升級前的基準線完整封存，再用最小範圍釐清兩者差異。每次做版本升級時，建議照著這套步驟來排查。
本篇目錄
固定完整版本，精準切分環境變數
記錄版本時，切記不能只記下安裝指令，更不能圖方便直接依賴 latest 這種浮動標籤。你必須將 Hermes 核心程式、執行環境（Python / Node）、模型適配器（Adapter）以及所有擴充工具的確切版本完整固定下來。
實務上應妥善保存依賴鎖定檔（例如 package-lock.json、poetry.lock）或容器的 Image Digest 雜湊值。如果你的 Agent 會調用主機上的 CLI 工具（如 curl、jq、git 等），底層的 Base Image 與系統套件版本也得一併列入清單。
只要一口氣更動多個元件，一旦出狀況就很難抓出真正的元兇。建議在 Git 開立專屬的升級分支，將每個相依套件的更新切成能單獨還原的 Commit，並在部署時打上清楚的版本號與日期標籤。
匯出有效設定快照，落實機密資訊遮罩
備份設定時，請匯出服務啟動後最終生效的「有效設定」（Effective Configuration），而不是只備份幾份手寫的 .env 或 YAML 檔。因為真正的執行環境，往往疊加了 Dockerfile 預設值、主機環境變數與程式碼內建的 fallback 數值。
匯出這份快照時，務必注意兩大細節：
- 敏感憑證遮罩：保留欄位架構與資料型別（字串、數值、布林值），但 API Key、Token、私鑰與 Session Cookie 必須做去識別化或隔離處理。
- 逐行抓出 Diff 差異：確認新版多了哪些新開關？哪些舊欄位已被廢棄（Deprecated）？又有哪些原本明確指定的值，在新版悄悄退回了預設值？
尤其要注意數值單位與空值判定。例如設定檔裡的 30，在新版究竟代表 30 秒還是重試 30 次？空字串 "" 是被當成空值，還是直接被認定為欄位未定義？未來如果需要復原，必須是「特定版本＋該版本的有效設定快照」整組同步退回，單獨置換程式套件很容易引發設定衝突。
準備固定最小回歸任務，避免全量測試浪費時間
要驗證升級是否安全，不用把整套龐大又耗時的日常正式工作流完整跑完。最有效率的方式是挑選 3 到 5 個具備代表性的「最小回歸任務」，鎖定最核心的行為邊界：
- 基礎推論任務：輸入固定 Prompt，確認與大型語言模型的連線狀態與基本輸出品質。
- 工具呼叫任務（Tool Call）：驗證在特定條件下，能否精準觸發指定的 Function，且帶入的參數型別完全正確。
- 例外重試任務：刻意製造 Timeout 或連線中斷，確認重試次數上限與例外捕捉機制是否正常啟動。
- 結構化輸出任務：驗證回傳的資料結構，是否能嚴格通過指定的 JSON Schema 驗證。
升級前先在測試環境跑一次留作基準；升級後在隔離環境用同一批輸入重新驗證。比對結果時不需要苛求自然語言的文字描述一字不差，重點要放在工具名稱有沒有選對、參數型別是否符合規格、狀態轉換是否正確，以及回傳的欄位結構是否完整。
發現行為偏差時，依循最短路徑安全回滾
如果回歸測試抓出工具調用權限異常、資料格式變形或產生非預期的副作用，首要動作是立刻停止把正式流量或工作排程導向新版本，並將當下的測試日誌與設定保留存查。
接著依照固定順序執行回滾：
- 還原至上一版通過驗證的 Hermes 核心版本與對應的 Runtime Image。
- 匯入升級前備份好的有效設定快照。
- 在隔離環境重跑那一組最小回歸任務，確認核心行為完全回到基準線後，再重新接回正式排程。
如果排查後發現只是輪詢頻率（Polling Rate）或預設逾時（Timeout）產生變更，未必要將整個環境降版。只要在設定檔中將舊版數值明確補回、重新跑完驗證即可；但這項異動務必提交進 Git 版本控制，避免下次更新時又被預設值覆蓋。
升級交付驗收標準
在正式將升級版本推上生產環境前，維運人員應確認能具體回答以下四個問題：
- 目前準備上線的 Git Commit、套件版本與容器 Digest 是否已完全固定？
- 有效設定快照與升級前的差異是否已完成逐行比對並記錄？
- 涵蓋 Tool Call 與輸出格式的最小回歸任務，是否已在隔離環境全數通過？
- 若線上環境出現非預期狀況，是否能在數分鐘內透過既有標籤與快照完成安全回滾？
只要四個問題都能明確確認，這次的版本升級才算具備可維護的交付水準。
FAQ 常見問題
A1：通常不需要。大型語言模型本身具備隨機性，只要確認關鍵的工具呼叫、參數型別、輸出 JSON Schema 與錯誤處理流程都維持正常，純自然語言措辭的合理變化都在容許範圍內。
A2：不建議。.env 檔案常包含資料庫連線字串與 API 密鑰等敏感資料。實務上應只備份環境變數的欄位結構與非敏感數值，真正的機密金鑰應交由專屬密鑰管理系統（Secret Manager）維護，避免備份檔案成為資安外洩破口。
A3：無論是新版本或是回滾後的舊版本，都必須在隔離環境中完整通過同一套最小回歸任務，且所有設定調整皆已記錄至版本控制系統後，才可重新掛上正式生產排程。