AVL Code

第二十四節 升級、備份與同步

24.1 升級

  • 應用內升級（推薦）：托盤選單 → 檢查更新 → 一鍵取代。升級套件帶簽章校驗，驗章失敗會自動復原。
  • 手動升級：從官網下載頁下載新版本構建，直接取代舊的執行（免安裝），設定目錄不動。
  • 升級快取目錄乾淨化：升級時的臨時安裝套件改放到隱藏的 cache 目錄，不再在可見目錄裡留中間文件；升級失敗 / 中斷遺留的孤兒暫存文件會被自動清理，不需要你手動收拾。
  • 升級彈窗的「發佈說明」直接取自 RELEASE_NOTES.md（不再用 git 記錄檔），只呈現面向使用者的版本說明，不洩露提交元資料。
  • 定期納入元件安全更新：隨版本升級第三方相依（如 Go 的 x/crypto / x/net、MCP SDK 等）以納入安全修正。

24.1.1 設定目錄遷移到 avlcode（自動）

內部識別由 zcode 統一遷移為 avlcode：全域設定目錄（如 ~/.config/avlcode/）、工作區內的 .avlcode 目錄、AVLCODE_… 環境變數，以及相關 YAML 與 frontmatter 欄位，都改用 avlcode 命名（SSH 遠端工作區一並處理）。

  • 自動且安全：在啟動和開啟工作區時自動遷移，過程有 toast 提示，不影響既有資料。
  • 保留舊名雙讀復原：遷移期間仍能讀到舊的 zcode / .zcode / ZCODE_…，老配置不會突然失效。
  • 介面與對外輸出裡殘留的「zCode」字樣統一為「AVL Code」。
  • 你一般無需任何操作；若曾在指令碼裡寫死 .zcode/ 路徑或 ZCODE_… 變數，建議改用 .avlcode/ / AVLCODE_…。

24.2 備份 v2 — .zbk 加密備份

設置 → 資料 Tab 內置三個對話框：建立備份 / 復原 / 歷史快照。

  • .zbk 加密備份文件（AES-GCM）— 覆蓋 14 類應用資料（含 plugins/ / ~/.avlcode/trust/ / 可選的 hook-outputs/）。
  • 建立備份：選擇類別 → 輸入密碼 → 落地 .zbk 文件。plugins / trust 預設勾選，跨機遷移不用重裝；hook-outputs 預設不勾選，僅按需帶走偵錯歷史。
  • 復原：選擇 .zbk → 輸入密碼 → 預覽要還原的類別 → 確認。

舊 / 新備份雙向相容，.zbk 格式版本號不變。

24.3 歷史快照（自動）

所有"破壞性操作"（單類清理 / 批量清理 / 全量重設）觸發前都會自動落一個清理前快照（命名形如 auto-clean-<ts> 或 auto-fullreset-<ts>）。

  • 歷史快照面板支持深鏈定位：從某條破壞性操作的成功 toast 直接跳到對應快照行。
  • 每個快照行都有「就近復原」按鈕，幾乎不留痕。

24.4 存儲佔用與按類清理

設置 → 資料 → 存儲佔用 視圖按 14 個備份類別 + 6 項非備份項（快取 / 快照 / 元資料）展示真實占盤大小。聚合條與 du 位元組級對齊：

  • 單項 / 批量清理 — 含敏感資料的類別（plugins / providers / trust 等）操作前自動落 auto-clean-<ts> 快照可一鍵復原。
  • 「全量重設」會深度清 14 類應用資料 + 重設預設配置 + 自動落 auto-fullreset-<ts> 快照。

24.4.1 工作區選單的「清除工作區全部文件」

工作區選單的「清除資料」入口下新增了 「清除工作區全部文件」 危險選項 — 不僅刪 AVL Code 自管的元資料（工作階段、todo、設置等），還真的把工作區目錄裡的全部文件清空。和其它破壞性按鈕一樣，inline 倒數計時 + 武裝確認，不可復原，請確認這是一個臨時 / 可重建的工作區再用。

24.5 破壞性操作的 inline 倒數計時

所有破壞性按鈕不再彈原生 confirm 彈窗，而是 GitHub 風格的"武裝 → 倒數計時 → 確認"兩步式：

  1. 第一次點擊 — 按鈕變紅 + 顯示 3 秒（全量重設 5 秒）倒數計時。
  2. 第二次點擊 — 才真正執行。

全域只允許一個按鈕處於武裝態（點新的會自動解除舊的），點擊空白處或 Esc 取消。成功反饋就近顯示在原行 — ✓ 已釋放 N · 復原 · 關閉，不再彈全域 Toast。

設置內刪除統一行內確認：設置面板裡刪技能 / 外掛 / 帳號 / Provider / 例行程式等的刪除按鈕全部統一為「就地行內二次確認」。修了之前點了刪除毫無反應的根因 — 系統原生確認彈窗被應用內嵌的網頁視圖靜默吞掉、直接當成「取消」；現在點了就有反饋，刪得掉。

24.6 同步（實驗性）

AVL Code 提供基於雲端的資料同步能力（實驗性）：在 設置 → 資料 → 同步 中啟用後，登入帳號下的多台設備可自動同步工作區與工作階段。同步只發生在你登入帳號關聯的設備之間。

24.7 資料脫敏

設置 → 資料脫敏 是一個外發場景的資料保護引擎 — 在內容離開本機之前對敏感欄位自動做取代 / 遮掩。預設停用（opt-in），配置落到 ~/.config/avlcode/redaction.yaml，主程式與子程序共用同一規則編譯。

作用範圍（按場景獨立開關）：

場景 預設 說明
export_html 開（總開關啟用後） 把工作階段匯出為 HTML 時套用脫敏
export_session 開（總開關啟用後） .zsession 匯出時套用脫敏
write_md 關 AI 寫 .md 等文件類文件落盤時做脫敏（Phase 2，慎用 — 可能改變你期望的寫入內容）

規則類型：

類型 說明
keyword 字面串全取代；Pattern 自動轉義、Replacement 當字面常數
regex RE2 正則；Replacement 支持 $1 / ${name} 捕獲模板，用於部分遮掩
ipv4_mask 結構化 IPv4 遮掩 — Octets（1-based，1..4，任意段含中間都可）或復原 Segments（掩前 N 段，相容舊配置）；MaskChar 預設 *
domain_mask 域名遮掩 — KeepLast 保留末尾幾段（預設 1，只留 TLD），其餘標籤替為 MaskChar

內置 secrets 預設（presets.secrets，可選開）— 高置信度、低誤報的常見憑證格式：

  • AWS Access Key（AKIA…）
  • GitHub PAT（ghp_…） / 其它 Token（gho_… / ghs_… / ghu_…）
  • Slack Token（xox[baprs]-…）
  • Stripe Live Key（sk_live_…）
  • GCP API Key（AIza…）
  • OpenAI Key（sk-…）
  • PEM 私鑰整塊（-----BEGIN … PRIVATE KEY----- 到 -----END …，跨行）

命中反饋：觸發脫敏的匯出 / 寫盤會彈一條 toast，告訴你命中了多少條、哪條規則，便於稽核；每條取代都帶規則 Label，可追溯不漏值。

匯出脫敏覆蓋程式碼區塊行首 IP 與嵌套 JSON：工作階段匯出的脫敏改為對解碼後的 JSON 文字值套用規則，修正了程式碼區塊中受 JSON 轉義影響、行首 IP 未被遮掩漏脫敏的問題；並會遞歸下鑽嵌套的 JSON 結構，覆蓋工具呼叫的參數與結果裡的敏感訊息，避免深層欄位被遺漏。

規則總開關關閉時所有場景一律放行原文，避免「開了之後不知道哪裡少東西」的困惑；建議先在「常規」組的 redaction.yaml 寫好規則、跑一遍小規模匯出確認效果再上正式資料。