@ljwei-stak/dsh-model-router 0.21.0 → 0.22.0

package/README.md

@@ -4,7 +4,7 @@
 
 A cost-aware model-routing workbench for **DeepSeek Harness Desktop**. Plan locally, compare configured routes, inspect execution permissions, and run dependent work packages through model APIs or supported official vendor CLIs.
 
-Current version: **0.21.0** (`@ljwei-stak/dsh-model-router`). This release adds Hermes Agent and Pi installation, updates, discovery and interactive terminals, and switches OpenCode npm/pnpm installs to the official V2 package. Compatibility remains **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**. Hermes and Pi do not yet have verified managed runners; real vendor execution evidence remains tied to **0.20.0**, with no new model experiments in this release. The router and [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) have been independent plugins since 0.12.0.
+Current version: **0.22.0** (`@ljwei-stak/dsh-model-router`). Choose algorithm recommendations or manually assign each decomposed package to an exact model API or official tool, preserving dependencies, refreshed cost previews and retry targets. Routing now supports task-specific quality evidence, joint model/effort selection, historical P90 resource estimates and dependency-aware search. Manual mixed execution is read-only; tools use their configured default model, while the existing editable official-team workflow remains available. Compatibility remains **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**, including Hermes/Pi installation and terminal support; neither has a verified managed runner yet. Real vendor execution evidence remains tied to **0.20.0**, with no new model experiments in this release. The router and [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) have been independent plugins since 0.12.0.
 
 Official CLI teamwork runs packages sequentially with dependency context and no automatic model-directory API fallback. Editable teams explicitly choose the Harness sandbox or the vendor CLI's normal environment. In the latter, Git worktrees collect edits but do not restrict OS access. CLIs retain their configured model unless explicitly mapped. See [real Windows validation and its limits](docs/releases/0.20.0-validation.md).
 
@@ -40,16 +40,16 @@ Generating a route recommendation is local: it does not start a vendor CLI or ma
 Open **Plugins → Add plugin** and enter:
 
 ```text
-@ljwei-stak/dsh-model-router@0.21.0
+@ljwei-stak/dsh-model-router@0.22.0
 ```
 
-Use the official HTTPS npm source `https://registry.npmjs.org/` when a mirror lacks that exact version. Enable the plugin, then fully quit Harness (including its tray process) and restart it. Plugin details should show **0.21.0** and the sidebar should contain **模型路由** (Model Router). A global `npm install -g` alone does not register a Desktop plugin.
+Use the official HTTPS npm source `https://registry.npmjs.org/` when a mirror lacks that exact version. Enable the plugin, then fully quit Harness (including its tray process) and restart it. Plugin details should show **0.22.0** and the sidebar should contain **模型路由** (Model Router). A global `npm install -g` alone does not register a Desktop plugin.
 
 You can instead install a local `.tgz` archive or its extracted inner `package` directory through the plugin manager. Both must contain `package.json` and `.dsh-plugin`. See [releases](https://github.com/Alice-Marx/dsh-model-router/releases) for archived builds, or build your own checkout below.
 
 ### Upgrade from the old package name
 
-The old name `@ljwei-stak/model-router-galgame` ended at 0.13.0. Remove that plugin entry while retaining your profile/application data, then add `@ljwei-stak/dsh-model-router@0.21.0`. Do not keep both entries installed: they share the internal plugin id `model-router-galgame` and tool names. The retained id lets existing router settings and history carry over.
+The old name `@ljwei-stak/model-router-galgame` ended at 0.13.0. Remove that plugin entry while retaining your profile/application data, then add `@ljwei-stak/dsh-model-router@0.22.0`. Do not keep both entries installed: they share the internal plugin id `model-router-galgame` and tool names. The retained id lets existing router settings and history carry over.
 
 For the combined 0.11.x package, back up the profile and export the GAL saves you want to preserve before upgrading. Story playback, artwork, music and saves now belong to the independent `@ljwei-stak/dsh-galgame` package. The detailed save limitations are in [MIGRATION.md](docs/archive/MIGRATION.md).
 
@@ -220,7 +220,7 @@ The CLI team runner is the plugin's own sequential dependency executor. It does
 | `pi` | Pi | Official npm/pnpm package and interactive terminal; enter `/login` inside Pi; no verified managed runner |
 | `zcode` | ZCode | Windows; approved `workspace-write` |
 
-Hermes uses its [official source installer](https://hermes-agent.nousresearch.com/docs/getting-started/installation) in non-interactive mode, then you run `hermes auth`. Its launcher and user data have separate vendor-managed locations; the shared install directory does not relocate them. Uninstall source installs through `hermes uninstall`. Pi uses [`@earendil-works/pi-coding-agent`](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) through npm/pnpm with `--ignore-scripts` and requires Node.js 22.19 or later. Start `pi`, then enter `/login`. Both tools keep login status unknown until confirmed in their own interface; the plugin does not read their credentials.
+Hermes uses its [official source installer](https://hermes-agent.nousresearch.com/docs/getting-started/installation) in non-interactive mode, then you run `hermes auth`. A configured shared root places its source in `<root>/hermes-agent`; the plugin binds that checkout's `.hermes/bin` launcher and refuses a different old global copy. Existing configuration, login and history stay in their original Hermes home. Without a shared root, vendor defaults remain in use. The installer may refresh its global convenience command to the selected checkout. Uninstall source installs through `hermes uninstall`. Pi uses [`@earendil-works/pi-coding-agent`](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) through npm/pnpm with `--ignore-scripts` and requires Node.js 22.19 or later. Start `pi`, then enter `/login`. Both tools keep login status unknown until confirmed in their own interface; the plugin does not read their credentials.
 
 Installers use fixed official npm packages at each vendor's `@latest`, the vendor's own installer script, or the official publisher-signed Windows ZCode installer. An installation newer than the reported latest is not downgraded. Latest-version lookups are cached for about 12 hours; unavailable lookups leave the version unknown. New vendor releases are not automatically validated by this project. ZCode's installation window still requires you to choose a directory and finish installation.
 
@@ -331,11 +331,13 @@ For example, a complete API result with 1,000 uncached input tokens at $1/millio
 
 ## How routing works
 
+Manual assignment: after planning, choose algorithm recommendations or select an API model / official tool for each package. See the [manual assignment guide](docs/MANUAL_TASK_ASSIGNMENT.zh.md).
+
 The planner is a deterministic local heuristic, not a trained success predictor. It classifies text, estimates complexity, creates suitable analysis/execution/verification/synthesis packages, discovers exact configured routes, overlays profiles, and applies capability/quality constraints. An explicit route bypasses comparison with other routes. Catalog quality/latency/risk hints are experimental priors, not measured success probabilities or live vendor quotes. Execution is currently text-oriented; a vision label does not establish an end-to-end multimodal pipeline.
 
 ### Token and price estimate
 
-Base input tokens are `max(80, ceil(text.length / 3.7))`, then adjusted by package-stage multipliers. Base output is 900, adjusted by stage/reasoning effort, with minimum 220. This is a text-length heuristic, not a vendor tokenizer. Let `I` be total estimated input, `R/W` the cached-read/write portions, `O` output, and prices USD per million tokens:
+Without matching resource evidence, base input tokens are `max(80, ceil(text.length / 3.7))`, then adjusted by package-stage multipliers. Base output is 900, adjusted by stage/reasoning effort, with minimum 220. This is a text-length heuristic, not a vendor tokenizer. Sufficient matching, complete history replaces these heuristics with empirical P90 resource estimates, without applying effort or stage multipliers again. Let `I` be total estimated input, `R/W` the cached-read/write portions, `O` output, and prices USD per million tokens:
 
 ```text
 C = ((I − R − W) × p_in + R × p_cache_read
@@ -359,7 +361,7 @@ u = wq × q + wc × costUtility
 assignmentScore = sum(package utility) − 0.015 × crossRouteDependencyEdges
 ```
 
-Quality uses the task-category LiveBench score when available, then overall LiveBench, then profile/catalog estimates. Public-data refresh is opt-in. Human ratings affect only the bounded `preferenceAdjustment`; they cannot increase objective quality or satisfy its floor.
+Quality first uses sufficient matching objective task evidence, then falls back to task-category LiveBench, overall LiveBench, and profile/catalog estimates. Model and effort are compared jointly only when at least two API efforts have usable task evidence; observed duration can replace the latency proxy. Public-data refresh is opt-in. Human ratings affect only the bounded `preferenceAdjustment`; they cannot increase objective quality or satisfy its floor.
 
 | Package basis | Quality | Cost | Latency | Specialty | Reasoning | Risk |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -374,13 +376,15 @@ Base quality floors are **.75 / .78 / .82** for simple/balanced/complex tasks; c
 
 1. Prefer candidates meeting each package's floor. If none qualify, retain up to three highest-quality fallbacks and report relaxation.
 2. Keep at most **12 candidates per package**, including anchors for lowest known cost, greatest utility and highest quality. Local Pareto pruning is disabled when dependencies exist, because route identity affects handoffs.
-3. Validate unique package IDs and topological dependency order. Search the retained Cartesian space exactly when its size is at most **4,096**; otherwise use **beam width 256**. Remaining minimum costs prune infeasible prefixes; the beam protects the cheapest feasible prefix under a finite budget.
+3. Validate unique package IDs and topological dependency order. Search the retained Cartesian space exactly when its size is at most **4,096**; otherwise use **beam width 256**. Search compresses dominated prefixes sharing the same future dependency boundary and ranks them using optimistic future handoffs. Remaining minimum costs prune infeasible prefixes; the beam protects the cheapest feasible prefix under a finite budget.
 4. Compare assignments lexicographically: fewer relaxed packages, smaller quality shortfall, higher utility, lower cost, fewer route switches, then stable route order. Minimum-cost mode compares cost before utility. Each dependency crossing a `provider/model` route subtracts .015 from utility.
 5. Report search metadata and feasibility. When a positive budget has no feasible assignment, a minimum-cost alternative can still be returned with `budgetFeasible: false`. A displayed plan is not proof that the budget is satisfied.
 
 “Exact” applies only to the retained candidate space and proxy objective. Candidate caps and beam pruning preclude a claim of global optimality over every configured model. Unit/synthetic tests establish mechanisms, not actual answer-quality gains. The public 2026-06-25 LiveBench score/cost tables used by the research audit are aggregate data; a paired per-question quality/cost matrix was not obtained, so no real routing gain is claimed. See [research](docs/ROUTING_RESEARCH.zh.md), [derivation/experiments](docs/ROUTING_DERIVATION_EXPERIMENTS.zh.md), and [validation protocol](docs/ROUTING_LIVEBENCH_VALIDATION.zh.md).
 
-Implementation: [router.mjs](.dsh-plugin/shared/router.mjs), [assignment-solver.mjs](.dsh-plugin/shared/assignment-solver.mjs), [routing-presets.mjs](.dsh-plugin/shared/routing-presets.mjs), [harness-plan.mjs](.dsh-plugin/shared/harness-plan.mjs) and [adaptive-feedback.mjs](.dsh-plugin/shared/adaptive-feedback.mjs).
+See the [algorithm optimization guide](docs/ROUTING_ALGORITHM_OPTIMIZATION.zh.md) for evidence import, fallback rules, effort handling, and optional JSON validation with escalation. Escalation defaults to off and permits at most one additional ordinary API request after billing and budget checks.
+
+Implementation: [router.mjs](.dsh-plugin/shared/router.mjs), [assignment-solver.mjs](.dsh-plugin/shared/assignment-solver.mjs), [routing-evidence.mjs](.dsh-plugin/shared/routing-evidence.mjs), [harness-plan.mjs](.dsh-plugin/shared/harness-plan.mjs) and [quality-gates.mjs](.dsh-plugin/shared/quality-gates.mjs).
 
 <a id="data"></a>
 

package/README.zh.md

@@ -4,7 +4,7 @@
 
 面向 **DeepSeek Harness Desktop** 的成本感知模型路由工作台。在本地规划任务、比较已配置路线、检查执行权限，并通过模型 API 或支持的厂商官方 CLI 执行有依赖关系的工作包。
 
-当前版本：**0.21.0**（`@ljwei-stak/dsh-model-router`）。本版增加 Hermes Agent 与 Pi 的安装、更新、检测和交互终端，并将 OpenCode npm/pnpm 安装切换至官方 V2 包。继续兼容 **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.22.0**（`@ljwei-stak/dsh-model-router`）。新增“按算法推荐分配 / 手动调整分配”：拆分后的工作包可逐个指定模型 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 起已拆分为独立插件。
 
 官方 CLI 协作按依赖顺序逐包执行、传递依赖上下文，不会自动回退到模型目录 API。可编辑团队需明确选择 Harness 沙箱或厂商 CLI 正常环境。后者通过 Git worktree 收集修改，但不限制操作系统访问。未显式设置模型映射时，各 CLI 沿用自身配置的模型。参见[真实 Windows 验证及其局限](docs/releases/0.20.0-validation.md)。
 
@@ -40,16 +40,16 @@
 打开 **插件 → 添加插件**，输入：
 
 ```text
-@ljwei-stak/dsh-model-router@0.21.0
+@ljwei-stak/dsh-model-router@0.22.0
 ```
 
-镜像缺少该精确版本时，使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。启用插件，然后完全退出 Harness（包括托盘进程）并重启。插件详情应显示 **0.21.0**，侧栏应出现 **模型路由**。仅执行全局 `npm install -g` 不会把插件注册到 Desktop。
+镜像缺少该精确版本时，使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。启用插件，然后完全退出 Harness（包括托盘进程）并重启。插件详情应显示 **0.22.0**，侧栏应出现 **模型路由**。仅执行全局 `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.21.0`。不要同时保留两条插件：它们共用内部插件 id `model-router-galgame` 和工具名。保留该 id 能让现有路由设置与历史记录继续使用。
+旧名称 `@ljwei-stak/model-router-galgame` 停留在 0.13.0。保留配置档/应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.22.0`。不要同时保留两条插件：它们共用内部插件 id `model-router-galgame` 和工具名。保留该 id 能让现有路由设置与历史记录继续使用。
 
 从合包 0.11.x 升级前，先备份配置档，并导出需要保留的 GAL 存档。剧情播放、立绘、音乐与存档现属于独立的 `@ljwei-stak/dsh-galgame`。详细存档限制见 [MIGRATION.md](docs/archive/MIGRATION.md)。
 
@@ -220,7 +220,7 @@ CLI 团队运行器是插件自身的顺序依赖执行器，不控制 Harness
 | `pi` | Pi | 官方 npm/pnpm 安装、版本检测、交互终端；启动后输入 `/login`；尚无经过验证的托管执行器 |
 | `zcode` | ZCode | Windows；获批的 `workspace-write` |
 
-Hermes 使用[官方源码安装器](https://hermes-agent.nousresearch.com/docs/getting-started/installation)的非交互模式，安装后运行 `hermes auth`。它的命令入口、源码和数据目录分别由厂商管理，统一安装目录不会迁移这些目录或凭据；源码安装请通过 `hermes uninstall` 卸载。Pi 使用 [`@earendil-works/pi-coding-agent`](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)，npm/pnpm 安装带 `--ignore-scripts`，要求 Node.js 22.19 及以上。启动 `pi` 后输入 `/login`。这两种工具的登录状态显示为未知，以各自界面为准；插件不会读取它们的凭据。
+Hermes 使用[官方源码安装器](https://hermes-agent.nousresearch.com/docs/getting-started/installation)的非交互模式，安装后运行 `hermes auth`。设置统一根目录后，源码安装到 `<根目录>/hermes-agent`，插件绑定该源码的 `.hermes/bin` 入口，不会改用其他旧的全局副本。配置、登录和历史仍保留在原 Hermes 数据目录；未设置统一根时沿用厂商默认位置。官方安装器可能将全局便利命令更新为指向所选源码。源码安装请通过 `hermes uninstall` 卸载。Pi 使用 [`@earendil-works/pi-coding-agent`](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)，npm/pnpm 安装带 `--ignore-scripts`，要求 Node.js 22.19 及以上。启动 `pi` 后输入 `/login`。这两种工具的登录状态显示为未知，以各自界面为准；插件不会读取它们的凭据。
 
 安装器使用各厂商 `@latest` 对应的固定官方 npm 包、厂商自有安装脚本，或带官方发行者签名的 Windows ZCode 安装器。已安装版本高于查询到的最新版本时不降级。最新版本查询约缓存 12 小时；查询不可用时版本保持未知。厂商新版本不会自动获得本项目的验证。ZCode 安装窗口仍需用户选择目录并完成安装。
 
@@ -331,11 +331,13 @@ actualUsd = (inputTokens × inputPrice + outputTokens × outputPrice
 
 ## 路由算法
 
+手动分配：生成任务建议后，可选择按算法推荐执行，或逐包指定模型 API / 官方工具。参见[手动分配使用说明](docs/MANUAL_TASK_ASSIGNMENT.zh.md)。
+
 规划器是确定性的本地启发式算法，不是训练得到的成功率预测器。它对文本分类、估计复杂度、创建适当的分析/执行/验证/汇总工作包，发现精确的已配置路线，叠加路线配置，并应用能力/质量约束。显式指定路线会跳过与其他路线的比较。目录质量/延迟/风险提示是实验性先验，不是实测成功概率或厂商实时报价。执行当前以文本为主；vision 标签不能证明已有端到端多模态流水线。
 
 ### Token 与价格估计
 
-基础输入 token 为 `max(80, ceil(text.length / 3.7))`，再乘以工作包阶段系数。基础输出为 900，按阶段/推理强度调整，最少 220。这是按文本长度估算，不是厂商 tokenizer。令 `I` 为估计输入总数，`R/W` 为缓存读取/写入部分，`O` 为输出，价格单位为美元/百万 token：
+没有匹配资源证据时，基础输入 token 为 `max(80, ceil(text.length / 3.7))`，再乘以工作包阶段系数。基础输出为 900，按阶段/推理强度调整，最少 220。这是按文本长度估算，不是厂商 tokenizer。匹配的完整历史记录达到样本门槛后，改用经验 P90 资源估计，不再重复乘档位和阶段系数。令 `I` 为估计输入总数，`R/W` 为缓存读取/写入部分，`O` 为输出，价格单位为美元/百万 token：
 
 ```text
 C = ((I − R − W) × p_in + R × p_cache_read
@@ -359,7 +361,7 @@ u = wq × q + wc × costUtility
 assignmentScore = sum(package utility) − 0.015 × crossRouteDependencyEdges
 ```
 
-质量优先使用对应任务类别的 LiveBench 分数，其次整体 LiveBench，最后才是路线配置/目录估值。公共数据刷新默认关闭，需主动启用。人工评分仅影响有界的 `preferenceAdjustment`，不能提高客观质量或满足质量下限。
+质量优先使用足量且匹配的任务客观证据，再回退对应任务类别的 LiveBench 分数、整体 LiveBench、路线配置/目录估值。至少两个 API 档位各有可用任务证据时，才联合比较模型与档位；经验耗时可替换延迟代理项。公共数据刷新默认关闭，需主动启用。人工评分仅影响有界的 `preferenceAdjustment`，不能提高客观质量或满足质量下限。
 
 | 工作包基础类型 | 质量 | 费用 | 延迟 | 领域 | 推理 | 风险 |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -374,13 +376,15 @@ assignmentScore = sum(package utility) − 0.015 × crossRouteDependencyEdges
 
 1. 优先保留达到各工作包质量下限的候选。若没有合格候选，保留质量最高的至多三个回退候选，并报告约束放宽。
 2. 每包最多保留 **12 个候选**，包含最低已知费用、最大效用与最高质量的锚点。存在依赖时禁用局部 Pareto 裁剪，因为路线身份会影响交接。
-3. 验证工作包 ID 唯一且依赖按拓扑排序。保留候选的笛卡尔空间大小不超过 **4,096** 时精确搜索；否则采用 **beam width 256**。剩余最小费用用于裁剪不可行前缀；有限预算时，beam 会保护最便宜的可行前缀。
+3. 验证工作包 ID 唯一且依赖按拓扑排序。保留候选的笛卡尔空间大小不超过 **4,096** 时精确搜索；否则采用 **beam width 256**。搜索按未来依赖的模型边界压缩被支配前缀，并用未来交接的乐观估计排序。剩余最小费用用于裁剪不可行前缀；有限预算时，beam 会保护最便宜的可行前缀。
 4. 按字典序比较分配：更少放宽包、更小质量缺口、更高效用、更低费用、更少路线切换，最后稳定的路线顺序。最小费用模式先比较费用，再比较效用。每条跨越 `provider/model` 路线的依赖边从效用中扣除 .015。
 5. 报告搜索元数据与可行性。正预算下若不存在可行分配，仍可返回最小费用备选，但标记 `budgetFeasible: false`。显示了计划不代表预算已满足。
 
 “精确”仅适用于保留下来的候选空间与代理目标。候选上限和 beam 裁剪意味着不能声称在所有已配置模型上全局最优。单元/合成测试验证机制，不证明真实回答质量提升。研究审查使用的公开 2026-06-25 LiveBench 分数/费用表属于汇总数据；未取得逐题配对的质量/费用矩阵，因此不主张真实路由收益。参见[研究](docs/ROUTING_RESEARCH.zh.md)、[推导/实验](docs/ROUTING_DERIVATION_EXPERIMENTS.zh.md)与[验证规程](docs/ROUTING_LIVEBENCH_VALIDATION.zh.md)。
 
-实现：[router.mjs](.dsh-plugin/shared/router.mjs)、[assignment-solver.mjs](.dsh-plugin/shared/assignment-solver.mjs)、[routing-presets.mjs](.dsh-plugin/shared/routing-presets.mjs)、[harness-plan.mjs](.dsh-plugin/shared/harness-plan.mjs) 与 [adaptive-feedback.mjs](.dsh-plugin/shared/adaptive-feedback.mjs)。
+证据导入、回退条件、推理档位与可选 JSON 验收升级的设置参见[算法优化使用说明](docs/ROUTING_ALGORITHM_OPTIMIZATION.zh.md)。验收升级默认关闭，启用后仍需通过计费与预算检查，最多增加一次普通 API 调用。
+
+实现：[router.mjs](.dsh-plugin/shared/router.mjs)、[assignment-solver.mjs](.dsh-plugin/shared/assignment-solver.mjs)、[routing-evidence.mjs](.dsh-plugin/shared/routing-evidence.mjs)、[harness-plan.mjs](.dsh-plugin/shared/harness-plan.mjs) 与 [quality-gates.mjs](.dsh-plugin/shared/quality-gates.mjs)。
 
 <a id="data"></a>
 

package/docs/INSTALLATION_GUIDE.zh.md

@@ -1,8 +1,8 @@
 # DeepSeek Harness Desktop · 独立插件安装与验证
 
-模型路由从 **0.12.0** 起独立发布；GAL 是独立的 **0.1.0** 插件。路由 **0.21.0** 声明支持官方 **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.22.0** 声明支持官方 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**。GAL 的兼容范围以其自身安装包为准。
 
-当前路由版本为 **0.21.0**，新增 Hermes Agent 与 Pi 的安装更新、检测和交互终端，OpenCode npm/pnpm 使用官方 V2 包。兼容声明列出已核对的宿主版本，不设置兼容豁免。保留原插件 id、配置与运行记录；安装后完全退出 Harness（包括托盘）再重启。官方终端、ZCode TUI 与统一安装设置继续沿用，公开数据默认关闭。
+当前路由版本为 **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.21.0` | 模型路由 |
+| 分析复杂度、按质量和费用选模型、调用官方工具 | `@ljwei-stak/dsh-model-router@0.22.0` | 模型路由 |
 | 剧情、立绘、音乐、存档、自由对话 | `@ljwei-stak/dsh-galgame@0.1.0` | Gal 模块 |
 | 两者都要 | 分别安装上面两个包 | 模型路由 + Gal 模块 |
 
@@ -24,7 +24,7 @@
 2. 在“包名、GitHub 仓库地址或本地目录路径”输入框填一个完整包名，例如：
 
    ```text
-   @ljwei-stak/dsh-model-router@0.21.0
+   @ljwei-stak/dsh-model-router@0.22.0
    ```
 
    只想安装 GAL 时填写：
@@ -40,7 +40,7 @@
    ```
 
 4. 核对预览的包名、版本和宿主兼容信息，安装并启用。完全退出 Harness（包括托盘进程）再启动，确保 Host 加载新代码。
-5. 检查插件详情与侧边栏：路由应为 **0.21.0 / 模型路由**；GAL 应为 **0.1.0 / Gal 模块**。仅装路由时没有 GAL 入口是预期行为。
+5. 检查插件详情与侧边栏：路由应为 **0.22.0 / 模型路由**；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.21.0` 获取同一安装包）
+- [模型路由 Releases](https://github.com/Alice-Marx/dsh-model-router/releases)（也可运行 `npm pack @ljwei-stak/dsh-model-router@0.22.0` 获取同一安装包）
 - [独立 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.21.0.tgz
+D:\Plugins\ljwei-stak-dsh-model-router-0.22.0.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.21.0.tgz'
+Get-FileHash -Algorithm SHA256 -LiteralPath 'D:\Plugins\ljwei-stak-dsh-model-router-0.22.0.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.21.0`。不要两个同时安装（条目 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.22.0`。不要两个同时安装（条目 id 与工具名相同）；条目 id 未变，路由设置与执行记录会保留。完成两项更新后再玩剧情，避免同时操作旧合并入口和新入口。
 4. 现在路由与 GAL 各有一个入口。独立 GAL 沿用旧存档 localStorage 键，核对当前进度和三槽；更换 profile 或进度未恢复时，先切换到匹配剧目，再导入 JSON 备份。
 5. 后续分别更新需要的插件；只用路由可以不启用或不安装 GAL。保留 profile 与应用数据，卸载插件时不要清理故事数据。
 
@@ -82,7 +82,7 @@ GAL 核心只包含**《回声之城·正篇》**与**《旧城迁移篇：未
 
 ## 5. 模型路由第一次使用
 
-工作台自 0.15.0 起分成**任务与执行、模型配置、官方工具、预算与安全**四页；0.21.0 沿用该布局。切换页面保留安装任务、终端会话和未完成的输入。
+工作台自 0.15.0 起分成**任务与执行、模型配置、官方工具、预算与安全**四页；0.22.0 沿用该布局。切换页面保留安装任务、终端会话和未完成的输入。
 
 1. 在 Harness 官方**模型**页配置供应商、模型与凭据。插件读取准确的 `provider/model` 目录，模型档案不保存 API Key。
 2. 在**模型配置**刷新目录，逐条填写自报质量评分、核对过的输入/输出单价（USD / 百万 token）和擅长方向；缺价留空。可选 `cliModel` 必须是该厂商 CLI 已验证接受的名字。可选 LiveBench 名称须准确对应版本与推理档位；它是用户确认的映射，不自动证明实际执行档位。
@@ -114,7 +114,7 @@ GAL 核心只包含**《回声之城·正篇》**与**《旧城迁移篇：未
 | 检查 | 预期 |
 | --- | --- |
 | 路由宿主版本 | 0.2.0-rc.1、0.2.0-rc.2 或 0.2.1-rc.2；包括 `rc` 后缀。 |
-| 路由独立安装 | 0.21.0 详情、模型路由入口、目录和模型档案可用；不出现旧合并 GAL 入口。 |
+| 路由独立安装 | 0.22.0 详情、模型路由入口、目录和模型档案可用；不出现旧合并 GAL 入口。 |
 | GAL 独立安装 | 0.1.0 详情、Gal 模块入口、标题与两部核心剧情可用；不要求安装路由。 |
 | 共同安装 | 两个入口各一份，路由工具和 GAL 播放器均能使用。 |
 | 存档迁移 | 同 profile 可读旧键；跨 profile 用匹配剧目 JSON 导入；旧篇目的数据不覆盖。 |
@@ -129,7 +129,7 @@ GAL 核心只包含**《回声之城·正篇》**与**《旧城迁移篇：未
 
 ## 8. 开发者从完整源码构建
 
-路由需要 Node.js **22.19+** 与 **pnpm 10.34.6**。从完整源码仓库根目录构建；当前源码版本为 0.21.0，复现已发布版本时检出对应发布标签。旧版（如 0.15.0）标签保留其当时内容。运行：
+路由需要 Node.js **22.19+** 与 **pnpm 10.34.6**。从完整源码仓库根目录构建；当前源码版本为 0.22.0，复现已发布版本时检出对应发布标签。旧版（如 0.15.0）标签保留其当时内容。运行：
 
 ```powershell
 pnpm install --frozen-lockfile --strict-peer-dependencies

package/docs/MANUAL_TASK_ASSIGNMENT.zh.md

@@ -0,0 +1,46 @@
+# 选择算法分配或手动调整
+
+在工作台生成路由建议后，可以选择 **按算法推荐分配**，也可以选择 **手动调整分配**。
+
+1. 输入任务，选择“团队分工”，生成路由建议。单任务也可以调整一个工作包；“指定模型”沿用原来的全局模型选择。
+2. 使用算法分配时，工作包按推荐方案和已设置的计费策略执行。
+3. 切换到手动调整后，每个工作包都有独立的目标选择。初始选择为该包的推荐模型 API，可改成其他已配置的模型 API，或者已安装且支持只读执行的官方工具。
+4. 核对任务目标、前置依赖、原算法推荐与新选择。修改目标不会改变任务拆分和依赖关系。恢复推荐可重新填入各包的推荐模型；切回算法分配会恢复原有自动策略。
+5. 点击“预览执行计划”，核对 Host 验证后的实际目标、费用和权限，再确认执行。修改任务、模型目录、设置、规划依据或分配选择后，需要重新预览。
+
+手动分配支持在一次运行中混合模型 API 与官方工具，例如由模型分析、Codex 检查、另一个模型汇总。各包按依赖执行，上游失败会阻止依赖它的后续工作包。结果和分配选择保存在同一份运行记录中，失败步骤重跑沿用保存的目标；改派重跑则使用新选择。
+
+## 模型和工具分别代表什么
+
+- **模型 API**：固定调用所选 provider/model，使用适配器默认推理档位。不会因为 CLI 已安装、订阅优先、质量升级或自动省钱策略而改为其他模型或渠道。配置为只用订阅的路线，以及编程套餐专用端点，不能直接作为普通 API 目标；预览会说明原因。
+- **官方工具**：固定调用所选的注册工具，使用该工具自身配置的默认模型。选择工具不等于选择某个 API 模型；如需控制工具内部模型，应在该官方工具的配置中设置。未安装、平台不支持或执行未就绪时，预览会拒绝执行；工具失败不会自动转 API。
+
+工具默认模型的价格通常无法可靠预估，因此显示“价格待配置/费用未知”，不会套用原推荐 API 模型的价格。已报告的真实费用仍按现有账本规则记录。预算 0 表示未设置本次估算上限；有限预算下，手动目标费用过高或无法确认满足本次预算时会暂停，确认后仍沿用手选目标，不会自动换成便宜模型。估算不是厂商实际扣费的硬上限。
+
+手动混合分配当前执行只读任务。需要编辑工程文件时，继续使用“官方工具协作 → 编辑文件”的隔离工作树流程。该流程保留现有权限确认与改动整合机制。
+
+如果“允许手动改派”设置关闭，工作台也会关闭手动分配入口。
+
+## 在官方会话工具中使用
+
+先调用 `model_router_plan`，保存返回的 `packagePlanKey` 和 `team.workPackages`。再调用 `model_router_execute`，使用相同的任务文本与规划模式，传入：
+
+```json
+{
+  "assignmentMode": "manual",
+  "packagePlanKey": "复制当前计划返回的键",
+  "packageAssignmentsJson": "以当前计划全部工作包 ID 为键的 JSON 对象"
+}
+```
+
+每个绑定只能是下面两种结构之一：
+
+```json
+{ "kind": "api", "provider": "目录中的供应商 ID", "model": "目录中的准确模型 ID" }
+```
+
+```json
+{ "kind": "tool", "toolId": "codex" }
+```
+
+必须覆盖当前计划中的全部工作包，不可添加其他包 ID。拆分键过期、目标不存在或后续工具未就绪时，会在第一个模型调用前拒绝整次执行。未传手动分配参数时，工具继续使用算法推荐。

package/docs/ROUTING_ALGORITHM_OPTIMIZATION.zh.md

@@ -0,0 +1,91 @@
+# 路由算法优化：实施与使用
+
+本轮把任务相关证据、模型与推理档位联合选择、真实资源估计和依赖感知搜索接入规划器，并提供可选的 JSON 结构验收级联。它们改进的是有证据约束的规划和执行行为；真实回答质量提高多少、总费用降低多少，仍需独立留出任务上的同题实测。
+
+## 已实现的行为
+
+- **任务相关质量证据**：按 provider、model、reasoningEffort、channel、任务类型精确匹配，再用查询的哈希词法特征检索相似训练任务。不同任务组才计为不同邻居；样本不足或查询不相似时回退原有估计，不给未调用模型补造标签。输出的邻居离散程度不是校准后的答对概率。
+- **模型 × effort 联合选择**：同一 API 模型至少有两个档位各自具备可用任务证据时，才把这些档位展开成独立动作。冷启动保留原档位选择方式；同一模型切换 effort 不计为跨模型交接。
+- **真实资源估计**：从成功且用量完整的工作包学习输入比例、输出 token 和耗时的经验分布，规划时使用可用的 P90 估计。计数不足、模型身份不符或用量不完整时回退启发式估计。经验分位数不保证整次运行不超预算。
+- **有界 DAG 搜索**：默认候选组合数不超过 4096 时精确枚举；更大空间保留未来依赖所需的模型边界，安全压缩被支配前缀，再按未来交接的乐观估计限宽，默认宽度 256。有限预算继续保护可负担前缀，未知价格不能证明预算可行。
+- **effort 执行一致性**：API 调用传递路由允许列表中的精确 effort ID，并记录计划值、请求值及状态。`requested` 只代表 SDK 请求已携带该控制，不证明提供方实际使用了该强度。CLI 规划使用厂商默认档位；显式传入尚未支持的 CLI effort 时记录 `unsupported`，换模型时不会继承原模型的档位。
+
+搜索结果中的 `strategy`、`expandedStates`、`dominancePruned`、`beamPruned`、`peakFrontier` 和 `beamWidth` 可用于审计。`exact` 的范围仅是传入的保留候选空间；beam 路径的 `approximate: true`、`boundCertified: false` 不提供全池最优或目标差距保证。
+
+## 导入离线质量证据
+
+在源码项目根目录运行：
+
+```powershell
+node scripts/build-routing-evidence.mjs --input data.json --output evidence.json
+```
+
+此命令只处理本地文件，不调用模型、不联网、不自动收集历史。输入顶层是 `{ "runs": [...], "observations": [...], "matrix": {...} }`，三项均可省略。输入文件上限 10 MB，`runs` 和最终展开的 `observations` 各不超过 10000 条；输入输出路径必须不同。
+
+一条 `observations` 的字段示例如下。示例不代表真实测量；`timestamp` 应使用实际采样的 Unix 毫秒时间，`quality` 应来自可追溯的客观验收。
+
+```json
+{
+  "observations": [
+    {
+      "id": "task-001:model-a:medium",
+      "groupId": "task-001",
+      "text": "修复缓存失效后返回旧值的问题",
+      "type": "code",
+      "provider": "configured-provider-id",
+      "model": "configured-model-id",
+      "reasoningEffort": "medium",
+      "channel": "harness-llm",
+      "quality": 1,
+      "split": "train",
+      "timestamp": 1792281600000,
+      "provenance": {
+        "kind": "objective",
+        "source": "unit-tests",
+        "reference": "audit/run-001"
+      }
+    }
+  ]
+}
+```
+
+每条记录必须有上述身份、任务文本、类型、评分、时间、训练划分和来源字段。`reasoningEffort: ""` 表示档位未知；不能替换为任意已知档位。`channel: "api"` 会归一为 `harness-llm`。质量分须在 `[0,1]` 内，来源须声明 `kind: "objective"` 和非空 `source`、`reference`；点赞、自评、模型裁判和主观偏好不能直接当作这类标签。
+
+`runs` 接受运行账本形状：run 含 `id`、`task`、`createdAt`、`finishedAt`、`packages`；工作包含 `id`、`provider`、`model`、`channel`、`type`、`purpose`、`ran: true`、`ok: true`、`usage`、`inputChars`、`finishedAt`，可含 `durationMs`。资源学习要求有效的非负 `usage.inputTokens`、`usage.outputTokens` 和实际正整数输入字符数。可选的 cache 计数必须是与未缓存输入互斥的读、写类别，不能把已包含缓存的总数再相加。缺失或未知计数不应补零。时间须落在有效窗口及所属 run 的起止范围内；失败、用量不完整、身份不符、重复或多次质量调用合并后的工作包不作为单动作资源样本。资源拒绝原因保留在产物 `stats` 中，账本中的评分不会自动变成质量标签。
+
+同题多动作也可用矩阵输入：`matrix` 必须含 `split: "train"` 和 `tasks`；每个 task 含 `id`、`groupId`、`text`、`type`、`timestamp`、`results`。每个 result 含 `action: {provider, model, reasoningEffort, channel}`、`quality`、`provenance`，可另给唯一 `id`。只写实际测量的动作，未调用的动作保持未知。
+
+重复 id、同一任务组的重复动作、未来或过期时间、非法客观记录和未经显式允许的 synthetic 记录会使 CLI 的质量导入失败。测试、验证、校准任务须按 `groupId` 在生成训练输入前分离；它们不能作为训练邻居导入。默认时间窗口为 180 天。
+
+`--min-samples N` 可用于离线实验，默认 8；`--now TIMESTAMP` 固定评估时间以便复现；`--allow-synthetic` 只用于测试夹具。**生产 Host 重新构建证据时固定采用至少 8 个匹配样本的门槛**，不会沿用离线降低的门槛；质量预测还要求这些样本来自不同且足够相似的任务组。上面的单条示例不足以触发质量预测。
+
+将生成文件的 JSON 文本填入插件设置的 `routingEvidenceJson`（最多 200000 字符）。Host 只从导入产物接收质量样本；资源统计从本机运行账本重新学习。`resourceLearningEnabled` 默认 `true`，关闭后停止使用账本重建资源证据。没有可用证据时保持原有冷启动回退。
+
+输出产物不保留任务和答案明文，但词法哈希不保证匿名。`revision` 是内容变化标识，不是来源认证或签名；严格解析只能校验声明的格式，不能证明评分和来源真实。
+
+## 可选结构验收与一次升级
+
+`qualityEscalationEnabled` 默认 `false`。在 `qualityGateJson` 中填写 JSON 文本，例如：
+
+```json
+{
+  "kind": "json-object",
+  "requiredKeys": ["answer"],
+  "fieldTypes": {"answer": "string", "sources": "array"}
+}
+```
+
+空文本或 `{}` 表示没有 gate。仅支持 `json-object`，只接受完整 JSON 对象，不从散文或 Markdown 代码块提取 JSON。`requiredKeys` 最多 32 个安全键；`fieldTypes` 支持 `string`、`number`、`boolean`、`object`、`array`、`null`，只检查存在的自身字段；需要必填的字段须同时列入 `requiredKeys`。未知配置字段、非法类型和危险键会被拒绝。JSON 数字必须有限。
+
+gate 检查结构，不判断回答是否正确。首次通过、没有 gate、升级关闭、请求失败、取消、阻塞、暂停或截断，都不会因此多调用模型。只有显式启用升级、首次结构验收失败、存在不同 provider/model 的已配置合格 API 替代路线，并通过预算与计费批准，才最多再调用一次；不循环重跑同一模型。
+
+当前自动质量升级适用于普通 API 工作包：原路线和替代路线均须显式配置 `execution: "api"`，或属于没有官方工具映射的提供方；两者都排除显式 `subscription-first`、`subscription-only` 和 `execution: "official"`，也排除计费计划识别出的任何订阅（含编程套餐名称与关联 `apiRoute`）。有官方工具映射的 API 路线可用 `subscription: "none"` 明确普通 API 身份。替代路线的已知质量先验须高于原路线。CLI、编程套餐订阅调用和 direct 强制指定模型不会自动换模型升级。首次调用已经产生的 usage、价格快照和报告费用会保留在 `qualityAttempts` 中；批准回调失败、第二次失败或两次之间取消，都不能抹掉首次消耗。不同模型的 token 不合并成一个虚假的单模型账单。部分费用未知时 `costUsd` 保持 `null`，已知部分另以 `knownCostUsd` 计入日/月已知小计，并保留未知标记。
+
+## 验证与解释边界
+
+```powershell
+npm run test:routing-algorithm
+node --test tests/routing-search-experiment.test.mjs tests/routing-search-summary.test.mjs tests/routing-search-frontier.test.mjs tests/routing-optimizer.test.mjs
+```
+
+搜索回归同时检查独立穷举 oracle、预算、随机 DAG、档位交接和顺序稳定性。已知 6561 组合反例恢复了零交接解；1728 组合反例的无预算 beam 路径也与 oracle 一致。不过宽度 1 的紧预算条件仍可能损失目标效用，测试继续保留这一差距。固定池上的这些结果不能代替真实模型质量与总成本评估。

package/docs/WORKBENCH_USER_GUIDE.zh.md

@@ -1,6 +1,8 @@
 # 模型路由工作台：配置、规划与实际执行
 
-适用版本：`@ljwei-stak/dsh-model-router@0.21.0`。声明兼容 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.22.0`。声明兼容 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)。
+
+0.22.0 新增“按算法推荐分配 / 手动调整分配”：生成任务建议后，可为每个工作包选择模型 API 或官方工具；修改后重新预览费用与渠道，再确认执行。任务依赖与重跑目标保留。手动混合执行当前只读，官方工具使用自身默认模型；编辑文件继续选择官方工具协作。详见[手动分配说明](MANUAL_TASK_ASSIGNMENT.zh.md)。Hermes 自定义程序目录、原配置/登录/历史位置，以及工具页顶部终端的行为继续保留。
 
 0.21.0 新增 Hermes Agent 与 Pi 的安装更新、版本检测及交互终端，OpenCode npm/pnpm 切换至官方 V2 包。Hermes 与 Pi 的登录由各自 CLI 完成，暂不提供经过验证的托管执行器。
 
@@ -164,7 +166,7 @@ MiniMax 官方 Windows 脚本的 `<# ... #>` 是 PowerShell 帮助注释。0.18.
 | Gemini CLI | ✓ | — | — | 支持 |
 | OpenCode | ✓ | bash | — | 包管理器支持；脚本固定 ~/.opencode/bin |
 | Step Code | — | bash | PowerShell | 脚本使用根目录/stepcode |
-| Hermes Agent | — | bash | PowerShell | 厂商管理独立的源码、命令与数据位置；统一目录不迁移这些位置 |
+| Hermes Agent | — | bash | PowerShell | 源码放统一根/hermes-agent；配置和数据仍保留原位置 |
 | Pi | npm/pnpm | — | — | `@earendil-works/pi-coding-agent`；Node.js ≥22.19，安装带 `--ignore-scripts` |
 | ZCode | — | — | — | 官方 Windows 桌面安装窗口中选择 |
 
@@ -199,7 +201,7 @@ MiniMax 官方 Windows 脚本的 `<# ... #>` 是 PowerShell 帮助注释。0.18.
 
 终端清单现覆盖全部十二个注册表工具，包含 Hermes Agent、Pi、OpenCode、Step Code 和 Windows ZCode 内置 TUI。“刷新”重新检测安装状态；启动沿用已保存的安装方式与目录，选定副本不存在时会提示，不改用 PATH 上的其他副本。
 
-Hermes 安装后运行 `hermes auth`；Pi 启动后输入 `/login`，没有独立的 `pi login` 命令。两者的登录状态显示为未知，插件不读取凭据。Hermes 的 Windows 命令目录默认为 `%LOCALAPPDATA%/hermes/bin`（配置 `HERMES_HOME` 时使用其 `bin` 子目录），POSIX 使用 `~/.local/bin`；这些路径由厂商管理。卸载 Hermes 源码安装请在终端使用 `hermes uninstall`，桌面/MSIX 版使用系统应用管理。
+Hermes 安装后运行 `hermes auth`；Pi 启动后输入 `/login`，没有独立的 `pi login` 命令。两者的登录状态显示为未知，插件不读取凭据。Hermes 的 Windows 命令目录默认为 `%LOCALAPPDATA%/hermes/bin`（配置 `HERMES_HOME` 时使用其 `bin` 子目录），POSIX 使用 `~/.local/bin`；未设置统一目录时沿用这些厂商命令目录；设置后，源码安装到统一根/hermes-agent，插件绑定其中的 `.hermes/bin` 入口，不迁移现有配置与历史。卸载 Hermes 源码安装请在终端使用 `hermes uninstall`，桌面/MSIX 版使用系统应用管理。
 
 已安装 **ZCode 桌面版**时，在 ZCode 工具行的“ZCode TUI 独立配置”填写其桌面目录，例如 `D:/Program Files/ZCode`，点击“保存并刷新 TUI 入口”；留空恢复自动检测。核验成功后在官方工具终端选择 **ZCode TUI（桌面版内置）**，使用现有登录环境自行配置模型和插件。无需额外独立 CLI 安装包。内置 CLI 随桌面版更新；ZCode 行可单独“检查并更新桌面版”或“重新安装桌面版”，在官方窗口完成后重新体检。桌面版本与内置 CLI 版本不同，工具行显示桌面版本。
 

package/docs/releases/0.22.0-validation.md

@@ -0,0 +1,28 @@
+# 0.22.0 release acceptance
+
+Date: 2026-10-19. Package: `@ljwei-stak/dsh-model-router@0.22.0`.
+
+This release combines routing algorithm improvements and the algorithm/manual work-package assignment choice. It retains the existing plugin identity, saved configuration, execution history and supported DSH SDK versions.
+
+## Automated and UI checks
+
+- Full suite: 966 tests, 963 passed, 0 failed, 3 existing platform-dependent skips. Skipped PTY/process checks do not count as real execution acceptance.
+- The manual-assignment increment adds 45 tests covering strict targets, task-decomposition identity, complete preflight validation, pinned APIs, exact tools, subscription restrictions, budget behavior, mixed dependency context, stored intent and retries.
+- Twelve Chromium interactions against the actual workbench component and offline fixtures passed: default algorithm mode, per-package manual controls, unavailable tool choices, mixed-target preview, stale confirmation invalidation, simulated execution and stored tool intent, restore, return to algorithm mode, single-package adjustment, direct mode, 390-pixel layout and stale asynchronous responses. Screenshots were inspected. These use simulated data and no paid model calls.
+- `pnpm install --frozen-lockfile --strict-peer-dependencies` with pinned pnpm 10.34.6, the actual client build, generated-client consistency, workbench preview compilation, package preflight and `git diff --check` passed.
+- Before publication, the generated tarball is checked against the exact release commit's Git blobs; after publication, registry and GitHub Release assets are downloaded and compared with that verified tarball. The release audit records the commit and tarball digests separately.
+
+One development run of the existing Windows multi-process state test encountered an `EPERM` while opening its lock file. Five isolated rechecks and the final full suite passed. This release does not claim to fix that intermittent locking behavior.
+
+## Behavioral boundaries
+
+- Manual mixed API/tool execution is read-only. Editing remains in the existing official-team workflow with its isolated worktree and permission checks.
+- An explicit API target uses the selected provider/model and adapter-default effort. It is not replaced by CLI preference, budget downgrade or automatic quality escalation. Subscription-only and coding-plan routes cannot bypass their billing policy by being selected as ordinary APIs.
+- A selected official tool uses its own configured default model. Missing installation, execution support or readiness blocks execution before the first paid package; failure does not silently switch to API. Unknown tool prices stay unknown.
+- Objective task evidence requires valid training observations and enough matching samples. Resource P90 values are empirical estimates, not joint budget guarantees. Beam search remains approximate over retained candidates. The tests establish mechanisms rather than measured production routing quality or savings.
+- JSON validation checks structure, not semantic truth. Automatic escalation defaults to off and permits at most one eligible API upgrade after budget approval, retaining every attempt's known or unknown cost.
+- Exact SDK effort requests do not establish the provider's actual internal reasoning effort. Official CLI effort mappings remain unsupported.
+
+No new real provider or vendor CLI model execution was performed for 0.22.0. Earlier real execution evidence remains in the dated [0.20.0 report](0.20.0-validation.md); it is not relabeled as evidence for this release's new behavior. Hermes/Pi managed execution remains unverified.
+
+Upgrade by fully quitting Harness, including its tray and Host process, updating the plugin to 0.22.0, and restarting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ljwei-stak/dsh-model-router",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "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": {
@@ -93,7 +93,15 @@
     "LICENSE",
     "CHANGELOG.md",
     "docs/assets/router-only-0.12.0.png",
-    "docs/releases/0.20.0-validation.md"
+    "docs/releases/0.20.0-validation.md",
+    ".dsh-plugin/shared/reasoning-execution.mjs",
+    ".dsh-plugin/shared/routing-evidence.mjs",
+    ".dsh-plugin/shared/quality-gates.mjs",
+    "docs/ROUTING_ALGORITHM_OPTIMIZATION.zh.md",
+    ".dsh-plugin/shared/package-assignments.mjs",
+    ".dsh-plugin/shared/manual-plan.mjs",
+    "docs/MANUAL_TASK_ASSIGNMENT.zh.md",
+    "docs/releases/0.22.0-validation.md"
   ],
   "scripts": {
     "build:client": "node scripts/build-client.mjs",
@@ -105,9 +113,12 @@
     "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 --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",
+    "test": "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",
     "prepack": "node scripts/prepack.mjs",
-    "pack:local": "npm pack --pack-destination dist"
+    "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",
+    "build:routing-evidence": "node scripts/build-routing-evidence.mjs",
+    "test:manual-assignment": "node --test tests/manual-package-execution.test.mjs tests/manual-plan.test.mjs tests/manual-assignment-ui.test.mjs tests/manual-assignment-host.test.mjs"
   },
   "license": "MIT",
   "engines": {