用 AI CLI 花一個下午，把散落多年的筆記整理進 Obsidian Vault

衣櫃深處的那個紙箱

想像一個鞋盒。不是整齊的那種 -- 是你搬家後在衣櫃深處挖出來的那種。裡面有餐巾紙上的塗鴉、便利貼、撕下來的雜誌頁、幾張拍立得、還有一張背面寫了什麼重要東西的收據。你知道那個紙箱裡有個很棒的想法。你曾經寫下來過，可能是 2022 年。但要找到它，你得把所有東西倒在地上，一張一張讀。

現在想像這個紙箱是數位的。它散落在四個 app、兩個雲端硬碟、一堆截圖、和你去年暑假掃描過的一本筆記本。你有五年份的筆記。上千則。而你永遠找不到任何東西。

這不是記憶力的問題，是結構的問題。筆記存在。知識也在。但它們像遊行後的碎紙花一樣散落一地 -- 每一片曾經有意義，但現在只是地上的一團混亂。

這篇文章教你把碎紙花重新拼回原本的句子。一個下午，你就能把多年的混亂筆記變成一個結構化、互相連結的知識庫 -- 不只是一堆 markdown 檔，而是一個活的 Obsidian vault，每則筆記都連結到它的鄰居，每個想法都只差一次搜尋。讓這件事成為可能的工具，是一個跑在你 terminal 裡的 AI agent。你可以把它想成一個能看懂你字跡的圖書館員 -- 只是這個館員還能讀截圖、PDF、語音備忘錄的逐字稿，而且還會寫 wikilinks。

為什麼目的地是 Obsidian

Obsidian 從一個小眾的個人知識管理工具，變成超過 1.5 億月活躍用戶、2,700+ 社群 plugin 的主流應用，原因簡單到近乎荒謬：一個 Obsidian vault 就是一個裝著 markdown 檔的資料夾。

沒有專屬資料庫。不需要 API 就能存取你自己的筆記。不需要你無法控制的 sync server。就是你檔案系統上一個目錄裡的 .md 檔。

在 AI CLI 的時代，這個架構變成一種超能力。你的知識庫是一個資料夾，用 AI agent 整理它就這麼簡單：

cd ~/vault && claude "organize my notes"

不用裝 plugin。不用設定 API key。不用走 OAuth 流程。Agent 讀檔案、寫檔案。Obsidian 讀同一批檔案，用 backlinks、graph view、全文搜尋來渲染它們。兩個工具，同一個資料夾，零整合工作。

所以我們不只是把筆記整理成 markdown。我們是把它們整理進一個 Obsidian vault -- 有 [[wikilinks]]、YAML frontmatter、tags、和 Obsidian graph view 能視覺化的資料夾結構。整理好的筆記立刻可搜尋、立刻互相連結、立刻有用。

你會建出什麼

這個下午結束時，你手上會有：

1. 一個 Obsidian vault，裝著你所有整理好的筆記，有完整的 frontmatter、tags 和 wikilinks。
2. 一組按主題分類的 markdown 檔，不是按來源 app 或日期分，而是按內容分 -- 每一份都是正規的 Obsidian 筆記。
3. 一張連結圖，你可以用視覺方式看到「API 設計決策」如何連結到原本散落在 Apple Notes、Notion 匯出檔、和一張白板照片裡的筆記。

關鍵在這裡：AI 不是按檔名或日期分類。它讀取內容，理解每則筆記在講什麼。一個叫 meeting-2024-03-15.txt 的檔案，會被歸類到「Project Alpha - API 決策」底下，因為 agent 讀了裡面寫的東西。一張白板照片會被分到「產品路線圖 Q3」，因為 agent 看了圖片，理解了上面的架構圖。因為輸出直接進 Obsidian vault，每一條連結都變成 graph view 裡可以點擊的節點。

差別就像用書的封面顏色來上架，和用書的主題來上架 -- 然後在每本互相引用的書之間拉上絲線。

前置需求

• Claude Code 已安裝並認證。還沒裝的話，跟著第一個小時教學走，十分鐘搞定。
• Obsidian 已安裝。個人使用免費。如果你已經有 vault，很好 -- 我們直接輸出到裡面。沒有的話，Obsidian 第一次打開時就會建一個。
• 你的筆記已匯出。 下一節會詳細說明。
• 基本 terminal 操作能力。 你會輸入指令、看輸出。不需要寫程式。

第一步：大匯出

AI 要讀你的筆記之前，筆記得先變成你電腦上的檔案。每個筆記 app 都有匯出功能。以下是各個 app 的做法。

Apple Notes： 打開備忘錄，全選（Cmd+A），然後檔案 > 輸出為 PDF。每則筆記變成一個 PDF 檔。

Notion： 到 Settings > Export all workspace content。選 Markdown & CSV 格式。你會得到一個 zip 檔，裡面每頁一個 markdown 檔。

Google Keep： 用 Google Takeout（takeout.google.com）。選 Keep，匯出並下載。筆記會以 HTML 檔案的形式出來。

已有的 Obsidian vault： 如果你已經在用 Obsidian 但 vault 一團亂，不需要匯出。我們直接在原地重整（AI 會寫到一個新的子資料夾，絕不碰原始檔案）。

Logseq： 你的筆記本來就是一個資料夾裡的 markdown 檔。直接複製過去。

語音備忘錄： 從手機匯出到電腦。它們會是 .m4a 或 .mp3 檔。

截圖和手寫筆記的照片： 從手機或相簿裡複製到資料夾。

建一個資料夾，全部丟進去：

mkdir -p ~/notes-raw
# 把所有匯出的筆記都丟進來
# Notion 匯出、Apple Notes PDF、截圖、語音備忘錄 -- 全部

匯出完，你的資料夾大概長這樣：

~/notes-raw/
  meeting-2024-03-15.txt
  Untitled 47.pdf
  IMG_3921.png
  project-ideas.md
  voice-memo-2025-01-08.m4a
  Screenshot 2024-11-02 at 3.41.22 PM.png
  api-design-notes.html
  random-thoughts.md
  book-notes-atomic-habits.pdf
  IMG_4102.jpg
  quarterly-review-prep.txt
  research-links.md
  whiteboard-photo.heic
  ...（還有幾百個）

一座好意的墳場。曾經有意義的檔名。在產出它們的 app 裡才說得通的格式。零結構把任何東西串在一起。

這是你的原料。AI agent 會讀取每一個檔案，然後把結果直接送進一個真正能用的 vault。

第二步：準備 Obsidian Vault

如果你已經有 Obsidian vault，可以直接輸出進去。沒有的話，建一個：

mkdir -p ~/vault

打開 Obsidian，選「Open folder as vault」指向 ~/vault。搞定。Obsidian 現在在監看這個資料夾。AI agent 寫入的任何 markdown 檔都會立刻出現在 Obsidian 裡 -- wikilinks 自動解析、tags 自動索引、graph view 自動更新。

這就是 Obsidian 在這裡至關重要的架構優雅之處。沒有匯入步驟。沒有同步延遲。Agent 寫一個 .md 檔。Obsidian 看到它。結束。

第三步：設定 CLAUDE.md

Agent 開始工作之前，需要指示。在你的工作目錄放一個 CLAUDE.md，就像在圖書館員碰書之前，先跟他說「我要這樣分類」。

在 ~/notes-raw/ 建立這個檔案：

# Note Organization Rules

## Goal

Read every file in this directory. Classify each note by its CONTENT, not by
its filename, source app, or file format. Build a structured knowledge base
as organized markdown files in an Obsidian vault.

## Output Destination

Write all organized files to: ~/vault/organized/

## Topic Categories

Classify notes into these top-level topics (create new ones if needed):
- projects/ -- notes related to specific projects, grouped by project name
- learning/ -- book notes, course notes, tutorials, concepts studied
- ideas/ -- brainstorms, product ideas, feature proposals, shower thoughts
- meetings/ -- meeting notes, discussion summaries, action items
- reference/ -- how-to guides, code snippets, configuration recipes
- personal/ -- journal entries, reflections, life plans, health notes
- research/ -- academic research, literature reviews, data analysis notes

## Classification Rules

1. READ the content of every file to determine its topic. Never classify by filename alone.
2. For images (PNG, JPG, HEIC): describe the visual content. If it is a photo of handwritten notes or a whiteboard, transcribe the text.
3. For PDFs: read the full document and extract the core topic.
4. For voice memos (M4A, MP3): transcribe the audio and classify by content.
5. If a single note covers multiple topics, place it under the PRIMARY topic and add cross-references to the others.
6. When uncertain, ask: "What would I search for to find this note?" That search term is the topic.

## Obsidian Output Format

For each topic, create a markdown file at:
  ~/vault/organized/{topic}/{subtopic}.md

Each markdown file MUST include:

### Frontmatter (YAML)
---
title: "Descriptive Title"
date: YYYY-MM-DD
lastUpdated: "2026-03-22T11:48:54"
sources:
  - original-filename-1.txt
  - original-filename-2.png
tags:
  - topic-tag
  - subtopic-tag
---

### Content
- A clear title (H1) matching the frontmatter title
- The actual content, cleaned up and formatted as readable markdown
- Wikilinks to related notes: use [[note-name]] format
  Example: "See also [[API Design Patterns]] and [[Sprint Notes Q3]]"
- Tags inline where relevant: #project-alpha, #api-design

### Wikilink Rules
- Link to other organized notes using [[filename]] (without path or .md extension)
- When referencing a specific section, use [[filename#section]]
- Create links even if the target note does not exist yet (Obsidian handles this gracefully)
- Prefer descriptive link text: [[api-rate-limiting|rate limiting strategy]]

## Index

Generate ~/vault/organized/INDEX.md as a Map of Content (MOC) that:
- Lists every topic and subtopic with [[wikilinks]]
- Shows how many notes are in each category
- Includes a "Key Connections" section highlighting notes that bridge multiple topics
- Uses tags: #MOC #index

## Safety

- NEVER delete or modify original files in ~/notes-raw/.
- Write all output to ~/vault/organized/.
- If a file cannot be read, log it in ~/vault/organized/SKIPPED.md with the reason.

這是你的分類大腦。把主題類別調整成符合你生活的版本。學生可能要加 courses/ 和 exams/。研究者可能要加 papers/ 和 experiments/。類別應該反映你怎麼想事情，而不是你的 app 怎麼想。

跟單純的 markdown dump 的關鍵差異：每個輸出檔都有正規的 Obsidian frontmatter、指向相關筆記的 wikilinks、和 inline tags。這些檔案落地到 vault 的瞬間，Obsidian 的 graph view 就會亮起你從沒看過的連結。

第四步：讓 Agent 讀所有東西

現在是人類要花三個週末才做得完的部分。AI agent 在你泡咖啡的時候搞定。

cd ~/notes-raw
claude

在 Claude Code 的 prompt 裡輸入：

Read every file in this directory. Follow the CLAUDE.md rules exactly.
For each file, read its content, classify it by topic, and write the
organized output to ~/vault/organized/.
Use Obsidian wikilinks and frontmatter as specified in CLAUDE.md.
Start with a scan of all files and show me the proposed classification
before writing anything.

Agent 掃描目錄、讀取每個檔案，然後給你一份分類計畫：

Found 847 files. Proposed classification:

projects/alpha-api/        -- 34 notes (from meetings, screenshots, text files)
projects/website-redesign/ -- 22 notes
learning/programming/      -- 67 notes (book notes, tutorials, snippets)
learning/design/           -- 18 notes
ideas/product-features/    -- 41 notes
ideas/side-projects/       -- 29 notes
meetings/2024/             -- 156 notes
meetings/2025/             -- 89 notes
reference/dev-setup/       -- 45 notes
reference/recipes/         -- 12 notes
personal/journal/          -- 78 notes
personal/health/           -- 23 notes
research/user-interviews/  -- 31 notes
research/market-analysis/  -- 19 notes

Unclassified: 14 files (3 corrupted, 11 ambiguous)

Proceed with writing organized files?

檢查計畫。如果 agent 把你的食譜放到 reference/recipes/，而你比較想放在 personal/cooking/，直接說：

Move cooking-related notes to personal/cooking/ instead of reference/recipes/.
Also split meetings/ by project, not by year.
Proceed with the rest.

Agent 調整後開始寫入。每個整理好的 markdown 檔長這樣：

---
title: "Project Alpha - API 設計決策"
date: 2024-11-02
lastUpdated: "2026-03-22T11:48:54"
sources:
  - meeting-2024-03-15.txt
  - IMG_3921.png
  - api-design-notes.html
  - Screenshot 2024-11-02 at 3.41.22 PM.png
tags:
  - project-alpha
  - api-design
  - architecture
---

# Project Alpha - API 設計決策

## REST vs GraphQL 決策（2024 年 3 月）

團隊決定公開 API 用 REST，內部服務用 GraphQL。
主要原因：
- 前端團隊對 REST 比較熟
- 以 CRUD 為主的公開端點不值得引入 GraphQL 的複雜度
- 內部服務需要跨微服務的彈性查詢

詳細實作參考 [[GraphQL Internal Services Setup]]。

## 認證流程（2024 年 11 月）

白板草圖（從 IMG_3921.png 轉錄）：
- 手機端用 OAuth 2.0 + PKCE
- 伺服器對伺服器用 API key + HMAC
- JWT 設 15 分鐘過期，refresh token 存在 HttpOnly cookie

相關筆記：[[OAuth PKCE Implementation Notes]]

## 限流策略

從 Slack 對話截圖擷取：
- 免費方案每個 API key 每分鐘 100 次請求
- 付費方案每分鐘 1000 次
- 用滑動窗口演算法，不用固定窗口

---

**延伸閱讀：**
- [[Project Alpha Sprint Notes]]
- [[API Design Patterns]]
- [[User Interview - Developer Experience|開發者體驗回饋]]

注意發生了什麼。四個檔案 -- 一個文字檔、一張白板照片、一個 HTML 匯出檔、一張截圖 -- 變成一份關於 API 設計決策的完整文件。Agent 看了圖片、轉錄了白板上的圖表、從 HTML 裡提取了相關內容，全部編織在一個有意義的主題底下。

但現在看 Obsidian 對這份文件做了什麼。打開 graph view。「Project Alpha - API 設計決策」跟「Sprint Notes」、「API Design Patterns」、「開發者體驗回饋」之間出現了連線。點任何一條 link。跟著脈絡走。筆記不只是被整理了 -- 它們被連成網路了。

meeting-2024-03-15.txt 這個檔名什麼都沒告訴你。一則有 wikilinks 的「Project Alpha - API 設計決策」筆記不只告訴你一切，還帶你走到所有相關的東西。

第五步：處理棘手的格式

大部分筆記是文字。但有趣的那些往往不是。

手寫筆記的照片

Agent 看得懂圖片。碰到筆記本頁面的照片時，它不只是分類這張照片 -- 它會讀取手寫內容並轉錄。你潦草寫的「查一下 distributed caching -- Redis vs Memcached??」會變成整理檔裡可搜尋的文字，加上 #infrastructure tag，wikilink 指向 [[Caching Architecture Decisions]]。

不是每份手寫都能辨識。如果 agent 沒把握，它會在輸出裡標註，並附上原始圖片路徑讓你手動確認。

截圖

Slack 對話截圖、瀏覽器分頁截圖、錯誤訊息截圖、程式碼片段截圖 -- agent 讀取圖片中的文字，按內容分類。一張 Stack Overflow 關於 PostgreSQL 索引的回答截圖，會被歸到 reference/database/，而不是塞進一個通用的 screenshots/ 資料夾。它會拿到一條指向 [[PostgreSQL Performance Tuning]] 的 wikilink 和一個 #database tag。

PDF

從 Apple Notes 和其他 app 匯出的筆記通常是 PDF 格式。Agent 原生讀取 PDF。一份 12 頁的工作坊會議紀錄 PDF 會被拆解成各自的主題，並加上交叉引用。

語音備忘錄

語音備忘錄會被 agent 轉錄並按內容分類。一則 8 分鐘、東講西講三個不同想法的語音備忘，會變成三個不同主題檔案裡的三筆獨立條目，每筆都標註回原始音檔。

第六步：建立內容地圖

Agent 整理完成後，會產生 ~/vault/organized/INDEX.md -- 一份 Obsidian Map of Content（MOC）：

---
title: "個人知識庫"
tags:
  - MOC
  - index
---

# 個人知識庫

最後整理日期：2026-03-23
處理筆記總數：847
成功分類：833
跳過（詳見 [[SKIPPED]]）：14

## 主題

### 專案（56 則）
- [[Project Alpha API Decisions]] -- API 設計、sprint 筆記、架構
- [[Website Redesign]] -- wireframe、文案、回饋

### 學習（85 則）
- [[Programming Notes]] -- 語言、模式、教學
- [[Design Notes]] -- UI 原則、排版、色彩理論

### 點子（70 則）
- [[Product Feature Ideas]] -- 功能提案、使用者需求
- [[Side Project Plans]] -- 週末專案計畫、原型

### 會議（245 則）
- [[Project Alpha Sprint Notes]]
- [[Design Review Notes]]
- [[One-on-One Notes]]

### 參考資料（57 則）
- [[Dev Setup Guides]] -- 機器設定、dotfiles、工具指南
- [[API Design Patterns]]

### 個人（101 則）
- [[Journal]]
- [[Health Notes]]
- [[Cooking Recipes]]

### 研究（50 則）
- [[User Interview Summaries]]
- [[Market Analysis]]

## 關鍵連結

- [[Project Alpha API Decisions]] 連結到 [[API Design Patterns]]
  和 [[User Interview - Developer Experience]]
- [[Side Project Recipe App]] 同時連結到 [[Cooking Recipes]]
  和 [[React Patterns]]
- [[Health Notes - Sleep]] 連結到 [[Journal - Productivity Reflections]]

在 Obsidian 裡打開這個檔案。每個 [[link]] 都可以點。從這一份 MOC 打開 graph view，你的整個知識庫以視覺網路的形式展開。叢集圍繞著專案形成。你從沒有意識到的想法之間出現了橋樑。

grep 做不到這件事。一堆扁平的文字檔做不到這件事。Wikilinks 把一堆整理好的筆記，變成一張可以導航的知識圖。

用 Obsidian CLI 加速

Vault 整理好之後，Obsidian 官方 CLI（2026 年 2 月隨 v1.12 發布）讓你從 terminal 就能跟 vault 互動 -- 而且可以跟 AI agent 串接。

# 不開 app 就能搜尋 vault
obsidian search query="rate limiting"

# 列出 vault 裡所有 tags
obsidian tags

# 找孤兒筆記 -- 沒有任何 incoming 或 outgoing link 的筆記
obsidian orphans

# 看特定筆記的 backlinks
obsidian backlinks "Project Alpha API Decisions"

對 AI workflow 來說最殺的功能：每個指令都支援 format=json 輸出。這表示 AI agent 可以用程式化的方式查詢你的 vault：

# Agent 回答問題前先找到相關筆記
obsidian search query="authentication flow" format=json | claude -p "Based on these notes, summarize our auth architecture"

效能數字很關鍵。Obsidian CLI 搜尋 vault index 的速度是 raw grep 的 60 倍，消耗的 token 比讓 AI agent 掃每個檔案少 70,000 倍。對一個有幾千則筆記的 vault 來說，差別在 2 秒鐘的答案和 10 分鐘燒 token 的遠征之間。

更深整合：MCP Server

如果你的 workflow 需要 AI agent 在一次對話裡讀取、搜尋、寫入 vault，有一個 MCP server 的選項：

npm install -g obsidian-mcp-server

這讓 Claude Code 透過 MCP protocol 直接存取 vault -- 搜尋、讀取、建立、連結筆記，不需要 shell out 到 CLI。它對複雜的多步驟操作很有用，比如「找出所有關於 Project Alpha 的筆記，找出缺口，然後寫三則新筆記來補上。」

但重點在這裡：你不需要 MCP server。 你的 vault 就是一個資料夾。cd ~/vault && claude 本來就行。MCP server 是最佳化，不是必要條件。先不裝。等你的 workflow 需要時再加。

腳本化：讓它可重複執行

新筆記會持續累積。你不會想每季都手動重做一次。這個腳本可以增量處理新筆記，直接輸出到你的 Obsidian vault：

#!/usr/bin/env bash
set -euo pipefail

NOTES_DIR="${1:?Usage: organize-notes.sh <notes-directory>}"
VAULT_DIR="${2:-$HOME/vault}"
ORGANIZED_DIR="$VAULT_DIR/organized"
PROCESSED_LOG="$ORGANIZED_DIR/.processed-files.txt"

mkdir -p "$ORGANIZED_DIR"
touch "$PROCESSED_LOG"

# 找出還沒處理過的檔案
NEW_FILES=$(comm -23 \
  <(find "$NOTES_DIR" -maxdepth 1 -type f | sort) \
  <(sort "$PROCESSED_LOG"))

NEW_COUNT=$(echo "$NEW_FILES" | grep -c '.' || true)

if [[ "$NEW_COUNT" -eq 0 ]]; then
  echo "No new files to process."
  exit 0
fi

echo "Found $NEW_COUNT new files to classify."

claude -p "You are a note organizer. Read CLAUDE.md in $NOTES_DIR for rules.

These are NEW files that need classification:
$NEW_FILES

Read each file, classify by content, and APPEND to the existing organized
markdown files in $ORGANIZED_DIR/. Use Obsidian wikilinks and frontmatter.
Update INDEX.md with any new entries and new [[wikilinks]].
Do not reprocess files already in the organized/ directory.

After processing, list the files you processed (one per line, full path)."

# Agent 輸出處理完的檔案路徑 -- 附加到紀錄
echo "$NEW_FILES" >> "$PROCESSED_LOG"

echo "Done. $NEW_COUNT new notes classified into $VAULT_DIR."

每個月跑一次。或每週。或只要你丟了一批新筆記進資料夾就跑。每次只處理新的 -- 而且每則新筆記抵達 vault 時，就已經帶著指向既有筆記的 wikilinks。

在 Vault 裡放一份 CLAUDE.md

初始整理完成後，考慮在 vault 本身放一份 CLAUDE.md。這會教任何進入 vault 的 AI agent，你的知識庫是怎麼運作的：

# Vault: Personal Knowledge Base

## Structure
- organized/ -- AI-classified notes from raw exports
- projects/ -- active project notes (manually maintained)
- daily/ -- daily notes (Obsidian daily notes plugin)
- templates/ -- note templates

## Conventions
- Filenames: kebab-case, descriptive (e.g., api-rate-limiting-strategy.md)
- Tags: lowercase, hyphenated (#project-alpha, #api-design)
- Wikilinks: always use [[descriptive name]], never raw file paths
- Frontmatter: every note MUST have title, date, and tags

## Tag Taxonomy
- #MOC -- Map of Content (index notes)
- #project-{name} -- project-specific tags
- #status/active, #status/archived, #status/idea
- #type/meeting, #type/reference, #type/journal

## When Adding Notes
- Always check for existing related notes and add [[wikilinks]]
- Update the relevant MOC if one exists
- Use templates/ for consistent structure

現在當你跑 cd ~/vault && claude "add my notes from today's architecture meeting"，agent 已經知道你的命名慣例、tag 分類法、和 linking 風格。新筆記到達時就是 vault 的原生公民，不是外來的匯入品。

到底改變了什麼

之前：847 個檔案散落在四個 app。沒有結構。沒辦法按主題搜尋。你知道自己曾經寫過關於 API 限流的東西，但要找到它，得打開三個 app，滾過上百則標題毫無意義的筆記。

之後：一個按你思考方式整理的 Obsidian vault。一張 graph view 顯示想法之間的連結。Wikilinks 讓你三次點擊就能從「API 設計」追到「使用者訪談回饋」再到「sprint 規劃筆記」。一次搜尋 -- 不管是在 Obsidian 裡還是從 terminal 用 obsidian search -- 幾秒鐘找到所有東西。

AI 不只是把檔案搬進資料夾。它讀了每一則筆記、理解內容、建出一個人類會建的結構，然後用 link 串起一個人類會加的連結 -- 如果那個人類有時間一口氣讀完 847 則筆記，還能記住它們之間的每一條關係。你沒有那個時間。Agent 有。

筆記一直都在。知識一直都在。它只是需要一個不只會分類、還會畫地圖的圖書館員。

更多 AI agent 批次處理檔案的做法，請看完整檔案整理指南。還沒裝 Claude Code 的話，從第一個小時教學開始。