備份 · 移轉(Export / Import)

把 Blyck 搬到另一台電腦時(例如 Windows 筆電 → macOS Mac mini),若手動複製 userData 資料夾,聊天會指向舊 PC 的絕對路徑、機密被綁在 OS 鑰匙圈而解不開、OS 相依的二進位檔也無法運作。

備份 · 移轉讓你一鍵打包(export)與解包(import),解包時自動轉換路徑,把聊天紀錄原封不動接續下去。Win↔Mac 四向皆可運作。

為什麼手動複製會壞掉

問題	內容
絕對路徑不一致	聊天指向 `D:\develope\…`,但新 PC 是 `/Users/…`
OS 相依機密	DB/SSH 密碼·GitHub token 由 OS 鑰匙圈(safeStorage)加密,在另一台 PC 無法解密
OS 相依二進位檔	python venv、LSP 伺服器等即使複製也無法運作
龐大的可重建快取	搜尋/嵌入索引(`workspace.sqlite` ~226MB)整包跟著搬

搬什麼、丟什麼

🟢 移轉對象(納入套件)

chats/ — 聊天紀錄(含訊息,自我完備)
blyck-history.db — 變更紀錄(VACUUM INTO 快照)
db-history.json · db-snippets.json — DB 查詢紀錄·程式碼片段
layout.json · blyck-locale.json · embeddings-settings.json — 版面·語言·設定
connections.json — DB/SSH 連線中繼資料(明文套件會 strip 掉機密)
attachments/ · changeSet-snapshots/ — 選用

⚫ 排除 — 在目標 PC 重建

workspace.sqlite — 搜尋/嵌入索引(~226MB)。大多衍生自程式碼庫,整包排除可讓套件從 230MB → 數 MB,並由目標 PC 的索引器自動重新索引。
python-venvs/ · lsp-servers/ — OS 二進位檔(重建)
Electron/Chromium 執行階段快取、記錄等

套件格式 `.blyckbundle`

ZIP 容器 + manifest.json(結構描述·應用版本·來源 OS·路徑根·各檔案 sha256)。

backup-YYYY-MM-DD.blyckbundle
├── manifest.json
└── files/                       # userData 相對路徑鏡像
    ├── chats/index.json, chat_*.json
    ├── blyck-history.db
    ├── db-history.json, db-snippets.json
    ├── layout.json, blyck-locale.json, embeddings-settings.json
    ├── connections.json         # 明文套件 strip 掉機密
    ├── attachments/**           # 選用
    └── changeSet-snapshots/**   # 選用

路徑重映射 — 讓聊天原封不動接續

import 時僅替換聊天 JSON 中具權威性的路徑欄位。

欄位	重映射
`projectRoot`	✅ 替換
`_lastSentProjectRoot`	✅ 替換
`extraRoots[]`	✅ 各元素替換
`projectRootSftp`	❌ 不變(遠端與 PC 無關)
`messages[]`	❌ 不變(保存紀錄)

規則是最長前綴比對 — 路徑若以來源根開頭,就只把前綴換成目標根,其餘分隔符隨之轉換。未映射的根維持原樣(聊天仍可開啟,僅專案未解析,由使用者重新開啟)。

跨 OS 四向(Win↔Mac 全組合)

remapPath 將來源分隔符(分割)與目標分隔符(結合)分開處理。來源分隔符由來源根自動偵測(\/磁碟機代號 → Win,/ → POSIX),目標分隔符依目標 OS 決定。

方向	來源路徑範例	結果範例
Win→Win	`D:\dev\App\src\a.js`	`E:\work\App\src\a.js`
Win→Mac	`D:\dev\App\src\a.js`	`/Users/x/App/src/a.js`
Mac→Win	`/Users/x/dev/App/src/a.js`	`D:\work\App\src\a.js`
Mac→Mac	`/Users/x/dev/App/src/a.js`	`/Users/y/App/src/a.js`

與磁碟機代號/根無關 — 因為是前綴替換,D:\ ↔ /Users/ 等任何根組合都能在映射表中 1:1 解析。

加密套件 + 含機密

export 時只要指定密碼,就會把整個套件加密。

方式:整包套件 AES-256-GCM — ZIP 內建加密(ZipCrypto)有弱點故不採用,而是先做出 zip,再用 Node 內建 crypto 整包加密(零外部相依)。KDF 為 scrypt,加密為 AES-256-GCM(機密性 + 完整性)。
密碼輸入錯誤 = GCM auth tag 驗證失敗 → 立即偵測「密碼錯誤」(無部分解密,資料不變)。
以明文標頭(BLYCKENC1)即使沒有密碼也能先判別是否加密。

機密與方向無關 — 以 Win safeStorage 解密 → 加密套件 → 以 Mac safeStorage 重新加密(反向亦同),因此 Win↔Mac 四向皆成立。

Export 流程

停止確認 — 若有忙碌中的回合則拒絕(資料一致性)
blyck-history.db → 以 VACUUM INTO 做單一快照(應用執行中亦安全)
收集納入檔案 + 各檔案 sha256
掃描 chats → 把不重複的路徑根記入 manifest.pathRoots
機密處理 — 未指定密碼:strip / 指定密碼:納入明文機密
ZIP 打包
指定密碼時以 AES-256-GCM 加密 → 寫出 *.blyckbundle

Import 流程

inspect — 以 magic 判別是否加密。若加密則跳出密碼輸入提示
解密 — 密碼 → scrypt → AES-256-GCM。auth tag 失敗則中止(資料不變)
路徑重映射 UI — 每個來源根各一輸入欄(自動推薦基底名:D:\develope\Blyck_Web → ~/dev/Blyck_Web)
安全備份 — 把目前的 chats/·*.db 保存到 userData/_pre-import-<ts>/
取出 files/ → 寫入 userData
套用重映射 — 對 projectRoot/_lastSentProjectRoot/extraRoots 做最長前綴替換 + 分隔符正規化(projectRootSftp·messages 不變)
機密還原 — 加密套件:以目標 OS safeStorage 重新加密 / 明文套件:標記「需重新輸入」
無 workspace.sqlite → 下次執行時自動重新索引
重新啟動提示

模式 — 取代 vs 合併

模式	動作	用途
取代(replace)	把目前 `chats/`·`*.db` 備份到 `_pre-import-<ts>` 後以套件取代	整包移轉到新 PC
合併(merge)	在既有安裝中以 chat id 為準合併(不取代,只新增)	把兩台 PC 的工作彙整到一處

合併之所以安全,是因為 chats/ 是依 id 分開的個別 JSON,可無衝突地合併。

安全機制

import 前自動備份目前資料(_pre-import-<ts>)
manifest 結構描述/應用版本相容閘門
各檔案 sha256 完整性驗證
聊天忙碌中拒絕 import
取代前需使用者明確確認
加密套件密碼輸入錯誤 → 在解密階段中止(資料不變)
明文套件不含機密(防外洩)

FAQ

Q. 聊天紀錄在新 PC 上能原封不動開啟嗎? → 可以。import 時會以路徑重映射把 projectRoot 等自動轉換成新 PC 的路徑,因此聊天與專案會原封不動接續。

Q. DB/SSH 密碼需要重新輸入嗎? → 以加密套件(指定密碼)匯出時會納入機密並以目標 OS 重新加密,因此不需重新輸入。明文套件基於安全性會排除機密,故需重新輸入。

Q. 在 Windows 製作的套件能在 Mac 解開嗎? → 可以。包含 Win→Mac、Mac→Win 在內的四向皆支援。路徑分隔符(\↔/)與磁碟機代號/根會自動轉換。

Q. 為什麼套件這麼小? → 226MB 級的 workspace.sqlite(搜尋索引)可從程式碼庫重建故予以排除。目標 PC 的索引器會自動重新索引,而聊天紀錄本身則原封不動保存。

Q. 忘記密碼怎麼辦? → 沒有復原手段。AES-256-GCM 在沒有密碼的情況下無法解密,因此請妥善保管加密套件的密碼。

Q. 想合併到既有 PC 的工作怎麼辦? → 請使用合併模式。它會以 chat id 為準合併,不刪除既有聊天,只做新增。