物理知識庫專案
用 Claude Code（Opus 4.5）將高中 108 課綱物理教材的全圖掃描 PDF 轉化為原子化增強筆記，搭配 qmd 混合搜尋 + agentic flow，建構能夠協助學生解題、詢問概念、幫助老師出題的知識系統。
目的
驗證 qmd 原子化筆記方案 在教育場景的可行性。具體目標：
- 學生端：輸入物理問題 → 系統精準回答，附帶概念解釋和相關題目
- 老師端：指定概念和難度 → 系統從知識庫生成或推薦題目
- 技術驗證：證明「LLM 增強筆記 + qmd + agentic flow」在回答品質上可行
- OJT 連結：作為 115 OJT 創新專案 的技術路線驗證（qmd vs RAG）
架構
全圖掃描 PDF
│
▼ Claude Code (Opus 4.5, multimodal 讀取)
│
原子化增強筆記 (Markdown + 連結)
│
▼ qmd collection add + qmd embed
│
混合索引 (BM25 關鍵字 + 向量語意 + LLM re-ranking)
│
▼ 使用者提問 → qmd query → Agent 讀取 → 沿 連結 擴展 context → 回答
資料夾結構
~/Documents/physics-kb/
├── CLAUDE.md # 專案指令（建構模式 + 查詢模式）
├── notes/
│ ├── concepts/ # 概念筆記（定律、理論、現象）
│ ├── scientists/ # 人物筆記（科學家）
│ ├── formulas/ # 公式筆記（方程式、計算）
│ ├── applications/ # 應用筆記（半導體、雷射、光纖...）
│ ├── questions/ # 題目筆記（每題一檔）
│ └── moc/ # 章節地圖
├── templates/ # 六種模板
├── attachments/ # 從 PDF 提取的圖片
├── sources/ # 原始 PDF（或 symlink）
└── scripts/
└── index.sh # qmd add + embed 腳本
框架與技術選擇
為什麼選 qmd + 原子化筆記，不選 Graph RAG
| 比較項 | qmd + 原子化筆記 | Graph RAG |
|---|---|---|
| 內容與關聯 | 合一（連結 在筆記正文中） | 分離（原文 chunk + 知識圖譜分開維護） |
| 建構成本 | LLM 跑一次（產出筆記） | LLM 跑多次（entity/relation extraction, resolution, summarization） |
| 維護成本 | 改 .md → 重跑 qmd add + qmd embed | 改原文 → 重建 chunk + 重建圖譜 + 重建 mapping |
| Agentic flow | 天然支援（筆記中的 連結 就是遍歷路徑） | 不支援（原文 chunk 裡沒有連結資訊） |
| 可讀性 | Obsidian / 任何編輯器直接閱讀 | 需要 Neo4j 介面或自建前端 |
| 回答品質 | 取決於筆記品質（LLM 增強過的精華） | 取決於 chunk 品質（原文切片） |
核心原則：內容品質勝過檢索技術。把算力前置投入在高品質筆記建構，而非後期用複雜架構補救。
技術棧
| 層級 | 技術 | 用途 |
|---|---|---|
| 筆記生成 | Claude Code + Opus 4.5 (multimodal) | 讀取掃描 PDF → 產出原子化增強筆記 |
| 搜尋引擎 | qmd | BM25 + 向量 + LLM re-ranking |
| 本地推論 | qmd 內建 GGUF 模型（via node-llama-cpp） | embedding（300MB）+ reranker（640MB）+ query expansion（1.1GB），首次使用自動下載至 ~/.cache/qmd/models/ |
| 查詢回答 | Claude Code | 接收問題 → qmd query → 讀筆記 → 沿連結擴展 → 回答 |
| 編輯 | Obsidian / 任何文字編輯器 | 人工校驗筆記 |
關鍵設計決策
| 決策 | 選擇 | 理由 |
|---|---|---|
| 題目顆粒度 | 每題一檔 | qmd 不怕檔案多；分組會傷害檢索精確度；出題場景需要精準命中 |
| 跨領域人物 | 一人一筆記 | 人物是天然知識單元；筆記內按領域分段並用 連結 指向概念 |
| CLAUDE.md 模式 | 建構 + 查詢合一 | MVP 階段需要緊密迭代：建完筆記 → 馬上提問測試 → 發現缺漏 → 補上 |
| 公式表示法 | LaTeX + 純文字描述雙寫 | LaTeX 供人讀；純文字描述供 qmd BM25 搜尋 |
| 圖片處理 | 提取圖檔 + 文字等效描述 | qmd 是文字搜尋；圖片必須有等效文字描述才能被檢索到 |
五種筆記類型
1. 概念筆記 (type/concept)
定律、理論、現象。例：光的波粒二象性、萬有引力定律、日心說。
tags: [type/concept, topic/*, chapter/*, difficulty/*, status/*]
prerequisites: ["背景概念"] # 理解此概念需先懂什麼正文：定義 → 背景知識連結 → 詳細說明 → 常見錯誤（LLM 增強）→ 相關概念連結 → 相關題目連結
2. 人物筆記 (type/scientist)
科學家。例：牛頓、伽利略、愛因斯坦。一人一筆記，跨領域用分段 + 連結處理。
tags: [type/scientist, topic/* (多個), era/*, status/*]
lifetime: "1642-1727"
nationality: 英國
fields: [力學, 光學, 天文學]正文：生平 → 按領域分段列貢獻（每項連結到概念筆記）→ 歷史地位 → 相關人物連結
3. 公式筆記 (type/formula)
方程式、計算公式。例：質能互換公式、百分誤差公式。
tags: [type/formula, topic/*, chapter/*, difficulty/*, status/*]正文：LaTeX 公式 → 純文字描述（供搜尋）→ 變數定義表 → 物理意義 → 應用場景連結 → 計算範例 → 易錯點
4. 應用筆記 (type/application)
物理技術的實際應用。例：半導體/IC、雷射、光纖、超導體、核能發電。
tags: [type/application, topic/*, chapter/*, status/*]正文：定義 → 物理原理連結 → 結構與運作 → 圖表描述 → 發展歷史 → 日常生活應用 → 相關應用連結
5. 題目筆記 (type/question)
每一道例題和類題。每題獨立一檔。
tags: [type/question, topic/*, chapter/*, difficulty/*, question-type/*, source/108-textbook, status/*]
tests_concepts: ["被測試的概念"]
answer: "答案"正文：題目 → 選項 → 答案 → 解析（逐選項分析 + 概念連結）→ 解題策略（LLM 增強）→ 相似題目連結
6. MOC 章節地圖 (type/moc)
每章一個索引，組織所有筆記的入口。
標籤系統
# 類型
type/concept | type/scientist | type/formula | type/application | type/question | type/moc
# 物理主題
topic/astronomy | topic/mechanics | topic/optics | topic/thermodynamics
topic/electromagnetism | topic/modern-physics | topic/measurement | topic/technology
# 章節
chapter/1-1 (物理學簡史) | chapter/1-2 (物理學對人類生活的影響) | chapter/1-3 (物理學與測量)
# 難度
difficulty/basic (記憶、定義) | difficulty/intermediate (理解、應用) | difficulty/advanced (分析、綜合)
# 題型
question-type/multiple-choice | question-type/fill-in-blank | question-type/calculation
# 來源
source/108-textbook
連結設計——Agentic Flow 的骨架
每則筆記至少三個方向的連結，讓 agent 能沿 [[]] 逐步擴展 context：
| 方向 | 用途 | 範例 |
|---|---|---|
| 向上 (prerequisites) | 理解此概念需先懂什麼 | 光的波粒二象性 → 光的波動說, 光的粒子說 |
| 平行 (related) | 同層級相關概念 | 萬有引力定律 → 克卜勒行星運動三大定律 |
| 向下 (applied_in / tested_by) | 被用在哪、被哪題考 | 全反射 → 光纖通訊, Q-光纖全反射判斷 |
Agent 遍歷範例：
- 學生問「光纖為什麼能傳輸訊號？」
- qmd 搜尋 → 找到
光纖通訊 - Agent 讀到「物理原理：
全反射、折射定律」 - 判斷需要解釋原理 → 再搜尋
全反射 - 全反射筆記有公式、條件、常見錯誤
- 組合 context → 生成完整回答
Generation Pipeline
建構流程
- 輸入：使用者在專案 Claude Code 中貼 PDF 路徑
- 讀取：Claude (multimodal) 讀取掃描 PDF 所有頁面
- 識別：列出所有知識單元清單（概念、人物、公式、應用、題目），讓使用者確認
- 生成：一次生成所有筆記（確保
連結一致性） - 校驗：人工檢查公式 LaTeX、歷史年代、連結指向
- 索引：
qmd collection add notes/ --name physics --mask "*.md" && qmd embed（首次）或qmd update && qmd embed（更新）
公式處理
Claude multimodal 直接從掃描圖片「看」到公式。每個公式三層表達：
- LaTeX：
$$E = mc^2$$ - 純文字：能量等於質量乘以光速的平方
- 變數表：markdown table 列出每個變數意義和單位
圖片處理
- 從 PDF 提取圖片存入
attachments/ - 筆記中嵌入：
![[光纖截面圖.png]] - 必須附詳細文字描述（qmd 看不到圖片，只能搜文字）
- 樹狀圖直接轉為 markdown 結構
Agentic Flow CLI 實作
目的
將 Phase 4 手動測試中「Claude Code 接收問題 → 搜尋 → 讀筆記 → 沿連結擴展 → 回答」的流程自動化為獨立 CLI 工具，不依賴 Claude Code session。
bun run src/index.ts "光纖為什麼能傳輸訊號？"架構
Question
→ Haiku 拆解搜尋關鍵字（extractKeywords）
→ Search（grep / qmd search / vsearch / query，依 .env 設定）
→ 讀取筆記 + 提取 連結
→ Judge：context 足夠嗎？
├─ No → 讀取建議的 連結 筆記 → 回到 Judge（最多 5 輪）
└─ Yes → Generate 答案
→ Verify：答案品質檢查
├─ No → 補充搜尋 → 重新 Generate（僅一次 retry）
└─ Yes → 輸出最終答案
檔案結構
~/Documents/physics-kb/agent/
├── package.json
├── tsconfig.json
├── .env / .env.example
└── src/
├── index.ts # CLI 入口（stderr 日誌 + stdout 答案）
├── agent.ts # Agent loop 主體（state machine）
├── search.ts # 搜尋策略抽象（Strategy Pattern × 4 種實作）
├── notes.ts # 讀筆記、提取 連結、建立 title→path 索引
├── llm.ts # Anthropic API 封裝（4 個 prompt）
└── config.ts # .env 載入 + 型別定義
依賴：@anthropic-ai/sdk + gray-matter，共 2 個。Bun 原生支援 .env、glob、TypeScript。
Model 選擇
| 步驟 | Model | 理由 |
|---|---|---|
| extractKeywords | Haiku 4.5 | 簡單的關鍵字拆解，不需要強推理 |
| judge | Haiku 4.5 | 判斷 context 是否足夠 + 建議追蹤連結，結構化輸出 |
| generate | Haiku 4.5 | 根據已收集的筆記生成答案，context 品質比模型能力重要 |
| verify | Sonnet 4.5 | 品質把關需要更強的判斷力（見下方「Prompt 調整」） |
成本：每次問答 3× Haiku + 1× Sonnet ≈ $0.01，可接受。
搜尋策略
透過 .env 的 SEARCH_STRATEGY 切換，Strategy Pattern 實作：
| 策略 | 指令 | 特性 | 適用場景 |
|---|---|---|---|
grep | grep -rl | 即時、全量召回、關鍵字精確匹配 | 預設，最穩定 |
search | qmd search | BM25，單詞搜尋（多詞有 AND 匹配問題） | 需要 BM25 排序時 |
vsearch | qmd vsearch | 向量語意搜尋 | 語意模糊的問題 |
query | qmd query | BM25 + 向量 + reranking | GPU 環境（CPU 太慢） |
Prompt 調整紀錄
問題：初版全用 Haiku，跨概念題目（如「密立坎油滴實驗跟原子模型的關係」）會混淆不同實驗、硬湊因果關係，且 Verify 判斷力不足，放過了錯誤。
調整：
- Generate prompt 加入：「嚴格區分不同的實驗/事件/理論」「資料不足以建立因果關係時誠實說明，不要硬湊」
- Verify 改用 Sonnet 4.5，加入：「檢查是否混淆不同概念」「因果關係是否有筆記支撐」
效果：調整後同一題目不再硬湊關聯，改為誠實回覆「筆記中未直接記載兩者的因果關係」，Sonnet Verify 判定此為合格回答。
測試結果
| 題目類型 | 範例問題 | Agent 行為 | 結果 |
|---|---|---|---|
| 概念題（單一概念） | 光纖為什麼能傳輸訊號？ | Search 15 篇 → Judge 1 輪即 sufficient → Verify PASS | ✅ 正確解釋全反射原理 |
| 概念題（開放） | 光的波粒二象性是什麼？ | Search 36 篇 → Judge 1 輪即 sufficient → Verify PASS | ✅ 涵蓋定義、實驗證據、歷史、常見錯誤 |
| 人物題 | 愛因斯坦有哪些重要貢獻？ | Search 45 篇 → Judge 1 不足 → 追蹤 愛因斯坦 原子模型演進 → Judge 2 sufficient → Verify PASS | ✅ 完整列出各領域貢獻 |
| 公式題 | 庫侖定律的平方反比是什麼意思？ | Search 46 篇 → Judge 1 輪即 sufficient → Verify PASS | ✅ 正確解釋 F∝1/r²，含常見錯誤提醒 |
| 跨概念題 | 密立坎油滴實驗跟原子模型的關係？ | Search 21 篇 → Judge 不足但無新連結 → Generate → Verify PASS（Sonnet 認可誠實回答） | ✅ 誠實說明筆記未記載因果，分別整理兩條脈絡 |
| 歷史演變題 | 從伽利略到牛頓的力學轉變？ | Search 6 篇 → Judge 1 不足 → 追蹤 4 篇 → Judge 2 仍不足但無更多筆記 → Generate → Verify PASS | ✅ 正確梳理亞里斯多德→伽利略→牛頓脈絡 |
關鍵觀察：
- 簡單概念題：Judge 一輪就夠，不需要連結追蹤
- 人物/歷史題：通常需要 1-2 輪連結追蹤來補充 context
- 跨概念題：當筆記本身對跨領域關聯描述不足時，agent 無法補救——此時「誠實說明不足」比「硬湊」更好
- grep 策略作為預設足夠穩定，搜尋速度快且召回率高
使用說明
環境需求
| 項目 | 需求 | 說明 |
|---|---|---|
| OS | Linux / macOS | Windows 未測試 |
| RAM | 8GB+ | qmd embed 需載入 embedding 模型（~300MB） |
| CPU | 任何 x86_64 | qmd query 的 reranking 在無 GPU 時很慢（~5 分鐘） |
| GPU | 非必要 | 有 GPU 可加速 qmd query |
| 磁碟 | ~500MB | notes + qmd 模型 + node_modules |
部署步驟
# 0. Clone repo
git clone https://github.com/echoedinvoker/physics-kb.git
cd physics-kb
# 1. 安裝 Bun（TypeScript runtime）
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
# 2. 安裝 qmd（搜尋引擎，必要依賴）
bun install -g github:tobi/qmd
# 3. 建立知識庫索引 + 向量嵌入（首次會自動下載 embedding 模型 ~300MB）
bash scripts/index.sh
# 4. 安裝 agent CLI 依賴
cd ~/Documents/physics-kb/agent
bun install
# 5. 設定 .env
cp .env.example .env
# 編輯 .env，填入 ANTHROPIC_API_KEY.env 設定說明
# 搜尋策略（必填）
SEARCH_STRATEGY=grep # 預設，最穩定
# SEARCH_STRATEGY=search # qmd BM25，需先跑 index.sh
# SEARCH_STRATEGY=vsearch # qmd 向量語意搜尋，需先跑 index.sh + qmd embed
# SEARCH_STRATEGY=query # qmd 全功能（BM25 + 向量 + reranking），CPU-only 很慢
# Anthropic API Key（必填）
ANTHROPIC_API_KEY=sk-ant-...
# Agent loop 控制（選填）
MAX_ITERATIONS=5 # Judge 最多迭代幾輪，預設 5
MAX_CONTEXT_NOTES=20 # context 最多放幾篇筆記，預設 20策略選擇建議：
- 日常使用 →
grep（即時、精確匹配） - 需要相關性排序 →
search（BM25） - 語意模糊的問題 →
vsearch（向量語意搜尋） - 有 GPU 的環境 →
query（最佳品質但最慢）
增加知識庫內容
方法 1：用 Claude Code 建構模式（批量生成）
# 在 physics-kb 目錄開啟 Claude Code
cd ~/Documents/physics-kb
claude
# 輸入指令觸發建構模式
> 處理教材：/path/to/教材.pdfClaude Code 會依照以下流程處理：
- 盤點現有筆記 — 掃描
notes/建立標題清單 - 讀取 PDF → 識別知識單元
- 跨章節比對 — 新清單與現有筆記比對，標記 🆕新增 / 🔄合併 / ⏭️跳過
- 確認清單 — 使用者確認每項的處理方式
- 生成 / 更新筆記 — 新建或合併到舊筆記（追加內容，不覆蓋）
- 回填連結 — 舊筆記中的空連結若被這次新建的筆記填補，自動回填
- 空連結報告 — 列出仍未解決的
連結
詳見 CLAUDE.md 的建構模式說明。
核心原則：筆記品質是整個系統的根基。每次新增章節時，必須與現有筆記建立正確的
連結，而非產出孤立的新筆記。
方法 2：手動新增筆記
- 從
templates/複製對應模板 - 用
date +%Y%m%d%H%M產生 ID 填入 frontmatter - 存入
notes/對應子目錄（concepts / scientists / formulas / applications / questions / moc） - 確保至少 3 個
連結（向上、平行、向下）
新增後更新索引
新增筆記後務必重新索引，確保所有搜尋策略都能找到新內容：
bash scripts/index.sh --update # 僅更新（較快）
bash scripts/index.sh # 完整重建（含 BM25 + 向量嵌入）發問方式
cd ~/Documents/physics-kb/agent
# 基本用法
bun run src/index.ts "你的物理問題"
# 範例
bun run src/index.ts "光纖為什麼能傳輸訊號？"
bun run src/index.ts "愛因斯坦有哪些重要貢獻？"
bun run src/index.ts "庫侖定律的平方反比是什麼意思？"
# 臨時切換搜尋策略（覆蓋 .env 設定）
SEARCH_STRATEGY=vsearch bun run src/index.ts "兩物體間的交互作用力"
# 輸出結構：
# stderr → agent loop 日誌（搜尋、Judge、連結追蹤過程）
# stdout → 最終答案（Markdown 格式）
#
# 可用 pipe 分離：
bun run src/index.ts "問題" 2>/dev/null # 只看答案
bun run src/index.ts "問題" > answer.md 2>&1 # 日誌到螢幕，答案存檔Chapter 1 預估筆記量
| 類型 | 數量 | 說明 |
|---|---|---|
| 概念 | ~15 | 日心說、地心說、萬有引力、運動定律、光的粒子說/波動說、熱力學定律… |
| 人物 | ~25 | 托勒密、哥白尼、伽利略、牛頓、愛因斯坦、法拉第、馬克士威… |
| 公式 | ~8 | 質能互換、百分誤差、絕對誤差、庫侖定律… |
| 應用 | ~6 | 半導體/IC、雷射、光纖、超導體、核能發電 |
| 題目 | ~80 | 例題 12 + 類題 ~68 |
| MOC | ~4 | 總覽 + 三個小節各一 |
| 合計 | ~138 |
規模化分析（1 章 → 25 章）
目前 Ch1 有 307 篇筆記。完整 20-25 章預估 6,000-7,500 篇。以下是已識別的瓶頸與處理狀態：
| 問題 | 嚴重度 | 狀態 | 說明 |
|---|---|---|---|
| grep 搜尋失去精準度 | 🔴 高 | 待處理 | grep 回傳無排序，7,000 篇時 slice(0,10) 取到的可能完全不相關。規模化後應改預設為 search（BM25 有排序），grep 退為標籤全量召回輔助 |
| buildNoteIndex 每次重掃 | 🟡 中 | ✅ 已修復 | 改為 JSON 快取（.note-index.json），index.sh 執行時清除快取，下次 agent 啟動自動重建 |
| 檔名碰撞 | 🟡 中 | ✅ 已修復 | NoteIndex 改為 title → path[]，碰撞時 stderr 警告並以啟發式規則選擇（優先非 question 筆記）。25 章下來需持續關注命名唯一性 |
| qmd embed 時間 | 🟢 低 | 可接受 | 7,000 篇的 embedding 建構時間會顯著增加，但為一次性操作 |
| qmd query CPU 效能 | 🟢 低 | 已有替代 | 無 GPU 環境已改用 search + vsearch 替代，不影響規模化 |
| LLM context window | 🟢 低 | 無需處理 | 20 篇 × 2000 chars = 40K chars，在 Haiku 200K window 內 |
Checklist
Phase 1：專案骨架
- 建立
~/Documents/physics-kb/目錄結構 - 撰寫 CLAUDE.md（定義建構模式與查詢模式）
- 建立六種筆記模板（concept, scientist, formula, application, question, moc）
- 撰寫
scripts/index.sh
Phase 2：工具安裝與驗證
- 安裝 Bun（
curl -fsSL https://bun.sh/install | bash） - 安裝 qmd（
bun install -g github:tobi/qmd）— 不需要 Ollama，qmd 自帶 GGUF 模型 - 驗證
qmd collection add/qmd embed/qmd search/qmd vsearch/qmd query
Phase 3：Chapter 1 筆記生成
實際盤點後筆記量為 ~335 則（原估 ~138），主要差異在科學家(55)和題目(~250)數量。分批生成。
3.1 讀取 PDF 與清單確認
- 讀取
~/Downloads/p1_01_small.pdf全部 44 頁 - 生成知識單元清單（概念22/人物55/公式10/應用5/題目~250/MOC4）
- 人工確認清單
3.2 批量生成——第一批：知識骨架（~93 則）
- 概念筆記 1-1（14 則：地心說～夸克理論）
- 概念筆記 1-3（7 則：測量與誤差～密度）
- 科學家——天文（4）：托勒密、哥白尼、第谷、克卜勒
- 科學家——力學（3）：亞里斯多德、阿基米得、伯努力
- 科學家——光學（7）：司乃耳、海更士、楊格、夫朗和斐、克希仁夫、菲左、佛科
- 科學家——熱學（5）：侖福特伯爵、卡諾、焦耳、克勞乃士、能士特
- 科學家——電磁學（13）：吉爾伯特～馬可尼
- 科學家——近代物理（21）：侖琴～蓋耳曼
- 科學家——跨領域（2）：伽利略、愛因斯坦（牛頓已存在）
- 公式筆記（9 則，質能互換公式已存在）
- 應用筆記（5 則：半導體、雷射、光纖、超導體、核能）
- MOC 筆記（4 則）
3.3 批量生成——第二批：題目（~250 則）
- 1-1 題目：物理史/力學/熱學（16 則）
- 1-1 題目：光學（11 則）
- 1-1 題目：電磁學（11 則）
- 1-1 題目：近代物理/原子/量子（21 則）
- 1-2 題目：半導體/雷射（16 則）
- 1-2 題目：光纖/超導體/核能（18 則）
- 1-3 題目：測量/有效數字/數量級（16 則）
- 1-3 題目：SI制/因次/時間（22 則）
- 1-3 題目：單擺/半衰期（16 則）
- 1-3 題目：長度/螺旋測微器/游標尺（21 則）
- 1-3 題目：三角測量/測遠儀/光學測微儀（14 則）
- 1-3 題目：體積/質量/密度（28 則）
3.4 校驗與索引
- 人工校驗（公式 LaTeX、歷史年代、連結指向）
- 從 PDF 提取圖片至
attachments/，補充文字描述 - 執行
bash scripts/index.sh建索引（307 則筆記） - 驗證
qmd search（BM25）基本可用 - 驗證
qmd vsearch（向量搜尋）基本可用 - 驗證
qmd query（combined：query expansion + reranking）— 修復 OOM 後通過
OOM 問題與修復：
qmd query同時載入三個 GGUF 模型（embedding 314MB + reranker 610MB + query expansion 1.2GB ≈ 2.1GB），在 7.5GB RAM 筆電上觸發 OOM 死當。根因：swap 為 zram（壓縮 RAM，非磁碟），swappiness=10。修復：建立 8GB btrfs swap file（btrfs filesystem mkswapfile）+ swappiness=60。修復後 query 正常運作。
Phase 4：查詢測試
測試策略：因
qmd query（reranking）在 CPU-only 筆電上太慢（~5 分鐘），改用qmd search（BM25）+qmd vsearch（向量）分開搜尋，由 Claude 判斷相關性。
- 學生場景：問概念問題（「什麼是全反射？」）
- 學生場景：問解題問題（「光速怎麼測量的？」）
- 老師場景：按概念搜題（「找所有電磁學選擇題」）
- 老師場景：要求出相似題（基於庫侖定律題目生成）
- 記錄失敗案例（見下方）
測試結果
| 場景 | 結果 | 問題 |
|---|---|---|
| 學生問概念（全反射） | ⚠️ 部分通過 | 缺少全反射概念筆記；BM25 多詞查詢零結果；連結追蹤淺（Q → 光纖通訊，無底層概念） |
| 學生問解題（光速測量） | ⚠️ 部分通過 | 找到菲左和相關題目；但菲左筆記太薄，未解釋旋轉齒輪法原理 |
| 老師按概念搜題（電磁學） | ❌ 召回率不足 | 實際 12 題，BM25 找到 3 題，vsearch 找到 5 題；標籤搜尋零結果 |
| 老師出相似題（庫侖定律） | ✅ 通過 | BM25 找到完整知識網（概念+公式+科學家+題目），context 充足 |
發現的問題
P1 — 跨章節概念缺口（預期行為，非 bug）：
- 全反射、折射定律等光學概念不在 Ch1 教材範圍，處理後續章節時自然補上
- 科學家筆記深度受限於教材提及的程度（如菲左在 Ch1 僅一句帶過）
P2 — BM25 多詞搜尋失敗（檢索問題）：
- 「全反射 原理 條件」「topic/electromagnetism question-type/multiple-choice」等多詞查詢零結果
- BM25 似乎做 AND 匹配，需用單詞搜尋
P3 — 按標籤搜題召回率低（檢索問題）：
- 老師場景需要「找出所有某主題的題目」，qmd search/vsearch 都無法保證全量召回
- 可能需要 grep 標籤作為補充手段，或在查詢模式中加入
grepfallback
P4 — qmd query 在無 GPU 筆電上不實用（效能問題）：
- Reranking 25 份文件需 ~5 分鐘（CPU-only）
- 改用 search + vsearch 分開跑 + Claude 判斷相關性作為替代方案
Phase 5：迭代優化
- P1：跨章節概念缺口是預期行為，處理後續章節時自然補上，不需額外動作
- P2/P3 修復：查詢模式改為三層搜尋策略（vsearch + search 單詞 + grep 標籤），grep 保證全量召回
- P4：qmd query 在無 GPU 筆電不實用，已改用 search + vsearch 替代，不需額外動作
重新索引並重測— 筆記內容未變動，索引有效，不需要- 撰寫驗證報告：實驗：qmd 原子化筆記方案驗證（物理 Ch1）
Phase 6：Agentic Flow CLI
- 建立
~/Documents/physics-kb/agent/專案骨架（package.json, tsconfig.json, .env） - 實作 config.ts（.env 載入 + 型別定義）
- 實作 notes.ts（readNote + extractWikilinks + buildNoteIndex）
- 實作 search.ts（Strategy Pattern × 4 種搜尋策略）
- 實作 llm.ts（4 個 prompt：extractKeywords / judge / generate / verify）
- 實作 agent.ts（agent loop state machine）
- 實作 index.ts（CLI 入口）
- 測試 6 種題型（概念 / 人物 / 公式 / 跨概念 / 歷史演變 / 開放問題）
- Prompt 調整：Generate 加入「不硬湊因果」規則，Verify 換 Sonnet 4.5
- 後續章節筆記建構完成後，重新測試跨章節概念題
Web Demo
詳見 物理知識庫 Demo。為 Agentic Flow CLI 做的瀏覽器介面（demo/server.ts + demo/index.html），支援即時思考過程串流、多輪對話、出題去重。
線上 Demo：https://physics-kb.fly.dev/（密碼保護，Fly.io 東京機房）
# 本地開發
cd ~/Documents/physics-kb/demo && ~/.bun/bin/bun run server.ts
# → http://localhost:3456
# 部署更新
cd ~/Documents/physics-kb && /home/matt/.fly/bin/flyctl deploy連結
- 優化：物理知識庫 Pipeline 優化專案
- GitHub：https://github.com/echoedinvoker/physics-kb
- 理論基礎：qmd 原子化筆記方案、內容品質勝過檢索技術、用 LLM 建構增強型知識筆記
- 工具：QMD 本地語義搜尋工具
- 文獻：Claude 對話 - 高中教材知識庫的 RAG 實現方案、RAG 與 Graph RAG 的本質差異
- OJT：115 OJT 創新專案
- 方法論：原子化筆記原則、連結優於分類