← 回 knowledge index

Knowledge Mirror

Agent、RAG、Harness 系統 Eval 功能設計

來源筆記：Agent、RAG、Harness 系統 Eval 功能設計.md

這份筆記整理一套用來評估 Agent / RAG / Harness 系統的 Eval 設計。重點不是做漂亮 demo，而是把系統裡容易退化、容易被改壞、但又很難靠肉眼長期盯住的規則，變成可重複執行的檢查。 核心原則： Eval 不是只拿來評分模型回答好不好，而是整個 AI 系統的防回歸機制。 對 Agentic system 來說，真正會壞的地方通常不是單一 prompt，…

Agent、RAG、Harness 系統 Eval 功能設計

#eval #agent #rag #harness #system-design #ai-engineering #openclaw #regression-test

這是什麼

這份筆記整理一套用來評估 Agent / RAG / Harness 系統的 Eval 設計。重點不是做漂亮 demo，而是把系統裡容易退化、容易被改壞、但又很難靠肉眼長期盯住的規則，變成可重複執行的檢查。

核心原則：

Eval 不是只拿來評分模型回答好不好，而是整個 AI 系統的防回歸機制。

對 Agentic system 來說，真正會壞的地方通常不是單一 prompt，而是：

所以 Eval 要從「單點答案評分」提升成「系統行為契約檢查」。

一、Eval 的分層

1. Regression Eval

Regression eval 用來保護已知規則與真實踩過的坑。

它的問題不是：

這次回答有多聰明？

而是：

以前修過的東西，有沒有又壞掉？

適合檢查：

這類 eval 應優先 deterministic，不需要 LLM-as-Judge。

2. Component Eval

Component eval 用來測單一元件是否符合契約。

常見元件：

例子：

輸入：一個需要查 know 的任務
預期：Agent 先查 knowledge-mirror，而不是直接憑記憶回答
輸入：一篇含下載連結、提取碼、雜訊文字的文章
預期：summary cleaner 移除 URL / pan.baidu / 提取碼，不把原文垃圾推到手機

Component eval 的價值是定位問題快：壞了就是某個元件的契約破了。

3. End-to-End Eval

End-to-end eval 測整條 workflow 是否完成。

例子：

輸入：一個 YouTube 影片 URL
預期：
1. 取得 transcript
2. 整理草稿
3. 使用者確認後寫入 know
4. git add / commit / push origin master
5. 回報 commit hash

E2E eval 可以捕捉 component eval 看不到的整合問題，例如：

4. Live Eval

Live eval 直接檢查真實環境狀態。

例子：

Live eval 的好處是能抓到 mock 抓不到的問題；壞處是較依賴外部狀態，應把不可控失敗標成 warning 或診斷訊息。

二、為什麼優先 deterministic checks

第一版 eval 不應急著做複雜的 LLM-as-Judge。

原因：

  1. 系統規則多半可被明確檢查

例如是否含 ollama-article、是否有 git status --short、是否有 Firestore summary。

  1. deterministic eval 便宜、快、穩定

可以頻繁跑，不會因模型漂移讓結果忽好忽壞。

  1. 真實回歸通常是工程契約破裂

不是回答風格差一點，而是某條流程被漏掉。

  1. LLM-as-Judge 適合最後一層主觀品質

例如摘要是否精煉、是否好讀、是否有洞察；但不適合拿來取代明確規則。

建議順序：

deterministic regression checks
→ component eval
→ end-to-end eval
→ live eval
→ subjective LLM-as-Judge

三、Agent Eval

Agent eval 要測的不是「模型有沒有想法」，而是它在固定工具與固定邊界內，是否做出正確決策。

Tool Selection Eval

檢查 Agent 是否選對工具。

例子：

| 任務 | 預期工具 |

|---|---|

| 查 prior work / preference | memory_search / memory_get |

| 查 know 文件 | knowledge-mirror / RAG |

| 寫程式與跑測試 | read / edit / exec |

| 使用 Ollama | ollama-presets scripts |

| GitHub issue / PR | gh / github skill |

失敗型態：

Planner / Action Eval

檢查 Agent 的行動順序是否合理。

例子：

任務：整理影片成 know 文件
預期順序：
1. 取得 transcript / source
2. 整理草稿
3. 等使用者確認
4. 寫入 know
5. git diff
6. commit
7. push
8. 回報 commit hash

常見錯誤：

Boundary Eval

檢查 Agent 是否守住邊界。

例子：

Agent 越自主，boundary eval 越重要。

四、RAG Eval

RAG eval 不應只看最終答案，也要拆成 retrieval 與 generation 兩段。

Retrieval Eval

核心問題：

使用者問這個問題時，系統有沒有找回該找的資料？

可測指標：

測資格式可以是：

{
  "query": "know 是什麼路徑？",
  "expected_sources": ["TOOLS.md"],
  "expected_terms": ["~/knowledge-mirror"]
}

Context Packing Eval

很多 RAG 失敗不是 retrieval 沒找到，而是 context packing 時把重要段落丟掉。

要測：

Answer Grounding Eval

最終回答要測：

這一層可部分使用 LLM-as-Judge，但 grounding / citation coverage 仍應優先做 deterministic 檢查。

五、Harness Lifecycle Eval

Harness 是 run-level control plane，所以 eval 重點不是單一回答品質，而是任務治理是否完整。

必測項目

成功標準

一個任務完成時，不只要有產出，還要能回答：

做了什麼？
目前在哪個 stage？
驗證了什麼？
留下哪些 artifacts？
如果要接手，下一步在哪？

這就是 Harness lifecycle eval 的核心。

六、目前系統的第一版 Regression Eval

目前 OpenClaw workspace 已落地第一版 runner：

[workspace]/evals/runners/system_regression_eval.py

執行：

python3 evals/runners/system_regression_eval.py

產報告：

python3 evals/runners/system_regression_eval.py --write-report --no-fail-exit

第一版檢查範圍：

know / knowledge-mirror

Ollama

Claw Notify

Harness

Preferences

七、Eval Report 格式

建議 eval report 至少包含：

{
  "status": "pass",
  "score": 18,
  "max_score": 18,
  "generated_at": "2026-05-07T...+08:00",
  "checks": [
    {
      "id": "notify.live_latest_summary_quality",
      "status": "pass",
      "description": "latest Firestore notifications have summary-like summaries",
      "details": "",
      "severity": "error",
      "metadata": {
        "inspected": ["..."]
      }
    }
  ]
}

Report 要能被人讀，也要能被 script 消費。

八、失敗等級設計

不是所有失敗都應該讓任務中斷。

建議分級：

| 等級 | 用途 | 是否 fail exit |

|---|---|---|

| error | 明確違反系統契約 | 是 |

| warning | 外部狀態不可控或需要人工確認 | 視情況 |

| info | 診斷資訊 | 否 |

例子：

九、後續擴充方向

1. RAG retrieval eval dataset

建立一組固定 query / expected source：

query → expected file / expected section / expected facts

先測 recall，再測 answer grounding。

2. Agent planner eval

建立一組任務情境，檢查 Agent 是否產生合理 action sequence。

例如：

3. Harness smoke run eval

建立最小任務，要求 Harness 完成：

start task
→ update task-state
→ produce artifact
→ validate artifact
→ write verification report
→ close task

4. LLM-as-Judge 補充主觀品質

只放在 deterministic eval 之後，用來評估：

但不能用它取代明確規則。

十、一句話總結

Agent / RAG / Harness 的 Eval，第一步不是追求高深模型評分，而是把真實工作中已經踩過的規則、邊界與 workflow 契約變成可重跑的防回歸檢查。

先讓系統不要重犯錯，再談更細的主觀品質評估。