物理知識庫 Pipeline 優化專案

目標：系統性優化 note generation pipeline、formatter、retrieval、cross-chapter linking 四個環節，使 pipeline 能可靠地從 300 篇擴展到 7,500 篇，並在大規模知識庫下維持檢索精準度和新知識的連結效率 為什麼現在做：Ch1 驗證完成（307 篇，物理知識庫專案 action/done），OJT 3 月底檢核需要 3-4 章 demo。直接擴展會放大既有問題（預估偏差 2.2x、人工校驗未完成、grep 在大規模下失效）；先優化再擴展投入回報比最高 專案路徑：~/Documents/physics-kb/ 部署目標：本地 CLI + Fly.io Demo（physics-kb.fly.dev）

背景知識

現有系統架構

物理知識庫使用「原子化增強筆記 + qmd 混合搜尋 + agentic flow」架構：

全圖掃描 PDF (教科書)
    │
    ▼ Claude Opus 4.5 (multimodal)
    │
原子化增強筆記 (Markdown + wikilinks)
    │
    ▼ qmd collection add + qmd embed
    │
混合索引 (BM25 + 向量語意 + LLM re-ranking)
    │
    ▼ Agent CLI: 提問 → 搜尋 → Judge → 沿 連結 擴展 → 生成 → Verify

核心原則：內容品質勝過檢索技術。把算力前置投入在高品質筆記建構（Opus），查詢時用便宜模型（Haiku/Sonnet）。

Ch1 驗證結果（Baseline）

詳見實驗：qmd 原子化筆記方案驗證（物理 Ch1）。

指標	Ch1 實測值	說明
筆記產出量	307 篇 / 44 頁	原估 138，2.2x 偏差（科學家 55 篇、題目 ~210 篇超預期）
生成時間	~1 天	分兩批：知識骨架 93 + 題目 ~210
人工校驗	❌ 未完成	LaTeX 公式、歷史年代、連結指向仍待校驗
搜尋召回率	grep 100% / vsearch 42% / BM25 25%	「找所有電磁學選擇題」場景
Agent 正確率	6/6 題型通過	含 prompt 調整後（Verify 改 Sonnet、Generate 加「不硬湊」規則）
跨章節空連結	未統計	預計 Ch4 光學概念才能填補

四個優化目標

環節	現況問題	優化目標
Generation Pipeline	預估偏差 2.2x、人工校驗瓶頸、大章節可能撞 context window	預估偏差 <30%、自動化校驗、分批生成 SOP
Formatter（模板）	frontmatter 缺層級定位、部分筆記太薄（菲左）、沒為 metadata filtering 準備	schema 強化、自足性、context_header
Retrieval	grep 在 7,500 篇失效、無 metadata pre-filter、agent traversal 無限制	hybrid pipeline + metadata filter + traversal budget
Cross-chapter Linking	連結注入機制未驗證、空連結未統計、回填流程未實測	自動連結注入 + 回填 pass + known-missing registry

關鍵技術概念

Metadata Pre-filtering：在大規模知識庫中，先用 frontmatter 欄位（chapter, topic_path）篩選出相關子集（7,500 → ~500 篇），再跑語意搜尋。這是 production RAG 的標準做法，能同時提升精準度和速度。

Contextual Retrieval（Anthropic 提出）：為每個 chunk 前綴一段上下文摘要，改善 embedding 品質。Anthropic 論文報告 49% retrieval failure reduction。在原子筆記場景中，相當於在 frontmatter 加一個 context_header 欄位。

Hybrid Search：BM25（精確關鍵字）+ 向量搜尋（語意相似度）+ RRF fusion + re-ranking。qmd 的 search + vsearch 分開跑再合併，本質上就是 hybrid search。

MOC-first Routing：Agent 第一輪搜 MOC（章節地圖）→ 從 MOC 內容提取相關 topic_path → 後續搜尋限定在該範圍。兩層檢索比全域搜尋更精準（來自 115 OJT 創新專案的架構建議）。

qmd 搜尋策略現況

策略	指令	速度	適用	7,500 篇時
`grep`	`grep -rl`	即時	標籤全量召回	❌ 無排序，top-10 取到垃圾
`search`	`qmd search`	快	BM25 排序	⚠️ 中文多詞 AND 匹配失敗
`vsearch`	`qmd vsearch`	中	語意模糊	✅ HNSW 向量搜尋，sub-linear
`query`	`qmd query`	極慢	最佳品質	❌ CPU ~5 分鐘，無 GPU 不可用

Phase 0：環境重建

目標：在本機重建 physics-kb 開發環境，確認 Ch1 筆記完整性

0.1 Clone repo
- 指令：git clone https://github.com/echoedinvoker/physics-kb.git ~/Documents/physics-kb/
- 驗證：ls ~/Documents/physics-kb/notes/ | wc -l 應接近 307
- ✅ 307 篇確認
0.2 檢查筆記完整性
- 統計各子目錄筆記數：for d in concepts scientists formulas applications questions moc; do echo "$d: $(ls notes/$d/ 2>/dev/null | wc -l)"; done
- 預期：concepts ~22, scientists ~55, formulas ~10, applications ~5, questions ~210, moc ~4
- 若缺失嚴重 → 記錄到「問題與變更紀錄」，Phase 1 改為「重建 + 優化」合併
- ✅ 實際：concepts 22 / scientists 56 / formulas 10 / applications 5 / questions 210 / moc 4
0.3 重建 qmd 索引
- 指令：cd ~/Documents/physics-kb && bash scripts/index.sh
- 驗證：~/.bun/bin/qmd search "牛頓" 應回傳結果
- ✅ 307 篇索引完成，搜尋正常（注：qmd 需透過 wrapper script 呼叫 npx tsx）
0.4 Agent baseline 測試
- 指令：cd agent && ~/.bun/bin/bun install && cp .env.example .env（填入 ANTHROPIC_API_KEY）
- 測試：~/.bun/bin/bun run src/index.ts "庫侖定律的平方反比是什麼意思？"
- 預期：5-30 秒內回傳正確答案
- ✅ 正確回答，Judge sufficient + Verify PASS，引用庫侖定律公式+題目筆記
0.5 統計 Ch1 空連結
- 做法：提取所有 target → 比對 notes/ 實際檔案 → 列出 broken links
- 產出：broken-links-ch1.txt（供 Phase 4 使用）
- ✅ 18 個 broken links（1355 total links），多為跨章節概念（光學、力學、數學）

Phase 驗證：Agent CLI 能回答「庫侖定律的平方反比是什麼意思？」且答案引用正確筆記。

Phase 1：Formatter 優化（筆記模板與 frontmatter）

目標：重新設計筆記模板，讓 frontmatter 支援 metadata filtering、筆記自足性更強、embedding 品質更好。這是最高槓桿率的優化——模板變更影響所有後續筆記。

1A: Frontmatter Schema 強化

1.1 設計新 frontmatter schema
- 所有 5 種類型新增的共用欄位：

# 新增欄位（5 種類型共用）
chapter: "1-1"                           # 章節編號（已有 chapter/ tag，但 frontmatter 更利於程式 filter）
topic_path: "物理學/物理學簡史/天文學革命"  # 三層知識路徑，用於 metadata pre-filter
related_chapters: ["2-1", "3-2"]          # 跨章節關聯（生成新章節時填入）
context_header: "這是高一物理第一章..."    # ~50 tokens 上下文摘要，提升 embedding 品質

topic_path 開銷：~20 tokens/note × 7,500 = 150K tokens（可接受）
context_header 開銷：~50 tokens/note × 7,500 = 375K tokens（Anthropic 論文支持值得）
related_chapters 是跨章節連結自動化的關鍵欄位
1.2 定義 topic_path 層級結構
- 第一層：物理分支（力學 / 熱學 / 光學 / 電磁學 / 近代物理 / 測量）
- 第二層：主題（如力學/牛頓定律）
- 第三層：細分概念（如力學/牛頓定律/第二定律）
- 產出：topic-taxonomy.md（供生成 prompt 參考）
- ✅ 8 大分類、66 個三層路徑，涵蓋完整高一物理課程
1.3 更新 templates/ 下的 6 個模板
- 檔案：templates/{concept,scientist,formula,application,question,moc}.md
- ✅ 6 個模板均已加入 chapter, topic_path, related_chapters, context_header 欄位

1B: 筆記自足性強化

1.4 修改概念筆記模板：加「一句話定義」欄位
- 放在 frontmatter 下方、正文第一行
- 目的：讓 Agent 光讀 frontmatter + 第一行就能判斷相關性
- ✅ 模板原本就有 > 一句話定義此概念。，保留
1.5 修改生成 prompt：「詳細說明」段落不依賴 wikilink 就能獨立理解
- 反面範例：「其原理類似全反射」→ 如果全反射筆記不在 context 中，這句話沒有意義
- 正面範例：「其原理基於全反射——當光從較密介質射向較疏介質，入射角大於臨界角時，光完全反射回原介質（詳見全反射）」
- ✅ 已加入 CLAUDE.md 筆記生成規則的「自足性原則」
1.6 修改題目筆記模板：必須包含完整題目文字
- 禁止「見教材第 X 頁」
- ✅ 模板 placeholder 改為 {{FULL_QUESTION_TEXT}}，CLAUDE.md 加入禁止規則

1C: context_header 設計

1.7 設計 context_header 的生成 prompt
- 格式：「這是{grade}{subject}第{chapter}章「{section_name}」中關於{topic}的{type}筆記。{one_sentence_summary}。」
- 範例：「這是高一物理第一章「物理學簡史」中關於天文學革命的概念筆記。本筆記討論哥白尼的日心說如何取代托勒密的地心說，推動科學革命。」
- 生成時機：與筆記正文同批生成（不額外跑 LLM）
- ✅ 已寫入 CLAUDE.md 筆記生成規則
1.8 驗證 qmd embed 是否會將 frontmatter 納入向量
- 測試：建兩篇內容相同但 context_header 不同的測試筆記 → qmd vsearch 看哪篇排更高
- 如果 qmd 只 embed 正文 → 改為把 context_header 放在正文最前面（而非 frontmatter）
- ✅ 驗證結果：qmd embed 會將 frontmatter 納入向量。context_header 放 frontmatter 即可

Phase 驗證：6 個更新後的模板 + topic-taxonomy.md + context_header prompt 都就緒。

Phase 2：Generation Pipeline 優化

目標：讓每章的生成+校驗時間可預測、可自動化，並解決 context window 壓力

2A: 預估模型校正

2.1 建立預估公式（基於 Ch1 數據）
- Ch1 數據：概念 22（估 15, 1.5x）、人物 55（估 25, 2.2x）、公式 10（估 8, 1.25x）、應用 5（估 6, 0.83x）、題目 ~210（估 80, 2.6x）、MOC 4
- 校正公式：預估總量 = (概念 × 1.5 + 人物 × 2.2 + 公式 × 1.25 + 應用 × 1.0 + 題目 × 2.6 + MOC) × 1.1
- 此公式在 Ch2 生成後校正第二次
- ✅ 已寫入 CLAUDE.md 建構模式步驟 3

2B: 分批生成 SOP

2.2 文件化三層生成策略
- Tier 1：知識骨架（concepts + scientists + formulas + applications + MOC）
  - 按 section 分批（1-1, 1-2, 1-3），每批 ~30 篇，不撞 context window
  - 一批生成確保 section 內 wikilink 一致性
- Tier 2：題目
  - 按 section 分批，每批 ~20-30 題
  - prompt 注入 Tier 1 的 note title list（確保 tests_concepts 連結正確）
- Tier 3：跨章節連結回填
  - 新章節全部生成後，跑回填 pass（見 Phase 4）
- ✅ 已寫入 CLAUDE.md 建構模式步驟 6
2.3 設計 Tier 2 的 title 注入 prompt
- 格式：在 system prompt 附上 ## 已存在的筆記\n- 牛頓第一運動定律\n- 庫侖定律\n- ...
- 目的：LLM 生成題目時能正確引用已存在的概念筆記
- Token 估算：300 篇 × 20 chars/title ≈ 6K tokens（可接受）
- ✅ 已寫入 CLAUDE.md「Tier 2 Title 注入格式」

2C: 自動化校驗

2.4 寫 scripts/verify.sh
- 檢查項目：
  1. LaTeX 語法：偵測未閉合的 $$、不匹配的 $ $
  2. Frontmatter 完整性：所有必要欄位存在（依 note type 不同）
  3. Wikilink 完整性：所有 target 有對應 .md 或在 known-missing list 中
  4. Tag 一致性：所有 tag 符合 topic-taxonomy.md 定義
  5. 重複偵測：標題相同或 >90% 相似的筆記
- 產出：verify-report.txt（列出所有問題 + 建議修復）
- ✅ 五項檢查 + summary 統計，支援 known-missing 排除
2.5 跑 Ch1 現有 307 篇過 verify.sh
- 統計現有錯誤率，作為 baseline
- 識別哪些錯誤是模板問題（Phase 1 修）vs 內容問題（Phase 5 重寫時修）
- ✅ 307 篇：0 errors, 0 warnings, 21 broken links（全為跨章節概念）, 0 duplicates

2D: 更新 CLAUDE.md 建構模式

2.6 將 Phase 1 模板 + Phase 2 SOP + Phase 2C 校驗整合到 CLAUDE.md
- 建構模式的完整流程：讀 PDF → 識別知識單元 → 預估（用校正公式）→ 確認 → Tier 1 → Tier 2 → Tier 3 → verify.py → 手動校驗重點項目
- ✅ CLAUDE.md 建構模式已更新：預估公式(步驟3)、三層生成(步驟6)、title注入、自足性原則、context_header、verify.py(步驟10)

Phase 驗證：verify.sh 能跑在 Ch1 307 篇上並產出報告；CLAUDE.md 建構模式已更新。

Phase 3：Retrieval Scalability 優化

目標：確保 600-7,500 篇規模下 Agent 仍能在合理時間（<30 秒）內找到正確筆記

3A: Metadata Pre-filter

3.1 調查 qmd 是否原生支援 frontmatter metadata filter
- 測試：~/.bun/bin/qmd search --filter "chapter:1-1" "牛頓" 或類似語法
- 查 qmd GitHub README / source code
- ✅ 結論：qmd 不支援 frontmatter filter。只有 -c (collection) 和 --min-score 選項。需自行實作
3.2 實作 metadata filter 策略
- 如果 qmd 原生支援：直接在 search.ts 加 filter 參數
- 如果不支援（較可能）：兩步驟策略
  1. grep -rl "chapter: \"2-1\"" notes/ → 取得候選檔案列表
  2. 將列表傳給 qmd search/vsearch（如果 qmd 支援 file list input）
  3. 或：grep 篩選後自行用 qmd 的 API 搜尋子集
- 檔案：agent/src/search.ts（新增 MetadataFilterStrategy）
- ✅ 實作 filterByMetadata() + applyFilter()，所有策略都支援 MetadataFilter 參數

3B: Hybrid Search Pipeline

3.3 實作 hybrid search
- 現有：search（BM25）和 vsearch（向量）是分開的 Strategy，二選一
- 改為：並行執行 BM25 + vsearch → union + dedup → 合併 candidate set
- 融合策略：Reciprocal Rank Fusion (RRF)
  - RRF_score(d) = Σ 1/(k + rank_i(d))，k=60
- 檔案：agent/src/search.ts（新增 HybridStrategy）
- ✅ HybridSearch class：並行 BM25 + vsearch → RRF fusion → ranked results
3.4 實作 LLM re-rank step
- 輸入：hybrid search 的 top-30 候選（title + context_header + 前 200 chars）
- 模型：Haiku（便宜、快）
- 輸出：ranked top-10
- 檔案：agent/src/llm.ts（新增 rerank prompt）
- 成本：+1 次 Haiku call/query ≈ +$0.002
- ✅ rerank() 函數：接收候選清單，用 Haiku 評分 1-5 並排序

3C: Agent Loop 優化

3.5 加入 traversal budget
- 現有：max 5 rounds，每輪追蹤所有建議的 link（無上限）
- 改為：max 3 rounds，每輪 max 3 links
- 理由：metadata filter + hybrid search 提供更好的初始結果，不需要深度追蹤補救
- 檔案：agent/src/agent.ts
- ✅ MAX_ROUNDS=3, MAX_LINKS_PER_ROUND=3
3.6 修改 Judge prompt：link relevance scoring
- 現有：Judge 只說「追蹤這些 link」
- 改為：Judge 對每個建議 link 給 1-5 relevance score，只追蹤 score ≥ 3 的
- 檔案：agent/src/llm.ts（修改 judge prompt）
- ✅ followLinks 改為 { name, relevance } 結構，agent.ts 按 relevance 排序取 top-3

3D: MOC-first 路由（實驗性）

3.7 實驗 MOC-first routing
- 做法：Agent 第一輪固定搜尋 notes/moc/ 目錄 → 從 MOC 內容提取相關 topic_path → 後續搜尋限定在該 topic_path（用 Phase 3A 的 metadata filter）
- 預期效果：7,500 篇 → MOC 路由到 ~500 篇 → hybrid search 在 500 篇中更精準
- 風險：如果問題跨多個 topic_path，MOC 路由可能遺漏
- 決策：benchmark 後決定是否採用（見 Phase 3E）
- ✅ mocRouting() 函數：noteIndex.size > 500 時啟用，搜尋 MOC 提取 chapter filter

3E: Benchmark

3.8 設計 benchmark test suite
- 6 題原始測試 + 4 題新增：
  1. 單一概念題（Ch1）
  2. 開放概念題（Ch1）
  3. 人物題（Ch1）
  4. 公式題（Ch1）
  5. 跨概念題（Ch1）
  6. 歷史演變題（Ch1）
  7. 【新】跨章節概念題（Ch1 + Ch2）— 待 Ch2
  8. 【新】精確標籤搜尋（「找所有力學選擇題」）— 待 Ch2
  9. 【新】模糊語意搜尋（「有什麼跟能量守恆有關的？」）— 待 Ch2
  10. 【新】多跳推理題（「解釋牛頓力學如何影響天文觀測技術」）— 待 Ch2
- ✅ benchmark.ts 已建立，6 題 Ch1 測試
3.9 跑 benchmark：比較 baseline（grep）vs optimized（hybrid + metadata filter + MOC routing）
- 指標：正確率、回應時間、LLM call 次數、token 消耗
- 產出：benchmark-report.md
- ✅ grep: 6/6, avg 17.4s | hybrid: 6/6, avg 40.3s | 307 篇時 grep 足夠，hybrid 優勢在大規模時體現

Phase 驗證：optimized pipeline 在 10 題 benchmark 中正確率 ≥ 8/10，回應時間 < 30 秒。

Phase 4：Cross-chapter Linking 優化

目標：新章節筆記自動與既有筆記建立雙向連結，系統性管理空連結

4A: 生成時連結注入

4.1 建立 scripts/export-titles.sh
- 輸出格式：title | type | chapter | topic_path（每行一筆）
- 範例：庫侖定律 | concept | 1-1 | 物理學/物理學簡史/電磁學
- 目的：生成新章節時注入 prompt，讓 LLM 能正確連結到既有筆記
- ✅ 307 筆輸出正常（topic_path 尚未填入，Phase 5 重寫時補上）
4.2 設計 title list 注入策略
- 全量注入：300 篇 × 60 chars ≈ 18K tokens → 可接受
- 3,000 篇 × 60 chars ≈ 180K tokens → 太大，需改為只注入 related_chapters 的子集
- 決策點：當總筆記 > 1,000 篇時，改用 related_chapters filter
- ✅ 策略已寫入 CLAUDE.md（Phase 2.3），export-titles.sh 產出可直接注入 prompt
4.3 更新 CLAUDE.md 建構模式 Step 4（生成筆記時注入 title list）
- ✅ 已在 Phase 2.3 寫入 CLAUDE.md（Tier 2 Title 注入格式）

4B: 回填 Pass

4.4 建立 scripts/backfill-links.sh
- 做法：
  1. 讀取新生成的筆記 title list
  2. 對每篇舊筆記，搜尋正文中是否提到新筆記的概念（fuzzy match）
  3. 產出建議清單：「在 X 筆記中加入 Y 連結」
- 執行者確認後批次套用
- ✅ backfill-links.py：支援 title file 或 —auto（git diff 偵測新筆記）
4.5 驗證 CLAUDE.md 建構模式 Step 6（回填連結）
- 測試：手動在 notes/ 中新增一篇測試筆記 → 觸發建構模式 → 確認回填流程正確
- ✅ 腳本已就緒，實際驗證待 Phase 6（Ch2 生成後回填 Ch1）

4C: Known-missing Registry

4.6 建立 notes/known-missing-links.md
- 從 Phase 0.5 的 broken-links-ch1.txt 初始化
- 格式：- 全反射 — 預計 Ch4 補上
- verify.sh 排除此清單中的 link 不報錯
- ✅ 18 個 broken links 分類：後續章節 6 個、數學 3 個、工具 4 個、人物 2 個、其他 3 個
4.7 更新 verify.sh：broken link 檢查排除 known-missing list
- ✅ verify.py 已內建 known-missing 排除。跑 308 篇：0 errors, 0 warnings, 0 broken, 0 duplicates

Phase 驗證：export-titles.sh 和 backfill-links.sh 能跑在 Ch1 上；known-missing-links.md 已建立。

Phase 5：Ch1 重寫

目標：用優化後的 pipeline（新模板 + 新 prompt + 新 SOP）重新生成 Ch1 全部筆記，同時驗證 Phase 1-4 的優化效果

5.1 備份現有 Ch1 筆記
- cp -r notes/ notes-ch1-v1/
- ✅ 307 篇備份完成
5.2 用新 pipeline 重新生成 Ch1
- 依 Phase 2B SOP：Tier 1 → Tier 2 → 回填題目連結 → verify.py
- 使用新模板（Phase 1）+ 新 prompt（自足性 + context_header）
- 預估 vs 實際：
  - 概念：45 估 → 52 實際（1.16x）
  - 人物：25 估 → 60 實際（2.4x，一人一檔策略）
  - 公式：10 估 → 10 實際（1.0x）
  - 應用：5 估 → 5 實際（1.0x）
  - 題目：80 估 → 210 實際（2.6x）
  - MOC：4 估 → 4 實際（1.0x）
  - 總計：342 篇（v1 307 篇，增 11%）
- verify.py 結果：342 篇，0 errors, 180 warnings（scientist frontmatter enrichment）, 0 broken links, 0 duplicates
- 回填：52 概念筆記中 47 篇回填了相關題目，5 篇無對應題目
5.3 重建 qmd 索引
- bash scripts/index.sh
- ✅ 342 篇索引 + 346 chunks 向量嵌入（1 分 3 秒）
5.4 跑 Phase 3E benchmark（6 題）
- v2 結果：grep 6/6, avg 20.3s, total 121.7s
- v1 baseline：grep 6/6, avg 17.4s
- 比較：正確率不變（6/6），平均時間略增（17.4s→20.3s）
- 題 6 歷史演變需 3 輪 Judge + Verify FAIL 觸發補充搜尋（36.4s），但最終正確回答
- 結論：v2 筆記品質維持 Agent 正確率，時間增幅主要來自筆記數增多（342 vs 307）
5.5 diff 分析：v1 vs v2 筆記品質差異
- 抽樣 10 篇（concepts 2, scientists 2, formulas 2, questions 2, MOC 1）
- v2 明確優勢：
  - Frontmatter：10/10 有新欄位（chapter, topic_path, related_chapters, context_header）
  - 連結完整性：v1 有 dangling links（狹義相對論、太陽能量來源），v2 為零
  - 概念原子化：52 vs 22 概念筆記
  - 題目回填：光的波粒二象性 2→4 題、國際單位系統 2→9 題
  - 事實準確度：v1 的密立坎油滴實驗誤述已在 v2 修正
- v2 待改善：
  - 公式筆記深度退化（缺計算範例、易錯點）
  - 人物筆記遺失 lifetime/nationality/fields 結構化 metadata
  - 題目解析略簡化（缺驗算步驟）
- 結論：pipeline 有效，結構性改善顯著；內容深度問題可在 prompt 調整後改善

Phase 驗證：

✅ Ch1 v2 筆記全部通過 verify.py — 0 errors, 0 broken links
✅ Benchmark 正確率 6/6（100%）
✅ 生成時間 < 1 天（Tier 1 + Tier 2 + 回填 + verify + index 約 3 小時）
⚠️ 預估偏差：概念 1.16x（OK），人物 2.4x（仍偏高），題目 2.6x（校正公式已包含）

Phase 6：Ch2 擴展驗證

目標：用優化後的 pipeline 生成第二章，驗證跨章節連結和大規模檢索

6.1 選定 Ch2 目標章節
- 建議：選與 Ch1 知識交叉多的章節（如力學/能量），能充分測試跨章節連結
- 確認 PDF 路徑
6.2 用 CLAUDE.md 建構模式生成 Ch2
- 注入 Ch1 title list（Phase 4A）
- 依 Tier 1 → Tier 2 → Tier 3 SOP
6.3 跑回填 pass（Phase 4B）
- Ch2 新筆記 → 更新 Ch1 的相關連結
- 更新 known-missing-links.md（已解決的移除）
6.4 跑 verify.sh
6.5 跑 benchmark（擴充到 600+ 篇的完整測試）
- 重點：跨章節題目（#7）和多跳推理題（#10）
6.6 部署 Fly.io demo
- cd ~/Documents/physics-kb && /home/matt/.fly/bin/flyctl deploy
6.7 校正預估公式
- 用 Ch2 實際數據更新 Phase 2A 的校正公式
- 記錄到「問題與變更紀錄」

Phase 驗證：

Ch2 筆記通過 verify.sh
跨章節 benchmark 題正確
Ch1 回填連結正確（雙向）
Fly.io demo 可正常運作

待確認問題

qmd 是否原生支援 frontmatter metadata filtering？（影響 Phase 1 和 Phase 3A 的實作方式）
qmd embed 是否將 frontmatter 納入向量計算？（影響 context_header 放 frontmatter 還是正文）
Ch2 選哪一章？（需要與 OJT 目標對齊——「3-4 個跨類型章節」：力學+熱學+波動）
physics-kb GitHub repo 的 307 篇筆記是否完整？（Phase 0 clone 後確認）
OJT 3 月底檢核具體需要什麼 demo？（影響 Ch3-4 的優先級）

問題與變更紀錄

執行過程中遇到的問題、洞察、計畫調整，都記在這裡。格式：- [日期] 問題描述 → 解決方案 / 計畫調整

[2026-02-25] Phase 0-4 完成。環境重建、模板優化、pipeline SOP、retrieval 優化、跨章節連結工具全部就緒
[2026-02-25] qmd 安裝問題：bun install -g 不會自動 build dist/，需要 wrapper script（~/.bun/bin/qmd → npx tsx src/qmd.ts）。index.sh 用 command -v 檢查需要 PATH 設定
[2026-02-25] qmd embed 包含 frontmatter：驗證確認 vsearch 會將 frontmatter（含 context_header）納入向量計算，不需額外處理
[2026-02-25] verify.py 取代 verify.sh：bash 解析 markdown 太脆弱（CRLF、算術展開問題），改用 Python
[2026-02-25] LaTeX 檢查修正：初版 regex ^\$\$ 會誤判單行 block math（如 $$F=ma$$）。改為逐行判斷：standalone $$ / 開頭 / 結尾 / 單行完整
[2026-02-25] Benchmark Ch1 結果：grep 6/6 avg 17.4s，hybrid 6/6 avg 40.3s。307 篇時 grep 仍然足夠，hybrid 優勢待大規模驗證
[2026-02-25] Ch1 品質 baseline：308 篇（含 known-missing-links.md），0 errors, 0 warnings, 0 broken（18 個在 known-missing 排除）, 0 duplicates
[2026-02-25] Phase 5 Ch1 v2 生成完成：342 篇（concepts 52, scientists 60, formulas 10, applications 5, questions 210, MOC 4）。verify.py: 0 errors, 0 broken, 180 warnings（scientist metadata）
[2026-02-25] v1→v2 diff 分析發現：公式筆記深度退化（缺計算範例+易錯點）、人物筆記遺失 lifetime/nationality/fields。→ Ch2 生成前修改 prompt：(1) formula template 加回「計算範例」和「易錯點」必填段落 (2) scientist template 加回結構化 metadata 欄位
[2026-02-25] 模板修正 + 批次修補完成：CLAUDE.md 加入段落必填規則；10 篇公式全數重寫（加物理意義+計算範例+易錯點+相關公式）；60 篇人物全數修補（加 lifetime/nationality/fields + 重要著作與實驗 + 相關人物）。verify.py 最終結果：342 篇, 0 errors, 0 warnings, 0 broken, 0 duplicates

注意事項

qmd query 的 CPU 效能問題：reranking 在無 GPU 筆電上 ~5 分鐘。Phase 3 的 LLM re-rank 是替代方案（用 Haiku 取代本地 reranker），成本 ~$0.002/query 但速度快得多
BM25 中文多詞 AND 匹配：qmd search 的 BM25 對中文多詞查詢做 AND 匹配，容易零結果。hybrid search 緩解此問題（vsearch 不受影響）
Opus API 成本：Ch1 重寫（307 篇）+ Ch2 生成（預估 ~300 篇）的 Opus 4.5 成本約 $10-20。在 Claude Max 額度內
context window 壓力：大章節（80+ 頁）的 Opus multimodal 讀取可能撞 200K token 限制。Phase 2B 的分批策略（按 section 分批）是解決方案
安全：ANTHROPIC_API_KEY 只存在 .env（已在 .gitignore），不要 commit

連結

上層：物理知識庫專案
OJT：115 OJT 創新專案
驗證報告：實驗：qmd 原子化筆記方案驗證（物理 Ch1）
理論：qmd 原子化筆記方案、內容品質勝過檢索技術、用 LLM 建構增強型知識筆記
工具：QMD 本地語義搜尋工具
比較：RAG 與 Graph RAG 的本質差異
Demo：物理知識庫 Demo

115 OJT 創新專案

探索

物理知識庫 Pipeline 優化專案

物理知識庫 Pipeline 優化專案

背景知識

現有系統架構

Ch1 驗證結果（Baseline）

四個優化目標

關鍵技術概念

qmd 搜尋策略現況

Phase 0：環境重建

Phase 1：Formatter 優化（筆記模板與 frontmatter）

1A: Frontmatter Schema 強化

1B: 筆記自足性強化

1C: context_header 設計

Phase 2：Generation Pipeline 優化

2A: 預估模型校正

2B: 分批生成 SOP

2C: 自動化校驗

2D: 更新 CLAUDE.md 建構模式

Phase 3：Retrieval Scalability 優化

3A: Metadata Pre-filter

3B: Hybrid Search Pipeline

3C: Agent Loop 優化

3D: MOC-first 路由（實驗性）

3E: Benchmark

Phase 4：Cross-chapter Linking 優化

4A: 生成時連結注入

4B: 回填 Pass

4C: Known-missing Registry

Phase 5：Ch1 重寫

Phase 6：Ch2 擴展驗證

待確認問題

問題與變更紀錄

注意事項

連結

關係圖譜

目錄

反向連結