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

package/docs/WORKBENCH_USER_GUIDE.zh.md

@@ -0,0 +1,192 @@
+# 模型路由工作台：配置、规划与实际执行
+
+适用版本：正式版 `@ljwei-stak/dsh-model-router@0.16.0`；声明兼容 DeepSeek Harness Desktop `0.2.0-rc.1 / 0.2.0-rc.2`。安装与开发见[中文 README](../README.zh.md)，旧包迁移见[迁移说明](../MIGRATION.md)。
+
+0.15.0 新增四页布局、规划后直接展示路由建议、执行输入变化时丢弃旧预览，以及历史裁剪和重试后的费用累计保留。源码中的独立 UI 预览使用模拟数据，用于组件检查，不代表真实账号调用或桌面端到端验收。
+
+0.16.0 加入可选动态公开能力/价格快照，以及分任务类型的持续反馈学习。公开数据默认关闭；反馈只调整本地主观效用，不改公共能力评分或质量门槛。本版发布验证见[更新记录](../CHANGELOG.md)，不把模拟数据测试视作真实付费调用或桌面端到端验证。
+
+工作台分成四页：**任务与执行、模型配置、官方工具、预算与安全**。顶部概览显示模型路线、工具检测与今日已记录 API 费用。切换页面保留面板状态；已有安装任务和终端会话不会因切页重新创建。
+
+## 第一次使用
+
+1. 在 Harness 官方**模型**页添加供应商、模型和凭据。
+2. 打开工作台的**模型配置**，点击目录的**刷新**，确认有准确的 `provider/model`。
+3. 到**官方工具**查看体检。安装、可信入口、登录、模型权限是不同状态；可先不安装 CLI，通过已配置的模型 API 执行。
+4. 按需要在**预算与安全**设置路由方案、每日/月度预算与订阅失败策略。
+5. 返回**任务与执行**，先生成本地计划，再决定是否预览、确认真实执行。
+
+目录数量不是可用账号数量。模型目录不会在这里新增模型，也不显示或接收 API Key。
+
+## 模型配置：给路由器可靠资料
+
+在**逐模型价格与能力**选择准确路线，逐条配置后点击**保存此模型**。配置只覆盖已经在官方目录中登记的路线。
+
+| 字段 | 含义与填写规则 |
+| --- | --- |
+| 质量评分 | `0–100` 的自报估值，不是官方排名；没有依据可留空。 |
+| 输入/输出单价 | 两项同时填写，单位 **USD / 百万 token**；未知留空，零表示确实按零价估算。 |
+| 缓存价 | 可选缓存读取/写入单价；应与相应供应商计费口径一致。 |
+| 擅长方向 | 英文小写标签，逗号分隔，例如 `code, reasoning`。 |
+| 官方 CLI 模型名 | 仅填厂商 CLI 已验证接受的名称；不等同于 Harness 模型 ID。ZCode 不支持逐次换模型。 |
+| LiveBench 准确模型名称 | 可选的显式基准映射，须确认模型版本与推理档位一致；不自动猜测别名，也不证明实际执行参数。 |
+| 执行方式 | `auto`、`official` 优先适用的官方工具；`api` 只走模型目录 API。 |
+| 计费方式 | 默认 `subscription-first`；也可指定 `api-only` 或 `subscription-only`。 |
+| 订阅来源 | 自动识别，或显式 `cli-login`、`plan-key`、`none`。 |
+| API 回退路线 | 仅套餐 Key 路线可指定，必须是另一个准确、已配置的 `provider/model`。 |
+
+套餐 Key、供应商地址和凭据在 Harness 官方设置中配置。模型档案不接受密钥、任意命令或自定义安装包。保存档案后旧计划失效，需要重新生成。
+
+## 任务与执行：先规划
+
+写清目标、交付物、约束与验收。复合任务按编号分别写，可明确指出依赖；大量背景文字可能被当作需求，过多执行项可能被合并。
+
+```text
+目标：审阅仓库并形成可实施的改进清单。
+1. 梳理主要入口、状态流转与 UI 页面。
+2. 检查宽屏、窄屏和长内容下的布局。
+3. 基于第 1、2 步，设计改动顺序和验收清单。
+4. 独立核查执行、权限和成本提示是否准确。
+验收：每项列出位置、问题、改动建议和检查方法。
+```
+
+| 规划模式 | 行为 |
+| --- | --- |
+| **单任务** | 推荐一条合适路线；不等于已经调用该模型。 |
+| **团队分工** | 对足够复杂的请求拆出带依赖的工作包；简单任务可能仍只有一个包。 |
+| **指定模型** | 为整项任务选择一个准确路线，跳过其他模型比较。 |
+
+**本次估算预算（USD）** 是规划目标：`0` 表示不限制本次估算，`10` 表示 10 美元目标，不是账号扣费上限。
+
+点击**生成路由建议**。建议直接显示在规划卡片之后，不需要先越过模型档案。这一步在本机完成，不读取工作区文件、启动 CLI 或向模型发送任务。
+
+启用动态公共数据后，生成前读取 Host 的当前账本/快照；到达检查间隔时会请求公开源，但不把任务、回答或用户反馈发送给该源。公开源开关关闭时不进行这些远程刷新。
+
+查看推荐路线、复杂度、估算成本、路由方案与执行渠道；团队结果还包括目标、依赖、难度、费用和验收清单。**价格待配置**表示缺少可靠单价；质量约束放宽或图像包无法分配时应先检查资料。**官方 CLI**是计划的渠道提示，不代表该账号一定有调用权限；**模型目录 API**也不代表该路线能进入 CLI 团队执行器。
+
+修改任务、模式、预算、档案、目录或学习/数据设置后重新生成建议。数据或反馈版本变化会使旧建议失效；陈旧异步回包不会替换新的输入。路由算法的实现与假设见 [README](../README.zh.md#路由算法从输入到分配)。
+
+## 在工作台执行：预览后确认
+
+**在工作台执行**沿用任务文本和规划模式，允许选择路由方案并填写工作区。它仅发起只读执行；需要 CLI 修改文件时使用官方会话。
+
+1. 输入已经存在的工作区绝对路径，例如 `F:\projects\demo`；留空沿用上次运行的路径。
+2. 点击**预览执行计划**。宿主根据当前目录、登录、额度、预算和方案给出与 `model_router_execute` 相同的决策，包括适用的省钱降级。
+3. 核对预估费用、路线、工作包及全部确认项。超预算和直接启动无沙箱 CLI 的原因会合并展示。
+4. 明确确认执行后才调用模型/CLI。期间状态变化可能导致宿主拒绝旧确认，需重新审阅。
+5. 在下方**执行记录与子任务**看结果、状态、实际渠道、原始失败原因和费用。实际运行可能计费。
+
+修改任务、模式、路由方案或工作区等执行输入后，正在请求或已经返回的旧预览会被丢弃。重新预览并核对当前请求后才能确认执行。
+
+**预览不会启动模型，确认会启动。** 模型 API 将任务文本发给供应商；CLI 可能读取工作区或其他其权限允许的文件。只读不等于所有 CLI 只能读取工作区，先看**预算与安全 → 安全边界**。
+
+工作台不自动控制 Blender、剪辑软件或图像引擎。它可以规划和委派文字/代码任务；真实图片、音频或视频交付仍需相应工具制作和验收。
+
+## 执行记录、失败处理与质量
+
+记录展示分配模型、执行渠道、费用、步骤依赖和错误。任务/回答摘录会本地保存，因此分享日志或截图前先脱敏。
+
+- **只读路由/团队失败**：重跑失败步骤及依赖它的未完成步骤；已完成结果作为上下文保留。允许时可改派另一条已配置路线。
+- **可编辑团队失败**：符合条件时在新独立工作树中套用此前改动后续跑；要求原仓库干净且仍在原基线。已经整合或等待人工整合的运行不能任意单步重跑。
+- **单工具调用失败**：重新执行原调用，生成关联的新运行；可编辑模式仍需审批。
+- **订阅普通失败**：默认显示**等待确认**，可选择**改用 API 重试、重试订阅、取消**。API 重试会需要确认，登录问题可先重新登录再重试。
+- **评价**：成功结果上的 👍/👎 是你的明确评价，再点已选按钮可撤回；按准确路线、任务类型和结果完成时间形成衰减、向零收缩的主观偏好效用。默认最大调整 ±0.04，可配置到不超过 ±0.1；不改变客观质量分或公共质量门槛。重跑替换结果后旧评价清除，旧页面上的评价请求会被拒绝，需刷新。
+- **复核**：强模型抽查由预算页的质量回路控制，会产生额外真实调用；复核分不作为人工反馈。通过官方会话的 `model_router_rate` 保存评价需要用户审批，Agent 不能给自己评分；来源标记是审计信息，不是独立的人类身份认证。
+
+保存的任务文本最多 20,000 字符，单个回答最多 4,000 字符；历史不是完整交付文件的替代，重跑可能使用截断后的上下文。
+
+## 官方工具：体检、安装与登录
+
+当前注册表包括 Kimi、Claude、Codex、MiniMax、MiMo、Grok、Gemini 和 ZCode。点**重新体检**查看实际安装、版本、入口及账号状态；最新版查询失败时保持未知，不表示已无更新。
+
+1. 未安装时可从卡片固定官方来源安装；npm 工具安装厂商 `@latest`。新厂商版本没有自动通过本项目测试。
+2. 安装中可查看日志或取消；取消后重新体检确认状态。
+3. 有更新时可更新；已安装版本比查询结果更高时不会降级。
+4. 已安装但未就绪时查看入口/平台原因，使用适用的修复动作；仅检测到文件不能证明可信执行。
+5. ZCode 打开官方安装窗口后，还需要手动选目录完成安装，再体检。它属于 Windows 桌面应用。
+6. 按**去登录**提示，在对应 CLI/终端完成厂商授权，然后用小任务验证权限。
+
+注册表 ID 和托管模式如下：
+
+| 工具 ID | 单工具/团队执行支持 |
+| --- | --- |
+| `claude-code`、`codex`、`mimo-code`、`grok-build` | 只读，以及经审批的可编辑执行。 |
+| `kimi-code`、`minimax-code`、`zcode` | 经审批的可编辑执行。 |
+| `gemini` | 路由无界面适配器，不进入单工具/团队托管执行器。 |
+
+### 交互终端
+
+在**官方工具终端**选择系统终端或已安装的 CLI，填写存在的绝对目录；支持时可选登录方式。启动确认显示命令、目录与权限范围。
+
+终端**不经过 Harness 沙箱**，保留用户登录环境、代理和 API Key 变量；输入的命令可按用户权限修改文件。它与上面的只读路由执行分别处理，不共享“只读”的承诺。
+
+PTY 加载失败时卡片显示**管道模式**：全屏界面、箭头键、尺寸同步可能不可用。最多四个并发会话，无人读取约两分钟或达到六小时上限会结束。切换工作台页面保留会话；关闭整个工作台会终止。完成后点**结束会话**。输入/输出不持久化，只记录工具、目录、时间及退出状态。
+
+## 预算与安全
+
+**成本控制与路由方案**支持省钱优先、均衡、效果优先，以及每日/月度预算、超预算动作、订阅普通失败策略和质量回路。指定模型模式跳过路线比较；未知价格无法保证满足预算。
+
+**订阅与 API Key**显示供应商计费方式、订阅来源、状态/恢复时间及 API 回退是否可用。检测到额度用尽或限流后，路由执行可按策略转 API 并记录原因；其他订阅错误默认暂停确认。单工具/团队托管执行不会自动转 API。
+
+API 花费计入预算；订阅显示按 API 价折算的参考费用，不计入预算。预算和费用是本地估算/核算，不代替厂商账单；无法确定费用时显示未知。
+
+0.15.0 会保留裁剪详细历史及重试前的费用累计，避免超过 200 条历史或重跑步骤后预算漏算。此前旧版本已丢弃的消费记录无法恢复。
+
+### 持续反馈与本地偏好
+
+在**预算与安全 → 成本控制与路由方案 → 持续反馈与本地偏好**设置**启用用户反馈学习**、半衰期（默认30天）、收缩强度（默认3）和最大偏好效用调整（默认0.04，允许0–0.1）。较旧结果权重更低，少量评价被收缩到接近零；没有评价不等于失败或满意，执行成功也不自动计为好评。查看有效反馈数、有效权重和策略版本后重新规划。
+
+学习限定在同一个本地 **DSH_HOME 工作室共享**、最近 **200 次运行**，不按账号隔离，也不无限保存学习记忆；未核验实际模型的 CLI 默认结果不会训练推荐模型。启停不删除评价。“从现在重新学习”会先请求确认，再将学习起点移到当前时间；此前结果不再参与调整，但执行历史和费用累计保留。本版不为学习自动探索或增加付费模型调用。
+
+### 动态公共数据
+
+在相邻的**动态公共数据**区域明确启用开关。默认关闭；启用后按**公共快照检查间隔**（默认1440分钟）在打开/刷新账本及执行前检查公开源。LiveBench 默认官方站点；自定义 JSON 镜像必须明确 `scoreScale: 1` 或 `100`，准确模型身份与分值须通过校验，不能用高推理档位成绩冒充其他动作。
+
+**价格快照公开源**可留空。配置时只接受不含认证、查询参数或片段的公开 HTTPS 地址；该数据是按官方文档策展、带来源与时间版本的严格 JSON，不是通用厂商价目表抓取器。当前仅支持准确 `provider/model` 的 USD/百万 token 固定输入/输出及可选缓存价；复杂阶梯、时段或非 token 计费不支持此格式。填写来源链接不代表插件已认证价目内容。人工配置单价优先，缺价仍保持未知。
+
+查看 LiveBench / 价格快照的状态、版本与校验时间；更新失败保留最近有效数据并标记状态，过期数据不能当作最新价格。清空价格源或关闭公开数据开关会停止使用对应动态数据，而不删除可恢复的历史快照。执行记录保存当次实际采用的费率和数据/策略版本，新价格不会回算旧费用。公开源不接收任务和反馈；真实执行仍会发送所选任务给相应模型/CLI。
+
+推导、快照协议与机制实验见[动态数据与持续反馈说明](ROUTING_ADAPTIVE_LEARNING.zh.md)。这些机制实验没有证明实际质量—成本收益，也没有验证所有模型的实际推理档位。
+
+**安全边界**显示各路线可读/写范围与沙箱。模型 API 没有本地进程文件访问；可编辑 CLI 要求 Harness 沙箱和独立 Git 工作树。缺少沙箱时可编辑托管执行被拒绝。交互终端始终在沙箱外运行。
+
+## 从官方会话启动任务
+
+在 Harness 选择正确工作区，使用自然语言明确要求调用插件工具。以下 JSON 是核对工具调用详情的示例，不需要粘贴到工作台任务框。
+
+只生成计划：
+
+```json
+{"task":"检查项目架构和 UI，给出分工及验收方法","mode":"team","budgetUsd":10}
+```
+
+对应 `model_router_plan`。真正调用一个 CLI：
+
+```json
+{"tool":"codex","task":"只读检查当前仓库并列出 UI 问题；不要改文件","mode":"read-only"}
+```
+
+对应 `model_router_tool_run`。按当前可执行 CLI 分工：
+
+```json
+{"task":"检查布局、接口和测试，逐包给出可核对的问题清单","mode":"read-only","budgetUsd":10}
+```
+
+对应 `model_router_team_execute`。要编辑文件，改为 `workspace-write`，并使用干净 Git 仓库、可编辑官方会话和宿主审批。团队会按当前已就绪且支持模式的 CLI 重新规划，因此可能与本地建议不同。
+
+其他常用工具为 `model_router_execute`（按路由或明确模型只读执行）、`model_router_consult`（模型 API 意见）、`model_router_health`、`model_router_rerun_step` 与 `model_router_rate`。完整列表见 [README](../README.zh.md#官方会话工具)。
+
+## 常见情况
+
+| 情况 | 处理 |
+| --- | --- |
+| 规划按钮不可用 | 等目录/工具检测完成；在模型配置刷新，必要时先配置官方模型页。 |
+| 找不到建议 | 返回任务与执行页；结果就在规划后方。输入变化后需重新生成。 |
+| 推荐路线不符合预期 | 核对质量、单价、专长、方案和任务描述；目录路线不代表账号权限。 |
+| 预览与旧建议不同 | 当前目录、登录、额度或预算可能已变化，以新预览核对。 |
+| CLI 卡片正常但执行失败 | 看原始错误、登录/模型权限、网络、平台支持、会话工作区及审批。 |
+| 提示后台版本旧 | 完全退出 Harness（包括托盘进程），再启动。 |
+| 终端 TUI 不显示 | 检查 PTY/管道模式；管道只能保证较简单命令行交互。 |
+| 工具名在会话中不可用 | 确认插件启用，重新开始会话；记录宿主/插件版本与脱敏错误。 |
+
+问题反馈请附宿主/插件版本、执行模式、工具状态及脱敏错误，勿提供密钥。源码、安装和资料入口见[中文 README](../README.zh.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ljwei-stak/dsh-model-router",
-  "version": "0.14.0",
+  "version": "0.16.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": {
@@ -44,6 +44,10 @@
     ".dsh-plugin/shared/harness-plan.mjs",
     ".dsh-plugin/shared/model-profiles.mjs",
     ".dsh-plugin/shared/router.mjs",
+    ".dsh-plugin/shared/assignment-solver.mjs",
+    ".dsh-plugin/shared/adaptive-feedback.mjs",
+    ".dsh-plugin/shared/dynamic-data.mjs",
+    ".dsh-plugin/shared/dynamic-data-view.mjs",
     ".dsh-plugin/shared/livebench.mjs",
     ".dsh-plugin/shared/official-tool-registry.mjs",
     ".dsh-plugin/shared/official-tools-runtime.mjs",
@@ -68,6 +72,14 @@
     "cordis.patch.yml",
     "README.md",
     "README.zh.md",
+    "docs/WORKBENCH_USER_GUIDE.zh.md",
+    "docs/ROUTING_RESEARCH.zh.md",
+    "docs/ROUTING_DERIVATION_EXPERIMENTS.zh.md",
+    "docs/ROUTING_LIVEBENCH_VALIDATION.zh.md",
+    "docs/ROUTING_LIVEBENCH_DATA_SEARCH.zh.md",
+    "docs/ROUTING_SELFTEST_STEPS.zh.md",
+    "docs/ROUTING_ADAPTIVE_LEARNING.zh.md",
+    "docs/assets/workbench-task-preview.jpg",
     "docs/assets/routing-workflow.svg",
     "docs/assets/desktop-official-tools-0.9.0.png",
     "docs/assets/workbench-usage.svg",
@@ -81,7 +93,14 @@
   "scripts": {
     "build:client": "node scripts/build-client.mjs",
     "check:client": "node scripts/build-client.mjs --check",
-    "test": "node --test tests/router.test.mjs tests/harness-*.test.mjs tests/official-tools.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/vendor-adapters.test.mjs tests/desktop-compat.test.mjs tests/plugin-split.test.mjs tests/task-executors.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",
+    "preview:ui": "node scripts/workbench-preview.mjs",
+    "eval:routing": "node scripts/evaluate-routing.mjs",
+    "experiment:routing-search": "node scripts/routing-search-experiment.mjs",
+    "experiment:routing-regression": "node scripts/routing-regression-study.mjs",
+    "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-team-runtime.test.mjs tests/model-profiles.test.mjs tests/model-profile-editor.test.mjs tests/tool-install-state.test.mjs tests/vendor-adapters.test.mjs tests/desktop-compat.test.mjs tests/plugin-split.test.mjs tests/task-executors.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",
     "prepack": "node scripts/prepack.mjs",
     "pack:local": "npm pack --pack-destination dist"
   },