昨日回顧

Day 17 把 ticket-source-guard 收成一份有版本、檔案清單與雜湊紀錄的發行物，並要求在乾淨目錄跑安裝後 smoke test。但封包在自己的 CI 通過，不代表另一台機器、另一個執行環境也能安全使用。今天把安裝視為一個有檢查點的狀態轉換：先辨識環境，再驗證封包，最後啟用；任何一步不合格，就停在原本可用的版本。

這篇使用中立的購票來源查核 Skill 為例。路徑與指令只是示意，實際安裝位置要依使用者的工具文件決定，不能猜一個目錄就覆寫。

先寫安裝契約

README 應明列「支援什麼」與「不會做什麼」，例如：

release: ticket-source-guard 0.3.0
runtime: Python >= 3.9, < 3.13
required files: SKILL.md, references/, scripts/, VERSION, MANIFEST.sha256
network: classifier 離線執行；來源重驗由使用者另行啟動
writes: 安裝程序只寫入指定的 Skill 目錄
secrets: 不需要憑證；封包與測試資料不能含私人 registry
failure: 保留舊版，不把未知來源回傳成 OFFICIAL

這是本系列的示例契約，不是在宣稱 Claude 或其他平台一定要求某個 Python 版本。真正的版本上下限，必須來自程式用到的語法、相依套件與實測矩陣。也要列出支援的作業系統、架構及安裝方式；如果沒有測過，就標示未驗證，不要寫「跨平台可用」。

安裝前先辨識目標

先確認操作者選的是哪個帳號、工作區、Skill 根目錄與現有版本。若同名 Skill 已存在，讀取它的 VERSION 與清單，確認是否為同一個專案；不要因為名字一樣就覆蓋。目標目錄若不在已核准的 Skill 根目錄之下、是符號連結，或權限不符，就停止並請人確認。安裝不應自行改動其他 Skill、全域設定或來源 registry。

來源也要分層驗證。從可信發布管道取得預期的封包雜湊或簽章，再比對下載檔；打開封包後驗證 MANIFEST.sha256 所列內容。只驗證封包內的清單不夠，因為被替換的封包可能附上一份一起被改過的清單。下載位址與版本號也要記錄在 release record，方便日後查回。

採用 staging，再切換

不要把新檔直接逐一複製到正在使用的目錄。先在同一個檔案系統的暫存目錄解壓，拒絕絕對路徑、..、符號連結與超出預期的檔案類型；確認每個檔案仍在 staging 根目錄下。之後才跑離線 smoke test。

下載發行物
  → 對照可信管道的封包雜湊或簽章
  → 安全解壓到 staging
  → 核對版本、MANIFEST 與相容性
  → 在 staging 執行 smoke test
  → 備份目前可用版本並切換
  → 對實際安裝目錄再跑一次最小測試

同檔案系統的重新命名通常可以讓目錄切換更可控，但不能籠統保證每個平台上的「替換非空目錄」都是原子操作。實作時要測試目標平台的具體切換方式，或用明確的版本目錄加上受控指標。整個流程還應避免兩個安裝程序同時改同一個目標；無法取得鎖定就等待或退出，而不是互相覆寫。

smoke test 要測會出事的邊界

最小測試不是印出「載入成功」。從 staging 裡的檔案啟動，至少要檢查：

有效的示例 registry + 固定日期 → 預期的來源狀態
過期的 review_after → UNCONFIRMED，不是 OFFICIAL
證據衝突 → CONFLICT
缺必要欄位 → INSUFFICIENT_INPUT 或明確的 schema 錯誤
classifier 不存在／執行失敗 → CONFIGURATION_ERROR
references 指針斷裂 → 安裝失敗

狀態名稱要對應 Day 13 已定義的語義；測試資料只用公開或虛構資料。若真實來源當天變更，不應讓離線 smoke test 因網頁內容浮動而變紅；來源重驗屬於另一個、帶時間戳的整合流程。

切換後仍需確認載入路徑

安裝目錄的檔案存在，不等於使用者的環境真的載入了新版。用一個無副作用的示例任務確認入口被找到、必要 reference 被讀到、script 的呼叫方式正確。再查實際載入的 VERSION 與封包雜湊。若執行環境快取了舊版，依該平台的正式機制重新載入或重啟；不要假設複製檔案後立刻生效。

若切換後的最小測試失敗，就回復到備份的上一個已驗證版本，重新執行同一測試，並在 release record 留下失敗原因與回退時間。如果舊版本也無法通過，停止使用該 Skill 並報告錯誤，不要把不確定的查核結果包裝成 OFFICIAL。這裡的「回退」只涵蓋檔案與載入指標；若新版改動了外部資料或 schema，必須另行設計可逆遷移，不能靠還原資料夾解決。

今天完成的驗收標準

[ ] 相容性矩陣列出已測過的 runtime、作業系統與架構
[ ] 目標帳號、工作區、根目錄及舊版身分已確認
[ ] 發行物對照可信管道驗證，解壓路徑與檔案型別安全
[ ] staging 與正式安裝目錄的 smoke test 均通過
[ ] 實際載入版本與預期 VERSION 一致
[ ] 失敗會保留或回到上一個已驗證版本
[ ] 錯誤與回退寫入 release record，不會誤報 OFFICIAL

明天預告

Day 19 把安裝完成後的 Skill 放進變更流程：當來源 registry 或判斷規則要更新，怎樣用差異審查、測試與版本紀錄避免一次小修補改壞既有決策。