資料傳輸 - lolly-backup 打包檔

Lolly 使用者累積的一切都存放在自己的裝置上 - 沒有帳號，沒有雲端。資料傳輸打包檔就是搬移這些資料的方式：在一台裝置上匯出，透過任何方式攜帶該檔案（USB、AirDrop、寄給自己的電子郵件、網路共用），再匯入另一台裝置。檔案本身就是傳輸方式。目標裝置可以離線或連線，兩者沒有差別，因為整個過程完全不會與任何伺服器通訊。

signed by Lolly2026-10-21vector SVG9 paths~4.9k nodes11 groups56 KB自己驗證取得已簽署檔案 signed by Lolly2026-10-21vector SVG9 paths~4.9k nodes11 groups56 KB自己驗證取得已簽署檔案

本頁是格式規格。給終端使用者的操作說明見找回你的成果 → 把你的作品移到另一台裝置。實作程式碼在 shells/web/src/data-transfer.ts，tests/data-transfer.test.ts 固定了往返契約。

範圍。 打包檔攜帶的是使用者資料，而不是目錄工具。目錄工具與目錄資產是分開同步的，並假設目標裝置上已經存在（最壞情況下版本較舊）；使用者自己製作的工具則會隨 profile.json 一起傳輸。匯入絕不會安裝或升級目錄工具。

目標

• 一種格式，所有殼層通用。 網頁版 PWA、Tauri 桌面／行動應用程式，以及未來的殼層，共用同一套封裝格式與支援的分片結構（schema）。可選分片取決於各殼層的能力；不支援的分片會被回報。每個能力橋接層都會提供自己的儲存轉接器。
• 經得起旅途考驗。 傳輸過程中損毀或截斷的打包檔，會在匯入時明確失敗，絕不會只還原一半。
• 比目前版本活得更久。 較舊版本的應用程式仍可匯入較新打包檔中可辨識的部分。真正不相容的格式則會被乾淨地拒絕。
• 可安全合併。 匯入到已在使用中的安裝環境時，絕不會清除打包檔中未包含的任何資料。

封裝格式

打包檔是一個單純的 .zip 檔。下載檔案會以其所屬的人命名 - LollyTools-<First>-<Last>-<YYYY-MM-DD>-<n>.zip(例如 LollyTools-Ada-Lovelace-2026-06-26-1.zip) - 讓下載資料夾中的備份檔保持可辨識。名字與姓氏這兩部分來自個人檔案，未設定時則省略。沒有個人檔案時會產生 LollyTools-2026-06-26-1.zip，只有名字時則產生 LollyTools-Ada-2026-06-26-1.zip。每個部分都會被清理為檔名安全的字串（保留 Unicode 文字／數字，移除空格與標點，上限 32 個字元）。<n> 是同一天、同一裝置下的序號，因此同一天重複匯出不會互相衝突，並維持順序。shells/web/src/data-transfer.ts 中的 backupFilename() 負責建立此名稱。無論檔名為何，zip 的內容都是相同的。內容如下：

打包檔刻意採用單純的 zip 格式：無論透過何種方式傳輸都能保持完整，且任何解壓縮工具都能檢視其內容。

profile.json 是最小的一部分，也是在應用程式中最先被讀取端看到的部分：由製作者填寫一次的詳細資料，以及讓工具得以使用這些資料的選擇性開啟設定。

signed by Lolly2026-10-21vector SVG15 paths~1.2k nodes30 groups1 image40 KB自己驗證取得已簽署檔案

manifest.json

{
  "format": "lolly-backup",
  "formatVersion": 3,
  "minReader": 1,
  "app": "lolly",
  "exportedAt": "2026-06-22T09:30:00.000Z",
  "counts": { "profile": true, "sessions": 2, "userAssets": 4, "prefs": 3, "assetVersions": 1, "fileOperations": 1 },
  "integrity": {
    "profile.json": "sha256-…",
    "sessions.json": "sha256-…",
    "assets.json": "sha256-…",
    "assets/blobs/0.bin": "sha256-…",
    "file-history.json": "sha256-…",
    "file-history/versions/0.bin": "sha256-…",
    "file-history/results/0.bin": "sha256-…",
    "prefs.json": "sha256-…"
  }
}

版本政策（向前相容性）

formatVersion 與 minReader 之間的區分，正是讓此格式得以演進、同時不會拋棄較舊安裝環境的關鍵：

• 當 manifest.minReader ≤ 讀取端自身的版本時，讀取端就會匯入該打包檔。只有在打包檔明確要求更新版本的讀取端時，才會拒絕匯入（顯示「需要更新版本的應用程式」）。
• 新增式變動 - 例如新增一個選填的部分，或新增一個選填的資訊清單欄位 - 會使 formatVersion 遞增，但 minReader 保持不變。較舊版本的應用程式仍會匯入它們所能辨識的每一個部分；無法辨識的部分則會被跳過（見下文），而非無聲丟棄。
• 破壞性變動 - 例如錯誤匯入某個部分會導致資料損毀，或原本選填的部分變成必要 - 會提高 minReader。較舊版本的應用程式便會乾淨地拒絕匯入，而不會嘗試處理它無法應付的內容。
• 若未來的打包檔設定了 formatVersion 卻省略了 minReader，讀取端會保守地退回以 formatVersion 作為判斷依據（將此變動視為破壞性變動）。

給作者的經驗法則： 如果每個現有的讀取端，即使忽略你新增的內容，仍能表現正確，那就是新增式變動 - 遞增 formatVersion，minReader 保持不變。否則就要提高 minReader。

完整性

當 manifest.integrity 存在時，讀取端會在寫入任何內容之前，驗證所列出每個部分的 SHA-256。若不相符（「未通過完整性檢查」）或缺少某個部分（「不完整」），整個匯入程序就會中止 - 不會有部分還原的情況。這能捕捉檔案傳輸過程中可能造成的損毀（例如中斷的 AirDrop、重新編碼附件的電子郵件閘道、損壞的 USB 磁區）。

完整性檢查在設計上是盡力而為：只有在 Web Crypto 可用時（所有安全的瀏覽器情境與現代 Node）才會寫入，也只有在對照表與 Web Crypto 皆存在時才會進行驗證。沒有對照表的打包檔 - 例如完整性機制出現之前建立的打包檔 - 會照常匯入，不受影響。「無法驗證」絕不會被視為「已損毀」。

資訊清單既不會列出自己，也不會列出重新產生的 lolly.txt 說明檔。摘要值涵蓋的是資訊清單所擔保的各個部分。

匯入語意

匯入是一次合併，絕不會全部取代：

• 目標裝置上既有的資料維持原狀。
• 當一個工作階段欄位或已上傳圖片的 id 在兩邊都存在時，儲存時間較新的那份副本會被保留，因此較舊的備份絕不會覆寫目標裝置上較新的作品。時間相同或未知時，保留目標裝置的副本。在帶有創作歷史的網頁版安裝中，同樣的規則決定一份創作的哪個副本維持為目前版本，另一份副本則作為受保護的草稿保留（見下文）。
• 個人檔案記錄會被合併，而不是被取代。目標裝置上的每個資料夾都會連同其內容保留；打包檔中有而目標裝置沒有的資料夾會被加入，兩邊都有的資料夾會保留目標裝置的名稱與所屬層級，並補上打包檔裡它缺少的成員。歸檔在目標裝置某個資料夾裡的工作階段仍會留在那個資料夾裡。
• 我的最愛（工具、目錄資產與專案項目）會被合併在一起。打包檔中的範本、專案藍圖與使用者工具，只要目標裝置上沒有對應 id 的記錄，就會被加入。兩邊的垃圾桶項目都會保留，因此原本在任一台安裝上都能還原的項目，現在仍然可以還原。
• 其他所有個人檔案欄位（姓名、聯絡方式、語言、功能旗標、隱藏的工具與其他設定）都會保留目標裝置的值。目標裝置上為空的欄位會採用打包檔的值。prefs.json 也是同樣的規則：只有在目標裝置沒有某項偏好設定時，才會寫入它。
• 裝置同步的一般套用是例外：為了讓各裝置保持一致，它會採用同步副本裡的個人檔案記錄、偏好設定、工作階段與圖片。復原較早的副本也是如此，因為那本來就是刻意回到過去。首次加入時的將它帶到此裝置，則會像匯入一樣進行合併。
• 歷史資產版本與操作 ID 是不可變的例外：重複匯入具有冪等性，而一個已經指名不同位元組／歷史記錄的 ID 會被拒絕，而不是被覆寫。重新匯入相同的目前資產會保留其版本。變更過的目前資產必須帶有不同的版本號。
• 創作歷史同樣會合併。兩邊都有的一份創作，會把儲存時間較新的那份副本保留為目前版本，另一份則作為受保護的草稿；如果目標裝置上同一個位置被另一份創作占用，這份創作就會被加入在旁邊；目標裝置垃圾桶裡的創作則繼續留在那裡。如果一個檢查點 id 在目標裝置上指名不同的內容，則保留目標裝置的那一份。未通過自身檢查的封存檔，會在觸及任何個人檔案、工作階段、資產或偏好設定之前就中止匯入。完全相同的重複匯入不會增加任何儲存空間。
• 打包檔中未包含的內容一律不會被觸動。目標裝置原有、但打包檔中沒有的工作階段，會在匯入後依然存在。

已儲存的工作階段會自動重新連結到其圖片：資產參照是以 id 保留的，橋接層會在已上傳圖片還原之後重新解析它們（無論如何都必須這麼做，因為 blob: URL 無法在重新載入後保留）。

匯入摘要會回報 { profile, sessions, userAssets, prefs, skipped, failedAssets }。failedAssets 計算的是無法還原的已上傳資產（例如裝置儲存空間已滿）。這與 skipped 不同，後者計算的是來自向前相容的較新寫入端、但此版本無法辨識的部分。使用者介面會呈現 skipped（「…‧N 個較新的項目已跳過」），讓還原結果誠實地呈現遺漏的內容。

當檔案歷史存在時，摘要還會攜帶 assetVersions、fileOperations 與 failedHistory。儲存空間耗盡或不可變 ID 衝突可能導致部分還原；介面會提示使用者保留原始備份。雲端同步在一次部分或不受支援的還原之後不會推進其已套用的修訂版本，因此該快照仍可用於重試。還原並非跨越個人檔案／工作階段／資產／歷史儲存的單一交易。

創作歷史（v3）

來自支援歷史記錄的網頁主機的手動備份，會包含帶有自己的 { version: 1, documents, revisions, recoveries } 結構的 revision-history.json。它攜帶保留下來的 ID、規範化的輸入快照、版本戳記、點陣預覽與獨立的寫入端草稿。歷史轉接器會在一次讀取交易中擷取目前的工作階段及其標頭；sessions.json 會為較舊的讀取端使用這些相同的目前快照。

還原過程會先檢查酬載的 SHA-256 與位元組數、唯一身分、文件／標頭關係、系譜、時間戳記、預覽類型與各項限制，然後才以一次交易提交該封存檔。被壓縮過的父層參照可能會缺失。既有的目前作品絕不會被靜默取代：當一份創作兩邊都有時，未保持為目前版本的一側會成為一份受保護的草稿。封存檔 384 MiB 的傳輸上限會被明確檢查，儲存限制的強制執行也不會截斷已保留的檢查點。整體備份目前仍使用記憶體內的 ZIP 實作，而非串流封存檔。

摘要新增了 revisions 與 recoveryDrafts，兩者只計算這次匯入新增的部分，此外還有 added、kept、replaced、copies 與 hidden，用來說明每份創作是如何被合併的。不具備此能力的殼層會還原一般工作階段，並將歷史部分回報為已跳過。原生檔案系統歷史目前仍不受支援，直到其轉接器提供持久的歷史交易為止。P2P 訪客狀態沒有持久的歷史記錄或復原封存檔。

個人快照同步明確不包含創作歷史。將一個快照套用到帶有歷史記錄的本機文件上，會把它先前的工作狀態保留為一份獨立的復原草稿，並使任何開啟中編輯器的寫入權杖失效。其不可變的檢查點仍保留在裝置上。這能在快照取代期間保護本機歷史，但不會合併多台裝置並行產生的歷史記錄。

歷史性的資產參照會被保留，但算繪時仍會透過目標裝置現有的資產庫來解析資產。此封存檔目前尚不保證舊有的資產位元組或舊工具算繪結果完全一致。資產版本與檔案結果的位元組仍會透過它們各自現有的獨立備份部分傳輸。

已儲存的版本與檔案結果（v2）

這個選用的歷史部分包含 { version: 2, assetVersions: [...], operations: [...], batches: [...] }；讀取端也接受不含 batches 的較早 history-v1 型態。每個快照都會標明穩定的資產 ID 與確切版本、儲存時間、位元組長度與十六進位 SHA-256，外加一筆資產記錄，其 _file 與選用的 _credentialFile 指向二進位部分。操作會攜帶原始檔案事實、請求、報告、時間戳記與選用的結果 _file；儲存後端名稱、OPFS 控制代碼與執行租約不會隨之傳輸。只支援 history-v1 的較舊讀取端，會在匯入前拒絕新的歷史版本，而不是悄悄捨棄批次成員關係。

批次清單會在處理之前記錄每一個被選取的來源檔案，包括從未被讀取的檔案、被取消的成員、預留結果空間失敗的情形以及被中斷的工作。每個成員都有一個穩定的操作 ID、來源參照／事實、要求的輸出名稱與終態報告。一個未被讀取的來源會有聲明的事實，而非憑空捏造的摘要。匯入會驗證成員身分，並與隨附的任何操作報告核對一致性。即使個別結果已被明確移除，批次報告仍然可用，但一份收據並不代表其輸出位元組仍然被儲存著。

• 在任何個人檔案或資產匯入寫入之前，每一筆已知的歷史記錄、報告與被參照的檔案都會先被驗證。即使封裝沒有完整性對照表，缺失的位元組與不相符的 SHA-256 也會導致失敗。擷取出的憑證始終維持為位元組陣列，即使是來自將其 JSON 序列化為數字鍵物件的舊版寫入端的匯入也是如此。
• 正在執行的操作在備份中會變成中斷記錄，附有說明性的失敗報告，且沒有結果。還原過程絕不會重新啟動背景工作，也不會匯入一個作用中的執行租約。重試需要重新選取原始檔案，並在可用時對照其記錄的 SHA-256 進行驗證。
• 已還原的結果會把位元組與中繼資料一起提交到 IndexedDB 中。一般的新結果會在可用時使用 OPFS，並以 IndexedDB 作為後備。一個既有的作用中操作絕不會被匯入取代。
• 歷史記錄的 ZIP 組裝目前仍在記憶體中完成：目前限制為256 MiB 的歷史酬載、4 MiB 的歷史中繼資料，最多100 個操作、100 個批次與2,000 個快照。匯出會明確拒絕過大或不完整的歷史記錄；它絕不會悄悄省略。請在移除較舊的本機副本之前，個別下載重要的版本／結果。這些限制並非針對手機尖峰記憶體用量的實測保證。
• 本機結果歷史有 512 MiB 的額度與 100 筆記錄上限。資產快照另有一份獨立的 512 MiB 額度，每個資產最多 20 個歷史版本；擷取出的憑證位元組會計入該快照額度。還原過程會遵守這些限制，絕不會悄悄清除既有的使用者資料。
• 本機批次中繼資料另有一份獨立的 4 MiB 額度，最多 100 份清單，每批次最多 20 個成員。待處理的成員會預留中繼資料容量，單一成員的報告上限為 32 KiB。這是邏輯上的額度，而非瀏覽器磁碟空間的保證；真正的配額失敗會被明確呈現，且記憶體中的報告仍可下載。重試一個批次成員會建立一個新批次，而不會覆寫舊報告。移除一筆批次記錄不會移除個別結果的位元組或資產庫中的資產。
• 轉換後的結果可以被明確加入資產庫，不做正規化或重新編碼。來源／輸出雜湊以及操作關係會隨該資產一併保存。重複加入會重複使用未變更的副本；已編輯的副本絕不會被覆寫。點陣影像可以用來開啟一份新的 Design 文件。該文件使用的是資產庫目前的資產 ID：要在整個 Design 執行環境與網址路徑中強制鎖定精確版本，仍是另外的工作。SVG／HTML／PDF／ZIP 結果會透過這次交接被當作不透明的檔案資產保留，而不會被提升為可信的互動式／向量內容。
• Convert → Recent file operations 會顯示歷史記錄的使用情形、報告、下載記錄與版本管理員。此管理員也能找到已刪除的資產庫資產的較早版本。還原一個快照會建立一個新的目前版本，同時讓所選快照維持原狀。設定 → 儲存空間會把結果與版本，和可隨意捨棄的快取分開計算。
• 明確的暫存檔清理只會移除由操作擁有、且未被參照的位元組。目前的記錄會保護自己的檔案；最近的 OPFS 檔案有一小時的寬限期。已儲存的結果與資產快照不會被自動清除。

較舊的讀取端仍會接受 v2 封裝（minReader: 1）並還原它們熟悉的部分，將不受支援的歷史部分計為已跳過。完整的歷史復原需要一個具備 fileHistory 轉接器的殼層；這是殼層內部的一條介面，而不是面向工具的新增 HostV1 能力。真實的雙裝置還原由本機 Chromium 關卡涵蓋；已安裝的 Tauri／iOS／Android 復原驗收仍是另外的工作。

不會被傳輸的內容

• 目錄快取（已下載的資產中繼資料與位元組、工具索引） - 會在目標裝置上免費重新同步。
• 目錄工具與目錄資產 - 不在範圍內，並假設目標裝置上已經存在。使用者新增的品牌 token、字型與標誌屬於使用者資產，因此會隨打包檔傳輸。
• blob: ／物件 URL - 由橋接層在載入時重新產生。
• 轉換原始檔案、作用中的執行租約與裝置本機的存取／簽署密鑰 - 不屬於可攜式的歷史酬載。已儲存的結果是一份副本，並不代表原始來源檔案已被備份。
• 匯出序號計數器 - 用於每日下載檔名編號的計數器（localStorage 鍵值 lolly-export-seq）只是本機命名的便利機制。它不列於 PREF_KEYS 中，因此絕不會出現在打包檔內。

儲存空間計量表會列出相同的分類。已儲存的工作階段、「我的圖片」與檔案結果與版本都會被納入打包檔中；資產快取、工具預覽以及下方的離線固定項目，皆可重新產生，因此不會被納入。

signed by Lolly2026-10-21vector SVG37 paths~4.9k nodes85 groups65 KB自己驗證取得已簽署檔案 signed by Lolly2026-10-21vector SVG37 paths~4.9k nodes85 groups65 KB自己驗證取得已簽署檔案

跨殼層保證

data-transfer.ts 只透過能力橋接層（host.profile、host.state、host.assets）與共用的 localStorage 偏好設定來讀寫。同一個模組在網頁版與 Tauri 上讀寫同一種通用封裝，底層分別是 IndexedDB 或檔案系統儲存。選用的歷史部分只會在對應的轉接器可用時才會出現；不受支援的部分會在匯入時被回報為已跳過。無頭測試套件針對記憶體內的橋接驗證了通用部分，而歷史交易則另有真實瀏覽器測試。

有兩個殼層基於不同原因不在此保證範圍內：

• 一次性 CLI 沒有東西要保留 - 它的狀態存在記憶體中，每次呼叫後即消失。
• TUI 確實會保留狀態（~/.lolly：sessions、folders、profile），其 Profile 畫面也能備份它，但寫出的是它自己較簡單的封存格式：每個 session 一個 saved-state/<slot>.json，再加上 profile.json 和 folders.json，沒有 manifest、沒有 formatVersion/minReader，也沒有完整性對照表。這個格式無法用本文的方式匯入 - 讀取器會拒絕它，判定為「不是 Lolly 備份」 - 而且容易混淆的是它用了類似的名稱（lolly-backup-<stamp>.zip）。統一這兩者是已知的落差。

保留的擴充點

信封格式設計上是一份 manifest 加上一組具名的部分，讓日後新型態的可攜資料能不需破壞性變更就搭上這個格式。它們會以附加部分的形式加入（新的 formatVersion，相同的 minReader），而目前的讀取器會跳過它不認得的內容。這些項目目前還沒有建置。之所以在此保留這些名稱,是為了讓格式在它們到位時仍保持一致。

• tokens.json - 設計權杖（design tokens）。 一份 W3C DTCG 設計權杖文件（Penpot 匯入匯出所用的格式 - 帶有 $value/$type/$description 的權杖,並組織成群組、集合與主題）。封裝中的權杖集合可讓使用者在安裝之間連同 session 一起搬移品牌基本元素。（使用者自己的品牌權杖，如今已經以 assets.json 中的 user/tokens/brand 資產形式隨打包檔傳輸；這個部分則會攜帶一整份附有其集合與主題的 DTCG 文件。）長期來看,匯入的權杖集合會成為工具與調色盤資產所依循解析的第一等來源。
• penpot/ - 已匯入的 Penpot 檔案。 為一個 Penpot 檔案（或從中擷取出、與 Lolly 相關的子集）匯入並以工具形式呈現而預留的目錄。打包檔會攜帶這份已匯入的定義，因此它會隨使用者其餘的資料一起傳輸。

對讀取器而言,任何不在這些保留名稱與上述部分之列的內容,都是未知部分：原封不動地保留,並計入 skipped。

參考

• 模組：shells/web/src/data-transfer.ts（exportBackup、importBackup、BACKUP_FORMAT、BACKUP_FORMAT_VERSION、BACKUP_READER_VERSION - 命名用的 backupFilename() 為內部函式）。
• 合約測試：tests/data-transfer.test.ts - 涵蓋往返、合併、完整性、向前相容與讀取器把關等案例。
• 歷史記錄合約測試：tests/file-history-backup.test.ts、tests/file-batch-history.test.ts 與 tests/file-result-library.test.ts。瀏覽器驗收測試：tests/file-history.browser.test.ts、tests/file-batch-history.browser.test.ts 與 tests/file-result-reuse.browser.test.ts。
• 使用的橋接介面：host.profile、host.state、host.assets - 詳見 Host API。