# 專案進度手冊 (Project Status Handoff)

> **用途**：這是新 Agent 進入此專案時，必須**第一個閱讀**的文件。它提供完整的現況快照、重要決策紀錄，以及下一步的明確任務。

---

## 🗂️ 專案一覽

| 項目 | 內容 |
|---|---|
| **專案名稱** | Taiwan Building Code RAG Benchmark |
| **GitHub Repo** | https://github.com/YuJunWang/taiwan-building-code-rag-benchmark |
| **本地路徑** | `E:\Project_AGY\11_RAG_GraphRAG_LLMwiki` |
| **目前版本** | V4.1（基準評測已完成）→ Phase 1（架構升級中）|
| **測試資料集** | 台灣《建築技術規則建築設計施工編》共 389 條 |

---

## ✅ 目前完成項目（V4.1 基準線已交付）

### 三大系統 V4.1 基準評測數據 (RAGAS 五維度量化)

| 系統架構 | Context Precision<br>(精確度) | Context Recall<br>(召回率) | Faithfulness<br>(忠實度) | Answer Relevancy<br>(相關性) | Answer Correctness<br>(正確性) | **五維度總平均** |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| 🏆 **OKF-Wiki** (Markdown階層導航) | 0.52 | 0.59 | 0.56 | **0.98** | **0.89** | **0.71** |
| 🥈 **Hybrid RAG** (向量 + BM25) | **0.58** | **0.69** | **0.58** | 0.71 | 0.62 | 0.64 |
| 🥉 **Graph RAG** (知識圖譜三元組) | 0.29 | 0.40 | 0.25 | 0.57 | 0.51 | 0.40 |

### 已完成的文件與基礎設施

| 文件 / 腳本 | 位置 | 說明 |
|---|---|---|
| V4.1 完整評測報告 | `docs/benchmark_v4_report.md` | 15 題逐題量化、檢索文本抽屜與專業審查紀錄 |
| 評估標準答案 (Ground Truth) | `benchmark/v3_ground_truth.json` | 15 題人工標準答案，用於正確性比對 |
| 評估卷宗派發器 | `benchmark/prepare_eval_tasks.py` | 生成 45 份帶有 Context 與 Ground Truth 的任務 JSON |
| 審查分析提示詞 | `benchmark/agent_eval_prompt.md` | 包含 Few-Shot、五維度量表與棄權處分原則 |
| 評測結果收斂腳本 | `benchmark/aggregate_evaluation.py` | 自動解析 Subagent 日誌並輸出 `ragas_baseline_v4.json` |
| Agent 行為規範 | `.agents/AGENTS.md` | 本專案最高指導原則，包含 V4.1 評測紀律 |

---

## 🔜 待完成項目（系統升級計畫）

> 詳細技術規格請閱讀：[`docs/v4_upgrade_plan.md`](./v4_upgrade_plan.md)

### ✅ Phase 0：V4.1 評估基礎設施與基準線建立 (已完成)
- 導入 RAGAS 五維度量表（Precision / Recall / Faithfulness / Relevancy / Correctness）。
- 導入人工標準答案 (`v3_ground_truth.json`) 與棄權零分機制。
- 建立全在地化 Subagent 平行評測框架，完成 45 份卷宗收斂。

### 🚀 Phase 1：Hybrid RAG V4 升級（成本最低，優先執行）
- [ ] **Layer A：Contextual Chunk Enrichment**
  - 利用 Gemini Flash 為每個法條分塊動態注入所屬章節脈絡與全域定義摘要，大幅降低檢索碎片化與雜訊。
- [ ] **Layer B：Self-Querying Metadata Filter**
  - 在 ChromaDB 建立法規專屬 Metadata Schema（章節、編號、適用建築類型）。
- [ ] **Layer C：Parent-Child Chunk Strategy**
  - 以細粒度子塊匹配檢索，回傳完整條文父文件。

### Phase 2：Graph RAG V4 升級
- [ ] **Fix A**：LazyGraphRAG 延遲建圖策略。
- [ ] **Fix B**：Graph-Vector 雙棲入口（向量種子 + 圖譜擴展）。
- [ ] **Fix C**：社群摘要預計算（Leiden 演算法）。

### Phase 3：OKF-Wiki V4 升級
- [ ] **Upgrade A**：向量空投輔助導航（Vector-Assisted Routing）。
- [ ] **Upgrade B**：工具特化（`search_toc` / `read_section` / `cross_reference_check`）。
- [ ] **Upgrade C**：語意快取機制。

### Phase 4：多架構融合路由（最終目標）
- [ ] 智慧 Query Routing 分流模組，依據問題特徵分發至最適合架構。
