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

package/docs/ROUTING_ADAPTIVE_LEARNING.zh.md

@@ -0,0 +1,151 @@
+# 动态数据与持续反馈：模型路由的推导、实现和实验
+
+研究日期：2026-10-04。原实验对象：源码开发版 `0.16.0-dev.1`。该实现随正式版 `0.16.0`（2026-10-05）发布，原实验时间与合成结果保留，不将正式发布视为真实收益验证。
+
+本轮已把动态数据和主观反馈接入 Host 与工作台，而不是只提出研究方案。验证使用真实规划器、合成反馈和模拟公开源，未读取用户历史、调用付费模型或证明真实质量—成本收益。此前的 [静态推导与 LiveBench 先验实验](ROUTING_DERIVATION_EXPERIMENTS.zh.md) 保留为冻结的历史研究；本篇记录新增闭环。
+
+## 1 为什么要拆成三层
+
+| 数据层 | 更新来源 | 影响什么 | 不代表什么 |
+| --- | --- | --- | --- |
+| 公共价格 | 用户选择的公开、按官方文档核对的 JSON 快照 | 下一次规划费用；当次 usage 计费估算 | 已自动抓取所有厂商官网、账号实际账单 |
+| 公共能力 | LiveBench 官方发布或明确比例的 JSON 镜像 | 任务类别能力先验、原有代理质量门槛 | 特定查询答对概率、用户个人满意度 |
+| 本地偏好 | 对真实记录结果的有用/不好/撤回 | 独立、有限幅度的偏好效用 | 模型客观能力变强、未选模型的成绩 |
+
+旧实现把人工点赞和模型复核混入全局质量偏置。本轮生产路径不再使用该标量：模型复核保留展示和费用记录，只接受明确主观评价作为个人学习输入。旧的纯函数接口仍为程序调用兼容保留，不能据此判断当前 Host 使用旧机制。
+
+非平稳环境需要允许政策随分布变化；相关上下文 bandit 研究提供了更强的检测和遗憾界。但本轮只采用有边界的时间折扣偏好估计，没有复现这些算法，也不继承其收敛保证。[Luo 等，2018](https://www.microsoft.com/en-us/research/publication/efficient-contextual-bandits-non-stationary-worlds/)
+
+## 2 主观偏好估计的推导
+
+设某个本地工作室中，准确 `provider/model` 和任务类别 `d` 的有效结果集合为 \(I_{m,d}\)。人工评价 \(r_i\in\{-1,+1\}\)，不评价或撤回不产生样本。完成时间为 \(t_i\)，当前时间为 \(t\)，半衰期为 \(H\)：
+
+\[
+w_i(t)=2^{-(t-t_i)/H},\qquad t_i\le t.
+\]
+
+以零偏好为收缩中心，求解加权、正则化的平方损失：
+
+\[
+\widehat\theta_{m,d}(t)
+=\arg\min_\theta\left\{\kappa\theta^2+
+\sum_{i\in I_{m,d}}w_i(t)(r_i-\theta)^2\right\}.
+\]
+
+令导数为零；\(\kappa>0\) 保证唯一解：
+
+\[
+\widehat\theta_{m,d}(t)
+=\frac{\sum_iw_ir_i}{\kappa+\sum_iw_i},\qquad
+b_{m,d}(t)=B\widehat\theta_{m,d}(t).
+\]
+
+实现还显式截断到 \([-B,B]\) 作数值保护。由于 \(|r_i|\le1\)，
+
+\[
+|b_{m,d}(t)|\le B\frac{\sum_iw_i}{\kappa+\sum_iw_i}\le B.
+\]
+
+默认 \(H=30\) 天、\(\kappa=3\)、\(B=0.04\)。一条刚完成的好评只给 \(0.01\) 的效用调整；同域20条新好评为约 \(0.0348\)。半衰期让**样本权重**减半，不让收缩后的偏置恰好减半，因为分母也会变化。持续无新证据时，偏好逐渐回到零。
+
+有限证据且 \(B>0\) 时上界严格小于 \(B\)；允许设置 \(B=0\)，此时偏好项恒为零。
+
+这不是概率校准，也不是把人工评分减去 LiveBench 分数的“质量残差”。\(r_i\) 衡量有用与否，\(b\) 的单位是现有归一化规划效用；\(B\) 是工程影响上限，需要后续独立数据选择，不是理论最优参数。
+
+实现每次从最近200条运行重算，不仅更新累积计数，因此同一 `runId/packageId` 的改评不会重复加样本，撤回立即移除证据，重跑替换结果后清除旧评分。它是有界滑动窗口，不是无限长期记忆；费用累计的既有保留机制与学习窗口分离。
+
+## 3 如何进入现有分配目标
+
+原有任务代理效用记为 \(U^0_j(m;t)\)，包括能力、当期费用、延迟、专长、推理适配、风险和质量短缺惩罚。本轮使用：
+
+\[
+U_j(m;t)=U^0_j(m;t)+b_{m,d_j}(t).
+\]
+
+组合求解器继续最大化工作包总效用减去交接惩罚，并执行原有预算与代理质量约束。关键区别是：
+
+\[
+q_{m,d_j}(t)\ge\tau_j
+\]
+
+中的 \(q\) **不加入** \(b\)。好评不能把不满足质量门槛的模型抬进可行池，也不能把 unknown/catalog-heuristic 改标为 LiveBench 证据。若整个池都不满足门槛，原有放宽分支仍会明确 `constraintRelaxed`；这不等于偏好绕过门槛。
+
+固定候选下新增有界可加项，不改变 exact/beam 的工程范围。Pareto 剪枝仍必须同时保持实际效用，不能只比较名义质量与费用；含依赖交接的局部剪枝仍关闭。有关条件保证见主推导报告。
+
+## 4 数据刷新、版本与历史费用
+
+用户在“预算与安全 → 动态公共数据”启用公开源后，打开/刷新账本、生成建议及 Host 规划/执行前按 TTL 检查。默认关闭；默认检查间隔24小时。失败重试间隔为 `min(TTL, 5分钟)`。没有后台定时任务，不使用时不会自行联网，也不为学习额外调用模型。
+
+更新流程为“公开地址校验 → 跨进程请求预留 → 有界下载 → 整包验证 → 原子保存”。同进程请求合并，晚到回包不能覆盖另一个请求的更新。每份快照记录来源、核验日、发布日期、版本及 SHA-256 内容身份；刷新失败保留最后有效快照并显示过期/失败状态。清空一个源会立即停止使用该源，但保留磁盘最后有效副本以便恢复。
+
+LiveBench 官方发布日不允许倒退。没有发布日期的镜像只能获得内容身份，不能证明其时间顺序。官方 CSV 固定按0–100解释；动态自定义镜像必须是 JSON 且声明 `scoreScale: 1` 或 `100`，拒绝超范围数据和模型规范化碰撞，不把百分制1分当满分。旧的非动态 CSV/JSON 适配调用保留兼容格式，不等于动态入口放宽验证。
+
+LiveBench 动态快照按完整原始名称匹配，不猜 API 别名。模型配置新增 `benchmarkModel`：仅在确认版本及测量设置一致后填写榜单中的准确名称。它是用户声明，不是执行证据，不能将 max 档评分当作 low 档的实测。当前还没有完成 `(model, effort)` 联合执行验证，真实验证仍应固定实际模型/档位。
+
+任务类别映射是启发式先验：普通 Coding 映射 code，Agentic Coding 不覆盖它；Data Analysis→research、Language→writing、IF→summarization。缺少类别时遵循现有显式/派生 overall 的证据规则，不能把这种映射叫特定查询校准。
+
+价格快照只支持准确路线、USD/百万token的固定输入/输出和可选缓存费率，人工填写的价格优先。每路 `asOf` 不允许倒退，重复路线、币种/单位错误或复杂阶梯字段使整包更新失败。**这是按官方文档策展的数据接口，不是通用官网自动抓价服务**；填写 `sourceUrl` 也不会自动认证其内容。阶梯、时段、长上下文、TTL、Batch、音视频等复杂计费不能强塞成统一单价；需另加对应厂商适配器或按原实验协议计算。
+
+运行记录冻结当时使用的费率、来源、版本及模型数据/偏好策略版本；后续更新不重写旧费用。旧记录不补造来源。订阅参考费用与 API 预算仍分开，缺失 usage/价格保持未知；当次计费估算使用当前有效快照，过期快照也可能继续作为估算，不能承诺等于现行官网价或真实账单。
+
+## 5 反馈有效性、停用与范围
+
+Host 用 `runId/packageId` 反查结果，客户端不能提供模型、任务域或用户ID来伪造学习事实。工作台反馈携带所见结果的 `expectedFinishedAt`；重跑后旧页面不能给新结果误评。Host 写入 `ratedAt`、策略版本和输入来源；衰减仍使用完成时间，反复点击旧答案不能刷新证据年龄。
+
+仅 `ran=true`、`ok=true` 的成功结果参与学习；等待、取消、未执行、失败和不合法时间不自动当差评。CLI 未明确报告相同实际模型时不训练推荐模型。缺少执行标记、结果ID或可用时间的旧记录不猜测；缺少type按general，缺少ratedAt沿用完成时间，不要求旧记录已有策略/来源标签。模型可调用的评价工具要求 Host 审批，Agent 不得自动自评；来源标签仅作审计，不是独立人类身份认证。
+
+可停用学习，设置半衰期/收缩/上限，或“从现在重新学习”。重置仅排除在起点及之前完成的结果，不删除运行、评分展示或费用。模型别名后台换版无法从相同字符串自动检测，需固定版本ID或人工重置。
+
+范围为本地 `DSH_HOME` 工作室，不是可信多租户账号隔离。不同用户应使用独立 DSH_HOME；同目录用户共享记录和偏好。未实现账号权限、跨设备同步或无限长期用户画像。
+
+## 6 已开展的实验与复现
+
+入口：
+
+```powershell
+node scripts/adaptive-routing-study.mjs --out docs/experiments/20261004-adaptive-routing/adaptive-study.json
+node --test tests/adaptive-*.test.mjs tests/dynamic-data.test.mjs
+npm run build:client
+npm test
+npm run check:client
+```
+
+固定时钟及虚拟 A/B 路线，调用真实 `buildPlan`、`createPlanFromRoutes`、反馈函数及费用记录函数。结果文件：[adaptive-study.json](experiments/20261004-adaptive-routing/adaptive-study.json)。全部标签、能力分、价格和 usage 都是合成，不是最新 LiveBench 逐题数据或真实用户结果。
+
+| 实验 | 控制与操作 | 观测 |
+| --- | --- | --- |
+| 正常使用反馈流 | 36轮，只给当轮选中模型合成评价 | 首轮A差评后下一轮B，最终35次B好评；B效用调整约0.03684，能力分始终0.90 |
+| 偏好漂移 | 180天前40条A好评，一小时前4条A差评 | 30天半衰期有效权重约4.621，选B；3650天控制约42.656，仍选A |
+| 价格版本变化 | 只改变假设价：A每百万0.1→5，B保持2 | 同一质量与任务下A→B；不是费用节省百分比实验 |
+| 基准版本变化 | 切换合成 LiveBench-shaped 分数 | 同一费用与任务下A→B；不是实际榜单新旧收益 |
+| 门槛保护 | A能力0.65，200次好评，调整上限0.1 | 仍选达到0.78门槛的B；客观分不被改写 |
+| 撤回与重置 | 从已学习状态移除证据/设置起点 | 恢复未个性化选择；合成记录费用约0.02592美元不变 |
+
+以上9个机制检查全部通过。独立集成测试另外验证 Host 真实开启数据刷新、同一快照 Client/Host 投影一致、人工价优先、清空源不误用缓存、费用版本冻结、旧时间戳拒评，以及20条按域反馈改变选模而不改变客观评分。测试使用独立临时 DSH_HOME、内存公开源和模拟模型流。
+
+浏览器核验只操作内存演示页：参数保存、学习停用、反馈/撤回及重新规划；不等价于真实 Harness Desktop 端到端验收。完整测试日志与源码哈希归档在本轮 exports 目录，历史实验文件不覆盖。
+
+## 7 尚未证明的收益与下一步真实实验
+
+只观察被选择模型的反馈，既有政策会决定可观测样本；不评价的用户也可能系统性不同，因此本轮估计的是已观测结果的偏好，不是所有任务总体满意率。没有随机探索及正概率覆盖，不能用这些日志无偏评估未选模型或宣称找到全局最优。[Li 等，2015](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/paper-7.pdf)
+
+真实验证应沿用 [同题实验步骤](ROUTING_SELFTEST_STEPS.zh.md)，补充时间顺序而非仅随机划分：
+
+1. 固定真实模型/版本/档位、官方计费函数、评价标准和费用上限；冻结数据快照与个人学习参数。
+2. 先采集训练/调整阶段的合法人工评价，再冻结策略；测试阶段评价不得回灌同一轮选择。
+3. 在时间外同题集比较“固定先验、仅动态价格、仅动态评分、仅反馈、三者合用”，预先规定非劣界与分组统计方法。
+4. 分别报告客观任务评分、个人满意度、真实 usage 成本、失败率、反馈覆盖率和策略/价格漂移；不把个人满意度改善替代客观质量非劣。
+5. 获得充分覆盖后才考虑用户明确同意、有预算约束的探索及 propensity 记录；本轮未实现，也不默认进行。
+
+因此已完成的是可持续更新的工程闭环、估计式推导和机制实验；真实质量—成本收益、最优参数、跨用户泛化以及实际推理档位验证仍未证明。
+
+## 8 实现索引
+
+- `shared/adaptive-feedback.mjs`：显式反馈、去重、时间折扣、收缩、重置与独立偏好字段。
+- `shared/dynamic-data.mjs` / `dynamic-data-view.mjs`：Host公开源刷新与浏览器安全投影。
+- `shared/livebench.mjs` / `model-profiles.mjs`：严格动态适配与准确基准映射。
+- `shared/router.mjs` / `harness-plan.mjs`：独立偏好效用、原有质量/预算约束与版本说明。
+- Host `index.mjs`、`router-state.mjs`、`run-ledger.mjs`：持久快照、反馈绑定和历史费率。
+- Client `catalog.mjs`、`router-main.jsx`、`router-insights.jsx`：同源规划、陈旧回包保护和设置界面。
+
+这些路径相对 `.dsh-plugin/`。2026-10-04研究阶段未推送、发布npm或变更用户现有设置；2026-10-05按用户要求将实现纳入正式版`0.16.0`，发布状态及安装方式见README/CHANGELOG。发布不自动修改用户现有设置或发起付费模型调用。