# 專案專屬 Agent 行為規範 (Project Agent Guidelines)

> **版本**：v4.1 | **更新日期**：2026-08-14
> **適用範圍**：所有在 `taiwan-building-code-rag-benchmark` 專案資料夾下工作的 AI Agent。
>
> ⚡ **新 Agent 快速定位**：請先閱讀 [`docs/PROJECT_STATUS.md`](../docs/PROJECT_STATUS.md) 了解目前進度與下一步任務，再回來遵守本文件的行為規範。

---

## 0. 專案快速定位 (Quick Context)

這是一個針對台灣《建築技術規則建築設計施工編》（389 條）所建立的 AI 知識檢索架構**客觀比較**專案。

三大受測系統：**Hybrid RAG** (向量+關鍵字) | **Graph RAG** (知識圖譜) | **OKF-Wiki** (Agent 目錄導航)

- **目前狀態**：V4.1 基準測試完成（RAGAS 五維度評分：OKF-Wiki `0.71` / Hybrid RAG `0.64` / Graph RAG `0.40`）
- **當前優先任務**：Phase 1 — 執行 Hybrid RAG 架構升級（Contextual Chunk Enrichment 上下文增強分塊，見 `docs/v4_upgrade_plan.md`）

---

## 1. 專案核心認知與語氣定調 (Context & Tone)

- **中立原則**：**絕對禁止偏袒單一架構**。本專案目的是客觀揭露每個系統從建置到使用的所有優缺點，不是為任何系統做行銷。
- **客觀語氣**：文件受眾為需要「技術選型」的企業與開發者。必須使用平實、專業的技術名詞，**嚴禁**使用帶有強烈情緒、行銷色彩或戲劇角色扮演的字眼（如「致命缺點」、「神助攻」、「法官審判」、「魔鬼代言人」）。
- **既定用語**：已確定使用「主要限制 (Limitations)」而非「致命缺點 (Cons)」，使用「初步檢驗 / 嚴格查核 / 綜合評定」替代法庭戲劇代稱。

---

## 2. 目錄防護與環境整潔 (Directory Restrictions)

- **根目錄潔癖**：**嚴禁**在專案根目錄建立任何測試檔（如 `test.py`）或暫存輸出（如 `dump.txt`）。所有臨時操作與 Log 一律放置於 `scratch/` 資料夾。
- **資料庫防護** ⚠️：`data/databases/` 中存放了三大架構**已建置完成**的資料庫（Chroma、NetworkX 圖譜、OKF Markdown 樹）。除非使用者明確下達「**重新建置 (Rebuild)**」指令，否則 Agent **不得**修改或刪除這些檔案。
- **文檔歸檔規範**：
  - 評估報告 → `docs/`
  - 原始評測數據 JSON → `benchmark/results/`
  - 臨時腳本 → `scratch/`（可隨時清理）
  - 圖片素材 → `pic/`

---

## 3. 測試與評估紀律 (Benchmark Workflow)

- **禁止通靈數據** ❌：若要更新評測報告，必須基於 `benchmark/results/ragas_baseline_v4.json` 中的真實數據，或是重新執行評估腳本。**絕對不允許由 AI 大腦自行推算或捏造 (Hallucinate) 評分數據**。
- **審查機制**：若 Agent 奉命擔任評估審查角色，必須調閱人工標準答案 (`v3_ground_truth.json`) 與檢索文本，逐題執行「初步檢驗 ➔ 嚴格查核 ➔ 綜合評定」之客觀量化分析，給出精準的 0.0 ~ 1.0 評分，並利用 Python 腳本將結果寫回 JSON，不可單憑對話紀錄計算。
- **重測警告 (Reproducibility)** ⚠️：只要修改了任何一個系統的核心參數（例如 Chunk Size、萃取 Prompt、OKF System Prompt），**過去所有的評分數據將全數失效**。Agent 修改這些參數前，必須主動告知使用者：「這將需要重新跑完整個 Benchmark 基準測試」。

---

## 4. 程式碼與開發規範 (Development Standards)

- **套件安全 (Dependency Safety)**：RAG 相關套件（LangChain、ChromaDB 等）迭代極快，API 常有破壞性更新。**絕對不可擅自升級 `requirements.txt` 中的套件版本**，必須先告知使用者風險。
- **編碼防雷 (Encoding & PowerShell Quirks)**：
  - Python 讀寫任何檔案強制加上 `encoding='utf-8'`。
  - Windows 環境下，**嚴禁**使用 PowerShell Here-string 寫入含有跳脫字元（`\`）的 Markdown 檔案，應優先使用原生工具（`write_to_file` / `replace_file_content`）或撰寫 Python 腳本。
  - 特別注意：`\v` 在 PowerShell 中為垂直定位字元，會使 Markdown 出現亂碼（此為已知血淚教訓）。
- **Agent 身分界定 (Agent Identity)**：在除錯 OKF-Wiki 時，必須清楚界定身分。Meta-Agent（協助開發的 AI）只能修改受測 Agent 的系統提示詞或工具程式碼，**絕對禁止**以硬編碼方式竄改受測 Agent 的輸出歷程來作弊。
- **資安防護 (Secret Management)**：此為開源專案。執行 `git add` 或 `git commit` 前，必須自主審查，**嚴禁**將任何 API Key、`.env` 內容推送至 GitHub。

---

## 5. 資源與效能管理 (Resource & Scale Limits)

- **成本控管 (Cost Limits)**：Graph RAG 知識圖譜建置極度消耗 Token。在執行全量重新建置前，Agent 必須建議「先在單一章節（小樣本）進行測試」，確認 Prompt 萃取無誤後，再放行全量建置。
- **大檔案防雷 (Repo Size Control)**：向量資料庫（`.sqlite3`）與圖譜檔案容易膨脹。執行 `git add` 前，Agent 必須主動確認 `data/databases/` 中是否有超過 **50MB** 的單一檔案（GitHub 硬限制為 100MB），並在推送前警告使用者。

---

## 6. V4 開發階段追加規範 (V4 Specific Rules)

> 進入 V4 開發階段後，以下規範額外生效：

- **RAGAS 五維度評估為量化標準**：V4 起，所有系統的性能改善主張，必須以 `ragas` 五維度指標為量化依據：
  1. `Context Precision` (檢索精確度)
  2. `Context Recall` (檢索召回率)
  3. `Faithfulness` (回答忠實度)
  4. `Answer Relevancy` (回答相關性)
  5. `Answer Correctness` (解答正確性，比對 `v3_ground_truth.json`)
- **棄權處分機制**：若受測系統回答「缺乏資訊/無法回答」，其 Faithfulness、Relevancy 與 Correctness 強制給予 `0.0` 分。
- **全在地化子代理人評測 (Local-First Subagent Framework)**：為節省成本並保持架構單純，我們捨棄外部 API (如 LangSmith) 與付費評估服務。
  - **Generator 角色**：負責讀取檢索腳本輸出與題庫，產生包含花費時間與答案的 JSON。
  - **Evaluator 角色**：負責根據 `benchmark/agent_eval_prompt.md` 執行嚴謹的雙向查核，並回傳完整的 RAGAS JSON 成績單。
  - 主 Agent 負責使用 `invoke_subagent` 發起 Generator 與 Evaluator 進行平行運算，最後透過 `aggregate_evaluation.py` 解析日誌 (Transcript) 來收斂成績。
- **每次升級須附基線對比**：每完成一個 Phase 的升級，必須提供「升級前 vs 升級後」的 RAGAS 數據對比表，方可宣告該 Phase 完成。
