# Benchmark V4 測試標準作業流程 (RAGAS Subagent Framework)

> **版本**：v4.0 | **狀態**：生效中 (取代 V3 的 LangSmith 與人工打字機模式)

為了確保專案未來所有的測試都能夠達到「客觀、零外部 API 成本、嚴謹量化」的標準，本專案一律採用以下「**全在地化子代理人評測框架 (Local-First Subagent Framework)**」。

## 核心理念 (Core Philosophy)

1. **捨棄外部 API 依賴 (Local-First)**：廢除 V3 依賴 LangSmith 與 OpenAI/Groq API 的評估方式。所有的生成與評估，皆交由本地端的 AI 子代理人 (Subagent) 執行。
2. **RAGAS 四維度評估**：揚棄 V3 僅憑「人類直覺」的主觀 Correctness 評分。導入嚴謹的 RAGAS 指標：
   - **Context Precision** (檢索精準度)
   - **Context Recall** (檢索召回率)
   - **Faithfulness** (忠實度/防幻覺)
   - **Answer Relevancy** (答案相關性)
3. **雙盲法官自我辯證 (Judge vs. Devil's Advocate)**：評分不再是單向給分。Evaluator Subagent 必須先擔任主審給出初步分數，再擔任魔鬼代言人試圖推翻自己，最後收斂出經得起檢驗的 0.0 ~ 1.0 量化分數。
4. **自動化日誌解析 (Transcript Parsing)**：捨棄讓 Agent 手動寫檔。採用平行發包 Subagent，再透過 Python 腳本直接從 `.system_generated/logs` 擷取 JSON 結果，大幅提高穩定性並防止編碼/跳脫字元錯誤。

---

## 角色與執行方式 (Agent Roles & Execution)

### 階段一：生成任務 (Generation Phase)
1. **準備任務**：執行 `python benchmark/prepare_eval_tasks.py`，將題庫 (`evaluation_questions.json`) 切割成 15 題，針對三套系統分別產生 `task_{system}_{id}.json`，共 45 份微型任務，放置於 `benchmark/gen_tasks/` 中。
2. **發包 Generator**：主 Agent 使用 `invoke_subagent` 工具，**平行喚醒 45 位 `rag_generator`**（每一位負責「單一系統的單一題目」）。
   - **模型選擇**：預設繼承主 Agent (Meta-Agent) 的頂級模型 (Pro-tier)，確保理解能力最大化。
   - Generator 讀取對應的任務 JSON。
   - 根據系統類型，執行 `retrieve_hybrid.py`、`retrieve_graph.py`，或如果是 OKF，則使用 `view_file` 自主翻閱 `data/databases/okf_knowledge/`。
   - Generator 將包含 `context`, `answer`, `retrieval_time_seconds`, `generation_time_seconds` 的標準 JSON 回傳至對話中。
3. **收斂答案**：主 Agent 執行 `python benchmark/aggregate_generation.py`，自動掃描 45 位子代理人的日誌，將答案彙整出給法官看的文件（放置於 `benchmark/results/eval_tasks/` 共 45 份）。

### 階段二：法官評分任務 (Evaluation Phase)
1. **發包 Evaluator**：主 Agent 再次使用 `invoke_subagent`，**平行喚醒 45 位 `rag_evaluator`**（每一位擔任「單一題目答案」的專屬法官）。
   - **模型選擇**：同樣繼承主 Agent 的頂級模型 (Pro-tier)，確保評分客觀性。
   - Evaluator 讀取 `benchmark/agent_eval_prompt.md` 規則。
   - 審閱 `eval_tasks/` 中含有 Question, Context, Answer 的完整資料。
   - 進行內部辯證後，回傳包含 RAGAS 四維度的標準 JSON。
2. **收斂成績單**：主 Agent 執行 `python benchmark/aggregate_evaluation.py`，解析所有法官的日誌，並計算出最終平均分。
3. **報告產出**：最終結果寫入 `benchmark/results/ragas_baseline_v4.json`，作為該版本的絕對基準。

---

## 防呆與嚴格紀律 (Strict Disciplines)

1. **禁止通靈與捏造**：如果 Generator 找不到對應的法規，必須老實回答「缺乏相關資訊」，**嚴禁**使用自身預先訓練的知識補齊答案。
2. **參數連動警告**：一旦修改了任何系統的核心參數（Chunk Size、Prompt、萃取邏輯），舊有的 Benchmark 成績將全數作廢，必須**重新執行上述完整的 V4 評估流程**以取得新的 Baseline。
3. **日誌防護**：由於大量依賴 Transcript JSON，所有的 Subagent 輸出必須被 \`\`\`json \`\`\` 嚴格包覆，且避免使用 PowerShell 的 Here-string 寫入可能破壞編碼的特殊字元。
