Obsidian 整合：自動儲存計畫到筆記庫
學完你能做什麼
- 自動將批准或拒絕的計畫儲存到 Obsidian vault
- 理解 frontmatter 和標籤的產生機制
- 自訂儲存路徑和資料夾
- 利用 backlink 建構知識圖譜
你現在的困境
你在 Plannotator 中審查 AI 產生的計畫，批准後這些計畫就「消失」了。你希望把這些有價值的計畫儲存到 Obsidian，方便後續回顧和尋找，但手動複製貼上太麻煩，而且格式會亂。
什麼時候用這一招
- 你使用 Obsidian 作為知識管理工具
- 你希望長期儲存和回顧 AI 產生的實施計畫
- 你想利用 Obsidian 的 graph view 和標籤系統組織計畫
核心思路
Plannotator 的 Obsidian 整合功能會在你批准或拒絕計畫時，自動將計畫內容儲存到你的 Obsidian vault。系統會：
- 偵測 vaults：自動從 Obsidian 設定檔讀取所有 vault
- 產生 frontmatter：包含建立時間、來源和標籤
- 擷取標籤：從計畫標題和程式碼區塊語言自動擷取標籤
- 新增 backlink：插入
[[Plannotator Plans]]連結，方便建構知識圖譜
什麼是 Obsidian？
Obsidian 是一款本機優先的雙向連結筆記應用程式，支援 Markdown 格式，可透過圖視圖視覺化筆記之間的關係。
🎒 開始前的準備
確保已安裝並設定好 Obsidian。Plannotator 會自動偵測系統中的 vaults，但你至少需要有一個 vault 才能使用此功能。
跟我做
第 1 步：開啟設定面板
在 Plannotator 介面中，點擊右上角的齒輪圖示開啟設定面板。
你應該看到設定對話框，包含多個設定選項。
第 2 步：啟用 Obsidian 整合
在設定面板中找到「Obsidian Integration」部分，點擊開關啟用該功能。
啟用後，Plannotator 會自動偵測系統中的 Obsidian vaults。
你應該看到下拉選單中列出偵測到的 vaults（例如 My Vault、Work Notes）。
第 3 步：選擇 vault 和資料夾
從下拉選單中選擇你希望儲存計畫的 vault。如果沒有偵測到 vault，可以：
- 選擇「Custom path...」選項
- 在文字方塊中輸入 vault 的完整路徑
然後在「Folder」欄位中設定儲存資料夾的名稱（預設為 plannotator）。
你應該看到下方的預覽路徑，顯示計畫將儲存的位置。
第 4 步：批准或拒絕計畫
設定完成後，正常審查 AI 產生的計畫。當你點擊「Approve」或「Send Feedback」時，計畫會自動儲存到設定的 vault 中。
你應該在 Obsidian 中看到新建立的檔案，檔案名稱格式為 Title - Jan 2, 2026 2-30pm.md。
第 5 步：檢視儲存的檔案
在 Obsidian 中開啟儲存的檔案，你會看到以下內容：
---
created: 2026-01-24T14:30:00.000Z
source: plannotator
tags: [plan, authentication, typescript, sql]
---
[[Plannotator Plans]]
## Implementation Plan: User Authentication
...你應該注意到檔案頂部有 YAML frontmatter，包含建立時間、來源和標籤。
檢查點 ✅
- [ ] 設定面板中 Obsidian Integration 已啟用
- [ ] 已選擇 vault（或輸入了自訂路徑）
- [ ] 已設定資料夾名稱
- [ ] 批准或拒絕計畫後，Obsidian 中出現新檔案
- [ ] 檔案包含 frontmatter 和
[[Plannotator Plans]]backlink
Frontmatter 和標籤詳解
Frontmatter 結構
每個儲存的計畫都包含以下 frontmatter 欄位：
| 欄位 | 值範例 | 說明 |
|---|---|---|
created | 2026-01-24T14:30:00.000Z | ISO 8601 格式的建立時間戳記 |
source | plannotator | 固定值，標識來源 |
tags | [plan, authentication, typescript] | 自動擷取的標籤陣列 |
標籤產生規則
Plannotator 使用以下規則自動擷取標籤：
- 預設標籤：總是包含
plannotator標籤 - 專案名稱標籤：從 git 儲存庫名稱或目錄名稱自動擷取
- 標題關鍵字：從第一個 H1 標題中擷取有意義的詞（排除常見停用詞）
- 程式碼語言標籤：從程式碼區塊的語言識別符擷取（例如
typescript、sql）。通用設定語言（如json、yaml、markdown）會被自動過濾。
停用詞清單（不會作為標籤）：
the,and,for,with,this,that,from,intoplan,implementation,overview,phase,step,steps
標籤數量限制：最多 7 個標籤，按擷取順序排列。
檔案名稱格式
檔案名稱採用可讀性強的格式：Title - Jan 2, 2026 2-30pm.md
| 部分 | 範例 | 說明 |
|---|---|---|
| 標題 | User Authentication | 從 H1 擷取，限制 50 字元 |
| 日期 | Jan 2, 2026 | 目前日期 |
| 時間 | 2-30pm | 目前時間（12 小時制） |
Backlink 機制
每個計畫檔案底部都會插入 [[Plannotator Plans]] 連結。這個 backlink 的作用：
- 知識圖譜連接：在 Obsidian 的 graph view 中，所有計畫都與同一個節點連接
- 快速導覽：點擊
[[Plannotator Plans]]可以建立一個索引頁面，彙總所有儲存的計畫 - 雙向連結：在索引頁面中使用反向連結檢視所有計畫
跨平台支援
Plannotator 自動偵測不同作業系統的 Obsidian 設定檔位置：
| 作業系統 | 設定檔路徑 |
|---|---|
| macOS | ~/Library/Application Support/obsidian/obsidian.json |
| Windows | %APPDATA%\obsidian/obsidian.json |
| Linux | ~/.config/obsidian/obsidian.json |
如果自動偵測失敗，可以手動輸入 vault 路徑。
踩坑提醒
問題 1：偵測不到 vaults
症狀：下拉選單顯示「Detecting...」但沒有結果
原因：Obsidian 設定檔不存在或格式錯誤
解決方案：
- 確認 Obsidian 已安裝並至少開啟過一次
- 檢查設定檔是否存在（參考上表路徑）
- 使用「Custom path...」手動輸入 vault 路徑
問題 2：儲存後找不到檔案
症狀：批准計畫後，Obsidian 中沒有新檔案
原因：vault 路徑錯誤或 Obsidian 未重新整理
解決方案：
- 檢查設定面板中的預覽路徑是否正確
- 在 Obsidian 中點擊「Reload vault」或按
Cmd+R（macOS）/Ctrl+R（Windows/Linux） - 檢查是否選擇了正確的 vault
問題 3：檔案名稱包含特殊字元
症狀：檔案名稱中出現 _ 或其他取代字元
原因：標題包含檔案系統不支援的字元（< > : " / \ | ? *）
解決方案：這是預期行為，Plannotator 會自動取代這些字元��避免檔案系統錯誤。
本課小結
Obsidian 整合功能讓你的計畫審查流程與知識管理無縫連接：
- ✅ 自動儲存批准或拒絕的計畫
- ✅ 智慧擷取標籤，方便後續檢索
- ✅ 產生 frontmatter，統一中繼資料格式
- ✅ 新增 backlink，建構知識圖譜
設定一次後，每次審查都會自動歸檔，不再需要手動複製貼上。
下一課預告
下一課我們學習 Bear 整合。
你會學到：
- 如何將計畫儲存到 Bear 筆記應用程式
- Bear 整合與 Obsidian 整合的區別
- 使用 x-callback-url 自動建立筆記
附錄：原始碼參考
點擊展開檢視原始碼位置
更新時間：2026-01-24
| 功能 | 檔案路徑 | 行號 |
|---|---|---|
| 偵測 Obsidian vaults | packages/server/integrations.ts | 135-175 |
| 儲存計畫到 Obsidian | packages/server/integrations.ts | 180-227 |
| 擷取標籤 | packages/server/integrations.ts | 34-74 |
| 產生 frontmatter | packages/server/integrations.ts | 81-89 |
| 產生檔案名稱 | packages/server/integrations.ts | 111-127 |
| Obsidian 設定儲存 | packages/ui/utils/obsidian.ts | 36-43 |
| Settings UI 元件 | packages/ui/components/Settings.tsx | 387-491 |
關鍵函式：
detectObsidianVaults()：讀取 Obsidian 設定檔，回傳可用的 vault 路徑清單saveToObsidian(config)：將計畫儲存到指定 vault，包含 frontmatter 和 backlinkextractTags(markdown)：從計畫內容擷取標籤（標題關鍵字、程式碼語言、專案名稱）generateFrontmatter(tags)：產生 YAML frontmatter 字串generateFilename(markdown)：產生可讀的檔案名稱
業務規則：
- 標籤數量最多 7 個（L73）
- 檔案名稱限制 50 字元（L102）
- 支援跨平台設定檔路徑偵測（L141-149）
- 自動建立不存在的資料夾（L208）