@ljwei-stak/dsh-model-router 0.24.0 → 0.25.1

package/README.zh.md

@@ -10,7 +10,7 @@
 
 面向 **DeepSeek Harness Desktop** 的成本感知模型路由工作台。在本地规划任务、比较已配置路线、检查执行权限，并通过模型 API 或支持的厂商官方 CLI 执行有依赖关系的工作包。
 
-当前版本：**0.24.0**（`@ljwei-stak/dsh-model-router`）。并发执行现在会在共享持久状态中预占剩余估算预算；每个工作包调用前、收到结果后都必须保存检查点。中断任务保留预算预占和待核对费用证据，工作台分别显示已记录支出和预占估计。新增 Windows/Linux Node 24 CI，执行全量测试、客户端构建和包完整性检查。工作台支持实时耗时、逐工作包进度和取消，保留已完成结果与已报告费用；关闭重开面板可接管原任务。支持“按算法推荐分配 / 手动调整分配”：拆分后的工作包可逐个指定模型 API 或官方工具，保留依赖、重新预览费用，并保存重跑目标。同时接入任务相关质量证据、模型与推理档位联合选择、历史资源 P90 估计与依赖感知搜索。手动混合执行当前只读；官方工具使用自身默认模型，原有官方团队编辑流程保留。继续兼容 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**，沿用 Hermes/Pi 安装与终端支持；两者仍无经过验证的托管执行器。真实厂商执行证据仍见 **0.20.0** 报告，本版未新增模型实测。路由器与 [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) 自 0.12.0 起已拆分为独立插件。
+当前版本：**0.25.1**（`@ljwei-stak/dsh-model-router`）。本次兼容更新使用 **0.2.1-rc.3** SDK 构建，并将该 Host 版本加入原有 peer 范围。API 按金额核算并检查日/月预算和预占；订阅独立统计调用次数与已报告 token 用量。已确认的订阅通道不会仅因 API 预算用满或缺少 API 单价而被阻止；真正转 API 前须对实际路线重新估价并通过预算预占，混合结果分别保留两个通道的收据。工作台把 API 支出/预占与订阅用量分开，缺失用量保持未知。工作台支持实时耗时、逐工作包进度和取消，保留已完成结果与已报告费用；关闭重开面板可接管原任务。支持“按算法推荐分配 / 手动调整分配”：拆分后的工作包可逐个指定模型 API 或官方工具，保留依赖、重新预览费用，并保存重跑目标。同时接入任务相关质量证据、模型与推理档位联合选择、历史资源 P90 估计与依赖感知搜索。手动混合执行当前只读；官方工具使用自身默认模型，原有官方团队编辑流程保留。兼容 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2 / 0.2.1-rc.3**，沿用 Hermes/Pi 安装与终端支持；两者仍无经过验证的托管执行器。真实厂商执行证据仍见 **0.20.0** 报告，本版未新增模型实测。路由器与 [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) 自 0.12.0 起已拆分为独立插件。
 
 官方 CLI 协作按依赖顺序逐包执行、传递依赖上下文，不会自动回退到模型目录 API。可编辑团队需明确选择 Harness 沙箱或厂商 CLI 正常环境。后者通过 Git worktree 收集修改，但不限制操作系统访问。未显式设置模型映射时，各 CLI 沿用自身配置的模型。参见[真实 Windows 验证及其局限](docs/releases/0.20.0-validation.md)。
 
@@ -27,26 +27,26 @@
 **安装（DSH Plugin Hub / web profile）：** 确保 DSH CLI 可用，然后安装已发布的 npm 包：
 
 ```sh
-dsh plugin --profile web add @ljwei-stak/dsh-model-router@0.24.0
+dsh plugin --profile web add @ljwei-stak/dsh-model-router@0.25.1
 ```
 
 **安装到 Harness Desktop：** 首次先启动一次 Desktop 初始化 `desktop` 配置，再彻底退出 Desktop，运行：
 
 ```sh
-dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.24.0
+dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.25.1
 ```
 
 也可以在 **Harness Desktop → 插件 → 添加插件** 中粘贴包名。安装后重启 Desktop。单独运行全局 `npm install -g` 不会注册 Desktop 插件。
 
-**发布包与入口：** [npm 上的 `@ljwei-stak/dsh-model-router@0.24.0`](https://www.npmjs.com/package/@ljwei-stak/dsh-model-router)。根目录[`package.json`](package.json)声明包名和 bundle patch；[`.dsh-plugin/index.mjs`](.dsh-plugin/index.mjs)导出所需的 `apply(ctx)` 入口。[许可证：MIT](LICENSE)。
+**发布包与入口：** [npm 上的 `@ljwei-stak/dsh-model-router@0.25.1`](https://www.npmjs.com/package/@ljwei-stak/dsh-model-router)。根目录[`package.json`](package.json)声明包名和 bundle patch；[`.dsh-plugin/index.mjs`](.dsh-plugin/index.mjs)导出所需的 `apply(ctx)` 入口。[许可证：MIT](LICENSE)。
 
 **配置文件与配置入口：** 当前不支持导入用户编写的 JSON/YAML 配置文件。Provider、模型和凭据在 Harness **模型**页面配置；路由档案与偏好在插件设置中配置。路由器持久状态存于 `$DSH_HOME/model-router/state.json`（默认：`~/.dsh/model-router/state.json`）。Provider CLI 沿用各自的登录和配置；路由器不会把 API 密钥复制进模型档案或终端日志。
 
-**截图与证据：** [工作台截图](docs/assets/workbench-task-preview.jpg)使用固定的模型、价格和健康状态数据，是模拟 UI 预览，不是实时 Harness 或模型运行。[路由流程图](docs/assets/routing-workflow.svg)展示执行路径。[真实 Windows 验证报告](docs/releases/0.20.0-validation.md)记录了 0.20.0 的具体执行及局限；0.24.0 尚无经过验证的端到端厂商运行。[实时进度截图](docs/assets/workbench-run-progress.png)是离线模拟；预算预占、检查点与验证边界见[0.24.0 验收报告](docs/releases/0.24.0-validation.md)。
+**截图与证据：** [工作台截图](docs/assets/workbench-task-preview.jpg)使用固定的模型、价格和健康状态数据，是模拟 UI 预览，不是实时 Harness 或模型运行。[路由流程图](docs/assets/routing-workflow.svg)展示执行路径。[真实 Windows 验证报告](docs/releases/0.20.0-validation.md)记录了 0.20.0 的具体执行及局限；0.25.1 尚无经过验证的端到端厂商运行。[实时进度截图](docs/assets/workbench-run-progress.png)是离线模拟；API/订阅分开计算与检查点见[0.25.0 验收报告](docs/releases/0.25.0-validation.md)，SDK 兼容与验证边界见[0.25.1 验收报告](docs/releases/0.25.1-validation.md)。
 
 **权限与风险：** 任务规划在本地完成，不调用模型。实际执行会把选定任务和上下文发送到所选模型 API 或厂商 CLI，并可能产生费用。默认使用 Harness 受限环境；只读运行不修改工作区，`workspace-write` 需要用户明确批准。明确选择 `cli-native` 的可编辑团队会在 Harness 进程沙箱之外，以当前操作系统用户权限运行；Git worktree 只收集修改，不限制操作系统访问。外部 Provider 和 CLI 服务各自适用其数据处理及计费规则。
 
-**兼容性：** 声明支持 DeepSeek Harness Desktop **0.2.0-rc.1**、**0.2.0-rc.2**、**0.2.1-rc.2**。Node.js **>=22.19** 与 pnpm **10.34.6** 仅为源码开发/构建要求，不是插件运行时前置条件；不承诺超出上述 Host 版本的兼容性。
+**兼容性：** 声明支持 DeepSeek Harness Desktop **0.2.0-rc.1**、**0.2.0-rc.2**、**0.2.1-rc.2**、**0.2.1-rc.3**。源码构建固定使用已发布的 **0.2.1-rc.3** SDK 包；保留旧版 peer 声明不表示离线测试已经替代安装版 Desktop 验收。Node.js **>=22.19** 与 pnpm **10.34.6** 仅为源码开发/构建要求，不是插件运行时前置条件；不承诺超出上述 Host 版本的兼容性。
 
 **目录：** [快速评估](#quick-evaluation) · [功能](#capabilities) · [安装](#install) · [工作台](#workbench) · [架构](#architecture) · [会话工具](#session-tools) · [官方工具](#official-tools) · [团队生命周期](#team-lifecycle) · [费用](#costs) · [路由算法](#routing) · [数据](#data) · [开发](#development) · [排障](#troubleshooting)
 
@@ -63,7 +63,7 @@ dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.24.0
 | 可编辑 CLI 执行 | 从工作台执行顺序 CLI 团队，或在会话中调用单个受支持 CLI；使用获批的隔离 Git worktree，并有条件地合入补丁。 |
 | 官方工具 | 对注册表中的十二种工具检测、安装/更新、检查启动就绪和登录状态；安装任务提供日志和取消功能。 |
 | 交互终端 | PowerShell/系统 shell 与十二种注册表 CLI 目标（经过验证的 Windows 桌面安装支持 ZCode TUI）；包含固定登录命令、实时输出和多会话。 |
-| 费用与订阅 | 日/月检查计入持久并发预占，已记录支出与剩余估计分别显示；保留订阅优先、额度冷却，以及其他订阅失败的显式处理。 |
+| 成本与订阅 | API 金额与并发预算预占、订阅调用/token 分别计算；缺失订阅用量保持未知，转 API 前重新估价并通过预算检查。 |
 | 历史与质量 | 逐包结果、依赖视图、失败详情、重跑/改派、评分与可选的更强模型复核。 |
 | 执行边界 | 显示每条路线可读写的范围，以及进程是否使用 Harness 沙箱。 |
 
@@ -78,16 +78,16 @@ dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.24.0
 打开 **插件 → 添加插件**，输入：
 
 ```text
-@ljwei-stak/dsh-model-router@0.24.0
+@ljwei-stak/dsh-model-router@0.25.1
 ```
 
-镜像缺少该精确版本时，使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。启用插件，然后完全退出 Harness（包括托盘进程）并重启。插件详情应显示 **0.24.0**，侧栏应出现 **模型路由**。仅执行全局 `npm install -g` 不会把插件注册到 Desktop。
+镜像缺少该精确版本时，使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。启用插件，然后完全退出 Harness（包括托盘进程）并重启。插件详情应显示 **0.25.1**，侧栏应出现 **模型路由**。仅执行全局 `npm install -g` 不会把插件注册到 Desktop。
 
 也可以通过插件管理器安装本地 `.tgz` 压缩包，或解压后的内部 `package` 目录。两者都必须包含 `package.json` 和 `.dsh-plugin`。历史构建见 [Releases](https://github.com/Alice-Marx/dsh-model-router/releases)，也可按下文从源码构建。
 
 ### 从旧包名升级
 
-旧名称 `@ljwei-stak/model-router-galgame` 停留在 0.13.0。保留配置档/应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.24.0`。不要同时保留两条插件：它们共用内部插件 id `model-router-galgame` 和工具名。保留该 id 能让现有路由设置与历史记录继续使用。
+旧名称 `@ljwei-stak/model-router-galgame` 停留在 0.13.0。保留配置档/应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.25.1`。不要同时保留两条插件：它们共用内部插件 id `model-router-galgame` 和工具名。保留该 id 能让现有路由设置与历史记录继续使用。
 
 从合包 0.11.x 升级前，先备份配置档，并导出需要保留的 GAL 存档。剧情播放、立绘、音乐与存档现属于独立的 `@ljwei-stak/dsh-galgame`。详细存档限制见 [MIGRATION.md](docs/archive/MIGRATION.md)。
 
@@ -351,18 +351,21 @@ worktree 用于分离和收集修改；只有所选 Harness 环境提供操作
 
 ## 成本、订阅与质量
 
-- **预算：** 单次规划目标加日/月检查。在同一个 DSH_HOME 中，启动时原子检查已记录的 API 支出和其他任务的剩余预占，再为本次执行预占预算。保存每步结果后，以实际核算替换相应估计；执行器完成收尾后才释放剩余预占。超预算路由可以尝试省钱预设，或暂停等待确认。有限日/月预算遇到未知价格、待核对实际费用或未知预占时，需要显式确认。每次后续付费调用前，都会按最新实际支出和剩余预占重新检查；前一步实际费用超过估计，或在有限预算下变成未知时，会暂停后续调用。预算检查停止运行后，已完成收据保留，未用预占在执行器收尾后释放；崩溃或存储失败则继续保留预占。这些本地估计不能保证厂商硬性计费上限。
+- **API 预算：** 单次规划目标与日/月金额检查用于 API 计费执行。启动时原子检查已记录 API 支出和其他 API 预占，再为本次 API 估计预占。有限预算下，API 单价、费用或预占未知需要显式确认；后续 API 调用会按最新支出与预占重验。已确认的订阅通道不占 API 金额，也不会仅因 API 预算用满或单价缺失而被阻止。订阅转 API 是一次新的金额准入：按实际 API 路线估价、取得所需确认并原子预占后才调用。本地估计不是厂商硬性扣费上限。
 - **检查点与中断：** 路由执行、重跑/改派、官方团队、单工具运行和会话咨询共用持久执行生命周期。可选复核和质量升级在追加调用前预占额度。质量升级启动前，先保存首个收据与待核对的追加尝试，避免中断时抹掉首次费用或把第二次尝试视为免费。界面区分实际支出与预占，预占不是账单。确认进程退出后仍保留中断预占及未知用量证据以供核对；仅凭经过时间不会释放，也不会自动重放调用。
 - **订阅优先：** 默认优先检测到的 CLI 账号订阅或已配置 coding-plan 路线。CLI 订阅尝试会移除 API-key 环境变量。`billing` 可为 `subscription-first`、`api-only` 或 `subscription-only`；`subscription` 可为 `cli-login`、`plan-key` 或 `none`。
-- **回退：** 检测到额度耗尽/限流时，将订阅标记为冷却，并可按策略与可用性在已配置 API 路线上重试该路由步骤。其他已尝试的订阅失败默认暂停（`onSubscriptionFailure: "ask"`）：可在历史中选择 API 重试、订阅重试或取消。订阅切换到 API 时，必须按实际 API 路线重新估算并检查预占；缺少价格或超预算时不会启动调用。托管可编辑/单工具/团队运行不会自动在 API 上重试。
-- **核算：** API 费用计入预算。订阅运行单独显示参考费用。有效的 CLI 报告金额（包括零）优先采用。按 token 计算 CLI 费用，需要完整用量，以及报告的实际模型匹配某个已配置模型或其显式 CLI 映射；身份未知或不匹配时费用保持未知。仅有推荐路线价格不能确定实际 CLI 费用。厂商账单为准。0.15.0 起保留已淘汰详细运行和被重试替换结果的支出，因此裁剪历史或重试步骤不会抹掉先前费用。更早版本已丢弃的费用无法重建。
+- **回退：** 检测到额度耗尽/限流时，将订阅标记为冷却，并可按策略与可用性在已配置 API 路线上重试该路由步骤。其他已尝试的订阅失败默认暂停（`onSubscriptionFailure: "ask"`）：可在历史中选择 API 重试、订阅重试或取消。订阅切换到 API 时，必须按实际 API 路线重新估算并检查预占。缺少价格或超出有限预算时，需要相应确认；未获确认不会启动 API 调用。托管可编辑/单工具/团队运行不会自动在 API 上重试。
+- **订阅用量：** 独立记录日/月调用次数、已报告输入/输出/缓存 token 和未知/不完整用量次数，并按供应商、工具、模型分组。缺失计数不视为零。订阅转 API 时同时保留订阅用量收据和 API 计费结果。旧记录的参考美元字段可保留，但当前订阅统计不再把它折算为金额，也不据此补造 token。token 数不能证明厂商订阅总额度、剩余额度或已用百分比。
+- **API 核算：** 对 API 计费结果，有效的 CLI 报告金额（包括零）优先采用。否则按 token 计算 CLI 费用，需要完整用量，以及报告实际模型匹配已配置单价或显式 CLI 映射。身份未知或不匹配时 API 费用保持未知；推荐路线价格不能证明实际成本。CLI 使用 API Key 时仍属于 API 计费，厂商账单为准。重跑替换的收据和已裁剪历史保留先前核算。
 - **质量与偏好：** 可选 `off`/`sample`/`always` 更强模型复核可能增加付费调用，且不作为人工反馈。显式评分以时间衰减和小样本收缩，调整精确路线、任务类型对应的独立主观效用（默认上限 ±0.04，可配置至 ±0.1）。评分不改变客观质量分或其硬下限；可禁用学习、撤回评分或重置学习起点。
 
 Coding-plan 密钥与端点保留在 Harness 供应商设置中。`plan-key` 配置可将已配置的精确 `apiRoute` 指定为回退；路线编辑器不接受凭据或任意命令。厂商套餐资格与条款需向厂商核实。
 
 ### 实际费用与规划估计
 
-有效的 CLI 报告美元金额（包括明确的零）优先于 token × 单价计算。否则，按 token 核算 CLI 费用要求完整、归一化的用量，已知非负价格，以及报告的实际模型匹配计价路线或其显式 CLI 映射：
+下面公式用于 API 计费结果。算法中的路线价格比较是规划输入，不会把订阅变成 API 账单；执行预览分别显示 API 金额和订阅预估 token。
+
+对 API 计费结果，有效的 CLI 报告美元金额（包括明确的零）优先于 token × 单价计算。否则，按 token 核算 CLI 费用要求完整、归一化的用量，已知非负价格，以及报告的实际模型匹配计价路线或其显式 CLI 映射：
 
 <!-- formula:actual-cost -->
 ```math
@@ -373,7 +376,7 @@ $`C_a`$ 对应 `actualUsd`；$`I_u`$、$`O`$、$`R`$、$`W`$ 分别对应 `input
 
 经适配器归一化后，这些账本计数互不重叠；不要把缓存 token 再加到已包含缓存的输入计数中。缺少可选缓存单价时，使用输入单价。用量不完整、价格缺失或身份未知/不匹配时，金额保持 `null`，不是零。完整的终态证据可在失败、取消、超时后保留；部分事件标记为 `usageIncomplete`。
 
-例如，完整 API 结果含 1,000 个未缓存输入 token（\$1/百万）和 500 个输出 token（\$5/百万），费用为 \$0.0035。订阅结果可把该金额显示为 `referenceCostUsd`，而 `costUsd` 保持 null；参考费用不加进 API 支出。厂商报告的 \$0 是该次尝试的明确证据，不能证明先前费用未知的尝试免费。实际厂商账单为准。官方团队模式不自动回退 API，防止的是路由器自身的回退；厂商 CLI 仍可能使用它自己配置的 API 凭据。
+例如，完整 API 结果含 1,000 个未缓存输入 token（\$1/百万）和 500 个输出 token（\$5/百万），费用为 \$0.0035。订阅结果记录已报告 token 和调用次数，不折算成 API 金额。API 尝试中厂商报告的 \$0 是该次尝试的明确证据，不能证明先前费用未知的尝试免费。实际厂商账单为准。官方团队模式不自动回退 API，但厂商 CLI 使用自身 API 凭据时仍产生 API 计费。
 
 <a id="routing"></a>
 
@@ -452,13 +455,13 @@ $`L`$ 为延迟效用：$`t`$ 是匹配历史的 P90 耗时，单位为毫秒；
 
 ## 数据与隐私
 
-路由配置/偏好保存在 Harness 插件设置中。运行时状态写入 `<DSH_HOME>/model-router/state.json`（默认 `~/.dsh/model-router/state.json`）：健康/入门状态、订阅冷却、评分、最多 200 条近期运行、最多 100 条执行预占、50 条终端元数据，以及主动启用的公共数据快照。预占引用的运行不会被历史裁剪删除。运行记录会冻结采用的单价、数据/反馈策略版本。偏好属于共享的本地 DSH_HOME，不是经过认证的独立用户账号；公共数据请求不会上传任务或反馈。
+路由配置/偏好保存在 Harness 插件设置中。运行时状态写入 `<DSH_HOME>/model-router/state.json`（默认 `~/.dsh/model-router/state.json`）：健康/入门状态、订阅冷却与独立用量汇总、评分、最多 200 条近期运行、最多 100 条执行预占、50 条终端元数据，以及主动启用的公共数据快照。预占引用的运行不会被历史裁剪删除。运行记录会冻结采用的单价、数据/反馈策略版本。偏好属于共享的本地 DSH_HOME，不是经过认证的独立用户账号；公共数据请求不会上传任务或反馈。
 
 0.15.0 起还保留有界支出汇总，最多覆盖 90 个有数据的日历日期与 24 个月。只包含金额/计数，不含任务或回答内容。
 
 运行历史包含任务文本、输出节选、路线/工作区、失败与费用。保存的任务最多 20,000 字符，每条回答最多 4,000 字符，因此重跑可能依赖被截断的已存上下文。插件不把 API key 存进模型配置，也不保存终端转录。任务执行仍会把所选任务/上下文发送给相应供应商或 CLI。
 
-状态写入使用锁和原子替换。状态结构 v2 保存执行所有权、预占和检查点，并升级可读的 v1 状态而不丢弃账本。旧插件会拒绝读取 v2 状态；升级前请完全停止所有 Host 进程，降级前先备份状态。无法解析的状态保留为 `state.json.corrupt-<timestamp>` 备份，并显示提示。迁移前请备份状态/配置档数据；不要分享未经脱敏的历史或日志。
+状态写入使用锁和原子替换。状态结构 v3 保留独立订阅用量和分通道预占，升级可读的 v1/v2 状态时保留 API 历史、预占与旧参考字段；历史缺失 token 保持未知。旧插件会拒绝读取 v3 状态；升级前完全停止所有 Host 进程，降级前备份状态。无法解析的状态保留为 `state.json.corrupt-<timestamp>` 备份并显示提示。不要分享未经脱敏的历史或日志。
 
 <a id="development"></a>
 
@@ -532,13 +535,14 @@ GitHub Actions 通过 Windows/Linux Node 24 矩阵执行冻结锁文件严格依
 | 现象 | 检查 |
 | --- | --- |
 | 没有路线或规划被禁用 | 配置 Harness 模型、刷新目录，并等待工具检测完成。 |
-| 费用未知 | 为每条参与比较的路线同时填写输入/输出美元单价。 |
+| API 费用未知 | 为每条参与比较的 API 路线填写输入/输出美元单价，并核对用量/模型证据。 |
+| 订阅用量未知 | 厂商未报告完整计数或历史记录缺失；不要从旧参考美元还原 token，也不要推断剩余额度。 |
 | CLI 已安装但不可执行 | 查看启动就绪原因、平台/模式支持和安装来源。 |
 | 登录/模型权限仍失败 | 检查厂商账号、CLI 登录、网络和实际模型访问；仅安装成功不够。 |
 | 前端提示 Host 版本较旧 | 完全退出 Harness（包括托盘进程）后重启。 |
 | 预览与旧建议不同 | 目录、登录、额度或预算状态已变化；请查看新预览。 |
 | 中断后预算仍被预占 | 核对原任务、保留的 worktree 和供应商账单。预占不会自动释放或续跑，本版没有手工核对并释放的操作入口。 |
-| 旧插件无法读取状态 | v2 状态包含受保护的预占；恢复兼容版本，不要删除账本绕过检查。 |
+| 旧插件无法读取状态 | v3 保留受保护执行和独立订阅用量；恢复兼容版本，不要删除账本绕过检查。 |
 | 终端 TUI 不渲染 | 检查卡片报告的是 PTY 还是管道回退模式。 |
 | 已登录但团队没有可执行路线 | 检查 `readyModes`、平台、所选安装和权限模式；仅终端已登录不能证明具备托管执行能力。 |
 | Claude 只读中没有 skills/MCP | 受限模式会禁用它们；可编辑/正常环境选项权限不同，需要相应确认。 |

package/docs/INSTALLATION_GUIDE.zh.md

@@ -1,8 +1,8 @@
 # DeepSeek Harness Desktop · 独立插件安装与验证
 
-模型路由从 **0.12.0** 起独立发布；GAL 是独立的 **0.1.0** 插件。路由 **0.22.2** 声明支持官方 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**。GAL 的兼容范围以其自身安装包为准。
+模型路由从 **0.12.0** 起独立发布；GAL 是独立的 **0.1.0** 插件。路由 **0.25.1** 声明支持官方 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2 / 0.2.1-rc.3**。GAL 的兼容范围以其自身安装包为准。
 
-当前路由版本为 **0.22.2**，修复中英文 README 正文数学符号显示与小数格式；0.22.0 新增算法推荐与手动工作包分配二选一，可逐包选择模型 API 或官方工具，并改进证据驱动规划与依赖搜索。手动混合执行目前只读；编辑文件继续走官方工具协作。沿用 Hermes/Pi 安装与终端支持、OpenCode 官方 V2 包和现有兼容声明。保留原插件 id、配置与运行记录；安装后完全退出 Harness（包括托盘）再重启。公开数据默认关闭，自动质量升级默认关闭。
+当前路由版本为 **0.25.1**，使用 0.2.1-rc.3 SDK 构建并新增该 Host 的 peer 兼容声明；API 费用与订阅用量分开计算，沿用实时进度、取消和中断记录。0.22.0 新增算法推荐与手动工作包分配二选一，可逐包选择模型 API 或官方工具，并改进证据驱动规划与依赖搜索。手动混合执行目前只读；编辑文件继续走官方工具协作。沿用 Hermes/Pi 安装与终端支持、OpenCode 官方 V2 包和现有兼容声明。保留原插件 id、配置与运行记录；安装后完全退出 Harness（包括托盘）再重启。公开数据默认关闭，自动质量升级默认关闭。
 
 [路由 README](../README.zh.md) · [迁移说明](archive/MIGRATION.md) · [独立 GAL README](https://github.com/Alice-Marx/deepseek-harness-galgame#readme)
 
@@ -10,7 +10,7 @@
 
 | 需求 | 添加插件输入框 | 安装后的入口 |
 | --- | --- | --- |
-| 分析复杂度、按质量和费用选模型、调用官方工具 | `@ljwei-stak/dsh-model-router@0.22.2` | 模型路由 |
+| 分析复杂度、按质量和费用选模型、调用官方工具 | `@ljwei-stak/dsh-model-router@0.25.1` | 模型路由 |
 | 剧情、立绘、音乐、存档、自由对话 | `@ljwei-stak/dsh-galgame@0.1.0` | Gal 模块 |
 | 两者都要 | 分别安装上面两个包 | 模型路由 + Gal 模块 |
 
@@ -24,7 +24,7 @@
 2. 在“包名、GitHub 仓库地址或本地目录路径”输入框填一个完整包名，例如：
 
    ```text
-   @ljwei-stak/dsh-model-router@0.22.2
+   @ljwei-stak/dsh-model-router@0.25.1
    ```
 
    只想安装 GAL 时填写：
@@ -40,7 +40,7 @@
    ```
 
 4. 核对预览的包名、版本和宿主兼容信息，安装并启用。完全退出 Harness（包括托盘进程）再启动，确保 Host 加载新代码。
-5. 检查插件详情与侧边栏：路由应为 **0.22.2 / 模型路由**；GAL 应为 **0.1.0 / Gal 模块**。仅装路由时没有 GAL 入口是预期行为。
+5. 检查插件详情与侧边栏：路由应为 **0.25.1 / 模型路由**；GAL 应为 **0.1.0 / Gal 模块**。仅装路由时没有 GAL 入口是预期行为。
 
 普通用户无需 `npm install -g`，该命令不会把插件注册到当前 Harness profile。
 
@@ -48,13 +48,13 @@
 
 进入对应 Release 下载 `.tgz`：
 
-- [模型路由 Releases](https://github.com/Alice-Marx/dsh-model-router/releases)（也可运行 `npm pack @ljwei-stak/dsh-model-router@0.22.2` 获取同一安装包）
+- [模型路由 Releases](https://github.com/Alice-Marx/dsh-model-router/releases)（也可运行 `npm pack @ljwei-stak/dsh-model-router@0.25.1` 获取同一安装包）
 - [独立 GAL v0.1.0](https://github.com/Alice-Marx/deepseek-harness-galgame/releases/tag/v0.1.0)
 
 在“添加插件”填写下载文件的**绝对路径**，例如：
 
 ```text
-D:\Plugins\ljwei-stak-dsh-model-router-0.22.2.tgz
+D:\Plugins\ljwei-stak-dsh-model-router-0.25.1.tgz
 ```
 
 ```text
@@ -64,7 +64,7 @@ D:\Plugins\ljwei-stak-dsh-galgame-0.1.0.tgz
 如附有 `.sha256` 文件，用 PowerShell 计算并比较摘要：
 
 ```powershell
-Get-FileHash -Algorithm SHA256 -LiteralPath 'D:\Plugins\ljwei-stak-dsh-model-router-0.22.2.tgz'
+Get-FileHash -Algorithm SHA256 -LiteralPath 'D:\Plugins\ljwei-stak-dsh-model-router-0.25.1.tgz'
 Get-FileHash -Algorithm SHA256 -LiteralPath 'D:\Plugins\ljwei-stak-dsh-galgame-0.1.0.tgz'
 ```
 
@@ -74,7 +74,7 @@ Get-FileHash -Algorithm SHA256 -LiteralPath 'D:\Plugins\ljwei-stak-dsh-galgame-0
 
 1. 在旧合并插件的 GAL 播放器导出需要保留的剧情进度，并备份整个 Harness profile。每份 JSON 仅保存**当前剧情状态**，不含所有手动槽、设置、已读记录或本地音乐；重要槽位可依次读档再导出。
 2. 在**同一个 profile**安装独立 `@ljwei-stak/dsh-galgame@0.1.0`。
-3. 0.13.0 起包名改为 `@ljwei-stak/dsh-model-router`（旧包名最后版本为 0.13.0，内容相同，之后不再更新）：在插件管理器卸载原 `@ljwei-stak/model-router-galgame`（保留 profile 与应用数据），再添加 `@ljwei-stak/dsh-model-router@0.22.2`。不要两个同时安装（条目 id 与工具名相同）；条目 id 未变，路由设置与执行记录会保留。完成两项更新后再玩剧情，避免同时操作旧合并入口和新入口。
+3. 0.13.0 起包名改为 `@ljwei-stak/dsh-model-router`（旧包名最后版本为 0.13.0，内容相同，之后不再更新）：在插件管理器卸载原 `@ljwei-stak/model-router-galgame`（保留 profile 与应用数据），再添加 `@ljwei-stak/dsh-model-router@0.25.1`。不要两个同时安装（条目 id 与工具名相同）；条目 id 未变，路由设置与执行记录会保留。完成两项更新后再玩剧情，避免同时操作旧合并入口和新入口。
 4. 现在路由与 GAL 各有一个入口。独立 GAL 沿用旧存档 localStorage 键，核对当前进度和三槽；更换 profile 或进度未恢复时，先切换到匹配剧目，再导入 JSON 备份。
 5. 后续分别更新需要的插件；只用路由可以不启用或不安装 GAL。保留 profile 与应用数据，卸载插件时不要清理故事数据。
 
@@ -82,7 +82,7 @@ GAL 核心只包含**《回声之城·正篇》**与**《旧城迁移篇：未
 
 ## 5. 模型路由第一次使用
 
-工作台自 0.15.0 起分成**任务与执行、模型配置、官方工具、预算与安全**四页；0.22.2 沿用该布局。切换页面保留安装任务、终端会话和未完成的输入。
+工作台自 0.15.0 起分成**任务与执行、模型配置、官方工具、预算与安全**四页；0.25.1 沿用该布局。切换页面保留安装任务、终端会话和未完成的输入。
 
 1. 在 Harness 官方**模型**页配置供应商、模型与凭据。插件读取准确的 `provider/model` 目录，模型档案不保存 API Key。
 2. 在**模型配置**刷新目录，逐条填写自报质量评分、核对过的输入/输出单价（USD / 百万 token）和擅长方向；缺价留空。可选 `cliModel` 必须是该厂商 CLI 已验证接受的名字。可选 LiveBench 名称须准确对应版本与推理档位；它是用户确认的映射，不自动证明实际执行档位。
@@ -113,8 +113,8 @@ GAL 核心只包含**《回声之城·正篇》**与**《旧城迁移篇：未
 
 | 检查 | 预期 |
 | --- | --- |
-| 路由宿主版本 | 0.2.0-rc.1、0.2.0-rc.2 或 0.2.1-rc.2；包括 `rc` 后缀。 |
-| 路由独立安装 | 0.22.2 详情、模型路由入口、目录和模型档案可用；不出现旧合并 GAL 入口。 |
+| 路由宿主版本 | 0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.2 或 0.2.1-rc.3；包括 `rc` 后缀。 |
+| 路由独立安装 | 0.25.1 详情、模型路由入口、目录和模型档案可用；不出现旧合并 GAL 入口。 |
 | GAL 独立安装 | 0.1.0 详情、Gal 模块入口、标题与两部核心剧情可用；不要求安装路由。 |
 | 共同安装 | 两个入口各一份，路由工具和 GAL 播放器均能使用。 |
 | 存档迁移 | 同 profile 可读旧键；跨 profile 用匹配剧目 JSON 导入；旧篇目的数据不覆盖。 |
@@ -125,11 +125,11 @@ GAL 核心只包含**《回声之城·正篇》**与**《旧城迁移篇：未
 | 动态公开数据 | 默认关闭；自行启用后核对快照版本、校验时间及失败/过期状态；人工单价仍优先。 |
 | 可编辑执行 | 在干净测试仓库核对审批、隔离工作区、补丁整合、厂商实际模型与计费。 |
 
-历史 0.15.0 的自动测试验证为 220 项通过、3 项 Windows 平台跳过；组件 UI 预览检查使用模拟数据。**0.18.2 的发布验证见[更新记录](CHANGELOG.md)**，不把模拟公开源/模型流和组件预览当作真实付费调用或 Harness Desktop 端到端验收；上表中的实际安装、账号和工作区检查仍需在使用环境中完成。
+历史 0.15.0 的自动测试验证为 220 项通过、3 项 Windows 平台跳过；组件 UI 预览检查使用模拟数据。当前 SDK 兼容与发布验证见[0.25.1 验收记录](releases/0.25.1-validation.md)，历史 0.18.2 的发布验证见[更新记录](../CHANGELOG.md)，不把模拟公开源/模型流和组件预览当作真实付费调用或 Harness Desktop 端到端验收；上表中的实际安装、账号和工作区检查仍需在使用环境中完成。
 
 ## 8. 开发者从完整源码构建
 
-路由需要 Node.js **22.19+** 与 **pnpm 10.34.6**。从完整源码仓库根目录构建；当前源码版本为 0.22.2，复现已发布版本时检出对应发布标签。旧版（如 0.15.0）标签保留其当时内容。运行：
+路由需要 Node.js **22.19+** 与 **pnpm 10.34.6**。从完整源码仓库根目录构建；当前源码版本为 0.25.1，DSH SDK 固定为 0.2.1-rc.3；复现已发布版本时检出对应发布标签。旧版（如 0.15.0）标签保留其当时内容。运行：
 
 ```powershell
 pnpm install --frozen-lockfile --strict-peer-dependencies

package/docs/WORKBENCH_USER_GUIDE.zh.md

@@ -1,6 +1,6 @@
 # 模型路由工作台：配置、规划与实际执行
 
-适用版本：`@ljwei-stak/dsh-model-router@0.23.1`。声明兼容 DeepSeek Harness Desktop `0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2`。安装与开发见[中文 README](../README.zh.md)，旧包迁移见[迁移说明](archive/MIGRATION.md)。
+适用版本：`@ljwei-stak/dsh-model-router@0.25.1`。声明兼容 DeepSeek Harness Desktop `0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2 / 0.2.1-rc.3`。源码构建使用固定的 0.2.1-rc.3 SDK；兼容验证与边界见[0.25.1 验收记录](releases/0.25.1-validation.md)。安装与开发见[中文 README](../README.zh.md)，旧包迁移见[迁移说明](archive/MIGRATION.md)。
 
 0.22.0 新增“按算法推荐分配 / 手动调整分配”：生成任务建议后，可为每个工作包选择模型 API 或官方工具；修改后重新预览费用与渠道，再确认执行。任务依赖与重跑目标保留。手动混合执行当前只读，官方工具使用自身默认模型；编辑文件继续选择官方工具协作。详见[手动分配说明](MANUAL_TASK_ASSIGNMENT.zh.md)。Hermes 自定义程序目录、原配置/登录/历史位置，以及工具页顶部终端的行为继续保留。
 
@@ -215,19 +215,21 @@ PTY 加载失败时卡片显示**管道模式**：全屏界面、箭头键、尺
 
 ## 预算与安全
 
-**成本控制与路由方案**支持省钱优先、均衡、效果优先，以及每日/月度预算、超预算动作、订阅普通失败策略和质量回路。指定模型模式跳过路线比较；未知价格无法保证满足预算。
+**API 费用、预算与路由方案**支持省钱优先、均衡、效果优先，以及 API 每日/月度金额预算、超预算动作、订阅普通失败策略和质量回路。API 预算包含已发生费用和其他任务的 API 预占；指定模型跳过路线比较。已确认的订阅通道不占 API 预算，不会仅因 API 预算满或单价缺失而被阻止。
 
 **订阅与 API Key**显示供应商计费方式、订阅来源、状态/恢复时间及 API 回退是否可用。检测到额度用尽或限流后，路由执行可按策略转 API 并记录原因；其他订阅错误默认暂停确认。单工具/团队托管执行不会自动转 API。
 
-API 花费计入预算；订阅显示按 API 价折算的参考费用，不计入预算。预算和费用是本地估算/核算，不代替厂商账单；无法确定费用时显示未知。
+**订阅用量**独立显示今日/本月调用次数、厂商已报告的输入/输出/缓存 token，以及未知或不完整用量次数，并按供应商、工具和模型分组。部分已报告字段保留，未报告字段显示“未报告”，不会当零。旧参考美元数据可以保留，但不用于现行订阅金额统计，也无法据此还原缺失 token。
 
-有效的 CLI 自报金额优先，包括 `0`。只有完整 token 用量与回报实际模型可核对到已配置模型或其显式 CLI 映射时，才按相应单价折算。缺失或不匹配的实际模型、不完整用量都保留未知费用；Harness 推荐模型的价格不能证明该 CLI 实际成本。预览仍可使用推荐路线作规划估算，须与实际核算区分。
+API 按金额核算并计入预算，订阅按用量核对；订阅 token 不是厂商总配额、剩余额度或已用百分比，插件不据此猜测厂商限额。预算/费用是本地估算和核算，不替代账单。订阅回退到 API 前，会按实际 API 路线重估、取得必要确认并原子预占；未通过时不发起 API 请求。混合执行记录同时保留订阅用量收据与 API 费用。
 
-0.15.0 会保留裁剪详细历史及重试前的费用累计，避免超过 200 条历史或重跑步骤后预算漏算。此前旧版本已丢弃的消费记录无法恢复。
+对 API 计费，CLI 有效自报金额优先，包括 `0`。CLI 使用 API Key 时仍走 API 费用核算。只有完整 token 用量与回报实际模型可核对到已配置模型或其显式 CLI 映射时，才按相应单价折算。缺失或不匹配的实际模型、不完整用量都保留未知费用；Harness 推荐模型的价格不能证明该 CLI 实际成本。预览仍可使用推荐路线作规划估算，须与实际核算区分。
+
+裁剪详细历史和替换重试结果时，API 费用和订阅用量分别保留累计，避免超过 200 条详细记录或重跑步骤后漏算/重算。旧版已经丢弃的费用与缺失 token 无法恢复。状态结构 v3 从可读的 v1/v2 状态迁移，保留旧费用和预占；升级前完全退出 Harness（包括托盘和所有 Host），降级前保留状态备份，旧插件无法读取 v3。
 
 ### 持续反馈与本地偏好
 
-在**预算与安全 → 成本控制与路由方案 → 持续反馈与本地偏好**设置**启用用户反馈学习**、半衰期（默认30天）、收缩强度（默认3）和最大偏好效用调整（默认0.04，允许0–0.1）。较旧结果权重更低，少量评价被收缩到接近零；没有评价不等于失败或满意，执行成功也不自动计为好评。查看有效反馈数、有效权重和策略版本后重新规划。
+在**预算与安全 → API 费用、预算与路由方案 → 持续反馈与本地偏好**设置**启用用户反馈学习**、半衰期（默认30天）、收缩强度（默认3）和最大偏好效用调整（默认0.04，允许0–0.1）。较旧结果权重更低，少量评价被收缩到接近零；没有评价不等于失败或满意，执行成功也不自动计为好评。查看有效反馈数、有效权重和策略版本后重新规划。
 
 学习限定在同一个本地 **DSH_HOME 工作室共享**、最近 **200 次运行**，不按账号隔离，也不无限保存学习记忆；未核验实际模型的 CLI 默认结果不会训练推荐模型。启停不删除评价。“从现在重新学习”会先请求确认，再将学习起点移到当前时间；此前结果不再参与调整，但执行历史和费用累计保留。本版不为学习自动探索或增加付费模型调用。
 
@@ -286,4 +288,4 @@ Windows Codex 在 Harness 环境仅支持只读：其原 `CODEX_HOME` 状态仍
 
 问题反馈请附宿主/插件版本、执行模式、工具状态及脱敏错误，勿提供密钥。源码、安装和资料入口见[中文 README](../README.zh.md)。
 
-执行恢复：预览、进度与取消请求等待超过15秒会终止该次网络等待；进度会重试同一任务，取消未确认可手动重试，任务不会自动重新启动。历史步骤重跑前，预算按目标及未成功的下游步骤合计；整组超限时先确认再运行，改派按所选路线重估，缺失价格不视为零费用。
+执行恢复：预览、进度与取消请求等待超过15秒会终止该次网络等待；进度会重试同一任务，取消未确认可手动重试，任务不会自动重新启动。历史步骤重跑前，API 预算按目标及未成功下游中的 API 部分合计；订阅部分单列预估 token。API 部分超限时先确认再运行，改派按实际计费渠道重估，缺失 API 价格不视为免费。

package/docs/releases/0.25.0-validation.md

@@ -0,0 +1,41 @@
+# 0.25.0 release acceptance
+
+Date: 2026-10-24. Package: `@ljwei-stak/dsh-model-router@0.25.0`.
+
+Source acceptance: passed. Local tests and the actual Windows/Linux matrix below verify the implementation. The final tagged commit, archive digests and post-publication anonymous download checks are recorded separately in the dated release/archive evidence, so this document does not embed the checksum of its own containing archive.
+
+## Problems and resulting behavior
+
+- API and subscription execution need different units. API results retain monetary charges and budget reservations. Subscription results have a separate quantity ledger: calls, reported input/output/cache tokens, and unknown/incomplete-usage counts, with daily/monthly and provider/tool/model summaries.
+- Confirmed subscriptions are not refused solely because an API money budget is exhausted or an API price is missing. Execution metadata and ownership remain durable for recovery, while subscription work does not consume API monetary capacity. Unknown authentication or unsupported execution capabilities are not treated as proof of an available subscription.
+- Unverified CLI authentication is not labelled as a confirmed subscription. It receives conservative API monetary admission; the resulting amount stays unknown rather than treating a reported reference figure as a settled bill. A failed unknown-billing CLI pauses before starting an extra API call.
+- Any actual API call, including fallback from a subscription, must estimate its actual API route and pass the applicable confirmation and atomic budget reservation before dispatch. CLI calls using API credentials remain API-billed. API quality escalation and optional API reviewers continue to incur API costs.
+- Mixed execution retains subscription-attempt usage evidence alongside the API financial result. Mandatory attempt/package checkpoints preserve available evidence. Retry replacement and detailed-history retention do not erase prior charges or subscription quantities and do not count the same receipt twice.
+- The workbench separates API money and subscription usage in the budget page, history and execution preview. A missing token counter stays unknown; a reported zero stays zero. Partial observed counters remain visible, while incomplete usage is identified. Old Host summaries that lack quantity data are unavailable rather than shown as a zero token balance.
+- State schema v3 accepts readable v1/v2 history and retains old reference fields and protected execution state. Old reference dollars are not used as current subscription monetary statistics, and absent historical tokens cannot be reconstructed from them. Older Hosts reject v3 instead of silently discarding the new state.
+
+## Validation record
+
+| Check | Observed evidence |
+| --- | --- |
+| Independent subscription quantities | 13 new quantity/state tests pass: reported zero, partial/unknown counters, provider/tool/model grouping, calendar rollover, legacy migration, retry replacement and history eviction. |
+| Host admission and fallback | 11 new Host tests pass, including full/unknown API budgets with a subscription, missing subscription prices, API-only/manual/key CLI admission, fallback repricing, an independent plan consultation, unknown CLI billing and a real killed child process at API dispatch. |
+| Receipt persistence and cancellation | 12 new runtime receipt tests and 11 reservation tests pass. They cover mandatory subscription receipt writes before fallback, cancellation, storage failure, independent API/quantity evidence, concurrent admission, pending API crash recovery and subscription steps between API steps. |
+| Workbench UI | Actual client inspected in the offline browser `billing-split` simulation: separate API money/subscription quantities, provider/tool/model rows and unknown counters. Browser console errors: 0. [Quantity screenshot](../assets/workbench-subscription-usage.png). New UI tests: 10/10. Amounts, usage and executions are simulated. |
+| Complete local suite | `npm test`: 1,186 tests; 1,183 pass, 0 fail, 3 environment skips. Full logs are retained in the release archive. |
+| Dependencies/client/docs | Strict frozen pnpm installation passed. Actual client build/check passed (986,763 bytes); syntax simplification retains readable names/lines and the existing under-1-MB bundle guard. README pairing/hashes and offline preview compile passed. Formula contents are unchanged. |
+| Windows/Linux CI | [Implementation matrix run](https://github.com/Alice-Marx/dsh-model-router/actions/runs/40082683345) on `2912b5b3bdebdd49ea7648bf87f2e252d4349c6d`: Node 24 / ubuntu-latest **success**; Node 24 / windows-latest **success**. Both ran strict installation, the complete suite, actual build/check, preview compilation and package verification. The final documentation commit runs the same matrix again before publication. |
+| Package/source integrity | Local candidate archive: 79 files match raw Git blobs, including all 42 local runtime modules. Final `v0.25.0` commit and archive digests are recorded in Release assets. The complete source ZIP is constructed from raw Git blobs and separately checked byte for byte. |
+| Public distribution | After tag/upload, the publication audit anonymously downloads the npm archive, GitHub Release page and every attached asset and compares bytes and registry integrity. Dated public-npm/public-github verification JSON files are retained with the release archive. Neither version metadata nor a pushed tag alone establishes complete publication. |
+
+## Boundaries and upgrade
+
+Subscription token counts are observed local usage, not a vendor allowance or quota meter. Different vendors may use different windows, token/cache rules or other charging units. The plugin does not infer a total allowance, remaining quota or percentage from API-equivalent prices or reported tokens. Quota exhaustion/reset information is only as reliable as vendor output and existing detection rules; a cooldown does not prove actual account eligibility.
+
+API estimates are not a hard provider billing cap, and the provider bill remains authoritative. A valid API zero applies to the observed attempt, not to earlier unknown attempts. A CLI can use its own configured API credentials even though it is launched as an official tool. Execution previews separate monetary API estimates from subscription token estimates; predicted quantities are not observed usage.
+
+Historical reference-dollar fields may remain for compatibility. Unknown old token usage remains unknown; already discarded records cannot be reconstructed. Existing package-level settlement/calendar granularity remains; this change does not claim independently settled provider invoices for every internal quality attempt.
+
+Crash or storage-failure recovery preserves unresolved execution evidence. There is no automatic paid replay, arbitrary timeout that clears live ownership, or new manual reconciliation/release control. Inspect the original task, retained worktree and provider usage/bill before recovery. Live progress handles remain in Host memory and are not restored as live workers after restart.
+
+No new real paid-provider/vendor CLI inference or installed-DSH end-to-end acceptance is claimed for this release. Prior real execution evidence remains dated in the [0.20.0 report](0.20.0-validation.md). Fully exit Harness, including tray and all Host processes, before updating; restart after installation. Back up state/profile data before migration or downgrade. Older plugin versions cannot read schema v3 state.

package/docs/releases/0.25.1-validation.md

@@ -0,0 +1,36 @@
+# 0.25.1 release acceptance
+
+Date: 2026-10-24. Package: `@ljwei-stak/dsh-model-router@0.25.1`.
+
+Source acceptance: passed. The published SDK comparison, local results and actual Windows/Linux matrix below verify the implementation. The final tagged commit, archive digests and post-publication anonymous download checks are recorded separately in the dated release/archive evidence, avoiding an archive digest embedded inside its own containing archive.
+
+## Problem and resulting behavior
+
+- Harness Desktop 0.2.1-rc.3 is outside 0.25.0's exact Host peer range. This update adds 0.2.1-rc.3 while retaining the existing 0.2.0-rc.1, 0.2.0-rc.2 and 0.2.1-rc.2 declarations.
+- Source development pins the published 0.2.1-rc.3 SDK graph and regenerates the Desktop client against that SDK. SDK checks must inspect the Host/client interfaces actually imported by the plugin, including remotes, settings, tools, model execution and the client loader.
+- Current bilingual installation examples and workbench documentation identify 0.25.1 and the declared Host versions. Historical release notes, tags and acceptance reports retain their original versions and evidence.
+- API monetary accounting, the independent subscription quantity ledger, durable execution checkpoints, progress and cancellation retain their existing behavior. This compatibility update does not introduce a state schema beyond v3 from 0.25.0.
+
+## Validation record
+
+| Check | Observed evidence |
+| --- | --- |
+| Published SDK comparison | Compared 51 direct DSH SDK packages across rc.2/rc.3 and verified all 102 official tarballs against registry SHA512 integrity. After excluding version strings, 46 packages' runtime/declarations are unchanged. Host core interfaces, model-catalog DTO and layout/settings contracts are unchanged; changed packages add telemetry fields, declaration comments, plugin-list navigation, menu/tooltip helpers and sidebar menus/pin controls. The imported interfaces remain available. Detailed package/diff evidence is retained in the release archive. |
+| Host/client contract regressions | 32/32 focused tests passed against the actual installed rc.3 SDK: app-boot compatibility without exemptions, Cordis Host/remote injection, settings ACK/revision/timeout behavior and generated-client loading. The old 0.25.0 manifest reproduces rc.3 rejection; the new manifest accepts the four declared candidates and still rejects unaudited rc.4/final releases. Older Host declarations are retained, not represented as new installed-Desktop tests. |
+| Dependency graph | `pnpm install --frozen-lockfile --strict-peer-dependencies` passed. All 51 direct DSH development packages are pinned to 0.2.1-rc.3 in package.json and the lockfile; the six DSH Host peer ranges retain the old candidates and add rc.3. |
+| Client and preview | Actual rc.3 client rebuild and `check:client` passed (986,763 bytes), preserving the existing under-1-MB guard. The real workbench component and offline fixtures compile successfully. |
+| README pairing | `npm run check:readme` passed after reviewing both translations: 6 paired display formulas, 33 paired inline expressions and current translation hashes. Formula contents are unchanged; no new GitHub MathJax rendering claim is made. |
+| Complete local suite | `npm test`: 1,187 tests; 1,184 passed, 0 failed, 3 environment skips. Full logs are retained in the release archive. |
+| Windows/Linux CI | [Implementation matrix run](https://github.com/Alice-Marx/dsh-model-router/actions/runs/40084735167) on `d90931a7f9c96a985eccc1b9eb59a2b69edf608c`: Node 24 / windows-latest **success**; Node 24 / ubuntu-latest **success**. Both ran strict frozen installation, the complete suite, committed-client consistency, actual build/check, preview compilation and package byte/runtime verification. The final documentation commit runs the same matrix again before publication. |
+| Package/source integrity | The local candidate archive's 80 files match raw Git blobs and include all 42 local runtime modules. Final `v0.25.1` commit and archive digests are recorded in Release assets. The complete source ZIP is constructed from raw Git blobs and separately verified byte for byte before upload. |
+| Public distribution | After publication, anonymously download the npm archive, GitHub Release page and every attached asset; compare exact bytes, registry integrity, main and tag. Neither metadata nor a pushed tag proves release completion. |
+
+## Boundaries and upgrade
+
+The [official rc.3 release](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.1-rc.3) adds sidebar/session menus and changes the official API-key route's model-list refresh. The router's existing `sidebar.panellist` registration remains visible by default and participates in the new menu; no forced pin preference is needed. Its existing asynchronous `session.modelCatalog` call continues to consume the Host-owned directory. No provider endpoint, key lookup or model identifier is reimplemented by this update.
+
+The rc.3 SDK dependency graph and offline contracts provide source/build evidence. They do not establish that every declared older Host has been newly tested in an installed Desktop, or that a vendor login, model identity or account entitlement is available. Installed-DSH end-to-end acceptance and new paid-provider/vendor CLI inference are not claimed unless separately recorded with their actual date, environment and results. Earlier real execution evidence remains in the [0.20.0 report](0.20.0-validation.md); API/subscription separation and accounting limits remain in the [0.25.0 report](0.25.0-validation.md).
+
+Fully quit Harness, including tray and all Host processes, before updating the plugin; restart after installation. Back up profile/state data before updating or downgrading. Existing v3 state is retained; plugin versions predating schema v3 cannot read it. Do not erase unresolved reservations or replay interrupted paid work to test compatibility.
+
+Subscription quantities are observed usage, not remaining vendor quota. API estimates are not a hard provider billing cap. Mock execution, local preview and successful automated tests do not validate provider billing or deliverable correctness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ljwei-stak/dsh-model-router",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "type": "module",
   "description": "Model Router for official DeepSeek Harness Desktop: cost-aware task routing, dependent work packages and official vendor CLI discovery, installation and execution. GAL is available separately as @ljwei-stak/dsh-galgame.",
   "repository": {
@@ -110,7 +110,12 @@
     ".dsh-plugin/shared/budget-reservations.mjs",
     ".dsh-plugin/shared/execution-lifecycle.mjs",
     "docs/releases/0.24.0-validation.md",
-    "docs/assets/workbench-budget-reservations.png"
+    "docs/assets/workbench-budget-reservations.png",
+    ".dsh-plugin/shared/execution-accounting.mjs",
+    ".dsh-plugin/shared/subscription-usage.mjs",
+    "docs/releases/0.25.0-validation.md",
+    "docs/releases/0.25.1-validation.md",
+    "docs/assets/workbench-subscription-usage.png"
   ],
   "scripts": {
     "build:client": "node scripts/build-client.mjs",
@@ -122,7 +127,7 @@
     "experiment:routing-summary": "node scripts/summarize-routing-search.mjs",
     "experiment:routing-adaptive": "node scripts/adaptive-routing-study.mjs",
     "audit:livebench": "node scripts/livebench-aggregate-audit.mjs",
-    "test": "node scripts/check-readme.mjs && node --test tests/adaptive-*.test.mjs tests/dynamic-data.test.mjs tests/router.test.mjs tests/routing-optimizer.test.mjs tests/routing-evaluation.test.mjs tests/routing-paired-statistics.test.mjs tests/routing-selftest-tools.test.mjs tests/livebench-aggregate-audit.test.mjs tests/livebench-prior-study.test.mjs tests/routing-search-experiment.test.mjs tests/routing-regression-study.test.mjs tests/routing-search-summary.test.mjs tests/harness-*.test.mjs tests/official-tools.test.mjs tests/official-tool-result.test.mjs tests/native-environment.test.mjs tests/native-entry-trust.test.mjs tests/tool-failure-ledger.test.mjs tests/official-team-runtime.test.mjs tests/model-profiles.test.mjs tests/model-profile-editor.test.mjs tests/tool-install-state.test.mjs tests/tool-install-sdk-ui.test.mjs tests/vendor-adapters.test.mjs tests/desktop-compat.test.mjs tests/plugin-split.test.mjs tests/install-settings-host.test.mjs tests/task-executors.test.mjs tests/tool-install-preferences.test.mjs tests/roadmap.test.mjs tests/insights-state.test.mjs tests/billing-team-ledger.test.mjs tests/subscription-billing.test.mjs tests/subscription-host.test.mjs tests/test-pass-regressions.test.mjs tests/roadmap-gaps.test.mjs tests/cordis-inject.test.mjs tests/cli-terminal.test.mjs tests/cli-terminal-gateway.test.mjs tests/latest-versions.test.mjs tests/vendor-installer-validation.test.mjs tests/install-entry-selection.test.mjs tests/script-directory-safety.test.mjs tests/zcode-config.test.mjs tests/zcode-runtime.test.mjs tests/client-loader.test.mjs tests/hermes-pi.test.mjs tests/effort-execution.test.mjs tests/routing-evidence.test.mjs tests/routing-query-effort.test.mjs tests/routing-search-frontier.test.mjs tests/quality-gates.test.mjs tests/algorithm-host-integration.test.mjs tests/quality-attempt-ledger.test.mjs tests/manual-package-execution.test.mjs tests/manual-plan.test.mjs tests/manual-assignment-ui.test.mjs tests/manual-assignment-host.test.mjs tests/readme-math.test.mjs tests/run-jobs.test.mjs tests/run-progress-host.test.mjs tests/run-progress-ui.test.mjs tests/execution-progress.test.mjs tests/rerun-budget-host.test.mjs tests/run-progress-transport.test.mjs tests/budget-reservation-ui.test.mjs tests/budget-reservations-state.test.mjs tests/ci-contract.test.mjs tests/execution-budget-host.test.mjs tests/execution-budget-paths-host.test.mjs tests/execution-checkpoints.test.mjs tests/execution-budget-recheck.test.mjs tests/receipt-checkpoint-time.test.mjs",
+    "test": "node scripts/check-readme.mjs && node --test tests/adaptive-*.test.mjs tests/dynamic-data.test.mjs tests/router.test.mjs tests/routing-optimizer.test.mjs tests/routing-evaluation.test.mjs tests/routing-paired-statistics.test.mjs tests/routing-selftest-tools.test.mjs tests/livebench-aggregate-audit.test.mjs tests/livebench-prior-study.test.mjs tests/routing-search-experiment.test.mjs tests/routing-regression-study.test.mjs tests/routing-search-summary.test.mjs tests/harness-*.test.mjs tests/official-tools.test.mjs tests/official-tool-result.test.mjs tests/native-environment.test.mjs tests/native-entry-trust.test.mjs tests/tool-failure-ledger.test.mjs tests/official-team-runtime.test.mjs tests/model-profiles.test.mjs tests/model-profile-editor.test.mjs tests/tool-install-state.test.mjs tests/tool-install-sdk-ui.test.mjs tests/vendor-adapters.test.mjs tests/desktop-compat.test.mjs tests/plugin-split.test.mjs tests/install-settings-host.test.mjs tests/task-executors.test.mjs tests/tool-install-preferences.test.mjs tests/roadmap.test.mjs tests/insights-state.test.mjs tests/billing-team-ledger.test.mjs tests/subscription-billing.test.mjs tests/subscription-host.test.mjs tests/test-pass-regressions.test.mjs tests/roadmap-gaps.test.mjs tests/cordis-inject.test.mjs tests/cli-terminal.test.mjs tests/cli-terminal-gateway.test.mjs tests/latest-versions.test.mjs tests/vendor-installer-validation.test.mjs tests/install-entry-selection.test.mjs tests/script-directory-safety.test.mjs tests/zcode-config.test.mjs tests/zcode-runtime.test.mjs tests/client-loader.test.mjs tests/hermes-pi.test.mjs tests/effort-execution.test.mjs tests/routing-evidence.test.mjs tests/routing-query-effort.test.mjs tests/routing-search-frontier.test.mjs tests/quality-gates.test.mjs tests/algorithm-host-integration.test.mjs tests/quality-attempt-ledger.test.mjs tests/manual-package-execution.test.mjs tests/manual-plan.test.mjs tests/manual-assignment-ui.test.mjs tests/manual-assignment-host.test.mjs tests/readme-math.test.mjs tests/run-jobs.test.mjs tests/run-progress-host.test.mjs tests/run-progress-ui.test.mjs tests/execution-progress.test.mjs tests/rerun-budget-host.test.mjs tests/run-progress-transport.test.mjs tests/budget-reservation-ui.test.mjs tests/budget-reservations-state.test.mjs tests/ci-contract.test.mjs tests/execution-budget-host.test.mjs tests/execution-budget-paths-host.test.mjs tests/execution-checkpoints.test.mjs tests/execution-budget-recheck.test.mjs tests/receipt-checkpoint-time.test.mjs tests/subscription-accounting-host.test.mjs tests/subscription-receipts-runtime.test.mjs tests/subscription-reservations.test.mjs tests/subscription-usage-state.test.mjs tests/subscription-usage-ui.test.mjs",
     "prepack": "node scripts/prepack.mjs",
     "pack:local": "npm pack --pack-destination dist",
     "test:routing-algorithm": "node --test tests/effort-execution.test.mjs tests/routing-evidence.test.mjs tests/routing-query-effort.test.mjs tests/routing-search-frontier.test.mjs tests/quality-gates.test.mjs tests/algorithm-host-integration.test.mjs tests/quality-attempt-ledger.test.mjs",
@@ -137,12 +142,12 @@
   "packageManager": "pnpm@10.34.6",
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-commands": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2",
-    "@deepseek-ai/dsh-settings": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.2 || 0.2.1-rc.3",
     "@deepseek-ai/schemastery": "~3.18.4"
   },
   "optionalDependencies": {
@@ -154,57 +159,57 @@
     "@deepseek-ai/cordis-plugin-include": "1.0.10",
     "@deepseek-ai/cordis-plugin-loader": "1.0.6",
     "@deepseek-ai/cordis-plugin-timer": "1.1.7",
-    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-agent-default-model": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-agent-preset-registry": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-api-remotes": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-app-boot": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-attachment": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-brand": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-connection": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-file-upload": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-layout": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-cmdline": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-commands": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-compaction": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-credentials": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-file-reference": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-fs": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-hmr": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-native-command": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-scope": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-session-projection": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-session-query": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-session-title": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-settings": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-skill": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-storage": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-storage-domain": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-subagent": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-tool-todo": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-user-approval": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-util-time": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-working-directory": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-workspace": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-agent-default-model": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-agent-preset-registry": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-api-remotes": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-attachment": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-brand": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-connection": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-file-upload": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-cmdline": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-commands": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-compaction": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-credentials": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-file-reference": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-fs": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-hmr": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-native-command": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-scope": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session-persistence": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session-query": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-session-title": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-settings": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-skill": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-storage": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-storage-domain": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-subagent": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-tool-todo": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-util-time": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-workspace": "0.2.1-rc.3",
     "@deepseek-ai/schemastery": "3.18.5",
     "@xterm/addon-fit": "0.11.0",
     "@xterm/xterm": "6.0.0",