第二十七節 升級與版本號
[!ref] 詳解見使用者手冊「升級、備份與同步」節。
27.0 設定目錄品牌遷移（zcode → avlcode）
自 v0.6.30-alpha 起，面向使用者的品牌識別——全域設定目錄、工作區 .zcode/ → .avlcode/、ZCODE_* → AVLCODE_* 環境變數等——統一遷移為 avlcode，啟動 / 開啟工作區時自動完成、有 toast 提示、保留舊名雙讀復原；內部行程名（zAgent / zMCP / zWorkspace）與 ZAGENT_* / ZMCP_* 等內部環境變數不在遷移範圍：
| 舊 | 新 |
|---|---|
全域設定目錄 ~/.config/zcode/ |
~/.config/avlcode/ |
工作區內 .zcode/（含 rag/、sbom.* 等） |
.avlcode/ |
環境變數 ZCODE_…（如 ZCODE_DISABLE_VENV_AUTODETECT） |
AVLCODE_… |
配置 YAML 與 frontmatter 欄位（x-zcode-… 等） |
對應 avlcode / x-avlcode-… |
UA 尾部令牌 zCode/<ver> |
avlcode/<ver> |
SSH 遠端 ~/.zcode、遠端工作區 .zcode |
~/.avlcode、.avlcode |
介面與對外輸出裡殘留的「zCode」統一為「AVL Code」。指令碼裡寫死過舊路徑 / 舊變數的，建議改用新名。
27.1 版本號格式
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
| 段 | 含義 |
|---|---|
| MAJOR | 不相容更改（資料遷移 / 配置不相容） |
| MINOR | 新功能（向後相容） |
| PATCH | 修正 / 優化（向後相容） |
| PRERELEASE | alpha.<n> / beta.<n> / rc.<n> |
| BUILD | 構建元資料，不參與版本比較 |
27.2 升級路徑
| 路徑 | 頻率 | 說明 |
|---|---|---|
| 應用內升級 | 預設每天檢查 | 推薦 |
| 手動下載（免安裝） | 按需 | 官網下載頁 www.avlcode.cn/#download，下載直接取代執行，設定目錄不動 |
| 內部市場 | 視團隊配置 | 組織管理員控制版本 |
Alpha 版本有效期 45 天：自版本號中編碼的發佈時間（UTC+8）起算，啟動時與此後每小時檢查；超期掛全螢幕鎖定遮罩 —— 已登入且有用量：自動檢查更新 → 下載 → 倒數計時重新啟動（可「立即重新啟動」）；未登入：「前往登入」「重新檢查」「造訪官方網站」；已登入無用量：「購買點券」「升級 · 訂閱套餐」「重新檢查」「造訪官方網站」；底部恆有「結束應用」。
官網下載頁按平台提供構建（Windows x64 / macOS 一般版·Apple 芯片版 / Linux x64·AppImage·Snap·WebKit4.1 / 銀河麒麟 V10 SP1 / 統信 UOS V20 / 銀河麒麟 ARM64），走 alpha 渠道、恆為最新構建。
27.2.1 國產化 ARM64 渠道
國產化 ARM64（aarch64）有獨立的發佈與升級源，與國產化 x86 互不影響：
| 項 | 取值 |
|---|---|
| 構建物 | 壓縮檔（linux-arm64-domestic.zip）與麒麟 V10 ARM64 DEB（avlcode_v10_<版本>_arm64.deb） |
| WebKit | DEB 包內自帶可重定位的 WebKit 4.1 執行階段，目標機無合適 webkit2gtk-4.1 也可執行 |
| 邏輯渠道 | 仍是 dev / alpha / beta / rc / stable；架構隔離由獨立的源命名空間表達，不新造渠道名 |
| 簽章 | 與既有發佈同一套國密 SM2 簽章與可信公鑰 |
| 用戶端 | 在 ARM64 國產化環境上自動選用該源檢查更新 |
本渠道當前不含 ARM64 的 AppImage / Snap 與多架構合並清單。
27.3 升級簽章
| 步驟 | 說明 |
|---|---|
| 下載 | 從內部升級源拉到本機快取 |
| 驗章 | 國密簽章 + 嵌入公鑰校驗 |
| 取代 | 驗章通過後原子取代主二進位 |
| 復原 | 驗章失敗 / 啟動失敗時自動復原到上一版本 |