@ljwei-stak/dsh-model-router 0.14.0 → 0.16.0

package/docs/ROUTING_LIVEBENCH_DATA_SEARCH.zh.md

@@ -0,0 +1,74 @@
+# LiveBench 逐题文件：扩展检索与候选审计
+
+核查日期：2026-10-04（Asia/Shanghai）。这是数据调查，不是路由收益实验。
+
+## 结论
+
+**已实际下载第三方逐题附件和调用日志，但在本次核查范围内，仍未取得官方最新 `2026-06-25` 的完整同题多模型质量—费用矩阵。** 不要求用户提供其没有的文件；不把旧题新上传、答案对、单模型改提示词实验或排行榜均分冒称所需矩阵。
+
+最新官方聚合数据的审计见 [前一阶段报告](ROUTING_LIVEBENCH_VALIDATION.zh.md)。本报告扩大检索范围，不改变此前“真实收益尚未验证”的结论；没有调用付费模型、联系第三方、使用用户令牌或发布版本。
+
+## 1 实际取得的候选文件
+
+| 来源 | 已下载内容／实际检查 | 能用来做什么 | 当前不能用来做什么 |
+|---|---|---|---|
+| [TuringCorp 提交 #449](https://github.com/LiveBench/LiveBench/issues/449) | 两个 ZIP；每包 13 个答案 JSONL、682 行；两包按任务+ID有682对答案 | 检查答案格式与提供者用量记录 | 无逐题评分；全部 `cost_usd=null`；无法验证质量—费用收益 |
+| [Neuromantix 提交仓库](https://github.com/ModernOps888/neuromantix-livebench/tree/38c100343fbbc9b65e25ebfdead8e1d1339a18e1) | 一个 ZIP；400条答案、300条judgment、5任务、1个提交动作 | 审查历史逐题评分覆盖 | 明确使用2024-11-25题集；无费用／token；不是多模型矩阵 |
+| [Redwood 原始实验](https://github.com/redwoodresearch/astra-filler-tokens/tree/56089d101e604b58468a0524bb937c57a8a097f6) | 实际下载的日志有8328调用；其中LiveBench1854调用＝618题×3提示词条件 | 检查旧题的单模型、修改提示词实验及实际API用量 | LiveBench部分仅 `gpt-6-astra`；旧题；不是官方新题多模型回放，未见USD金额 |
+
+这三组均是来源提供者公开的自有记录；本轮只读解析，不执行他们的程序，也未独立重跑评分器。原文仅作本地研究归档，不将仓库代码许可自动扩大为所有题目/回答的再分发许可。
+
+### 1.1 TuringCorp：包名日期与题目身份分开
+
+提交帖和包名自称 `2026-01-08`；但682个 `(category, task, question_id)` 全部在官方旧公开题库中找到，题目 `livebench_release_date` 分布为：2024-06-24有246，2024-07-26有50，2024-08-31有86，2024-11-25有300。没有2026新题ID的证据。包不含原始prompt，**ID匹配不证明实际执行提示词完全相同**，也不能仅由题目初次发布日证明某次题集筛选的完整组成。
+
+题目对齐使用官方HF viewer全部分页，五个非coding test split均已读完；取数后各仓库SHA仍与取数前一致。viewer不提供对应Parquet精确revision身份，因此报告为“当次viewer快照中的ID/题目日期匹配”，不冒称固定Parquet字节复现。详情在归档 `summary-question-alignment.json`（分页覆盖）与 `summary-deeper.json`（正确字段的最终日期核对）。早期中间摘要错误读取 `livebench_release` 得到null；最终使用实际字段 `livebench_release_date`，中间稿保留而不作为结论。
+
+两包各682条都含输入/输出/缓存token记录；缓存计数均为0，费用全部未知。无法确认多模型编排的内部调用、隐藏推理、重试及用量是否全部进入这些字段，不以外层token数量直接推断总账。
+
+一致性缺口：提交帖Junior/Senior总分为81.6/85.2，包内SCORES为80.5/84.0；Math为81.1/86.8与75.5/80.4。应先由提供者解释评分文件／配置对应关系；这些差异本身不证明造假，也不能由无逐题标签的摘要自行修复。
+
+### 1.2 Neuromantix：上传时间不等于新题与完整评分
+
+作者明确标2024-11-25。实际包内AMPS_Hard有150答案但100评分，zebra_puzzle有100答案但50评分；两任务各50个answer-only ID。其余三个任务各50答案／评分。缺失标签保留未知，不填0，不用有标签子集代替声称的全部分母；无逐题费用，且只有一个提交动作。
+
+### 1.3 Redwood：有调用记录，但协议和动作池不同
+
+固定源码提交2026-09-28。实际LiveBench日志是618个旧题、同一模型、条件`B/0`、`CB/300`、`CB/1000`各618调用；618题三条件ID交集完整。都有布尔correct、输入/输出token及API返回记录，不能把三个提示词条件说成三个模型。
+
+618题元信息的首次release为2024-06-24（382）、2024-07-26（50）、2024-08-31（136）、2024-11-25（50）。作者去除了原题CoT/输出格式句，禁止推理，并按gold答案长度设输出上限；这不是本项目的原题直接回答协议。公开日志的billing只有payer字段，未见USD金额。故可做来源实验的描述性复核，不能直接用于当前选模算法或最新版收益验证。
+
+## 2 实际检索范围与证据
+
+| 核查入口 | 覆盖与结果 | 可复核资料 |
+|---|---|---|
+| 官方HF组织 | 10公开数据集；10 refs列表均只有main与convert/parquet、无tags/额外分支；main历史返回107提交，无后续分页；最新main提交止于2025-04-07 | `manifest-hf.json`、`summary-hf.json`；[组织API](https://huggingface.co/api/datasets?author=livebench&limit=100&full=true) |
+| 官方GitHub分支 | 两页API枚举120分支；bare/blob过滤克隆的全部120分支tip SHA与API逐一一致；递归树未见jsonl/parquet/csv/zip/tar/sqlite/db格式结果文件 | `summary-alltrees.json`；[分支API](https://api.github.com/repos/LiveBench/LiveBench/branches?per_page=100&page=1) |
+| 官方GitHub发布 | releases API返回空数组，无可从此入口获取的发布资产 | `official-releases.json`；[releases API](https://api.github.com/repos/LiveBench/LiveBench/releases?per_page=100) |
+| 最新题集线索 | #540是历史运行元信息请求；#513是hosted evaluation请求。核查时两者comments均0，未附逐题结果 | [#540](https://github.com/LiveBench/LiveBench/issues/540)、[#513](https://github.com/LiveBench/LiveBench/issues/513)，原API快照归档 |
+| 新上传镜像 | lthn评分文件LFS SHA与官方2025评分相同；Distillio题目LFS SHA与官方2025 coding相同。没有重复下载244.8MB旧题文件 | `summary-hf.json`；[lthn](https://huggingface.co/datasets/lthn/livebench-model_judgment/tree/1c7a95d00f89e5dd07a2d3699278f6ba0da493cd)、[Distillio](https://huggingface.co/datasets/Distillio/Livebench/tree/a5adcf34a862856cb02a55af9344e2a315d99b02) |
+| 同名候选 | mm-eval为2024月份的多模态LiveBench；aleeyanger只有1.51GB无schema说明的LiveBG压缩包，未下载，不声称已检查包内内容 | 各metadata快照；[mm-eval](https://huggingface.co/datasets/mm-eval/LiveBench)、[aleeyanger](https://huggingface.co/datasets/aleeyanger/live_bench) |
+| 其他路由自报 | SCX模型卡给出LiveBench聚合路由分与本地`results/report.json`名称；不等于公开完整逐题质量/费用文件 | [作者模型卡](https://huggingface.co/scx-admin/scx-router-v0.1)；本轮未下载模型权重或训练 |
+
+上述“未找到”仅涵盖被核查的匿名公开入口及当前可达分支tip，**不涵盖私有/gated/已删除/不可达历史、未知名称仓库或全网所有附件**。未对所有120分支的全部历史提交做内容搜索。下载/解析的路径与哈希可复核；第三方来源真实性、模型配置、评分准确性仍需独立证明。
+
+官方README仍提示全类别公开题需用2024-11-25，而新站费用生成说明提到`livebench-private`。因此，不能仅靠升级下载脚本得到2026完整题集。[官方README](https://github.com/LiveBench/LiveBench/blob/8f8e5c381a16e3f24257776edd53471fe86f8091/README.md)、[新站数据说明](https://github.com/LiveBench/new-livebench/blob/caa4253c8a3aa93b5c7ec234e681d4f120a20240/README.md)
+
+## 3 原文件身份与重放
+
+| 文件 | bytes | SHA256 |
+|---|---:|---|
+| `turingcorp-team-junior-v1_livebench-20260108.zip` | 290630 | `4fdfaba07ef69928ea0cb1764fc6c1d261d16bd1f9b3f25e1fc26e655210ce51` |
+| `turingcorp-team-senior-v1_livebench-20260108.zip` | 279738 | `a74ddb9109bdb57fa83eb99e29b74e5a1428c2c804bf41780e34f0a13be95161` |
+
+其余文件字节数、URL、SHA256见本机raw中分阶段manifest；最终归档manifest覆盖所有原始文件。ZIP不提取、不执行；只用标准库读JSONL，检查路径和解压后总量。Gzip日志设40MB展开上限。原始文件只写新路径，不改旧档案。
+
+归档的`collect-public.mjs`、`audit-files.py`是本轮自行编写的取数/检查工具，不是下载的第三方代码。`deeper`可离线重做最终ID日期与覆盖统计；`alltrees`只读已克隆的Git对象树。最初树命令使用`--long`读取对象大小可能触发blob懒获取，已中断并改用无`--long`的树元信息检查；未执行来源仓库的程序。HF的Node传输失败后，用本机requests直连成功，未安装新依赖或使用私有认证。
+
+## 4 下一步与不越界的停止条件
+
+现有文件无法补出官方2026-06-25完整矩阵。下一条有明确价值的路线是向维护者索取该release的版本化逐题评分、同题匿名ID、精确动作、用量/费用和可本地读取的题目特征；如果不能公开prompt，单靠ID+标签仍不够重放query-dependent选模。
+
+已在本地归档拟好数据请求草稿，**尚未发送**。对外联系需要用户授权；任何重新付费评测还需要模型池、题集与预算上限。取得合格数据前，不执行配对收益检验、不报告节省百分比、不改生产能力先验；可用的旧题/改协议数据只按其真实范围另立实验。
+
+2026-10-04用户决定结束检索，之后自行实测。本轮到此停止，不再联系维护者或补测。自测记录建议保留 `(release, category, task, question_id)`、prompt、精确模型/effort、生成参数、逐题quality、计费用量或costUsd、评分器版本、运行时间以及全部失败/重试。费用未知保留null；路由选择先冻结再连接标签，避免测试结果参与选模。未来实验需依据实际模型池重新审计协议，不自动把现有候选作为训练标签。

package/docs/ROUTING_LIVEBENCH_VALIDATION.zh.md

@@ -0,0 +1,154 @@
+# LiveBench：最新证据与同题质量—成本验证
+
+核查日期：2026-10-03（Asia/Shanghai）。对应本地未发布 `0.16.0-dev.1`，稳定版本仍为 `0.15.0`。
+
+本轮依用户要求，将真实数据调查从 LLMRouterBench 转为 LiveBench。结论是：**找到最新公开聚合数据，但尚未取得这个版本的完整逐题质量—费用矩阵，不能宣称新路由算法已经获得真实质量—成本收益。** 已实现聚合审计和连续分配对统计工具；未训练路由器、未付费调用、未修改生产选模逻辑、未发布。
+
+2026-10-04扩展检索：[逐题文件查找与候选审计](ROUTING_LIVEBENCH_DATA_SEARCH.zh.md)。实际下载了答案附件、历史评分包及单模型日志，核验全部120官方分支与10个HF数据集；这些候选仍不满足最新完整同题质量—费用矩阵条件。
+
+## 1 来源、日期与证据粒度
+
+不同日期不能互相替代：论文日期描述研究，仓库提交日期描述代码变化，release 日期描述题集，而数据文件日期描述实际公开记录。
+
+| 官方来源 | 固定版本／日期 | 能直接使用的证据 | 不能推断的内容 |
+|---|---|---|---|
+| [当前官网](https://livebench.ai/)与[新站源码](https://github.com/LiveBench/new-livebench/tree/caa4253c8a3aa93b5c7ec234e681d4f120a20240) | release `2026-06-25`；源码 `caa4253…`（2026-09-29 提交） | 66 个模型变体 × 23 个任务，分属 7 类；任务均分、任务总费用与题数 | 每个模型在同一道题上的答案、质量分和费用 |
+| [公开逐题评分](https://huggingface.co/datasets/livebench/model_judgment/tree/9704e5da7bfbefe75ac1482a13de827127295993) | revision `9704e5…`；2025-04-07 更新 | 60,372 行；`question_id/task/model/score/turn/tstamp/category` | 2026 题集结果；逐题 token 或费用 |
+| [公开逐题回答](https://huggingface.co/datasets/livebench/model_answer/tree/bc43a286b08243d6dcfa89ba2e906283e9adac9c) | revision `bc43a2…`；2024-10-22 更新 | 回答文本及 task/category/model 等元信息 | 与最新题集一致的完整矩阵；实际计费用量 |
+| [采集与评价源码](https://github.com/LiveBench/LiveBench/tree/8f8e5c381a16e3f24257776edd53471fe86f8091) | `8f8e5c…`（2026-09-29 提交） | 可检查当前评分、采集方式 | 源码支持记录费用，不代表相应逐题数据已公开 |
+
+这里的“尚未取得”指本轮核查的官方公开文件、官网前端取数路径和下载工具；不声称作者没有内部数据。最新费用生成说明指向 `livebench-private`。[官方数据布局说明](https://github.com/LiveBench/new-livebench/blob/caa4253c8a3aa93b5c7ec234e681d4f120a20240/README.md)
+
+三个最新官方文件已下载到本机不可变 raw 档案；源码和元信息共 12 份，另有来源 manifest。仓库仅交付审计脚本和派生报告，不复制未知独立许可的原始表。
+
+| 文件 | bytes | SHA256 |
+|---|---:|---|
+| `table_2026_06_25.csv` | 11,069 | `1021e4ef211ccba609d6da2c22032f46d695c1546508cf144a58a2f3d6960f3d` |
+| `categories_2026_06_25.json` | 725 | `dad300ad18655b69db720e1b88fc5a5eac06c5b2f0e52c2bf50f10ff057674f3` |
+| `cost_2026_06_25.csv` | 28,845 | `d572014a891e76ef3f30896f66cc873ec02eb5c7d10909a6796efe450ad05ba9` |
+
+官方 datasheet 声明 benchmark suite 使用 Apache-2.0；HF 元信息及新站聚合表未单独标明各文件许可，不将代码许可自动扩大为所有原始题目、回答和聚合表的再分发许可。[datasheet](https://github.com/LiveBench/LiveBench/blob/8f8e5c381a16e3f24257776edd53471fe86f8091/docs/DATASHEET.md)
+
+## 2 最新表应该怎样计算
+
+令 $S_{mt}$ 为模型 $m$ 在任务 $t$ 的公开平均分（0–100），$T_k$ 是类别 $k$ 的任务集合。完整覆盖时：
+
+$$Q_{mk}=\frac1{|T_k|}\sum_{t\in T_k}S_{mt},\qquad Q_m=\frac17\sum_{k=1}^{7}Q_{mk}.$$
+
+这是类别等权的质量画像，不是所有题的微平均。任务总费用 $C_{mt}$、有效计数 $n_{mt}$ 给出：
+
+$$\bar C_m=\frac{\sum_t C_{mt}}{\sum_t n_{mt}}.$$
+
+费用按题数加权，不能先求每类费用均值再除以 7。保留精确模型 ID 和 effort/reasoning 后缀，不把不同动作合并成同一模型。公式来自官方[质量平均代码](https://github.com/LiveBench/new-livebench/blob/caa4253c8a3aa93b5c7ec234e681d4f120a20240/src/Table/Averaging.js)和[费用计算代码](https://github.com/LiveBench/new-livebench/blob/caa4253c8a3aa93b5c7ec234e681d4f120a20240/src/lib/compute.js)。
+
+`livebench-aggregate-audit.mjs` 使用自己的严格文本解析，不执行下载的 JavaScript。缺失分数/费用保留缺失，不填 0；拒绝重复模型 ID、非法数值、重复列及不一致格式。先按完整计数向量的众数确定审计对照组，选择不使用质量/费用优劣；只有全部 23 任务评分/费用/计数完整、计数向量相同且公开平均费用为正的模型，进入有价格的描述性静态 Pareto 比较。公开零费用保留原值并单列，不证明免费可用，不参与有价格前沿。计数相同仍**不能证明题目身份相同**。
+
+静态 Pareto 的意思仅是：在这些聚合数值上，没有另一模型同时质量不低、费用不高且至少一项严格更好。不代表逐题路由最优，不代表 DAG 最优，不生成逐题样本、bootstrap 区间或算法收益结论。
+
+数值审计使用 Neumaier 补偿求和／均值；支配关系比较使用微小计算容差：质量 $32\,\mathrm{EPSILON}\max(1,|Q_a|,|Q_b|)$（0–100分），费用 $32\,\mathrm{EPSILON}\max(|C_a|,|C_b|)$（USD/题，无绝对美元下限）。容差内视为平局，至少一项须超过容差才算严格改善；这不是业务非劣margin，也不是统计显著性界限。十进制文本精确检查符号、评分上界和正整数题数，拒绝非零下溢，避免先转浮点再把非法小数题数当整数。
+
+最新聚合审计结果保存为 [latest-aggregate-audit.json](experiments/20261003-livebench/latest-aggregate-audit.json)。这是一份真实公开表的描述性检查，**不是新旧路由实验**。
+
+### 2.1 实际聚合审计结果
+
+三个文件 SHA256 与固定版本一致。66 模型均有完整任务评分/费用/计数，63 模型具有相同题数向量（总计 1,270）；3 模型计数向量不同，不进入对照池：`gpt-5.4-nano-xhigh`（1,246）、`gpt-5.4-mini-xhigh`（1,257）、`claude-opus-5-max-effort`（1,271）。另 `ox-alpha-max` 全任务公开费用为 0，作为未验证免费证据排除有价格前沿。最终有价格比较池 62 个动作，静态前沿 9 点：
+
+| 精确动作 ID | 类别等权分 /100 | 公开聚合 USD/题 |
+|---|---:|---:|
+| `deepseek-v4-flash` | 65.48 | 0.010534 |
+| `smaug-flash` | 77.44 | 0.010863 |
+| `deepseek-v4.1-flash-max` | 81.11 | 0.023670 |
+| `gpt-6.1-sol-xhigh` | 81.11 | 0.075744 |
+| `gpt-6.1-sol-max` | 81.62 | 0.115550 |
+| `claude-opus-5-5-xhigh-effort` | 82.06 | 0.199206 |
+| `gpt-6-astra-max` | 82.16 | 0.604605 |
+| `claude-opus-5-5-max-effort` | 83.22 | 0.665127 |
+| `claude-fable-5-1-max-effort` | 83.41 | 1.010765 |
+
+表中只舍入显示；前沿使用未舍入数值。两个显示为81.11的动作原始类别均分分别为81.109702…与81.110190…，故都保留；微小差异没有逐题区间支持，不称统计显著提升。费用沿用作者该release聚合计费口径，不是本项目账单或当前调用报价。这里没有本项目路由的选择记录，因此没有“节省X%且不降质”的实测结论。
+
+## 3 为什么聚合表不能重建路由收益
+
+以下是说明信息缺失的**人工反例，不是 LiveBench 实验**。两道题、两个模型，路由事先固定为“题 1 选 A，题 2 选 B”。
+
+| 数据世界 | A 的逐题质量／费用 | B 的逐题质量／费用 | 每模型公开均分／均费 | 路由均分／均费 |
+|---|---|---|---|---|
+| 世界一 | `(1,0)`／`($1,$3)` | `(0,1)`／`($3,$1)` | 都为 `0.5 / $2` | `1 / $1` |
+| 世界二 | `(0,1)`／`($3,$1)` | `(1,0)`／`($1,$3)` | 都为 `0.5 / $2` | `0 / $3` |
+
+公开的模型任务均分和费用完全相同，固定路由却从高质量低成本变成低质量高成本。聚合过程丢失了查询特征、选中动作与逐题结果之间的联合关系。因此，不论排行榜有多新，不能从均分推出当前算法的质量—成本收益，也不能把任务均分复制成多道题来制造置信区间。
+
+## 4 完整 LiveBench 回放仍需要的数据
+
+取得数据后，必须先完成来源和覆盖审计，再冻结实验。最少字段如下；**这是待采集合同，不是已经拥有的数据**。
+
+- 题集 release、category、task、question_id、完整 prompt 和题目时间元信息。
+- 模型精确版本、provider、effort/reasoning、生成参数、回答、评分器版本及 `[0,1]` 质量分。客观评分可能有部分分，禁止 `Boolean(score)` 或把所有非 1 分剔除。
+- 同题每个候选模型的费用或可复核计费桶，包含缓存、可计费隐藏推理、失败与重试；注明价表时间和估算/实收口径。无法从旧回答重新 tokenize 恢复这些数据。
+- 运行时间、缺失和错误记录。失败不免费，费用未知不是 0，缺失不能按错误标签补齐。
+
+ID 至少按 JSON 编码的 `(release, category, task, question_id)` 连接，不能只按 question_id。再根据规范化 prompt 及同源题族建立 group，防止重命名重复题跨 split。模型变体必须是独立动作；如果采集参数与本项目执行参数不同，只能评价该记录动作，不能冒称本项目线上执行效果。
+
+### 4.1 计划中的固定协议
+
+详情见 [evidence-protocol.json](experiments/20261003-livebench/evidence-protocol.json)。聚合审计的证据界限已固定；逐题协议仍待真实文件的元信息审计，当前不能宣称已完成预注册试验。
+
+1. 同题完整候选池的覆盖资格在看测试优劣之前确定，公开所有排除理由。重复组整体划分；初步计划为 train/validation/test = 60/20/20，以固定盐的 group SHA256 进行划分。跨域重复组必须先合并并确定单一规范 domain，不能为保留分层而拆散。
+2. 使用 train 构造同一套模型能力/费用先验给 0.15.0 和当前版本；关闭额外线上排行榜刷新。validation 选 best-single、cheapest-single 和诊断性 domain-single。每个模型的推理配置固定。需要学习/校准时另建独立校准集，本协议本身不认证概率。
+3. 两版路由只读取 query 与冻结 profiles，不读取 test 答案、质量分、实际输出 token 或逐题费用。先写出全部选择并保存 hash，再连接结果。置换 test 标签或放大 test 费用不得改变选择。
+4. 主实验限定为 `first-stage-model`：比较两版首个工作包所选动作在原题作者记录上的直接回答。**不重放 DAG**，也不测新推理等级的效果。另报告两版都恰好一个执行节点的共同子集覆盖，不能仅挑当前版容易完成的题。
+5. 主比较为当前 balanced 分别对旧 balanced、validation best-single、domain-single，共 $K=3$。domain-single 只有在可获得相同 domain 信号时才是可部署基线；否则明确称使用基准域标签的诊断参照。随机、cheapest、其他 preset 和 hindsight Oracle 只作描述性补充，Oracle 不可部署。
+6. 质量不降且费用严格降低才是收益。未经独立业务依据，不临时放宽非劣边界；初步主协议取 $\delta=0$。不得挑选 test 上最好的预算、seed 或 preset 作为主结果。
+
+费用条件若只能用作者 token × 历史价表估算，结论只能是“该历史名义计费口径下的收益”；不能换成当前价表后仍称真实账单。当前价表重新计算须另标 counterfactual repricing。不能把模型输入/输出平均 token 当作每题实际用量。
+
+### 4.2 已实现的配对统计
+
+新模块 [routing-paired-statistics.mjs](../scripts/routing-paired-statistics.mjs) 接收已经冻结选择后连接好的真正逐题结果：
+
+```js
+import { pairedRoutingComparison } from './scripts/routing-paired-statistics.mjs'
+// rows 来自真实逐题记录，不来自排行榜均分。质量保持 [0,1] 部分分。
+const result = pairedRoutingComparison(rows, {
+  strategy: 'new-balanced', reference: 'old-balanced',
+  seed: 20261003, resamples: 4000, alpha: 0.05,
+  claims: 3, nonInferiorityMargin: 0,
+})
+```
+
+每行格式为 `{id,groupId,domain,outcomes:{策略名:{quality,costUsd}}}`，每个所比较策略必须在同一行有结果。兼容二元 `correct`；与 `quality` 并存时二者必须严格一致。
+
+逐题差 $d_i=Y_{i,\pi}-Y_{i,b}$、$e_i=C_{i,\pi}-C_{i,b}$；主指标是 $\bar d$、$\bar e$，节省比为 $1-\bar C_\pi/\bar C_b$，不是逐题节省率的均值。宏领域质量差是领域内均差的等权平均。
+
+每次在每个 domain 内有放回抽原数量的 group，整组保留所有题；两个策略共用抽样。组内题数不同会使每次 domain 的题数变化，微质量/平均费用按该次题数加权，宏质量仍领域等权；这是分层整组比率估计，不是固定领域行数权重的另一种估计。每次重新计算微/宏质量、费用和费用比。报告每个指标名义双侧 95% percentile 描述区间（四个区间没有同时覆盖校正），以及按 $\alpha/(2K)$ 分配的质量下界 $L_Q$、费用上界 $U_C$。模块的理论比较规则为：
+
+$$L_Q\ge-\delta\quad\text{且}\quad U_C<0.$$
+
+数值实现另作保守守卫：质量同时要求补偿计算的 $L_{Q+\delta}\ge0$；费用要求 $U_C<-\tau_C$，其中 $\tau_C=32\,\mathrm{Number.EPSILON}\max(\bar C_\pi,\bar C_b)$。使用逐题配对差与补偿求和，保留质量边界残差，不把数值epsilon加进业务margin；费用守卫也没有固定美元门槛。完全相同费用多重集合不因舍入被认作节省；同margin边界的可辨别质量损失不被抹掉。超小量数值无法表达时不得据此通过非劣。这些守卫不是统计保证。
+
+这是近似 bootstrap 推断，**不是有限样本风险保证或正式认证**；Bonferroni 不会修复失真的单项区间。每域只有一个 group 时无法估计该域组间变异，模块报告警告，报告作者不得以退化区间宣称显著性。独立组和分布代表性还需采集设计支持。
+
+空集返回 `null`，不制造 0%；参考平均费用为 0 时节省率为 `null`。若任何重采样的费用比无定义，其区间整体为 `null`，不偷偷筛掉该次抽样。未知费用输入直接拒绝，交由采集报告披露。本轮此模块仅用人工单元测试验证，没有对最新聚合表调用它。
+
+## 5 复现与交付范围
+
+在完整源码目录，Node >=22.19；聚合审计不联网、不调用模型：
+
+```powershell
+npm run audit:livebench -- --input-dir "<LIVEBENCH_INPUT_DIR>" --output "test-artifacts/livebench-aggregate-audit.json"
+node --test tests/livebench-aggregate-audit.test.mjs tests/routing-paired-statistics.test.mjs
+npm test
+npm run check:client
+```
+
+将 `<LIVEBENCH_INPUT_DIR>` 替换为已下载并核对固定来源 hash 的公开输入目录。本页操作示例与仓库中的核验 JSON 使用发布脱敏投影：本机路径改为仓库相对路径或占位符，日期、版本、hash 和数值核验结果保留；公开副本字节不等同原始记录，原始归档保持不变。
+
+其他机器先从固定 revision 获取上述 table/categories/cost 文件到独立目录，并核验 SHA256；`--input-dir` 使用该目录。输出不能放进原始输入目录。报告保存来源哈希、覆盖、排除与局限；相同输入应得到相同结果。
+
+已有二元评估器 `evaluate-routing.mjs` 不因新增工具自动支持 LiveBench 部分分。连续分研究使用新配对模块，不对旧工具静默转换标签。生产 `shared/livebench.mjs` 的能力先验适配与本轮科研统计也相互独立；未将聚合 Pareto 当逐题标签注入生产。
+
+已完成：最新官方来源核验、不可变归档、聚合审计、连续分配对统计及回放协议文档。
+
+本轮全量 `npm test` 为367项：364通过、3项既有Windows条件跳过、0失败；新增两组相关测试共73项（统计52、聚合21）全部通过。`npm run check:client` 成功。原文哈希及数值边界经独立复核；这些都是工程检查，不是回答质量实验。
+
+未完成：2026-06-25 的真正逐题矩阵、0.15.0 与当前版的真实同题质量—成本回放、时间/域外测试、概率校准和完整 DAG/端到端收益验证。下一步需要作者提供该 release 的逐题文件，或另行确认模型池、题集和费用上限后采集新结果；本轮不会自行扩大为付费实验。

package/docs/ROUTING_RESEARCH.zh.md

@@ -0,0 +1,59 @@
+# 模型路由：论文驱动的求解与评估
+
+本说明对应未发布开发版 `0.16.0-dev.1`。稳定 npm 版本仍为 `0.15.0`；本轮不自动上传或替换已发布内容。
+
+详细公式、条件证明、多种子控制实验、原始记录及未来学习/风险认证协议见[数学推导与实验记录](ROUTING_DERIVATION_EXPERIMENTS.zh.md)。
+
+最新数据调查依用户要求改用 LiveBench，见[来源核验与同题协议](ROUTING_LIVEBENCH_VALIDATION.zh.md)：2026-06-25 官方表为66模型×23任务的聚合评分/费用，不是逐题矩阵。已补充严格聚合审计和支持 `[0,1]` 部分分的配对 bootstrap 模块；尚未运行最新真实同题新旧路由比较，也未把旧HF逐题记录冒称最新。
+
+## 为什么先改搜索和评估
+
+[RouteLLM（2024，更新 2025）](https://arxiv.org/abs/2406.18665) 使用查询与偏好数据学习路由。我们尚无本项目的多模型同题质量标注集，不能仅把加权分数改名为“学习概率”，也不能套用论文的节省数字。
+
+[RouterBench（2024）](https://arxiv.org/abs/2403.12031) 将质量与实际推理费用放在同一评估框架中。[LLMRouterBench（2026-01）](https://arxiv.org/abs/2601.07206) 则指出正确专家召回不足，以及多种复杂方法与简单基线之间的差距有限。我们借鉴其评估原则，优先补足候选保留、明确基线和质量—成本核验；本实现不是这几篇论文的算法复现。
+
+## 已实现的改变
+
+1. **候选池无关的成本尺度。** 使用当前工作包的 token 估价（含输入、输出、缓存及推理开销），成本效用为 `1 / (1 + C / C_ref)`。参考价格固定为 input=1、output=5 USD/百万 token，缓存参考价为 1；它是偏好尺度，不是厂商价格或学术最优参数，未来须在验证集调参。加入无关极贵模型不再压平原有成本差。
+2. **保住预算可行候选。** 在质量达标候选中，截断到 12 个候选前先保留已知价格的最便宜路线，以及最高分、最高质量路线；没有路线达标时，沿用质量前 3 名的放宽候选范围。这不是全模型池预算可行性的证明。未知价格不得证明有限预算可行。
+3. **依赖安全的剪枝。** 存在工作包依赖时停用局部路线 Pareto 剪枝：某路线单步稍差，仍可能因避免后续交接而使整体更优。独立工作包的剪枝还必须保留实际效用优势。
+4. **精确/近似分开报告。** 保留候选的笛卡尔空间不超过 4,096 时穷举精确求解；更大空间用宽度 256 的 beam，并在预算约束下保留低成本前缀。精确仅指“保留候选 + 当前代理目标”最优，候选截断和质量估计仍可能漏掉真实最佳模型。
+5. **去掉无证据的加分。** 不再按模型名给整合阶段固定奖励；修复未知模型质量反馈重复加分，按每个工作包分别标记质量证据。派生类别平均分和无来源标记的旧类别缓存不充当未测任务的已知质量；显式 overall 仍是跨任务代理先验，不是逐题证据。费用基线同样过滤图像能力不匹配的路线。模型评分、复杂度、延迟先验、质量门槛和交接罚分仍是可审计启发式，**不是答对概率或质量保证**。
+
+规划输出的 `optimization.search` 报告搜索方式、组合数、扩展状态和 beam 截断；`qualityFiltered`、`paretoPruned`、`candidateTruncated` 分别报告质量筛选、局部剪枝、数量截断；`localParetoDisabled` 与 `optimalityScope` 标明求解边界。
+
+## 已验证与未验证
+
+`tests/routing-optimizer.test.mjs` 包括真实复现的预算候选丢失、依赖交接、无关极贵路线、重复反馈反例；小规模随机 DAG 与独立完整枚举比较，并验证输入顺序不变性和未知价格隔离。
+
+这些测试证明所覆盖输入下的求解行为，**不证明真实回答质量、费用节约或厂商实际模型能力**。仍缺本项目同题多模型质量矩阵、独立校准集、时间/域外测试和真实付费调用验证。本轮没有训练神经路由器、没有额外模型调用，也没有自动付费探索。
+
+## 离线结果矩阵评估
+
+从完整源码运行，不依赖账号，不发送网络请求：
+
+```powershell
+npm run eval:routing -- tests/fixtures/routing-evaluation.synthetic.json
+node scripts/evaluate-routing.mjs --help
+```
+
+内置文件明确标为 **synthetic**，仅用于验证指标和工具，不能作为路由质量基准。真实数据文件可按如下结构准备：
+
+```json
+{
+  "provenance": "recorded",
+  "models": ["p/cheap", "p/strong"],
+  "validation": [{"id":"v1","domain":"code","results":{"p/cheap":{"correct":true,"costUsd":0.001},"p/strong":{"correct":true,"costUsd":0.01}}}],
+  "test": [{"id":"t1","domain":"code","selected":"p/cheap","routingCostUsd":0,"results":{"p/cheap":{"correct":false,"costUsd":0.001},"p/strong":{"correct":true,"costUsd":0.01}}}]
+}
+```
+
+每道题需同一固定模型池的完整结果；正确性标签应来自客观测试或明确的独立评价标准，不能把“请求成功”当作“答案正确”。记录实际 input/output/reasoning/cache token、重试及账单成本；路由器费用另计 `routingCostUsd`，不要漏计已经发生的级联调用。遗漏该字段默认按 0 计算；其他基线的路由开销未测量，报告不是所有策略的完整账单核验。`selected` 必须是事先记录的选择，而非查看测试答案后补选。评估器不代你训练或选择 test 的路线，也不能验证采集数据是否真的无泄漏。
+
+validation 只用于选择 best-single（宏领域正确率、费用、ID 稳定排序）与 cheapest-single（平均费用）；test 用于报告记录路由器、单模型、固定种子随机和事后 Oracle。不同 split 的 ID 禁止重叠，但重命名重复题等语义泄漏仍须采集者检查。
+
+指标包含微/宏正确率、领域正确率、平均模型/路由/总费用、与 Oracle 的正确率差，以及“只有 1 个、2–3 个、4+ 个模型正确”的正确专家召回率。每桶召回为选中正确模型的题数除以该桶题数，空桶为 `null`，不是候选 `recall@k`。Oracle 使用 test 标签，是事后参照，**不可部署**；模型都错误时不算可召回专家。
+
+本工具只评估已记录的单次选择与费用，不重放多工作包 DAG，不比较旧/新算法的真实输出，也不自动给出预算扫描、校准或置信区间。后续应先建立 train/calibration/validation/test 和时间外数据，再固定同一模型池与任务集比较 0.15.0、当前开发算法、单模型及 Oracle，绘制同预算质量/同质量成本曲线；没有这些数据时只报告工程正确性。
+
+`scripts/routing-paired-statistics.mjs` 是另一个科研模块，可对已冻结选择并连接好的真实逐题结果计算整组、领域分层配对区间。它支持连续 `quality`，不改变上述二元工具的输入合同；近似 bootstrap 不是有限样本风险认证，更不能对最新任务均分冒充逐题使用。聚合审计从源码运行 `npm run audit:livebench -- --input-dir <原始文件目录> --output <独立输出文件>`，详见 LiveBench 文档。

package/docs/ROUTING_SELFTEST_STEPS.zh.md

@@ -0,0 +1,192 @@
+# 自行实测：安装验收与模型路由质量—成本实验
+
+日期：2026-10-04。状态：实验方案，真实实验尚未执行。本方案不再等待最新 LiveBench 逐题文件；可以使用你自己新编、具有使用授权的题目，名称写“自建题集”，不要称为官方 LiveBench 最新成绩。
+
+费用口径按用户补充调整：主实验采用各供应商官方计费规则与实际 usage 计算成本（`usage-priced`），不要求账单或实际扣费金额作为开测/统计前提。账单只作可选交叉核验；以下“成本”默认指这一官方定价核算口径。
+
+## 先知道哪些需要你测
+
+| 层次 | 需要实际验证的内容 | 是否调用模型 | 能得到的结论 |
+| --- | --- | --- | --- |
+| A：桌面验收，先做 | 本地安装、UI 排版、配置保存、预览失效、预算提示、真实执行路线 | 大部分不需要；最后做少量调用 | 本机宿主是否可用，不证明选模更优 |
+| B：同题矩阵，主要实验 | 每题让每个候选模型作答、盲评、记录费用，比较冻结的新旧选择 | 需要 | 固定生成设置下的模型选择投影，是否质量不降且成本下降 |
+| C：完整团队，B 后选做 | 带依赖的实际工作包、汇总、改派、失败/重试、总账 | 需要，可能较多 | 真正端到端团队效果；不能由 B 直接推得 |
+
+已有单元测试、合成求解实验和 UI 模拟预览是工程证据；不需要你手工重复每条单测，但要在自己的环境重跑。真实收益、供应商实际模型身份、费用、延迟和宿主交互仍需实测。
+
+重要边界：`buildPlan().selected` 是计划首包选择，复杂题首包可能是分析；`mode: single` 也不保证只有一个节点。当前推荐的 reasoning effort 尚未完整传入执行链。本轮 B 只测 **provider/model 选择投影**，不能宣称同时验证了 effort 优化或 DAG。
+
+## 步骤 1：准备独立测试环境，完成 A
+
+在仓库根目录运行，已有依赖时可跳过安装；依赖安装需要网络，但这些检查不调用付费模型：
+
+```powershell
+Set-Location 'F:\everyAI\dsh-model-router-all\dsh-model-router'
+node --version
+pnpm --version
+pnpm install --frozen-lockfile --strict-peer-dependencies
+npm run build:client
+npm test
+npm run check:client
+npm run pack:local
+npm run preview:ui
+```
+
+项目要求 Node.js 22.19+、pnpm 10.34.6。模拟预览默认 `http://127.0.0.1:4173`；它不是宿主执行验收。将 `dist` 中生成的 `.tgz` 绝对路径填入 Harness 的插件安装框；或者使用包含 `package.json`、`.dsh-plugin` 的内层项目目录。不要把外层 `dsh-model-router-all` 当插件目录。
+
+使用独立测试 profile；备份原 profile/state，不覆盖日常数据。旧新版插件 ID 相同，不在同一 profile 同时启用。记录 Harness 版本、Windows 版本、插件包 SHA-256、源码 dirty 状态；不只写开发版本号。
+
+逐项打勾，截图附窗口大小、缩放和复现动作：
+
+- [ ] 本地包能安装、启用，重启宿主后仍存在；安装失败保存原始错误，不用发布新版本来绕过本地故障。
+- [ ] 1280×720、1920×1080，Windows 100%/125%/150% 缩放下：无遮挡、按钮可见、长模型名不挤坏布局、滚动与弹窗正常。
+- [ ] 空模型目录、未知价格、目录/网络报错有说明，不显示假的免费费用或成功状态。
+- [ ] 配置保存并重启后仍正确；改任务/模型/预算/工作目录后必须重新预览，不能执行旧计划。
+- [ ] 不执行时预览不启动供应商；执行前能审阅路线、读写权限与预算。
+- [ ] 预算不足的提示/暂停先用离线估算或模拟验证；应用预算不是供应商硬扣费上限。
+- [ ] 获得费用上限后，选一个简单题实际执行一次：记录所选与实际 provider/model、实际 cap、返回结果及费用；未知模型身份不算验证通过。
+
+建议记录：`检查项 / 环境 / 预期 / 实际 / 通过或失败 / 截图或日志 / 是否收费`。凭据只留本机安全配置，不放记录、仓库或聊天。
+
+## 步骤 2：先冻结方案，不看结果挑规则
+
+复制配套文件到自己新建的实验目录，保留原模板：
+
+- `docs/experiments/20261004-selftest/protocol.template.json`：预算、模型动作与比较规则。
+- `docs/experiments/20261004-selftest/replay-input.template.json`：仅含题目与冻结 planner 输入。
+- `docs/experiments/20261004-selftest/paired-input.template.json`：后续连接真实结果的统计输入。
+
+模板中的待填 `null`、空模型/结果数组和 `TODO` 必须补全，不是实验数据；有明确关闭语义的 `liveBench: null` 则应保留。正式测试前将协议设为 `frozen` 并保存 SHA-256；以后改规则必须另立实验 ID。
+
+固定 3 个你当前确实可调用的模型（低价、中档、高质量各一个即可；不可根据 test 成绩挑模型池）。每个动作记录精确 provider/model、版本/日期、API 或 CLI 通道、实际 effort、system prompt、解码参数、输出 cap、超时、重试/降级规则。某参数不支持就注明，不能假称三家行为完全一致。
+
+先只做文字直接回答、禁工具和联网，避免把工具能力混进选模比较。一个模型固定一种实际生成设置；两版共享同一动作池、路由档案、价格和可用性。不要拿高 effort 答案去支持低 effort 的选择。
+
+初次 B 推荐 `preset: balanced`、`mode: single`、`liveBench: null`，冻结目录顺序与外部画像；`budgetUsd: 0` 表示 planner 不设预算约束，**不表示免费调用**。另在协议中设置实际采集金额上限，最好同步设置供应商端限额。本轮不证明同预算 DAG 优化；预算敏感性另立实验。
+
+预先登记主比较家族（K=3）：
+
+1. 当前源码 `current-balanced` vs 0.15.0 `old-balanced`。
+2. 当前源码 vs 验证集选出的最佳固定单模型 `validation-best-single`。
+3. 当前源码 vs 验证集分领域固定单模型 `validation-domain-single-diagnostic`；这是依赖已知题目领域的诊断基线，不直接视为可部署路由器。
+
+主指标：逐题 `quality ∈ [0,1]` 的 micro 均值、逐题同口径 USD 成本。默认质量非劣界限为 0；若业务允许下降，必须在 test 前写明具体界限，不能看结果后放宽。macro/逐领域质量、失败率、延迟 p50/p95、截断率和实际预算超限率一并报告。
+
+## 步骤 3：先做小样，确认采集可行再扩大
+
+小样建议 **18 题 × 3 模型 × 1 次 = 54 次模型调用**：6 个领域各 3 题，例如数学、推理、代码、信息抽取、摘要、指令遵循。它用于检查评分、日志、费用和 cap，不用于宣布正式收益。18 题不是统计充分样本。
+
+小样只检查采集链，可以不运行正式比较统计；不从小样成绩推导 test 收益。54 次不包含 A 的冒烟调用、重试和收费裁判，应另计总预算。
+
+自己写新题或用有授权的材料；客观题先写答案/测试，主观题先写 rubric。避免私密资料，不执行模型给出的未知危险代码。先估算 54 次调用与可能重试、评分器的研究总费用，写好金额上限后才采集；超过上限或出现身份/计费异常就暂停，不能靠无休止重试完成矩阵。
+
+小样完成后确定正式样本规模。一个可调整的工作量示例是 **600 题 × 3 模型 × 1 次 = 1800 次调用**，并非已经做过功效分析，也不保证显著。按小样的成对差异、独立题组数和预算重新规划；预算小就报告探索性研究，不承诺收益成立。费用预算包括 train/validation/test 所有调用、失败尝试和评分；后续若增加重复次数，调用量同比增加。
+
+小样题及同材料/近重复模板族不进入正式 test，不能只换措辞或ID就当新测试。正式题目相似改写/同材料题设为同一 `groupId`，重复生成同题也不当作独立样本。跨领域重复题先归并到同一规范领域。
+
+在采集结果前按组划分：`SHA256('dsh-selftest-v1:' + groupId)` 取前 8 个十六进制字符转整数、模 100；0–59 为 train，60–79 为 validation，80–99 为 test。比例约 60/20/20，实际数不必刚好 360/120/120。保存题目清单、split、prompt hash 与评分规则，不能为了结果好看重新分组/划分。
+
+正式 train/validation/test 均须非空；若初始划分为空，先在未查看test结果时补充独立新题组并更新预登记规模，不改salt挑好分组。各领域独立组过少时只能探索性报告，不能用几百条同材料改写伪装大样本。
+
+## 步骤 4：每一题让全部候选作答，保存完整记录
+
+同题给所有候选相同可见输入和输出任务，生成设置按步骤 2 固定。模型调用顺序随机交错，记录时间区间，避免一个模型全在高峰期。采集可以用你已有 API/CLI 或手工执行；**当前项目没有通用矩阵采集器和自动评分器**，以下字段需要你保存，不能把模板当采集结果。
+
+正式阶段先采集/评分 train 和 validation，完成步骤 5 的画像/基线冻结及步骤 6 的 test 选择封存后，再采集和评分 test。若提前采集了 test，结果与评分必须由独立人员/存储封存，调参者不可查看。这里的步骤 4–6 分阶段执行，不是先看完全部题目成绩再选规则。
+
+每次尝试至少记录：
+
+- 题目：`id / groupId / domain / split / 完整 prompt / promptSha256 / 题集日期`。
+- 动作：实际 provider/model/version/effort、完整生成设置、通道、请求或响应 ID、时间戳。
+- 原始结果：完整回答、错误类型、每次重试/降级、输出是否截断、耗时；可用时保存 TTFT。
+- 用量与费用：输入/输出/缓存/推理 token 的厂商原字段、每次尝试金额、币种、计费来源与价格生效日期。
+- 评分：quality、评分规则/评分器版本、评分理由与盲评标识。
+
+不要只依赖插件历史：任务和回答摘录会截断，无法替代完整实验原文。原始响应另存，只分享脱敏副本。
+
+主实验的 `costBasis` 使用 `usage-priced`：按每个具体模型/供应商的官方价格与计费说明，乘以实际返回的 usage，得到可复算的官方定价成本。无需等待账单；`invoiced` 只用于你愿意另做的实际扣费核验。官方价核算不是账户折扣、赠额、订阅或中转商的实际扣款，报告将两者区分即可，不因此阻止实验。
+
+### 官方计费成本怎么计算
+
+1. 选定动作后，为每个精确 provider/model/版本/接口保存官方价格页与 usage 字段说明、查阅日期、生效时间、原币种及计量单位。记录服务档、上下文长度档、缓存TTL、批量/实时模式以及适用的时段规则；不把同名模型不同通道的价格混用。
+2. 将原始 usage 按官方说明拆成不重叠的计费项，再用对应费率。通用记账形式是 `单次成本 = Σ(该计费项实际用量 × 单价 ÷ 该单价对应的计量单位) + 适用非token收费`；只有全部单价都按百万token时，才统一除以 `1,000,000`。这不是要求所有供应商使用同一种输入字段。
+3. 缓存读、不同TTL缓存写、普通输入、输出分别按文档计费；总输入字段若已包括缓存，不能整段按普通输入价格计一次后再加缓存费。推理token若已含在计费输出总数中，不能再加一次。原字段保存不变，另外记录你的映射和计算过程。
+4. 对每次实际尝试单独计算并相加，计入可确认的失败/重试、工具等费用。重试次数不等于每次都一定收费；应以厂商计费规则和真实用量为准。没有usage或关键计费项时保持未知，不按字符数、任务预算或可见回答长度伪造实际token，也不能填0。
+5. 冻结的是价目表和计算规则版本，不是把不同长度档/时段硬塞成一个费率。跨价格变更时逐次记录当时费率；若另外用统一日期价目表重算，标明为统一价反事实成本，不冒充历史实际费用。原币非USD时保存换算来源/日期，不混加币种。
+
+规则核对示例（2026-10-04，未替你指定候选模型或填价格）：[DeepSeek官方价目表](https://api-docs.deepseek.com/quick_start/pricing/)区分缓存命中/未命中与适用时段；[Claude缓存文档](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)区分普通输入、缓存读与缓存写的usage；[Claude推理计费说明](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost)明确计费输出总数包含推理token。这些示例说明应逐供应商映射，不代表所有模型已经完成价格登记。
+
+直连API按该供应商官方规则核算；若你选择订阅CLI或中转通道，却统一采用原厂API价格做比较，标为“官方标准API等价成本”，不要称为该通道实际扣费。CLI未提供完整usage时，改用能记录真实usage的采集通道或补齐日志。插件规划的 estimatedSavings 仍不是实测成本。
+
+提前固定失败规则：超时/拒答等导致无可用答案，可在“运营质量”指标记 0，但必须保留尝试和费用。缺日志、没采集到或费用未知属于缺数据，不冒充答错/免费。截断回答按冻结规则评分，不自动丢弃。任何排除都报告数量与覆盖，禁止根据“这题新版选错/更贵”删题；无法形成完整成本矩阵时先报告缺失，不能宣布完整收益。
+
+## 步骤 5：盲评，再用 train/validation 冻结画像和基线
+
+数学/抽取按答案，代码按隔离环境中的测试，摘要/指令按先写的 rubric。主观评分隐藏模型名、版本和成本，随机回答顺序；可以用双人评分并处理分歧。若用模型裁判，冻结裁判模型/提示词，并人工抽查；评分器费用记入研究预算，不冒充路由执行费用。
+
+quality 直接保留 `[0,1]` 部分分，不能 `Boolean(score)`。验证回答的是同一个 prompt、动作设置与 cap；不同提示词实验必须分开。每题全部候选均有原始回答、评分和同口径成本才进入完整矩阵核验。
+
+train 仅用于建立模型质量/专长等档案；无新学习器时不声称完成概率校准。两版使用相同冻结画像，不能新版用真实 train、旧版用默认弱画像。validation 选择最佳固定单模型及分领域单模型：最高平均质量，平手按较低平均成本，再按稳定动作 ID；某领域 validation 没有完整有效题时，预登记回退到全局 validation-best-single，并报告覆盖。若全局也没有完整有效题则暂停，不用 test 选基线。test 不能参与此选择。若以后学习策略或调参，也只能用 train/validation。
+
+单价、latency/risk、目录和 LiveBench 输入也冻结；没有依据的风险/延迟保持“未测”标记，路由器缺省代理值不能当实测结果，不把 test 标签换成“任务质量分”。将每题原文和同一个 plannerInput 写入独立 `replay-input.json`，这个文件不能含答案、评分或结果字段。
+
+`plannerInput.available` 每项用宿主准确的 `provider`、`model`；`quality` 为该模型 train 分的 `[0,1]` 均值，`qualityBias` 设 0，`pricing` 的 input/output/cacheRead/cacheWrite 为 USD/百万 token。实际支持可控 effort 时，`reasoningEfforts` 只放本轮固定的那个 ID，`defaultReasoningEffort` 同值；否则注明供应商默认/不可控。latency/risk 是归一化代理而不是毫秒/错误率，若加入必须事先定义变换；不可直接填毫秒数。另保存每个字段的 train/价格来源。不要依赖内置目录的历史模型质量和价格作为本次真实证据。
+
+## 步骤 6：离线生成两版选择，先存 hash 再连接 test 结果
+
+本次配套增加了两个小型离线入口，只在 Git 源码仓库中使用；不会调用模型。正式 `replay-input.json` 的 queries 仅放冻结划分中的 test 题，题目ID逐一对照split清单，不混入train/validation/小样；探索性回放另存。旧版基线目录已存在，但使用前仍需核对：
+
+```powershell
+git -C .\test-artifacts\github-0.15.0-checkout rev-parse HEAD
+node .\docs\experiments\20261004-selftest\replay-choices.mjs --help
+node .\docs\experiments\20261004-selftest\replay-choices.mjs .\my-experiment\replay-input.json .\test-artifacts\github-0.15.0-checkout | Out-File -Encoding utf8 .\my-experiment\choices.json
+Get-FileHash -Algorithm SHA256 .\my-experiment\choices.json
+```
+
+基线应为 `aca9912921aee50858e4b95c8698e3177e22335c`；若目录缺失或 commit 不符，先核对来源，不用别的版本冒充。当前 dirty 源码由辅助入口记录 shared `.mjs` hash，另保存 `git status --short`。保存两版完整 plan、首选 provider/model、节点数和输入 hash；plan 的 generatedAt 不用于选择一致性比较。
+
+此入口只把两版 `plan.selected` 投影到固定模型池。空选择、池外选择、不同 effort/cap 或无法匹配的动作必须报告；不能事后换成该题最高分模型。补充分析若只看“两版都恰有一个 execution 节点”的题，必须依据 query/plan 定义资格并报告覆盖，不能假称所有 single 计划都是这种情况。
+
+确认选择文件封存后，按步骤 4–5 的冻结采集/评分规则取得 test 矩阵，再按精确题目+动作连接真实 test quality/cost，生成 `paired-input.json`：每行有相同 `id/groupId/domain`，outcomes 包含四个策略的 quality/costUsd。策略成本是选中动作由真实usage按冻结官方规则计算的成本，加预先约定的路由开销；无需账单，未知用量/费用不能填零。本地无供应商调用的 planner 可记供应商路由费 0，CPU时间另记，不能一概把其他开销记 0。
+
+做泄漏自检：保持 query-only 输入不变，仅在外部结果副本中打乱标签、将 test 成本乘 10，再运行选择；去掉 generatedAt 后选择必须不变。辅助入口拒绝题目中的结果字段，但仍需人工核对画像确实来自 train。
+
+注意：为了采集矩阵，你实际上支付了全部模型调用费用。按某个策略选中单元格得到的是“固定直接回答实验下的回放成本”，不等于这次研究账单已经省钱，也不是完整生产 DAG 成本。
+
+## 步骤 7：算配对统计，按预先规则判断
+
+先在 `protocol.json` 写好并冻结比较家族与统计设置；把选择文件 hash 填入 paired 输入，未知成本保持缺失并先解决数据核验。配套入口支持连续分：
+
+```powershell
+node .\docs\experiments\20261004-selftest\analyze-paired.mjs --help
+node .\docs\experiments\20261004-selftest\analyze-paired.mjs .\my-experiment\paired-input.json .\my-experiment\protocol.json | Out-File -Encoding utf8 .\my-experiment\paired-report.json
+```
+
+默认 seed=20261003，4000 次、领域内整组配对 bootstrap，alpha=0.05，K 取完整比较家族数。质量差为“新−基线”，成本差也为“新−基线”；节省比例为 `1 − mean(Cnew)/mean(Cbase)`，不是逐题节省率平均。
+
+正式 `paired-input.json` 的 stage 为 `test`，rows 只含冻结划分中的 test 题，不混入 train/validation/小样；辅助入口只校验字段，split 成员身份仍需和封存清单核对。
+
+每个比较只有同时满足以下条件才有“质量不降且成本下降”的近似统计支持：
+
+1. 经比较家族校正的一侧质量下界 ≥ 负的预登记非劣界限，并通过补偿计算的边界检查。
+2. 一侧成本差上界严格低于公开数值容差的负值。
+
+“没有显著变差”不等于非劣成立；某一对通过不代表三对都通过。样本少或每领域只有一个独立组时不宣布可靠结论。bootstrap 是近似推断，不是有限样本风险认证；辅助工具不能自动认证原始数据真实性、组独立性或 test 没被偷看。
+
+以 `usage-priced` 作为主成本轴即可检验“在官方计费口径下，质量不降且成本下降”，不用等账单；结论写清所用规则/日期。只有另外声称账户实际扣费节省，才需要对应扣费证据。没有通过时写“证据不足/质量下降/费用未下降”，不要自动调规则重测同一 test。最佳便宜单模型、随机和事后 Oracle 可作描述性补充，Oracle 不可部署；增加正式比较时必须事先扩充 K。
+
+现有 `node scripts/evaluate-routing.mjs <dataset.json>` 是另一个二元 `correct:boolean` 描述工具，依赖外部提供的 selected，不采集、不生成双版本选择。连续分实验使用本步骤入口，不把部分分硬转布尔。
+
+## 步骤 8：B 后再单独做 C，最后形成报告
+
+若要验证用户真正感受到的“团队更好/更省”，另立协议，使用新任务：先做 4 个工作流排障，再按预算扩至例如 20 个。旧新版本的最终交付标准相同，固定运行环境、权限、工具/模型池、可见文件、预算和超时；运行顺序交错，每次从等价的独立输入工作区开始。具体样本与重复数仍须规划，不沿用 B 的显著性结论。
+
+保存实际执行 plan 与每个工作包上下文、实际模型/设置、依赖答案、汇总、重试/降级、工具/复核调用、完整最终结果和累计总成本。执行入口可能重新规划，不能只保存 UI 初次预览。对最终成果盲评，与实际总账成对比较，同时报告工作流成功率和耗时；订阅/API账分开。
+
+没有实际观测到 effort 被传入并生效时，写“未验证/实现缺口”；若要实验 model×effort 联合策略，先补齐执行链并采集各动作矩阵，另立方案。本指南不自动修复该实现缺口。
+
+最后交回：冻结协议、题目与分组划分、动作设置、脱敏原始响应、逐题评分与费用、两版选择/完整 plan、hash manifest、配对报告、UI验收记录、失败/缺失/覆盖表。研究总花费和策略回放费用分别列出；结论限定到本次题集、日期、动作池与执行协议，不外推所有模型或未来版本。
+
+第一轮建议只完成 A 与 54 次小样。记录可靠、金额可接受后，再决定正式规模；目前没有进行真实采集，也没有验证真实收益。
+
+相关文档：[推导与已有实验](ROUTING_DERIVATION_EXPERIMENTS.zh.md)、[LiveBench 验证协议](ROUTING_LIVEBENCH_VALIDATION.zh.md)、[数据检索结束记录](ROUTING_LIVEBENCH_DATA_SEARCH.zh.md)、[工作台指南](WORKBENCH_USER_GUIDE.zh.md)。