前言¶
給 LLM/Agent 應用做評測，常見的問題不是沒有數字，而是數字不敢用：判據讀的是模型自己的回答措辭，而不是服務端日誌；負向斷言在空回答上恆真，於是”沒泄漏”被誤判爲 PASS；評測腳本本身有 bug，但全綠。改完 RAG、工具或提示詞之後，我們想知道的是”有沒有退化”，而現有做法多半隻能給一個”看起來對”的總分。
下面介紹的 ltj002/dsh-eval-harness 是一套面向 DeepSeek Harness（DSH）的 Agent 應用評測技能包，維護者 LTJ002，MIT 許可證，在社區目錄 SkillHub 上歸入 admin-security 分類。它針對上面這幾類問題給出方法學和可直接運行的腳本：判據只取外部事實、雙向斷言、基線按條數對比、安全類零容忍、並用變異測試驗證評測器本身沒壞。
這是什麼¶
一句話定位：dsh-eval-harness 是給模型讀的評測方法論（SKILL.md）加上可直接運行或改寫的評測實現（assets/ 下的 Python 腳本，JUnit 落盤器用 Java），打包成 DSH 技能包。
它不是宿主功能插件。倉庫裏 package.json 只用 dsh.bundle 把技能註冊進 ctx.skills，不提供 dsh.client、不改宿主 UI 或命令、不注入運行時代碼。安裝後技能以 bundled provider 形式出現在 ctx.skills 中（rank 600）。
它也不是評測平臺：不連你的檢索服務、不連你的模型網關，只負責”按你導出的外部事實算指標並判退化”。
框架無關是它的設計前提。LangChain、LangChain4j、Spring AI、AutoGen、CrewAI、Dify 等構建的 Agent 應用，只要滿足兩個前提就能用同一套判據：
- 對話可編程訪問——暴露可調用的對話接口（HTTP/SSE 均可）；
- 副作用可查詢——工具調用、寫操作留有可查詢記錄（審計表、結構化日誌或 DB）。
判據從這些外部事實讀取，不讀模型的自我陳述。換框架只改適配層，不改判據。
核心能力¶
分五塊看。
1. 三層評測：離線斷言 + 在線真打模型 + 基線對比。
eval_online.py：在線評測骨架，四套件tool/inject/answer/multi-turn，對應的是真實調用鏈路上的判據；eval_rag.py：檢索層指標 Recall@K、MRR、nDCG@K、Precision@K；eval_rag_answer.py：生成層 Faithfulness、引用準確性、完整性、矛盾檢測，基於人工標註對，不用模型互評；eval_baseline.py：與基線按用例對比，掉條數就紅。
2. 雙向判據，避免”假綠”。
判據要麼正向（該答的答了），要麼反向（不該答的沒答、不該出現的沒出現）。安全類用例反向判據尤其重要：答了敏感內容就是失敗，而不是”沒答對”。eval_online.py 把五條防誤報紀律固化成代碼：
# ① 工具是否被調用 → 查審計日誌，不看回答措辭
called = tool_calls_of(conversation_id)
# ② 降級跳過：負向斷言在空回答上恆真，不能算 PASS
if is_degraded(text, cost):
continue
# ③ PII 判"未打碼"，不判寬禁詞
UNMASKED_PHONE = re.compile(r"(?<!\d)1[3-9]\d{9}(?!\d)")
# ④ 觀測不到 → None，不進分母也不判失敗
called = tool_calls_of(cid)
if called is None and needs_tool:
unobservable += 1
continue
# ⑤ 401/402 基礎設施異常單獨計 errors：不因重試恢復，退出碼升 2
except urllib.error.HTTPError as exc:
if exc.code in (401, 402):
errors += 1
第 ② 條針對的是空回答陷阱：模型沒答，反向斷言自然成立，看起來”沒泄漏”，其實是沒跑。第 ④ 條是分母紀律：觀測不到的數據不進分母，避免”因爲沒測到而通過”。
3. 三檔嚴格度，安全類零容忍。
| kind | 默認容忍波動 | 理由 |
|---|---|---|
offline |
0 條 | 純函數無隨機性，掉 1 條就是真掉了 |
live-strict |
0 條 | 安全/編造類門禁（提示詞泄漏、PII、越權） |
live |
1 條 | 普通能力類，波動必須留痕 |
live-strict 的取捨是明確的：模型輸出的隨機性可以解釋能力波動，解釋不了泄漏。
4. 變異測試，驗證評測器自己沒壞。
assets/mutation_check.py 在臨時副本上把實現改壞，驗證斷言是否真的會翻紅。這是對”評測腳本在騙自己”這一風險的直接回應。assets/selftest.py 是判據與分母紀律的迴歸自檢，改任何腳本後都要跑。npm test 還包含 EvalResults.java 的編譯加運行冒煙（無 JDK 時顯式跳過）。
5. 治理與可追溯。
eval_governance.py 提供根因分層、數據集治理、Judge 校準三件套——Judge 一致率與 kappa 不達標就禁止進門禁。eval_manifest.py 對提示詞與數據集做 sha256 指紋並記錄 config diff，eval_report.py 出彙總報告但只讀、不設門禁。實驗口徑由 eval_manifest.py 與 ci-eval.yml.example 這三處共同約束。
安裝與啓用¶
安裝命令取自倉庫 README，是倉庫 URL 形式，不要按 dsh plugin add github:owner/repo 拼接：
dsh plugin add https://github.com/LTJ002/dsh-eval-harness
裝完不需要把技能複製到項目的 .agents/skills，會話內通過技能目錄或 @ai-eval-harness 引用即可。
需要說明的是，package.json 刻意不寫 dsh.compatibility.dsh（宿主版本範圍）。README 給出的理由是本包只依賴公開的技能註冊接口，未經多版本 DSH 宿主實測，因此不聲明兼容範圍。engines.node >= 20 是本倉庫開發與 CI 的構建期要求，不是 DSH 宿主版本要求。當前版本 1.0.0。
典型用法¶
第一步，建數據集。assets/datasets/*.example.jsonl 是格式樣板，不是測試題庫，裏面的問法來自寫作時的示例項目（攝影訂單），與你的業務無關。按下面步驟換成自己的：
- 把
*.example.jsonl複製成eval/datasets/下的真實數據集，問題、期望文檔、期望答案、禁詞全部換成你的業務內容； - 期望值（
expected/mustContain/ 預期工具）必須有真實出處（知識庫文件、接口文檔），不要憑感覺寫； - 正向、反向、多輪、檢索標註對都要覆蓋，格式不變。
不需要重寫的是判據引擎：eval_rag.py 的指標數學、eval_baseline.py 的嚴格度、eval_online.py 的五條紀律、mutation_check.py 的門禁機制與業務無關，換項目零改動。
第二步，對接適配層。eval_online.py 是骨架，login() / chat() / tool_calls_of() 要按你的項目契約改寫。assets/adapters.py 通過 EVAL_ADAPTER 指向項目側模塊，未實現的函數回退內置 base。詞表也外置了：markers.py 加 markers.default.json（7 組）必須與 eval_online.py / eval_governance.py 一起復制，否則 import 會給可行動錯誤；換業務詞表用 EVAL_MARKERS 覆蓋。
第三步，跑基線對比與自檢：
python skills/ai-eval-harness/assets/selftest.py # 判據與分母紀律迴歸自檢
python skills/ai-eval-harness/assets/mutation_check.py # 變異測試：斷言必須翻紅
npm test # bundle 結構冒煙，含 Java 落盤器編譯運行
退出碼約定：
| 碼 | 含義 |
|---|---|
| 0 | 通過 |
| 1 | 質量失敗（真實退化、真實泄漏） |
| 2 | 結果不可用（路徑錯、數據集缺、全降級、觀測不到、分母變化、401/402）——先修 harness，別當退化 |
退出碼 2 是這套設計裏容易被忽略的一點：結果不可用和質量失敗分開，避免把”環境沒配好”誤判成”應用退化了”。
適用場景與注意¶
適合這樣的團隊：有 LLM/Agent 應用在持續迭代（改 RAG、工具、提示詞），有可查詢的服務端副作用記錄，希望用可復現的判據而不是模型互評來守門禁。
幾處邊界在動手前要清楚：
eval_online.py是骨架，接口和數據集都要按項目改寫，assets/datasets/*.example.jsonl必須整體替換；eval_rag.py/eval_rag_answer.py不連接任何檢索或生成服務，retrieved、supportFacts、citations、requiredPoints等標註對由你的系統導出或人工標註；- 判定邏輯的迴歸自檢 monkeypatch 模塊級函數，驗證的是判定紀律，不是真實網絡路徑，真實連通性仍需跑一次在線評測；
- 整句語義相似度、答案是否”自然”這類判斷不在工具內，需要模型互評或人工評審，按第一原則不進門禁；
eval_governance.py judge只負責校準 Judge 是否夠格當輔助分； - 多輪套件與工具五階段的判據設計已實現（
run_multi_turn_suite/check_tool_stages），但對應數據集需按業務改寫，tool_call_records()的完整副作用記錄接口需按項目審計表對接。
這個技能包以當前 DSH 進程的權限運行，註冊的是方法學與腳本而非宿主能力。安裝前應自己讀一遍倉庫源碼，確認 SKILL.md 的判據設計和 assets/ 的實現與項目合規要求一致，並確認 MIT 許可證可接受。另外，倉庫當前星標爲 0、無 fork，屬於新項目，README 裏聲稱的四項本地驗證（結構冒煙、判據自檢、變異測試、Java 冒煙）以其倉庫 CI 與本地運行輸出爲準。
相關鏈接¶
- 目錄頁（社區目錄，獨立站點，與 DeepSeek / 幻方無官方從屬關係）：https://www.skillhub.cn/plugins/LTJ002/dsh-eval-harness
- 源碼與完整文檔：https://github.com/LTJ002/dsh-eval-harness
- 英文版 README：倉庫內
README.en.md
