Obsidian 專案同步是做什麼的？

儲藏庫自我描述。 專案的位置、已完成專案的歸檔地點、掛鉤留下日誌的位置，以及宣告儲藏庫慣例的筆記：所有這些資訊都來自儲藏庫根目錄下的 .claude-vault.json，而 scan 會回傳這些資訊。此技能不預設任何資料夾名稱。

儲藏庫不僅僅包含專案，其慣例筆記會說明每個資料夾的用途。在建議新內容的放置位置時請謹記這一點：影響多個專案的決策或事實，不應放在單一專案的筆記中。

優先讀取本地地圖

在執行任何其他操作之前，請先尋找此技能的本地地圖：一個位於使用者固定指示（Claude Code 中的 CLAUDE.md 檔案，應從磁碟讀取而非上下文中的副本，因為副本可能早於編輯；或 claude.ai 中的專案指示或使用者偏好設定）中的、名為 obsidian-project-sync local map 的章節。當此技能為某個 claude.ai 帳戶打包時，在此 SKILL.md 內部新增的、名為 Local map for this install 的章節也同樣有效；但固定指示中若有相反規定則以固定指示為準。本地地圖包含只有該安裝環境才知道的資訊：儲藏庫的路徑、使用者基於儲藏庫慣例之上的自訂慣例（每個專案都附帶的配套筆記、callout 樣式），以及其他指向儲藏庫且必須隨之變更的檔案。請遵循本地地圖的指示；它會覆蓋此處的預設值。

腳本與儲藏庫

腳本是位於此 SKILL.md 旁 scripts/ 資料夾中的 vault.py：請根據技能自己的資料夾建構其路徑（Claude Code 在載入技能時會說明基底目錄）。以下每個範例都將之寫為 vault.py。它需要 Python 3.8 或更新版本；如果找不到 python，請嘗試 python3，然後再試 py。

儲藏庫的路徑，依次來自本地地圖、OBSIDIAN_VAULT 環境變數，或向使用者詢問。請使用 --vault 參數傳遞路徑，可在子命令之前或之後。此腳本刻意沒有內建預設值：如果沒有儲藏庫，它會停止並告知。

永遠優先：先檢視再寫入

python vault.py scan --vault "<vault>"

若不帶 --project，它會回傳儲藏庫的庫存清單：有哪些專案存在、位於哪個區域、以及 status 為何。statuses_in_use 會列出使用者已在使用中的值；請選擇其中一個，不要自創標籤。

然後是專案本身：

python vault.py scan --vault "<vault>" --project "<folder name>"

它會回傳資料夾、主要筆記、筆記的前置資料、其章節標題的確切清單、資料夾中的其他檔案、工作階段日誌（以及它所讀取的日誌檔案，位於 session_log_file），以及 sessions_since_note_changed：自筆記上次磁碟變更以來較新的已記錄工作階段。最後這個清單是「尚未寫入筆記的內容」的起始點，而非證明：在聲稱任何內容遺失之前，請先與筆記進行比對。

--project 接受儲藏庫中專案資料夾的名稱，比對時不區分大小寫與重音符號。當從程式碼儲存庫工作時，資料夾名稱通常與儲存庫名稱相同；若非如此，請執行不帶 --project 的 scan，並透過主要筆記的前置資料（如果儲藏庫有使用 path 或 url 鍵）進行比對，若無任何符合則詢問使用者。

歸檔區中的專案代表已完成。請勿將其重新建立在活躍專案中，或未經詢問即更新它。

第二步：閱讀儲藏庫的慣例

scan 會回傳一個 config 區塊：

"config": {
  "source": ".claude-vault.json",
  "projects": "Projects",
  "archive": "Archive",
  "logs": "Toolbox/Claude Sync",
  "conventions": "/path/to/vault/Meta/Conventions.md"
}

conventions 是主導一切的筆記。 在寫入任何其他筆記之前，請先閱讀它：它宣告了前置資料的綱要、該儲藏庫中筆記的撰寫方式、哪些內容可以不經詢問即變更，以及哪些內容不可以。此技能刻意不攜帶該筆記的副本：副本會過時，而此技能的較早版本曾導致指向一個已不存在的資料夾。

如果 conventions 為 null，表示該儲藏庫未宣告任何慣例。在寫入任何筆記前都必須詢問使用者。

同一個區塊會說明資料夾的來源。如果 source 是 defaults，表示儲藏庫尚未自我描述，而你正在基於假設進行操作：請說明這一點，並提議寫入 .claude-vault.json（格式請見 references/mechanics.md）。如果出現了 warning，則設定檔已損壞，需要在繼續之前修復。

每個專案資料夾都不盡相同：有些只包含筆記和畫布，有些則帶有零散的筆記。請信任 scan，絕不要依賴上次的狀態。

在筆記中寫入

筆記是手寫的。沒有範本，沒有隱藏標記，也不會新增這些東西。特定章節的內容會被取代：

python vault.py section --vault "<vault>" --note "<path>" --heading "Deploy" --content "<file>" --dry-run

章節標題的比對不包含表情符號，並使用部分比對，因此 Deploy 會找到 ## 🚀 Deploy。如果沒有符合的項目，腳本會列出存在的章節標題，而不是自行編造一個。

--content 是一個包含新 Markdown 內容的檔案。請將其寫入到一個臨時資料夾（工作階段的暫存區，或系統暫存資料夾），切勿寫入儲藏庫或程式碼儲存庫內部，並在之後刪除它。

真正重要的規則：

永遠先執行 --dry-run，並且在使用者同意後才能進行實際寫入。 向使用者顯示乾跑的差異比對結果，說明每個變更是事實性還是散文性質，然後等待。只有在他們同意後，才執行相同的命令但不帶 --dry-run；一次同意僅涵蓋他們所看到的差異，不包含其他內容。
--content 承載的是整個章節，而不僅僅是變更的部分。 replace 會交換該章節下的整個內容。如果你只送出一個表格，其下的散文就會消失。請先讀取當前的章節，將變更融入其中，然後送出完整的結果。
筆記的最後一個章節是受保護的。 頁尾連結通常位於其下方，不屬於任何章節，如果被取代將會遺失。腳本會以退出碼 2 停止並說明原因。請使用 --mode append 來附加內容而不刪除，這對於像「近期變更」這樣的執行日誌幾乎總是正確的做法。
append 會尊重 callout。 當一個章節是圍欄式 callout（```ad-note，來自 Admonition 外掛）時，新文字會進入圍欄內部，在其結束行之前；當它是原生 callout（> [!note]）時，新行會被加上引號以保留在 callout 內部。無論哪種情況，頁尾都保持在最後。
模仿現有的風格。 語言、語氣、散文或項目符號、長度：儲藏庫的慣例筆記會宣告它，而你要修改的筆記會確認它。在起草之前請先閱讀。
在聲明之前先檢查。 寫入筆記中的計數、版本或狀態，必須來自你在此工作階段中讀取或執行的內容。如果現在無法檢查，請將其省略或說明其未經驗證。

新增章節需要說明其插入位置： --heading "Testing" --after "Gotchas"。請先詢問：一個新章節會改變使用者所撰寫文件的結構。

無須詢問即可變更的內容

由儲藏庫宣告，在其慣例筆記中：說明了哪些是事實性且可驗證的（因此無須詢問即可修正），以及哪些是散文，未經許可不能觸碰。

在你閱讀該筆記之前，請將所有內容視為散文並進行詢問。

當新資訊不適合任何現有章節時，提供兩種出路讓使用者選擇：擴展現有章節，或建立一個從主要筆記連結的獨立筆記。不要自行決定。

前置資料 (Frontmatter)

綱要屬於每個儲藏庫，由其慣例筆記宣告。scan 會回傳每篇筆記的實際前置資料，這是查看它的另一種方式。

python vault.py frontmatter --vault "<vault>" --note "<path>" --set updated=2026-09-13 --dry-run

僅限純量鍵。腳本刻意拒絕區塊列表：變更筆記的主題是作者的決定。section --touch-updated 已經會設定日期，因此這很少單獨需要。

屬於外掛（如貼紙、圖示）的欄位，絕不觸碰。

畫布 (Canvas)

.canvas 檔案是包含 nodes 和 edges 的 JSON（JSON Canvas 1.0）。版面配置是手動完成的，具有精心安排的群組和連接。

python vault.py canvas --vault "<vault>" --file "<path>.canvas" --report

它會提供節點、邊、群組名稱、已連結的筆記，以及是否有任何節點指向已不存在的檔案。

以及 state_outside_its_group，這個欄位最需要關注。 一個按 state 分組筆記的畫布會將該事實儲存兩次：在前置資料中，以及在節點的位置和顏色中。變更了 state，卻將卡片留在原位，畫布不會壞掉；它仍然指向一個存在的檔案，但會顯示舊的顏色。它開始說謊，卻沒有任何東西可以警告任何人。

因此，每當你變更 state 時，請檢查該專案或資料夾是否有按 state 分組的畫布，並執行報告。 反之亦然：建立筆記後，請檢查它是否有一張卡片。對於閱讀畫布的人來說，不在畫板上的筆記等同於不存在。

修正它需要移動節點並重新著色，這是手動編輯：腳本會報告，但不會重新排列。請說明這一點並提議變更。

python vault.py canvas --file "<path>.canvas" --add-file "Relative/Path/Note.md" --color 6 --dry-run

新節點會落在所有現有節點下方的空隙中：既有的任何東西都不會移動。將它們放入群組中是使用者的手動工作，這很合理。一旦使用者同意，再執行一次不帶 --dry-run 的命令。

如果報告顯示有斷開的連結，請說明並停止。不要刪除節點。

工作階段日誌

一個 SessionEnd 掛鉤會將每個 Claude Code 工作階段的原始資料記錄在儲藏庫所宣告的日誌資料夾（config.logs）中，每個儲存庫一個 JSON 檔案：日期、分支、自上次以來的新的提交、觸及的檔案，以及是否有任何未提交的內容。它不會寫入任何筆記。

這就是原始材料。當使用者要求更新時，scan --project 會將它直接帶入，位於 session_log 和 sessions_since_note_changed 中。請將這些提交與筆記中的內容進行比對，並提議哪些章節已經過時。

如果掛鉤尚未安裝，請閱讀 references/hook-install.md。

來自 claude.ai 對話的筆記

claude.ai 的專案不在磁碟上，因此那裡沒有腳本。請在一個程式碼區塊中寫入完整的 Markdown，並附上遵循使用者儲藏庫綱要的前置資料（如果你不知道，請詢問使用者，或要求提供一篇現有筆記來模仿），並說明要儲存在哪裡。如果該專案已經有一篇筆記，請說明要貼入哪個章節，而不是建立一個鬆散的檔案。

故障處理

python 無法識別：嘗試 python3，然後試 py。如果都不行，表示沒有 Python；請說明這一點，並提議使用檔案工具手動編輯，這會較慢且有較高風險。
「未提供儲藏庫」：本地地圖中沒有儲藏庫路徑，且 OBSIDIAN_VAULT 未設定。請詢問使用者路徑，並提議將其加入本地地圖。
腳本以退出碼 2 停止：這是最後章節保護機制在作用。請切換至 --mode append。
差異比對顯示的刪除內容比預期多：不要寫入。這幾乎總是因為 --content 內容不完整。
專案的資料夾不存在：請詢問。不要自行在專案區中建立新資料夾。

參考資料

references/hook-install.md：在 Windows、macOS 和 Linux 上安裝工作階段記錄掛鉤。
references/mechanics.md：腳本的運作方式及其保證：設定檔、章節標題的尋找方式、保護機制、日誌格式。

撰寫慣例不在此處。 它們位於儲藏庫中，在 scan 回傳的 config.conventions 筆記內。

Obsidian 專案同步