niceeval 0.17.0 → 0.18.0

package/docs-site/zh/examples/integrations/pi-sdk.mdx

@@ -20,7 +20,7 @@ Adapter 只需填写应用地址和审批接口地址。示例中的 `calculate`
 
 接入的全部代码变更（生成时从两个目录实测统计）：
 
-<table className="gd-summary"><tbody><tr><th>{"类别"}</th><th>{"文件数"}</th><th>{"行数"}</th></tr><tr><td>{"应用侧配置（必要：依赖声明）"}</td><td>{"3"}</td><td>{"+6 −1"}</td></tr><tr><td>{"Adapter（必要：连接应用，协议映射由 NiceEval 提供）"}</td><td>{"2"}</td><td>{"+112"}</td></tr><tr><td>{"评估用例与实验（按需增长）"}</td><td>{"6"}</td><td>{"+128"}</td></tr><tr className="gd-total"><td>{"合计"}</td><td>{"11"}</td><td>{"+246 −1"}</td></tr></tbody></table>
+<table className="gd-summary"><tbody><tr><th>{"类别"}</th><th>{"文件数"}</th><th>{"行数"}</th></tr><tr><td>{"应用侧配置（必要：依赖声明）"}</td><td>{"3"}</td><td>{"+6 −1"}</td></tr><tr><td>{"Adapter（必要：连接应用，协议映射由 NiceEval 提供）"}</td><td>{"2"}</td><td>{"+112"}</td></tr><tr><td>{"评估用例与实验（按需增长）"}</td><td>{"6"}</td><td>{"+130"}</td></tr><tr className="gd-total"><td>{"合计"}</td><td>{"11"}</td><td>{"+248 −1"}</td></tr></tbody></table>
 
 ## 文件清单
 
@@ -82,9 +82,9 @@ pi-sdk/
 </div>
 
 <div className="gd-file">
-<div className="gd-head"><span className="gd-name">{"evals/basic-qa.eval.ts"}</span><span className="gd-stats"><span className="gd-plus">{"+27"}</span></span></div>
+<div className="gd-head"><span className="gd-name">{"evals/basic-qa.eval.ts"}</span><span className="gd-stats"><span className="gd-plus">{"+28"}</span></span></div>
 <div className="gd-body">
-<table className="gd-table"><tbody><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"1"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineEval, defineJudge } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"2"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"3"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"answerQuality"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineJudge"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"4"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  name: "}</span><span className="gdt2">{"\"answer-quality\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"5"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  rubric: "}</span><span className="gdt2">{"\"助手是否用一两句话正常介绍了自己,而不是报错或答非所问?\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"6"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"7"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"8"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 这条 eval 验证 agent 能正常问答、不瞎调工具,顺带冒烟 usage 有没有正确从"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"9"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// message_end 的 AssistantMessage.usage 累加进 Turn.usage。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"10"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"export"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"default"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineEval"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"11"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  description: "}</span><span className="gdt2">{"\"测试 agent 能正常问答且不瞎调工具\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"12"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"13"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  "}</span><span className="gdt4">{"async"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"test"}</span><span className="gdt0">{"("}</span><span className="gdt7">{"t"}</span><span className="gdt0">{") {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"14"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"turn"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"send"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"用一句话介绍一下你自己,这轮不用查天气也不用算数。\""}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"15"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" turn."}</span><span className="gdt5">{"succeeded"}</span><span className="gdt0">{"()."}</span><span className="gdt5">{"orStop"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"16"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"17"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"group"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"正常收发、没有多余工具调用\""}</span><span className="gdt0">{", () "}</span><span className="gdt4">{"=>"}</span><span className="gdt0">{" {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"18"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"succeeded"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"19"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"usedNoTools"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"20"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    });"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"21"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"22"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt6">{"// usage 冒烟:拿不到就应该是 0,不该抛错;上限给得宽松,只为证明数字不是编的。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"23"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    t."}</span><span className="gdt5">{"maxTokens"}</span><span className="gdt0">{"("}</span><span className="gdt1">{"20_000"}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"24"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"25"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    t."}</span><span className="gdt5">{"judge"}</span><span className="gdt0">{"({ prompt: turn.input, answer: turn.message }, answerQuality)."}</span><span className="gdt5">{"gate"}</span><span className="gdt0">{"("}</span><span className="gdt1">{"0.6"}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"26"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"27"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr></tbody></table>
+<table className="gd-table"><tbody><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"1"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineEval } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"2"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineJudge } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval/expect\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"3"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"4"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"answerQuality"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineJudge"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"5"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  name: "}</span><span className="gdt2">{"\"answer-quality\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"6"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  rubric: "}</span><span className="gdt2">{"\"助手是否用一两句话正常介绍了自己,而不是报错或答非所问?\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"7"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"8"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"9"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 这条 eval 验证 agent 能正常问答、不瞎调工具,顺带冒烟 usage 有没有正确从"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"10"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// message_end 的 AssistantMessage.usage 累加进 Turn.usage。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"11"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"export"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"default"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineEval"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"12"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  description: "}</span><span className="gdt2">{"\"测试 agent 能正常问答且不瞎调工具\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"13"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"14"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  "}</span><span className="gdt4">{"async"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"test"}</span><span className="gdt0">{"("}</span><span className="gdt7">{"t"}</span><span className="gdt0">{") {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"15"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"turn"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"send"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"用一句话介绍一下你自己,这轮不用查天气也不用算数。\""}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"16"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" turn."}</span><span className="gdt5">{"succeeded"}</span><span className="gdt0">{"()."}</span><span className="gdt5">{"orStop"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"17"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"18"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"group"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"正常收发、没有多余工具调用\""}</span><span className="gdt0">{", () "}</span><span className="gdt4">{"=>"}</span><span className="gdt0">{" {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"19"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"succeeded"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"20"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"usedNoTools"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"21"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    });"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"22"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"23"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt6">{"// usage 冒烟:拿不到就应该是 0,不该抛错;上限给得宽松,只为证明数字不是编的。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"24"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    t."}</span><span className="gdt5">{"maxTokens"}</span><span className="gdt0">{"("}</span><span className="gdt1">{"20_000"}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"25"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"26"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    t."}</span><span className="gdt5">{"judge"}</span><span className="gdt0">{"({ prompt: turn.input, answer: turn.message }, answerQuality)."}</span><span className="gdt5">{"gate"}</span><span className="gdt0">{"("}</span><span className="gdt1">{"0.6"}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"27"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"28"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr></tbody></table>
 </div>
 </div>
 
@@ -110,9 +110,9 @@ pi-sdk/
 </div>
 
 <div className="gd-file">
-<div className="gd-head"><span className="gd-name">{"evals/weather-tool.eval.ts"}</span><span className="gd-stats"><span className="gd-plus">{"+25"}</span></span></div>
+<div className="gd-head"><span className="gd-name">{"evals/weather-tool.eval.ts"}</span><span className="gd-stats"><span className="gd-plus">{"+26"}</span></span></div>
 <div className="gd-body">
-<table className="gd-table"><tbody><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"1"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineEval, defineJudge } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"2"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { jsonMatch, pattern, toolMatch } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval/expect\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"3"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"4"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"answerQuality"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineJudge"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"5"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  name: "}</span><span className="gdt2">{"\"answer-quality\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"6"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  rubric: "}</span><span className="gdt2">{"\"助手是否给出了具体的天气数据(温度或天气状况),而不是拒绝回答或含糊其辞?\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"7"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"8"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"9"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 这条 eval 验证 agent 遇到实时天气问题时会调 get_weather,而不是直接编一个答案。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"10"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"export"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"default"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineEval"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"11"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  description: "}</span><span className="gdt2">{"\"测试 agent 在天气问题中正确调用 get_weather 并基于结果作答\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"12"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"13"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  "}</span><span className="gdt4">{"async"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"test"}</span><span className="gdt0">{"("}</span><span className="gdt7">{"t"}</span><span className="gdt0">{") {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"14"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"turn"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"send"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"北京今天天气怎么样?\""}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"15"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" turn."}</span><span className="gdt5">{"succeeded"}</span><span className="gdt0">{"()."}</span><span className="gdt5">{"orStop"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"16"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"17"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"group"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"调用 get_weather 且城市正确\""}</span><span className="gdt0">{", () "}</span><span className="gdt4">{"=>"}</span><span className="gdt0">{" {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"18"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"calledTool"}</span><span className="gdt0">{"("}</span><span className="gdt5">{"toolMatch"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"get_weather\""}</span><span className="gdt0">{", { input: "}</span><span className="gdt5">{"jsonMatch"}</span><span className="gdt0">{"({ city: "}</span><span className="gdt2">{"\"北京\""}</span><span className="gdt0">{" }) }));"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"19"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"check"}</span><span className="gdt0">{"(turn.message, "}</span><span className="gdt5">{"pattern"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"/"}</span><span className="gdt8">{"°C"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"气温"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"天气"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"晴"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"多云"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"雨"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"阴"}</span><span className="gdt2">{"/"}</span><span className="gdt0">{"));"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"20"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    });"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"21"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"22"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt6">{"// 「是否走了工具」由上面的 t.calledTool 确定性把关;judge 只评回复本身的质量。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"23"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    t."}</span><span className="gdt5">{"judge"}</span><span className="gdt0">{"({ prompt: turn.input, answer: turn.message }, answerQuality)."}</span><span className="gdt5">{"gate"}</span><span className="gdt0">{"("}</span><span className="gdt1">{"0.7"}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"24"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"25"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr></tbody></table>
+<table className="gd-table"><tbody><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"1"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineEval } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"2"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { defineJudge } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval/expect\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"3"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"import"}</span><span className="gdt0">{" { jsonMatch, pattern, toolMatch } "}</span><span className="gdt4">{"from"}</span><span className="gdt0">{" "}</span><span className="gdt2">{"\"niceeval/expect\""}</span><span className="gdt0">{";"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"4"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"5"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"answerQuality"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineJudge"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"6"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  name: "}</span><span className="gdt2">{"\"answer-quality\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"7"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  rubric: "}</span><span className="gdt2">{"\"助手是否给出了具体的天气数据(温度或天气状况),而不是拒绝回答或含糊其辞?\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"8"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"9"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"10"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt6">{"// 这条 eval 验证 agent 遇到实时天气问题时会调 get_weather,而不是直接编一个答案。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"11"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt4">{"export"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"default"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"defineEval"}</span><span className="gdt0">{"({"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"12"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  description: "}</span><span className="gdt2">{"\"测试 agent 在天气问题中正确调用 get_weather 并基于结果作答\""}</span><span className="gdt0">{","}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"13"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"14"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  "}</span><span className="gdt4">{"async"}</span><span className="gdt0">{" "}</span><span className="gdt5">{"test"}</span><span className="gdt0">{"("}</span><span className="gdt7">{"t"}</span><span className="gdt0">{") {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"15"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"const"}</span><span className="gdt0">{" "}</span><span className="gdt1">{"turn"}</span><span className="gdt0">{" "}</span><span className="gdt4">{"="}</span><span className="gdt0">{" "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"send"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"北京今天天气怎么样?\""}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"16"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" turn."}</span><span className="gdt5">{"succeeded"}</span><span className="gdt0">{"()."}</span><span className="gdt5">{"orStop"}</span><span className="gdt0">{"();"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"17"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"18"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt4">{"await"}</span><span className="gdt0">{" t."}</span><span className="gdt5">{"group"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"调用 get_weather 且城市正确\""}</span><span className="gdt0">{", () "}</span><span className="gdt4">{"=>"}</span><span className="gdt0">{" {"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"19"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"calledTool"}</span><span className="gdt0">{"("}</span><span className="gdt5">{"toolMatch"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"\"get_weather\""}</span><span className="gdt0">{", { input: "}</span><span className="gdt5">{"jsonMatch"}</span><span className="gdt0">{"({ city: "}</span><span className="gdt2">{"\"北京\""}</span><span className="gdt0">{" }) }));"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"20"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"      t."}</span><span className="gdt5">{"check"}</span><span className="gdt0">{"(turn.message, "}</span><span className="gdt5">{"pattern"}</span><span className="gdt0">{"("}</span><span className="gdt2">{"/"}</span><span className="gdt8">{"°C"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"气温"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"天气"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"晴"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"多云"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"雨"}</span><span className="gdt4">{"|"}</span><span className="gdt8">{"阴"}</span><span className="gdt2">{"/"}</span><span className="gdt0">{"));"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"21"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    });"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"22"}</td><td className="gd-sign">{"+"}</td><td className="gd-code">{" "}</td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"23"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    "}</span><span className="gdt6">{"// 「是否走了工具」由上面的 t.calledTool 确定性把关;judge 只评回复本身的质量。"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"24"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"    t."}</span><span className="gdt5">{"judge"}</span><span className="gdt0">{"({ prompt: turn.input, answer: turn.message }, answerQuality)."}</span><span className="gdt5">{"gate"}</span><span className="gdt0">{"("}</span><span className="gdt1">{"0.7"}</span><span className="gdt0">{");"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"25"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"  },"}</span></td></tr><tr className="gd-add"><td className="gd-ln"></td><td className="gd-ln">{"26"}</td><td className="gd-sign">{"+"}</td><td className="gd-code"><span className="gdt0">{"});"}</span></td></tr></tbody></table>
 </div>
 </div>
 

package/docs-site/zh/explanation/judge.mdx

@@ -12,7 +12,7 @@ Judge 用独立裁判模型评估事实一致性、摘要忠实度和说明质
 在模块顶层写出标准。`rubric` 说明评价维度，`anchors` 给连续质量量尺提供可校准的落点：
 
 ```ts
-import { defineJudge } from "niceeval";
+import { defineJudge } from "niceeval/expect";
 
 const explainsRisk = defineJudge({
   name: "explains-risk",

package/docs-site/zh/index.mdx

@@ -16,6 +16,24 @@ description: "像写单元测试一样写评估，像做实验一样比较 Agent
 
 所有运行都在你自己的机器和 CI 里完成，不需要注册账号。
 
+## 直接检查数值和比例
+
+在 `defineScoreEval` 的 `test(t)` 中，已计算好的 0 到 1 比例可以直接计分，不需要自定义 fraction matcher：
+
+```ts
+import { atMost, isTrue, measured, quantile } from "niceeval/expect";
+
+t.score(completionRate, { weight: 20 });
+t.score(measured(optionalRate, { unavailable: "no-samples" }), { weight: 10 });
+t.check(ready, isTrue()).gate();
+t.check(measured(latencyMs, { unavailable: "no-actions" }), atMost(1200)).gate();
+t.check(quantile(intervalsMs, 0.9), atMost(3000)).gate();
+```
+
+`measured` 将 null 保留为带原因的不可判定材料，不会当成零。`t.score` 要求比例在 0 到 1 之间，不隐式截断；领域确需限定范围时请显式处理。
+`quantile` 默认采用线性插值，也可传 `{ method: "nearest-rank" }`。结果的 `statistics` 提供样本数、分位点和算法；空样本返回 `no-samples`，无效样本返回 `non-finite-sample`。
+纯统计报告可以由 Adapter 用 `ctx.attach` 保存为 Markdown 或 JSON 附件，无需创建恒真 check。
+
 ## 从这里开始
 
 <CardGroup cols={3}>

package/docs-site/zh/introduction.mdx

@@ -26,7 +26,8 @@ NiceEval 用来回答这个问题。它以 Agent 为主要场景，也能评任
 
 ```ts
 // evals/weather-tool.eval.ts
-import { defineEval, defineJudge } from "niceeval";
+import { defineEval } from "niceeval";
+import { defineJudge } from "niceeval/expect";
 import { includes } from "niceeval/expect";
 
 const groundedAnswer = defineJudge({

package/docs-site/zh/reference/define-agent.mdx

@@ -144,7 +144,7 @@ readonly signal: AbortSignal;
 #### `models`
 
 ```ts
-readonly models: ResolvedModelSlots;
+readonly models: Readonly<Record<Slots, ResolvedModelSlot>>;
 ```
 
 Frozen application model selections for this Attempt.
@@ -152,7 +152,7 @@ Frozen application model selections for this Attempt.
 #### `recordUsage`
 
 ```ts
-recordUsage(input: import("./adapter-usage.ts").AdapterUsageInput): void;
+recordUsage(input: Omit<import("./adapter-usage.ts").AdapterUsageInput, "modelSlot"> & { readonly modelSlot?: Slots | null }): void;
 ```
 
 #### `sealUsage`

package/docs-site/zh/tutorials/authoring.mdx

@@ -100,7 +100,8 @@ export default defineEval({
 “回答是否有依据”“语气是否适合小学生”这类问题，正则写不出来。把它交给裁判模型 Judge 打分：
 
 ```ts
-import { defineEval, defineJudge } from "niceeval";
+import { defineEval } from "niceeval";
+import { defineJudge } from "niceeval/expect";
 
 const grounded = defineJudge({
   name: "grounded-answer",

package/docs-site/zh/tutorials/control-run-cost.mdx

@@ -115,11 +115,9 @@ Headless Adapter 使用 `ctx.recordUsage` 登记真实调用，并在采集结
 ```ts
 import { atLeast } from "niceeval/expect";
 
-const planner = t.usage.cacheRead.modelSlots.find(group => group.modelSlot === "planner");
-t.check(
-  planner?.rate ?? { state: "unavailable", reason: "model-slot-not-recorded" },
-  atLeast(0.6),
-).gate();
+t.check(t.usage.cacheRead.rate("planner"), atLeast(0.6)).gate();
+// 不区分用途时，检查所有已登记调用的合计。
+t.check(t.usage.cacheRead.rate(), atLeast(0.6)).gate();
 ```
 
 读取率是同组调用的 **缓存读取 token 总量 / 含缓存输入 token 总量**，包括失败调用与重试。它不是逐次百分比的平均值。每次调用优先使用 `inputTotalTokens`；没有独立总量时，必须同时提供 `inputTokens`、`cacheReadTokens`、`cacheWriteTokens` 三个互斥桶。
@@ -129,3 +127,84 @@ t.check(
 缺失输入、未 seal、partial seal、unknown 调用状态、空组或零分母均返回 `unavailable`，`reasons` 列出原因。缺失不按零处理；完整且有正输入总量的零缓存读取率才是数值 0。旧账本没有明确的生产者完整性声明时，也返回不可判定。
 
 使用 `niceeval show <Attempt locator> --usage` 或 View 查看读取率、覆盖情况与原因；脚本通过 `attempt.usage` 的 `usage.cacheRead` 读取相同报告。已有 `recordUsage` 调用无需改名，但必须登记缓存 token，并在采集完成后诚实 seal。无需迁移历史结果文件。
+
+
+槽位名来自 Experiment 的 `models` 键，不是框架内置名单。`model` 单模型简写对应 `default`。
+传入未声明的槽位会在调用处报错，并列出可用名称。已声明但完整记录中没有调用的槽位返回 `slot-has-no-calls`；采集不完整时仍返回 `collection-incomplete`。
+Eval 可以被多个 Experiment 复用，因此此入口在运行回调里校验槽位，不在定义期检查动态字符串。
+
+### 登记命令行 Agent 的用量
+
+Adapter 应按外部回执记录真实调用，并将 `modelSlot` 设为 Experiment 声明的用途，例如 `mind`。
+同一请求的流式增量和最终回执不能各登记一次；先按请求 ID 合并，收到最终回执后再登记。
+
+```ts
+// 单次 Claude 请求的最终 usage；字段缺失时保留 null。
+ctx.recordUsage({
+  callId: requestId,
+  modelSlot: "mind",
+  provider: observedProvider,
+  model: observedModel,
+  status: observedStatus,
+  inputTokens: usage.input_tokens ?? null,
+  cacheReadTokens: usage.cache_read_input_tokens ?? null,
+  cacheWriteTokens: usage.cache_creation_input_tokens ?? null,
+  outputTokens: usage.output_tokens ?? null,
+});
+```
+
+Claude 的 `input_tokens` 是未命中缓存的输入桶，含缓存总量需加上读取和写入桶，见 [Claude 缓存用量说明](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)。
+Codex 的 usage 若提供含缓存的 `input_tokens`，应映射到 `inputTotalTokens`，`cached_input_tokens` 映射到 `cacheReadTokens`，不要再把缓存加进总量。
+不能仅因命令成功退出就认定全部模型调用都已被记录；需核对所用 CLI 版本输出的是逐请求、Turn 还是会话合计。
+
+只有会话总量时，不要把多次物理调用伪装成一次调用，也不要把合计与明细同时登记。
+当前 `recordUsage` 的单位是物理调用；将会话合计保存在统计附件中，并声明 `partial`，缓存判据会诚实地显示不可判定。
+完全没有 usage 时同样声明 `partial`，不要填零或声明完整空账本：
+
+```ts
+ctx.sealUsage({ state: "partial", reason: "usage-not-exposed" });
+// 只提供会话总量、不能证明逐调用完整性时：
+// ctx.sealUsage({ state: "partial", reason: "session-totals-only" });
+```
+
+确实拿到全部物理调用的最终记录后，再调用 `ctx.sealUsage({ state: "complete" })`。
+
+## 让模型用途名称参与类型检查
+
+从 0.18 起，共享声明让同一评估可用于多个实验，同时在编译时检查用途名称：
+
+```ts title="models.ts"
+import { defineModelSlots } from "niceeval";
+
+export const slots = defineModelSlots({
+  mind: { model: "provider/planner" },
+  speech: { model: "provider/speaker" },
+});
+```
+
+在已有 Adapter 的绑定工厂上声明要求。也可解构 `adapter.defineScoreEval`，但根入口的同名工厂不接受 `requires`：
+
+```ts title="evals/cache.eval.ts"
+import { atLeast } from "niceeval/expect";
+import { adapter } from "../adapter";
+import { slots } from "../models";
+
+export default adapter.defineScoreEval({
+  requires: { models: slots },
+  test(t) {
+    t.check(t.usage.cacheRead.rate("mind"), atLeast(0.6)).gate();
+    // rate("mimd") 会产生 TypeScript 错误；rate() 仍查询全部用途的合计。
+  },
+});
+```
+
+实验使用 `defineExperiment({ adapter, models: slots, evals: ["cache"] })`。
+其它实验可为这些用途选择不同模型；`requires` 要求用途存在，不要求模型值相同。
+加载实验时会检查它选中的全部评估，CLI 的标签或前缀过滤不能隐藏缺失用途。
+
+给 `defineAdapter` 也传入 `requires: { models: slots }`，即可同时收窄 `ctx.models` 和 `ctx.recordUsage` 的 `modelSlot`。
+`null` 或省略的 `modelSlot` 仍表示未归属到用途的调用。已声明但本次没有调用时，`rate` 返回原因 `slot-has-no-calls` 的不可用材料。
+
+0.17.x 中省略 `requires` 的写法在 0.18 继续兼容，名称仍在调用时校验。
+迁移时先提取共享声明，再给 Adapter 和绑定评估分别添加 `requires`。
+不要先把声明标注成 `Record<string, ModelSlotSelection>`，否则 TypeScript 已丢失具体键，无法检测拼写错误。

package/docs-site/zh/tutorials/upgrade-0-18.mdx

@@ -0,0 +1,64 @@
+---
+title: "升级到 0.18"
+description: "共享模型用途、原生数值材料与公开入口调整"
+---
+
+0.18 保留 0.17 的 `t.usage.cacheRead.rate()` 与按用途查询方式，并增加可复用的用途类型声明。
+在评估项目中升级依赖：
+
+```sh
+pnpm add niceeval@^0.18.0
+```
+
+## 共享模型用途
+
+用 `defineModelSlots` 提取声明，实验的 `models` 与 Adapter 绑定评估的 `requires.models` 引用它。
+给 `defineAdapter` 同样添加 `requires.models` 后，`ctx.models` 与 `ctx.recordUsage` 的用途键也会被收窄。
+完整示例见[按用途检查缓存读取率](/zh/tutorials/control-run-cost#让模型用途名称参与类型检查)。
+
+0.18 继续接受省略 `requires` 的 0.17 写法，按调用时校验名称。
+根入口的 `defineEval`、`defineScoreEval` 属于 Agent 路径；共享声明只扩展 Adapter 绑定工厂。
+用途要求不会绑定具体实验或固定模型值。
+
+## 调整重复的导入入口
+
+| 原来的入口 | 0.18 写法 |
+| --- | --- |
+| 根入口的 `defineJudge`、`defineScoreMatch`、`defineMaterialMatch`、`defineContextMatch` | 从 `niceeval/expect` 导入 |
+| 根入口的 `factuality`、`faithfulness`、`instructionFollowing`、`pairwisePreference` | 从 `niceeval/expect` 导入 |
+| 根入口的 `readScoreMatchAudit` | 从 `niceeval/inspection` 导入 |
+| `niceeval/sandbox` 的 `resolveDockerProfileAlias` | 使用同入口的 `resolveDockerProfile` |
+| 根入口的 `requireEnv`、`getEnv`、`stripComments` | 取消公开导出，由项目自行提供需要的工具 |
+
+例如，自定义评分判据改为：
+
+```ts
+import { defineScoreEval } from "niceeval";
+import { defineScoreMatch } from "niceeval/expect";
+```
+
+判据的执行语义不变，原有根类型导出与错误类保留。
+环境工具原先将空字符串当作缺失；改用 `process.env` 时请明确保留还是改变这一行为。
+文本 matcher 的 `stripComments` 选项仍可使用，不受同名通用函数移除影响。
+
+## 替换项目数值工具
+
+```ts
+import { atMost, isTrue, measured, quantile } from "niceeval/expect";
+
+// value 为 null 时保留原因，不会把缺失转换成 0。
+t.check(measured(durationMs, { unavailable: "record-incomplete" }), atMost(3000)).gate();
+
+// 默认 linear；也可显式选择 nearest-rank。
+t.check(quantile(intervalsMs, 0.5), atMost(1200)).gate();
+t.check(quantile(intervalsMs, 0.9, { method: "nearest-rank" }), atMost(3000)).gate();
+
+// fraction 直接作为评分材料；无样本继续显示不可判定。
+t.score(measured(successRate, { unavailable: "no-samples" }), { weight: 1 });
+t.check(completed, isTrue()).gate();
+```
+
+`quantile` 返回值的 `statistics` 包含 `sampleCount`、`probability` 与 `method`。
+空集合返回 `no-samples`，非有限样本返回 `non-finite-sample`；非法概率或算法参数直接报错。
+`measured` 对非有限数值返回 `non-finite-number`。
+`fraction` 必须位于 `[0, 1]`，`t.score` 不会替作者截断越界值。

package/docs-site/zh/tutorials/verify-judge.mdx

@@ -68,7 +68,8 @@ export default defineEval({
 
 ```ts
 import { readFile } from "node:fs/promises";
-import { defineEval, defineJudge } from "niceeval";
+import { defineEval } from "niceeval";
+import { defineJudge } from "niceeval/expect";
 import { judgeImage } from "niceeval/judge";
 
 const actionQuality = defineJudge({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",