# 建置指南：打造本地 Notion + WordPress RAG 知識庫
> 這份指南是給想要自己動手複製的讀者。
> 你不需要懂程式——你只需要把下面的提示詞，貼給 Claude Code 執行就好。
> 每個 Phase 都附有「驗收方式」，確認成功再繼續下一步。
## 這套系統的架構特色：RAG + SQL 雙引擎
很多人說的「本地 RAG 知識庫」，指的是語意向量搜尋（Qdrant）。
這套系統多加了一層：**同時跑 SQLite 做精準條件篩選**。
兩個引擎各自解決不同的問題：
| 查詢類型 | 引擎 | 範例 |
|---------|------|------|
| 語意模糊查詢 | Qdrant 向量資料庫（RAG） | 「有沒有關於讀書方法的筆記？」 |
| 精準條件篩選 | SQLite（SQL） | 「所有狀態是 Finished、分類是商業管理的書」 |
光用語意搜尋，你問「Finished 的書有哪些」可能出不來——因為語意搜尋是找「意思相近」的，不做條件過濾。
光用 SQL，你問「有什麼讀書心得」找到的可能很有限——因為它只找文字完全吻合的。
兩個並行，才能涵蓋你所有可能問的問題類型。
---
## 你需要準備什麼
### 軟體安裝（事前準備）
| 項目 | 說明 | 下載位置 |
|------|------|---------|
| Python 3.11 以上 | 整套系統的執行環境 | python.org |
| Ollama | 本機跑 AI 圖片分析模型 | ollama.com |
| Claude Desktop | 對話介面，連接你的知識庫 | claude.ai/download |
| Claude Code | 幫你寫程式的 AI 工程師 | claude.ai/code |
安裝 Ollama 後，開終端機執行：
```bash
ollama pull llava-phi3
```
這會下載圖片分析模型（約 2.9 GB），只需下載一次。
### 帳號 & API
| 項目 | 說明 |
|------|------|
| Notion Integration Token | 到 notion.so/my-integrations 建立，選「Read content」權限即可 |
| WordPress 網址 | 你的 WordPress 部落格網址（選配，有才需要做 Phase 9） |
> **Notion Integration 設定提醒**：建立 Integration 後，要去每個 Notion 資料庫，點右上角「...」→「連結到」，把你建立的 Integration 加進去，AI 才讀得到。
### 磁碟空間
| 項目 | 估計空間 |
|------|---------|
| Python 套件 | 約 3-5 GB |
| llava-phi3 模型 | 約 2.9 GB |
| 圖片下載（視資料量） | 視個人 Notion 而定 |
| 建議總預留空間 | 15 GB 以上 |
---
## 系統架構全貌
### 整體架構（RAG + SQL 雙引擎）
```
┌──────────────────────────────────────────────────┐
│ 資料來源 │
│ Notion（3,000+ 頁筆記、圖片、PDF） │
│ WordPress（100+ 篇部落格文章） [選配] │
└──────────────┬───────────────────────────────────┘
│ 每天凌晨自動同步
↓
┌──────────────────────────────────────────────────┐
│ 本地資料儲存 │
│ pages.json 圖片附件 PDF 附件 │
└──┬─────────────────┬──────────────────┬──────────┘
↓ ↓ ↓
sqlite_sync process_images process_pdfs
（屬性索引） （AI 看圖說話） （PDF 文字擷取）
↓ ↓ ↓
┌──────────────────────────────────────────────────┐
│ build_vector_db.py │
│ 把所有資料合併，建立語意向量索引 │
└──────────────┬───────────────────────────────────┘
│
┌────────┴─────────┐
↓ ↓
┌──────────┐ ┌──────────────┐
│ Qdrant │ │ SQLite │
│ 向量資料庫│ │ 屬性資料庫 │
│ （語意） │ │ （精準篩選）│
└────┬─────┘ └──────┬───────┘
└─────────┬──────────┘
↓
┌──────────────┐
│ MCP Server │
│（本地自建橋接）│
└──────┬───────┘
↓
┌───────────────┐
│ Claude Desktop│
│ │
│ 3 個工具可用 │
│ search_knowledge 語意搜尋
│ query_properties 精準篩選
│ get_page_content 取完整頁面+自動開啟圖片
└───────────────┘
```
### 每日自動同步流程
```
凌晨 3:00
│
↓ [1] Windows 工作排程器觸發
daily_sync.bat
│
↓ [2] 同步資料來源
sync_all.py
├── notion_sync.py（增量同步 Notion，只處理有變動的頁面）
└── wordpress_sync.py（增量同步 WordPress）[選配]
│
↓ [3] 處理附件
process_pdfs.py（擷取 PDF 文字，增量，已處理跳過）
│
↓ [4] AI 圖片描述
process_images.py（llava-phi3 看圖，增量，已描述跳過）
│
↓ [5] 重建向量索引
build_vector_db.py（把所有資料向量化存入 Qdrant）
│
↓ 記錄 log，寫入 last_sync_status.txt
完成
```
---
## 完整提示詞（依序執行）
> **使用方式**：開啟 Claude Code，切換到你的專案資料夾，把以下提示詞貼入，讓 Claude Code 幫你完成。
> 每個 Phase 完成後，先驗收，再繼續下一步。
---
### Phase 1：環境準備
**完成這個 Phase 之後**：你的電腦上會有一個完整的專案資料夾結構、Python 虛擬環境、以及所有必要設定檔。
```
我要建立一套本地 RAG 知識庫系統，讓 Claude Desktop 可以智慧查詢我的 Notion 筆記。
這個系統會：
1. 把 Notion 所有筆記同步到本地
2. 建立語意搜尋（Qdrant 向量資料庫）
3. 建立屬性精準篩選（SQLite）
4. 透過 MCP Server 讓 Claude Desktop 可以查詢
請幫我完成環境準備：
1. 建立專案資料夾結構：
專案根目錄/
├── .env # 存放 API Token
├── .gitignore
├── sync/
│ └── data/ # 存放 pages.json
├── embeddings/
├── mcp_server/
├── scripts/
├── attachments/
│ ├── images/
│ └── pdfs/
└── logs/
2. 建立 Python 虛擬環境（venv），安裝以下套件：
notion-client, qdrant-client, sentence-transformers,
python-dotenv, mcp, beautifulsoup4, Pillow, PyMuPDF, requests
3. 建立 sync/config.py，集中管理所有設定：
- 專案根目錄路徑
- pages.json 路徑
- attachments 路徑
- API 請求間隔（SLEEP_BETWEEN_REQUESTS = 0.5）
- 每批處理頁面數（BATCH_SIZE = 10）
- Embedding batch size（EMBEDDING_BATCH_SIZE = 32）
4. 建立 .env 模板（只含變數名稱，不含實際值）：
NOTION_TOKEN=
NOTION_WORKSPACE_NAME=
5. 建立 .gitignore（包含 .env、venv/、qdrant_data/、*.db、sync/data/）
請確認每個步驟是否完成，最後列出已安裝的套件清單。
```
**驗收**：資料夾結構存在，`venv\Scripts\python.exe -c "import notion_client; print('OK')"` 不報錯。
---
### Phase 2：Notion 同步腳本
**完成這個 Phase 之後**：可以把你的 Notion 所有頁面同步到本地 pages.json，包含圖片和 PDF 附件下載。
```
環境準備已完成（Phase 1），現在要建立 Notion 同步腳本。
請建立 sync/notion_sync.py，功能如下：
1. 讀取 .env 的 NOTION_TOKEN
2. 抓取我的 Notion 所有頁面（搜尋所有 page 和 database 類型）
3. 每個頁面儲存以下資料：
- id（Notion UUID）
- title（標題）
- source（固定值 "notion"）
- last_edited_time
- created_time
- url（Notion 頁面網址）
- database_name（所屬資料庫名稱）
- properties（頁面的所有屬性值）
- text_content（純文字內容，從 blocks 擷取）
- attachments（圖片和 PDF 的本地路徑）
- content_hash（md5，用於增量偵測）
4. 增量同步邏輯：
- 比對 last_edited_time，沒變動的頁面跳過
- 新頁面才下載附件
5. 圖片和 PDF 附件下載到 attachments/images/ 和 attachments/pdfs/
6. 結果存為 sync/data/pages.json
7. API 速率保護：每次請求之間 sleep(0.5)，每批 10 頁
重要注意事項：
- Notion parent type 有時是 "data_source_id"（不是 "database_id"），兩種都需要處理
- 建立 database_names.json 快取，記錄 database_id → 名稱的對應，減少重複 API 呼叫
- 同步完成後印出統計：總頁面數、文字頁面數、下載附件數
請同時建立一個簡單的測試腳本，讓我可以先測試 API Token 是否有效。
```
**驗收**：執行後 pages.json 出現資料，確認有你的 Notion 頁面標題。
---
### Phase 3：語意向量資料庫
**完成這個 Phase 之後**：pages.json 的所有內容會被向量化，存入 Qdrant，可以做語意搜尋。
```
Notion 同步腳本已完成（Phase 2），pages.json 已有資料。
請建立 embeddings/build_vector_db.py，功能如下：
1. 使用 sentence-transformers 的 paraphrase-multilingual-MiniLM-L12-v2 模型
（支援中英混雜，384 維向量）
2. 建立本地 Qdrant 資料庫（存在 qdrant_data/ 資料夾），Collection 名稱 "notion_pages"，
使用 Cosine 相似度
3. 為每個頁面建立 combined_text（供向量化用）：
標題 + 屬性摘要（屬性名稱: 屬性值） + 文字內容前 1000 字
如果有 image_descriptions（圖片 AI 描述），也納入
如果有 pdf_texts（PDF 文字），也納入
4. Qdrant payload（必須包含以下欄位，之後搜尋時需要）：
- id（頁面 UUID）
- title（標題）
- source（"notion" 或 "wordpress"）
- database_name（所屬資料庫名稱）
- url（頁面連結）
- property_summary（屬性摘要，搜尋結果顯示用）
5. 分批處理，batch_size = 32（記憶體保護，不要改大）
6. 支援增量更新：已存在且內容未變的跳過
重要注意事項：
- qdrant-client 1.12 以上已棄用 search()，改用 query_points() API
- Collection 不存在時自動建立
- 完成後印出統計：向量總數、本次新增數
請同時建立 embeddings/verify_index.py，讓我可以輸入關鍵字測試搜尋是否正常。
```
**驗收**：執行 `verify_index.py`，輸入任意關鍵字，能搜到相關頁面。
---
### Phase 4：MCP Server
**完成這個 Phase 之後**：Claude Desktop 可以透過 MCP 協定，呼叫兩個工具查詢你的知識庫。
```
向量資料庫已建好（Phase 3）。
請建立 mcp_server/server.py，這是一個 MCP Server（stdio 模式），提供兩個工具：
工具一：search_knowledge
- 功能：語意搜尋，返回最相關的頁面（預設 top 5）
- 輸入參數：query（搜尋詞），top_k（返回數量，預設 5）
- 使用 Qdrant query_points() 搜尋
- 返回格式：
[1] 頁面標題 📔 Notion / 📝 WordPress（根據 source 欄位）
資料庫：所屬資料庫名稱
屬性摘要（如果有）
相關度：0.XX
網址：https://...
- 搜尋結果顯示 📔 Notion 或 📝 WordPress 來源標示
工具二：get_page_content
- 功能：根據頁面 ID 取得完整內容
- 輸入參數：page_id
- 返回：頁面標題 + 所有文字內容 + 圖片本機路徑（最多 5 張）
- 圖片會同時用 os.startfile() 在 Windows 自動彈開（Claude Desktop 不支援在對話視窗渲染圖片）
重要注意事項：
- MCP Server 使用 stdio 模式，所有 print() 和 log 必須輸出到 stderr
（print("...", file=sys.stderr)），絕不能輸出到 stdout，
否則會汙染 MCP JSON 通訊導致 Claude Desktop 無法讀取
- 使用 mcp 套件，工具定義使用 @server.call_tool() 裝飾器
請同時建立 mcp_server/claude_desktop_config.json，
內容是 Claude Desktop 的 MCP 設定，讓我知道要貼到哪裡。
```
**驗收**：重啟 Claude Desktop，在設定 → MCP Server 確認你的 server 出現，並對 Claude 問一個問題，確認它會呼叫 search_knowledge。
這邊我還有去claude desktop的個人設定(setting)敘述如何調用知識庫工具，內容如下:
## 本地知識庫 MCP 使用規則
當我說查找我知識庫資料的時候, 請使用本地端MCP ( local-rag-knowledge)來執行查詢
我有一個本地端 Notion RAG 知識庫，透過 MCP 連接，有三個工具：
**工具一：search_knowledge（語意搜尋）**
用途：找「跟某主題相關的內容」、筆記、想法、文章
範例：「我有沒有讀過關於投資心理的書」、「跟咖啡相關的記錄」
**工具二：query_properties（精準屬性篩選）**
用途：找「符合某條件的項目」，凡是涉及以下條件一律用這個：
- 位置（例：淑娟電腦、世傑電腦、世傑隨身）
- 狀態（使用中、備用、退役）
- 閱讀狀態（Reading、Finished、排隊中）
- 廠牌、購買通路、分類
- 日期範圍、金額大小比較
**工具三：get_page_content（取得完整頁面內容與附件圖片）**
用途：取得某頁面的完整內容，包含文字、屬性、以及原始圖片附件
使用時機：
- 找到頁面後想看詳細內容或圖片
- 使用者問「能看到圖片嗎」、「有附件嗎」、「詳細內容是什麼」
- 需要判讀圖片內容（產品圖、截圖、掃描文件等）
注意：最多回傳 5 張圖片，需要先有 page_id 才能呼叫
**使用原則：**
- 問「XX有哪些設備/物品」→ query_properties，key=位置
- 問「我買了哪些XX牌的東西」→ query_properties，key=廠牌
- 問「讀完的書有哪些」→ query_properties，key=閱讀狀態
- 問「某筆記說了什麼」→ search_knowledge
- 問「這個頁面的圖片/附件是什麼」→ get_page_content
- 不確定時，優先用 query_properties，沒結果再用 search_knowledge
- 需要圖片或完整內容時，先用前兩個工具找到 page_id，再用 get_page_content 取得
當我說「查找我知識庫資料」，請使用本地端 MCP（local-rag-knowledge）執行查詢。
---
### Phase 5：SQLite 精準屬性篩選
**完成這個 Phase 之後**：多了一個資料庫專門處理精確條件查詢（指定狀態、分類、標籤等）。
```
MCP Server 基礎版已完成（Phase 4）。
要新增 SQLite 精準屬性篩選功能，請做以下事情：
1. 建立 sync/sqlite_sync.py：
- 建立 SQLite 資料庫 notion_properties.db
- Table 結構：
pages 表（page_id, title, database_name, source, url, last_edited_time）
page_properties 表（page_id, property_name, property_value, property_type）
- upsert_page()：更新頁面基本資料
- upsert_properties()：更新屬性值（先刪後寫）
- delete_removed_pages()：刪除已移除的頁面
2. 建立 sync/build_sqlite_from_json.py：
一次性從 pages.json 建立完整 SQLite（初始化用）
3. extract_property_value() 函數，支援以下 Notion 屬性類型：
title, rich_text, select, multi_select, number, date, url, checkbox, email, phone_number
4. 修改 notion_sync.py，在同步完成後自動寫入 SQLite
5. 修改 mcp_server/server.py，新增第三個工具：
工具名稱：query_properties
功能：支援條件篩選，例如：
- 「閱讀清單裡狀態是 Finished 的書」
- 「金額超過 5000 的支出」
- 「WordPress 部落格的所有文章」
輸入：自然語言條件，轉成 SQL WHERE 條件
重要注意事項：
- Notion parent 有時 type = "data_source_id"（不是 "database_id"）
兩種情況都要能正確提取 database_id
```
**驗收**：執行 `build_sqlite_from_json.py`，然後在 Claude Desktop 問「我的閱讀清單有哪些書」確認 query_properties 工具有被呼叫並返回結果。
---
### Phase 6：圖片 AI 描述 + 圖片自動開啟
**完成這個 Phase 之後**：Notion 裡的圖片可以被語意搜尋找到；呼叫 get_page_content 時，圖片會自動用 Windows 預設程式彈開給你看。
> **重要說明**：Claude Desktop 收到 MCP 工具回傳的 `ImageContent` 時，Claude 自己（AI）確實看得到圖片並可以描述，但對話視窗**不會把圖片渲染出來給使用者看**。解決辦法是讓 MCP Server 在回傳圖片的同時，呼叫 `os.startfile()` 自動用 Windows 預設程式開啟圖片。
```
SQLite 已完成（Phase 5），本機已安裝 Ollama 並拉好 llava-phi3 模型。
請建立 embeddings/process_images.py：
1. 掃描 attachments/images/ 資料夾的所有圖片
2. 對每張圖片呼叫本機 Ollama API（llava-phi3 模型），請它用中文描述圖片內容
3. 描述結果存回 pages.json 對應頁面的 image_descriptions 欄位
4. 增量處理：已有描述的圖片跳過，節省時間
重要注意事項 1（這是一個容易踩到的坑）：
Notion 下載的圖片，副檔名可能是 .png，但實際格式是 WEBP。
直接把 WEBP 格式的圖片送給 Ollama 會報錯。
解決方法：先用 Pillow 的 Image.open() 偵測真實格式（檢查 img.format），
如果不是 JPEG 或 PNG，就先轉成 JPEG 再送給 Ollama。
重要注意事項 2：
如果 Ollama 沒有在跑，跳過圖片描述，不要讓程式崩潰。
請同時修改 mcp_server/server.py 的 get_page_content 工具：
- 頁面有 attachments 時，從本地讀取圖片檔案
- 用 ImageContent 型別（base64）回傳圖片（Claude AI 可看到並描述），最多 5 張
- 回傳每張圖片時，同步呼叫 os.startfile(local_path)，自動用 Windows 預設程式開啟
- 在回應文字末尾附上每張圖片的本機絕對路徑（使用者可手動開啟備用）
【os.startfile() 的效果】：等同使用者在 Windows 資料夾裡雙擊圖片，
會用預設看圖程式（Windows Photos 等）自動彈開，使用者立刻看到圖片，
不需要自己去找資料夾。
```
**驗收**：執行 `process_images.py` 後，在 Claude Desktop 說「把 [某有圖片的頁面] 完整給我看」，確認：
1. Claude 對話框出現「已自動開啟 X 張圖片」的訊息
2. Windows 看圖程式自動彈出，圖片顯示正常
---
### Phase 7：每日自動排程（Windows）
**完成這個 Phase 之後**：系統每天凌晨 3 點自動同步，早上起來知識庫已是最新狀態。
```
所有核心功能已完成（Phase 1-6）。
請建立自動排程：
1. 建立 scripts/daily_sync.bat，依序執行 5 個步驟：
[1/5] 設定路徑和記錄開始時間
[2/5] 執行 Notion 增量同步（sync/notion_sync.py）
[3/5] 擷取 PDF 文字（embeddings/process_pdfs.py）
[4/5] AI 圖片描述（embeddings/process_images.py）
[5/5] 重建向量資料庫（embeddings/build_vector_db.py）
- 每個步驟失敗都記錄到 logs/sync_YYYYMMDD.log
- 全部完成後寫入 logs/last_sync_status.txt（包含 SUCCESS/FAILED 和時間）
- 執行 build_vector_db.py 之前，先用 taskkill 關閉所有 python.exe
（因為 Qdrant 被 MCP Server 佔用時無法重建）
2. 建立 scripts/setup_scheduler.bat：
使用 Windows schtasks 設定每天凌晨 3:00 執行 daily_sync.bat
（提示：schtasks /create /tn "NotionSync" /tr "..." /sc DAILY /st 03:00）
執行 setup_scheduler.bat 完成排程設定後，
教我如何確認排程有沒有設定成功（Windows 工作排程器查看方式）。
```
**驗收**：Windows 工作排程器裡看到 "NotionSync" 任務，狀態為「就緒」。手動執行一次 daily_sync.bat，確認 last_sync_status.txt 出現 SUCCESS。
---
### Phase 8：PDF 文字擷取
**完成這個 Phase 之後**：Notion 附件裡的 PDF 內容也會被索引，可以被語意搜尋找到。
```
每日排程已完成（Phase 7）。
請建立 embeddings/process_pdfs.py：
1. 掃描 attachments/pdfs/ 的所有 PDF 檔案
2. 使用 PyMuPDF（import fitz）擷取每個 PDF 的純文字
3. 把文字存回 pages.json 對應頁面的 pdf_texts 欄位（是個 list，每個元素一個 PDF 的文字）
4. 增量處理：已有 pdf_texts 的頁面跳過
請確認 build_vector_db.py 在建立 combined_text 時，也把 pdf_texts 的內容納入向量化。
安裝指令：venv\Scripts\pip.exe install PyMuPDF
```
**驗收**：執行後，對 Claude 問「我有沒有關於 [你某個 PDF 的主題] 的資料」，確認搜尋結果出現 PDF 相關內容。
---
### Phase 9：WordPress 部落格同步（選配）
**完成這個 Phase 之後**：你的 WordPress 部落格文章也會進入知識庫，可以和 Notion 筆記一起搜尋。
> 只有 WordPress 部落格才適用。其他部落格平台需要調整 API 呼叫方式。
```
Notion RAG 系統已完成（Phase 1-8），現在要把 WordPress 部落格一起納入。
我的 WordPress 網址：[填入你的 WordPress 網址]
請建立 sync/wordpress_sync.py：
1. 呼叫 WordPress REST API 抓取所有已發布文章：
GET https://你的網址/wp-json/wp/v2/posts?per_page=100&status=publish&_embed=1
（_embed=1 可以一次拿到分類、標籤、特色圖片，不需要額外 API）
2. 每篇文章轉成以下格式（與 Notion pages 相容）：
- id：使用 uuid.uuid5(uuid.NAMESPACE_URL, "https://你的網址/?p={post_id}")
（確定性 UUID，同一篇文章每次 ID 相同，且不與 Notion UUID 衝突）
- source："wordpress"
- title：文章標題
- database_name："WordPress部落格"（固定值）
- last_edited_time：modified_gmt + "Z"（用於增量偵測）
- text_content：用 BeautifulSoup 把 HTML 轉成純文字
- properties：包含分類、標籤、發布日期、文章連結
- attachments：特色圖片 + 內文圖片（最多 5 張，下載到 attachments/images/wp_{id}_{n}.jpg）
3. pages.json merge 策略：
- 讀取現有 pages.json，把 WordPress 文章（source == "wordpress"）和 Notion 分開
- 更新 WordPress 部分
- 合併後存回 pages.json（Notion 頁面完整保留，不刪除）
4. 同步寫入 SQLite
5. 建立 sync/sync_all.py，統一入口：先跑 notion_sync，再跑 wordpress_sync
重要注意事項（避免踩坑）：
- 修改 notion_sync.py 的 delete_removed_pages()：
加入保護邏輯，把 SQLite 裡所有 database_name='WordPress部落格' 的頁面 ID，
加進「不刪除」的保護清單，避免 Notion 同步時誤刪 WordPress 頁面。
- 修改 notion_sync.py 的 load_existing_data() 和 save_results()：
load 時把 source != "notion" 的頁面分開保存到 self._preserved_pages；
save 時把 self._preserved_pages 一起合回去存檔。
（否則每次 Notion 同步後，WordPress 頁面會消失，下次 WordPress 同步就要重抓全部）
- 修改 build_vector_db.py，Qdrant payload 加入 source 和 database_name 欄位
（否則 Claude 無法區分 Notion 和 WordPress 的搜尋結果）
- 修改 mcp_server/server.py：
搜尋結果根據 source 欄位，在標題後加上 📝 WordPress 或 📔 Notion 標示
- 修改 scripts/daily_sync.bat 的 [2/5]，改成執行 sync_all.py
請說明安裝 beautifulsoup4 的指令，以及如何驗收（100 篇全部可以搜尋到）。
```
**驗收**：重建向量庫後，對 Claude 說「我部落格裡有哪些讀書心得文章」，確認搜尋結果出現 📝 WordPress 標示的文章。
---
## 常見問題 & 踩坑清單
以下是建置過程中容易遇到的問題，提前知道可以省很多時間：
### 坑 1：圖片副檔名是 .png，但實際是 WEBP 格式
- **症狀**：process_images.py 跑完一大堆錯誤，圖片描述一片空白
- **原因**：Notion 下載的圖片有時副檔名是 .png，但實際格式是 WEBP，Ollama 不接受
- **解法**：用 Pillow 的 `Image.open()` 偵測真實格式，不是 JPEG/PNG 就先轉換再送
### 坑 2：向量庫重建時報「Qdrant 被鎖定」
- **症狀**：執行 build_vector_db.py 報錯，說資料庫被佔用
- **原因**：Claude Desktop 開著時，MCP Server (python.exe) 還在跑，Qdrant 被鎖住
- **解法**：重建向量庫前先執行 `taskkill /IM python.exe /F` 關閉所有 Python 程序
### 坑 3：MCP Server 啟動後 Claude Desktop 沒有反應
- **症狀**：Claude Desktop 重啟後，問問題 AI 不呼叫任何工具
- **原因 A**：server.py 裡有 print() 輸出到 stdout，汙染了 MCP JSON 通訊
- **解法 A**：所有 log 改成 `print("...", file=sys.stderr)`
- **原因 B**：Claude Desktop config.json 路徑填錯
- **解法 B**：確認 config.json 的 python 路徑和 server.py 路徑都是絕對路徑
### 坑 4：WordPress 文章搜尋只出現少數幾篇
- **症狀**：明明同步了 100 篇，搜尋只找到 3-5 篇
- **原因**：Qdrant payload 沒有 source 和 database_name 欄位
- **解法**：確認 build_vector_db.py 的 payload 包含 `source` 和 `database_name` 欄位
### 坑 5：每天同步後，WordPress 文章全部重新下載
- **症狀**：每次凌晨同步都要跑 100 次 API，花很多時間
- **原因**：notion_sync.py 的清理邏輯把 WordPress 頁面從 pages.json 刪掉
- **解法**：在 notion_sync.py 加入 `_preserved_pages` 機制保留 WordPress 頁面
### 坑 6：Notion Integration 設定後仍讀不到資料
- **症狀**：同步程式跑完但頁面數是 0
- **原因**：Notion Integration 需要手動連結到每個 database
- **解法**：進每個 Notion Database → 右上角「...」→「連結到」→ 選你建立的 Integration
---
## 驗收清單
完成全部建置後，用以下問題測試你的知識庫：
**語意搜尋測試（search_knowledge）**
- [ ] 「有沒有關於時間管理的筆記？」→ 出現相關頁面
- [ ] 「讀書心得有哪些？」→ 出現結果，WordPress 文章有 📝 標示
**精準篩選測試（query_properties）**
- [ ] 「我的閱讀清單裡狀態是 Finished 的書有哪些？」→ 返回精確清單
- [ ] （如有 WordPress）「WordPress 部落格的所有文章」→ 返回完整清單
**完整內容測試（get_page_content）**
- [ ] 在搜尋結果後說「把第一篇完整給我看」→ 返回全文
- [ ] （如果該頁面有圖片）Claude 回應出現「已自動開啟 X 張圖片」，Windows 看圖程式自動彈開
**自動同步測試**
- [ ] logs/last_sync_status.txt 顯示 SUCCESS
- [ ] 修改一篇 Notion 筆記後，第二天早上搜尋能找到更新後的內容
---
## 後記
整套系統建完之後，你有一個每天自動維護的私人知識庫。
Notion 和部落格的累積，不再是搜不到、找不到的死資料，
而是可以對話、可以整合、可以跨來源查詢的第二大腦。
建置過程中遇到問題很正常——把問題描述清楚，貼給 Claude Code，
通常幾分鐘內就能找到根因並修好。
---
*複製指南版本：2026-02-27*
*對應系統版本：Phase 9（Notion + WordPress 完整整合）*
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet