上一篇，我寫了為什麼用了三年 Heptabase 之後決定搬到 Obsidian。這篇寫怎麼搬。

先講結論：不需要會寫程式，也不需要打開終端機。 你需要的是一個能直接讀寫電腦檔案的 AI（Claude Code 或 Codex 都可以）、一份寫好的搬家規格，還有耐心在幾個關鍵點親眼檢查。

我自己前後搬了三輪，花了大約五週的下班時間。三千多張卡片、九十多張白板、七百篇 Journal。這篇把我踩過的坑整理成一條比較好走的路。

這篇適合誰

  • 第一次搬：你還在用 Heptabase，想整個搬到 Obsidian。
  • 搬過但搬得不完整：你已經搬過一次，打開 Obsidian 發現白板亂掉、圖片不見、連結斷掉，想補救，但又不想弄壞已經在用的筆記。

這兩種情況的做法不一樣，後面會分開說。

如果你只有幾十張卡片、沒什麼白板，直接用 Heptabase 匯出的 Markdown 放進 Obsidian 就好，不需要這麼大費周章。

我搬了三次

在講怎麼搬之前，先讓你看看搬壞了會長什麼樣子。這些都是我自己搬出來的。

第一輪：檔案都到了，內容沒有

8 月 17 日到 21 日。我讓 AI 讀 Heptabase 匯出的資料，轉成 Obsidian 的格式。它很快就回報完成。打開來，看到的是這些：

卡片的名字變成一串亂碼 ID。

卡片標題變成 696db46b-4e9c-… 這種 ID

白板上直接出現程式碼。 原本應該是文字或圖片的卡片，只剩 {"type":"doc","content":…}。

白板上出現 JSON 程式碼和「Heptabase media missing」

圖片不見了，只剩一句「media missing」。

圖片位置只剩 Heptabase media missing 的提示

日記整片空白。

一整排 Missing journal content

同一張白板，被搬出了好幾份。

同一個白板出現五次

後來我才注意到，Heptabase 官方其實提醒過：匯出的 Markdown 可以放進其他 app，但白板的配置、卡片之間的關係和 metadata，不一定能照原樣保留。

問題不是檔案沒有搬過去，而是檔案搬過去了，但內容、關係和位置沒有一起過去。從這裡開始，我不再把搬家當成「轉檔」，而是當成一件需要規格、需要驗收的工程。

第二輪：看起來什麼都沒少

中間我停了三個禮拜，把第一輪的教訓寫成第一份搬家規格。9 月 13 日到 15 日，讓 AI 照著規格重搬一次。這次白板都在，卡片都在，看起來什麼都沒少。

但有兩件事我當時沒發現：

  • 有些「空白卡」其實是圖片。 它們是圖片卡，只是沒有取標題。
  • 白板裡的白板不見了。 Heptabase 可以把一張白板放進另一張白板裡。每張白板都搬過去了，但「這張放在那張裡面」的關係沒有。

沒有被搬過去的東西，本來就不會出現在錯誤清單裡。

第三輪：讓另一個 AI 從頭驗一次

9 月 15 日到 21 日。我讓 Codex 在不看前兩輪結果的情況下，照規格從頭再搬一次，把漏掉的東西一個一個抓出來，再交給 Claude Code 修好、補回我已經在用的 Obsidian：

  • 17 張沒有標題的圖片卡，找回來了。
  • 83 個「白板裡的白板」，補回 27 張白板裡原本的位置。
  • 重複的白板從 102 份整理成 93 份。
  • 白板上 3,198 個卡片引用，0 個斷掉。

但這個「0」只檢查了白板。筆記裡還有將近 1,700 個斷掉的連結，後面會講。

這三輪的教訓，就是下面這條路。

你要準備的東西

項目 說明
Heptabase 完整匯出 在 Heptabase 打開「設定 → Backup → Export now」。一定要勾選「Include files and images」，不然圖片不會一起匯出。匯出的資料夾裡會有 Markdown 檔案和一個 All-Data.json，兩個都要。
一個全新的測試 Vault 在 Obsidian 另外建一個空的 Vault 專門試搬。不要直接在你正在用的 Vault 上操作。
AI 工具 Claude Code 或 Codex 的桌面版。我用的是 Claude Pro 和 ChatGPT Plus，各 20 美元一個月。
搬家規格 我整理好的 Migration Guide（GitHub 連結見文末）。它是寫給 AI 讀的，你不需要讀完。
備份 匯出的原始資料放一份在別處，整個過程都不要動它。

關於訂閱方案：20 美元的方案做得到，但搬到一半常常會用完額度、需要等待。把時間拉長一點，不要想一個週末搞定。

匯出本身很快。我三年的資料匯出後是一個 5 GB 左右的資料夾，裡面有九千多個檔案，打開會看到這些：

Heptabase 匯出的資料夾內容：Card Library、Highlight、Insight、Journal、Mindmap、Text Element、Whiteboard 和 All-Data.json

Card Library、Journal、Whiteboard 這些資料夾是 Markdown，看得懂的內容都在這裡。最下面那個 All-Data.json 才是關鍵：白板上每張卡片放在哪裡、誰連到誰、哪張白板放在哪張白板裡面，都只記在這個檔案。它看起來只是一個檔案（我的大約 48 MB），但沒有它，白板就只能搬回一堆散落的卡片。

怎麼讓 AI 開始

第一步：把東西放在一起。

建一個工作資料夾，裡面放：

我的搬家資料夾/
  Heptabase-Data-Backup-…/   ← 你的 Heptabase 匯出
  Obsidian_Test_Vault/        ← 空的測試 Vault

然後在 Claude Code 或 Codex 打開這個資料夾。

第二步：把規格給 AI。

不需要下載。把 GitHub 上 Guide 的網址直接貼給 AI，它會自己去讀。

第三步：貼上第一段指令。

第一輪只讓 AI 看，不讓它改任何東西：

請先讀這份搬家規格：
https://github.com/cindyinee/heptabase-obsidian-migration-guide/blob/main/guide.md

先不要修改任何檔案。

請檢查我的 Heptabase 匯出和 Obsidian 測試 Vault，然後告訴我：

1. 我有哪些資料、各有多少
2. 你建議哪些要搬、哪些只封存、哪些跳過，以及原因
3. 需要我做決定的項目
4. 主要的風險
5. 你建議先用哪一張白板試做

原始的 Heptabase 匯出只能讀，不能改。
在我同意試做結果之前，不要開始全部轉換。

你和 AI 的分工

搬家的過程中，AI 負責盤點、轉換和驗證。你負責的是兩件事：做決定，和親眼檢查。

AI 第一次回報時，會列出一張清單，也會問你很多問題：Journal 要不要搬？Highlight 要不要搬？沒有標題的卡片怎麼處理？

我當時花了很多時間回答這些問題，後來才發現，有些問題我根本不知道答案會影響什麼。所以我的建議是：

AI 問你問題的時候，先反問它：「這個答案會影響哪個決定？如果我選 A 或 B，最後在 Obsidian 裡看起來會差在哪？」

能說清楚影響的問題，才值得花時間想。說不清楚的，請 AI 先用它的建議做，試做的時候再看結果。

Claude Code 還是 Codex？

兩個我都用了，各有千秋，也各有讓我頭痛的地方。

  • Claude Code 比較會抓大方向。 它很快就能搭出整體的搬家流程，後期修問題也比較乾脆。
  • Codex 比較嚴謹。 它會把資料格式的細節一筆一筆比對到底，幫我抓出很多在 Claude 階段沒有串起來的資料。但它有一種「沒完沒了」的個性，一直在找問題，很難收尾。

所以我最後的分工是：定義格式、確認檔案細節交給 Codex；收斂和修問題交給 Claude Code。 如果你只打算用一個，兩個都做得到，只是要知道它的個性，適時幫它踩煞車或推一把。

先試一張白板

不要一開始就全部搬。挑一張中等大小、東西齊全的白板先試：有卡片、有圖片、有連線、有心智圖，最好裡面還放了另一張白板。不要挑最大的那張，太大了很難一張一張檢查。

AI 轉完之後，用 Obsidian 打開，親眼看：

  • 卡片的位置和原本差不多嗎？
  • 圖片有出來嗎？
  • 卡片之間的連線還在嗎？
  • 心智圖的分支還在嗎？（排列會和原本不同，這是正常的，看節點和文字有沒有少）
  • 白板裡的子白板，有在原本的位置嗎？

有問題就把截圖丟給 AI，請它修好再試一次。這一步沒過，不要進行下一步。

搬好的樣子，應該像這樣。同一張白板，上面是 Heptabase，下面是搬進 Obsidian 之後：

搬家前：Heptabase 裡的「閱讀學習中」白板

搬家後：同一張白板在 Obsidian Canvas 裡，卡片、圖片和分區都在原本的位置

卡片的位置、分區、圖片都在原本的地方。縮小檢視時 Obsidian 不會顯示卡片裡的文字，這是正常的，放大就看得到。

全部搬完後，你自己可以做的五個檢查

AI 會告訴你「0 個錯誤」，但我學到的是：0 個錯誤不代表搬好了。 有些東西如果根本沒被搬過去，就不會出現在錯誤清單裡。

這五個檢查不需要任何技術，只要打開 Obsidian：

  1. 搜尋「empty card」和「media missing」。 每找到一個，都回頭問 AI：這張卡片在 Heptabase 裡原本是什麼？我遇到的「空白卡」，後來發現有 17 張其實是圖片，只是沒有標題。

  2. 打開一張有子白板的白板。 看子白板還在不在裡面，而不是變成另一個獨立的檔案。

  3. 隨便點 10 個筆記裡的連結。 看能不能打開。

  4. 打開幾張有圖片的卡片。 圖片要真的顯示出來，不是只剩一串路徑。

    圖片沒顯示，只剩一串路徑

  5. 打開幾篇筆記，看正文乾不乾淨。 如果每段後面都掛著 ^ 開頭的一串亂碼，或標題後面多了一串 ID，請 AI 清理。

    卡片標題後面多一串 ID，段落後面掛著亂碼

如果你已經在用 Obsidian 了

這是我最想提醒的一段。

我的第三輪搬家做得比前兩輪好很多，但那時候我的 Obsidian 已經用了一段時間，裡面有我後來新增、修改過的筆記。這時候絕對不能讓 AI 用新版整包覆蓋。

請 AI 先做一件事：列出哪些檔案是舊的搬家結果、哪些是你後來自己新增或修改的。然後只把新版比較好的部分「補」回去，例如漏掉的圖片、白板裡的子白板、心智圖的結構。你自己寫的東西，一個字都不要動。

另外，整理資料夾的時候也要小心。我最後一次整理時把卡片分到不同資料夾，白板都正常，但筆記裡有將近 1,700 個連結還指向舊的資料夾位置，點下去打不開。整理完資料夾，一定要請 AI 檢查全部筆記裡的連結，不是只檢查白板。

搬了幾輪之後，資料夾很容易變成這樣：

多輪搬遷後，同樣的東西散在好多個資料夾

所以不要直接刪除舊的東西。請 AI 把確定不要的檔案移到 Vault 外面的另一個資料夾，確認都沒問題了，你自己再刪。

限制和資料安全

  • 這不是一鍵搬家工具。它是一份讓 AI 照著做、讓你可以檢查的規格。
  • 原始匯出永遠不要動，整個過程都在測試 Vault 裡做。
  • 有些東西 Heptabase 的匯出本身就沒有，例如部分圖片檔、側邊欄的排列順序。這些 AI 也救不回來，但應該要列出來告訴你，而不是假裝沒事。
  • 我的數字（五週、三輪、17 張圖片卡）只代表我的資料。你的情況可能更簡單，也可能更複雜。

常見問題

一定要付費訂閱 AI 嗎？ 需要能直接讀寫電腦檔案的 AI，目前 Claude Code 和 Codex 都需要付費方案。20 美元的方案做得到，只是要有耐心等額度。

要花多久？ 我前後三輪、大約五週，但大部分時間花在踩坑和摸索規則。有了這份規格，應該可以少走很多路。

我不會寫程式，真的做得到嗎？ 做得到。你不需要看懂 AI 寫的程式，但需要在試做和搬完後，自己打開 Obsidian 親眼檢查。

我已經搬過一次了，還能用這份規格嗎？ 可以，而且這正是它特別處理的情況。記得跟 AI 說你已經在用 Obsidian，並且要求它不能覆蓋你新增或修改過的筆記。

最後

搬完之後我最大的體會是：真正要問的不是「檔案都在嗎」，而是**「我真的搬到了我以為自己搬到的東西嗎？」**

如果你也準備搬，搬家規格就放在 GitHub 上。希望你不用從我第一次踩的坑開始。