@ljwei-stak/dsh-model-router 0.14.0 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.dsh-plugin/client.js +246 -73
- package/.dsh-plugin/index.mjs +9 -9
- package/.dsh-plugin/shared/router-state.mjs +17 -7
- package/.dsh-plugin/shared/run-ledger.mjs +88 -24
- package/CHANGELOG.md +11 -0
- package/INSTALLATION_GUIDE.zh.md +35 -27
- package/README.md +154 -365
- package/README.zh.md +154 -356
- package/docs/WORKBENCH_USER_GUIDE.zh.md +170 -0
- package/docs/assets/workbench-task-preview.jpg +0 -0
- package/package.json +4 -1
package/README.zh.md
CHANGED
|
@@ -1,441 +1,239 @@
|
|
|
1
1
|
# Model Router · DeepSeek Harness 模型路由插件
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
为 **DeepSeek Harness Desktop** 提供任务规划、成本感知的模型分配和官方工具执行工作台。输入任务，比较已配置模型，审阅计划，再明确选择是否执行。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
当前版本为 **0.15.0**，包名为 `@ljwei-stak/dsh-model-router`；声明兼容的宿主为 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2**。自 0.12.0 起，路由与 [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) 已拆成两个独立插件。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**0.15.0 更新**：工作台分为四页，路由建议紧接任务规划展示；执行输入变化时丢弃旧预览；裁剪历史或重试后仍保留费用累计；源码开发新增独立模拟 UI 预览。
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
[English](README.md) · [工作台完整指南](docs/WORKBENCH_USER_GUIDE.zh.md) · [安装与验证](INSTALLATION_GUIDE.zh.md) · [迁移说明](MIGRATION.md) · [更新记录](CHANGELOG.md)
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## 当前功能
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
- [订阅优先：额度用尽才切换 API Key](#订阅优先额度用尽才切换-api-key)
|
|
26
|
-
- [路由算法：从输入到分配](#路由算法从输入到分配)
|
|
27
|
-
- [官方工具与执行边界](#官方工具与执行边界)
|
|
28
|
-
- [可选安装 GAL](#可选安装-gal)
|
|
29
|
-
- [验证与开发](#验证与开发)
|
|
30
|
-
|
|
31
|
-
## 安装与版本选择
|
|
32
|
-
|
|
33
|
-
在 **DeepSeek Harness Desktop → 插件 → 添加插件** 中，按需求填写一个完整包名：
|
|
34
|
-
|
|
35
|
-
| 安装内容 | 输入框填写 | GitHub 仓库 |
|
|
36
|
-
| --- | --- | --- |
|
|
37
|
-
| 模型路由、模型档案与官方工具 | `@ljwei-stak/dsh-model-router@0.14.0` | [Model Router](https://github.com/Alice-Marx/dsh-model-router) |
|
|
38
|
-
| GAL 剧情、自由模式与播放器 | `@ljwei-stak/dsh-galgame@0.1.0` | [DeepSeek Harness GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) |
|
|
39
|
-
|
|
40
|
-
1. npm 安装源选择官方 **HTTPS** 地址 `https://registry.npmjs.org/`；国内镜像尚未同步时可改用此源或版本化 GitHub 安装包。
|
|
41
|
-
2. 核对安装预览版本与宿主版本，安装并启用；有重启提示时重启。
|
|
42
|
-
3. 路由详情应为 **0.14.0**，侧边栏显示 **模型路由**；独立 GAL 详情应为 **0.1.0**，另显示 **Gal 模块**。
|
|
43
|
-
|
|
44
|
-
普通使用不需要 `npm install -g`：全局 npm 安装不会注册到当前 Harness profile。路由与 GAL 都可以不安装另一插件而运行。
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
### 从旧包名 @ljwei-stak/model-router-galgame 升级
|
|
48
|
-
|
|
49
|
-
0.13.0 起包名改为 `@ljwei-stak/dsh-model-router`。旧包名的最后版本同样是 0.13.0，内容相同，之后的更新只发布到新包名。插件管理器无法原地更新旧条目：
|
|
50
|
-
|
|
51
|
-
1. 在插件管理器卸载 `@ljwei-stak/model-router-galgame`（保留 profile 与应用数据）。
|
|
52
|
-
2. 添加 `@ljwei-stak/dsh-model-router@0.14.0`，按提示重启。
|
|
53
|
-
3. 不要两个同时安装：二者使用相同的 profile 条目 id `model-router-galgame` 和相同的 `model_router_*` 工具名。条目 id 未变，所以 profile 中保存的路由设置以及 `~/.dsh/model-router/state.json` 里的执行记录会保留。
|
|
54
|
-
|
|
55
|
-
### 从合并版 0.11.x 升级
|
|
13
|
+
| 功能 | 实际行为 |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| 任务规划 | 本地分析任务类型与复杂度；生成单路线建议、带依赖的团队工作包，或直接指定一个已配置模型。 |
|
|
16
|
+
| 模型配置 | 读取 Harness 官方目录中的准确 `provider/model`；可填写自报质量、美元单价、专长、CLI 模型名、执行与计费偏好。 |
|
|
17
|
+
| 路由方案 | 省钱优先、均衡、效果优先；按质量门槛、预估 token 成本与有限组合搜索分配模型。未知价格保持未知。 |
|
|
18
|
+
| 只读执行 | 工作台先预览、再确认执行；也可在官方会话调用工具。支持的无界面 CLI 或模型目录 API 返回结果并留存记录。 |
|
|
19
|
+
| 可编辑执行 | 通过官方会话启动单个 CLI 或顺序 CLI 团队，经审批在独立 Git 工作树修改，满足条件后整合补丁。 |
|
|
20
|
+
| 官方工具 | 八个固定注册表工具的检测、安装/更新、可信入口与登录体检；安装有日志和取消操作。 |
|
|
21
|
+
| 交互终端 | 系统终端/PowerShell 与七个 CLI，含固定登录命令、多会话和实时输出。 |
|
|
22
|
+
| 成本与订阅 | 每日/月度预算检查、自动尝试省钱方案或暂停、订阅优先、额度冷却，以及其他订阅失败的确认流程。 |
|
|
23
|
+
| 执行与质量记录 | 逐工作包结果、依赖图、失败详情、重跑/改派、用户评价与可选强模型复核。 |
|
|
24
|
+
| 执行边界 | 显示每条路线可读/可写范围，以及是否经过 Harness 进程沙箱。 |
|
|
56
25
|
|
|
57
|
-
|
|
58
|
-
2. 在**同一个 profile**安装 `@ljwei-stak/dsh-galgame@0.1.0`。
|
|
59
|
-
3. 在插件管理器卸载原 `@ljwei-stak/model-router-galgame`，再添加 `@ljwei-stak/dsh-model-router@0.14.0`（见上文“从旧包名升级”）。完成两项安装后再游玩；旧合并插件的 GAL 入口随路由升级移除，只留下新 GAL 插件的入口。
|
|
60
|
-
4. 打开独立 GAL 检查进度。它保留原 localStorage 存档键；更换 profile 或没有读到旧进度时，先选择对应剧目，再导入备份 JSON。
|
|
26
|
+
**生成路由建议在本机完成，不启动 CLI，也不调用付费模型。实际执行可能产生费用。**
|
|
61
27
|
|
|
62
|
-
|
|
28
|
+
|
|
63
29
|
|
|
64
|
-
|
|
30
|
+
## 安装到 Harness Desktop
|
|
65
31
|
|
|
66
|
-
|
|
32
|
+
打开 **插件 → 添加插件**，填写：
|
|
67
33
|
|
|
68
34
|
```text
|
|
69
|
-
|
|
35
|
+
@ljwei-stak/dsh-model-router@0.15.0
|
|
70
36
|
```
|
|
71
37
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
```powershell
|
|
75
|
-
Get-FileHash -Algorithm SHA256 -LiteralPath 'D:\Plugins\ljwei-stak-dsh-model-router-0.14.0.tgz'
|
|
76
|
-
```
|
|
38
|
+
镜像缺少该精确版本时使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。安装并启用后，完全退出 Harness（包括托盘进程）再启动。插件详情应显示 **0.15.0**，侧栏出现**模型路由**。仅运行全局 `npm install -g` 不会把插件注册到桌面版 profile。
|
|
77
39
|
|
|
78
|
-
|
|
40
|
+
也可在插件管理器填写本地 `.tgz` 文件的绝对路径，或解压后的内层 `package` 目录；其中应包含 `package.json` 与 `.dsh-plugin`。[历史发布页](https://github.com/Alice-Marx/dsh-model-router/releases)提供归档；已克隆源码的开发方式见下文。
|
|
79
41
|
|
|
80
|
-
###
|
|
42
|
+
### 从旧包名升级
|
|
81
43
|
|
|
82
|
-
|
|
83
|
-
| --- | --- | --- |
|
|
84
|
-
| **模型路由 0.14.0** | **0.2.0-rc.1 / rc.2** | 新增官方工具终端（系统终端与官方 CLI、登录）；官方工具跟随各厂商最新版并提示更新，保留签名校验。更新后请完全重启 Harness。推荐精确版本，也可用 `@latest`。 |
|
|
85
|
-
| [模型路由 0.13.3](https://github.com/Alice-Marx/dsh-model-router/releases/tag/v0.13.3) | 0.2.0-rc.1 / rc.2 | 修复 Windows 版 Harness Desktop 中官方 CLI 执行无输出（沙箱启动器环境；Codex 改用自带只读沙箱）。 |
|
|
86
|
-
| [模型路由 0.13.2](https://github.com/Alice-Marx/dsh-model-router/releases/tag/v0.13.2) | 0.2.0-rc.1 / rc.2 | Codex 支持非 Git 工作区；Windows Desktop 中经沙箱的 CLI 执行仍无输出。 |
|
|
87
|
-
| [模型路由 0.13.1](https://github.com/Alice-Marx/dsh-model-router/releases/tag/v0.13.1) | 0.2.0-rc.1 / rc.2 | 修复 `cannot get property "credentials" without inject`；Windows 上 Codex 拒绝非 Git 工作区。 |
|
|
88
|
-
| [模型路由 0.13.0](https://github.com/Alice-Marx/dsh-model-router/releases/tag/v0.13.0) | 0.2.0-rc.1 / rc.2 | 体检、成本控制、订阅优先、执行记录；在 Harness 中执行会失败（0.13.1 已修复）。 |
|
|
89
|
-
| **GAL 0.1.0** | **0.2.0-rc.1 / rc.2** | 独立 GAL 首版，两部核心剧目。推荐精确版本。 |
|
|
90
|
-
| [模型路由 0.12.0](https://github.com/Alice-Marx/dsh-model-router/releases/tag/v0.12.0) | 0.2.0-rc.1 / rc.2 | 首个独立路由版本（GAL 拆出）。 |
|
|
91
|
-
| [合并版 0.11.1](https://github.com/Alice-Marx/model-router-galgame/releases/tag/v0.11.1) | 0.2.0-rc.1 / rc.2 | 历史路由与 GAL 合并包；修正 0.11.0 发布说明。 |
|
|
92
|
-
| [合并版 0.11.0](https://github.com/Alice-Marx/model-router-galgame/releases/tag/v0.11.0) | 0.2.0-rc.1 / rc.2 | 历史播放器更新。 |
|
|
93
|
-
| 0.10.2 | 0.2.0-rc.1 / rc.2 | 未发布的本地兼容修复。 |
|
|
94
|
-
| [0.10.1](https://github.com/Alice-Marx/model-router-galgame/releases/tag/v0.10.1) | 0.2.0-rc.1 | 历史发布版；rc.2 会拒绝其 peer 范围。 |
|
|
95
|
-
| [0.9.0](https://github.com/Alice-Marx/model-router-galgame/releases/tag/v0.9.0) | 0.2.0-rc.1 | 历史官方桌面适配版。 |
|
|
96
|
-
| 0.8.0 | 0.1.7-rc.2 依赖 | 与当前 0.2.0-rc.1 / rc.2 不兼容。 |
|
|
97
|
-
| 0.4.32 | 旧 DSH settings 依赖范围 | 历史发布记录，不用于当前宿主。 |
|
|
44
|
+
`@ljwei-stak/model-router-galgame` 的最后版本为 0.13.0。保留 profile 与应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.15.0`。不要同时安装两个包：它们共用内部插件 id `model-router-galgame` 与工具名；id 保留使已有路由设置和执行历史能够延续。
|
|
98
45
|
|
|
99
|
-
|
|
46
|
+
从 0.11.x 合并版迁移时，先备份 profile 并导出希望保留的 GAL 进度。剧情、立绘、音乐、自由模式和存档属于独立 `@ljwei-stak/dsh-galgame` 插件。导出范围及同 profile 迁移的限制见 [MIGRATION.md](MIGRATION.md)。
|
|
100
47
|
|
|
101
|
-
##
|
|
48
|
+
## 工作台的四个页面
|
|
102
49
|
|
|
103
|
-
|
|
104
|
-
2. 打开**模型路由 → 逐模型价格与能力**。为准备比较的每条路线填写自己认可的质量评分（0–100）、输入/输出单价（USD / 百万 token）、擅长方向；有缓存价格时可另外填写。未知项可以留空，界面会说明估价缺失。
|
|
105
|
-
3. 输入任务，先查看单任务、团队计划，或在**指定模型**里直接选一条已配置路线。结果会给出复杂度、工作包目标与依赖、质量门槛、推荐路线、预计费用及 `official-cli` / `harness-llm` 渠道。规划本身**不会调用付费模型**。
|
|
106
|
-
4. 在**逐模型价格与能力**里可以为每条路线选择执行方式：`auto` / `official` 优先该厂商官方工具，缺失或失败时回退模型目录 API；`api` 始终走模型目录。不填写时按 `auto`。
|
|
107
|
-
5. 在**官方工具**卡片上检测、一键下载安装或修复执行入口。工具就绪只说明安装与可信入口通过核验；首次登录、模型权限和真实费用仍要在对应厂商账号中验证。
|
|
108
|
-
6. 在官方会话里使用 `model_router_execute` 按计划或指定模型执行并汇总结果。`model_router_consult` 仍是一次模型目录咨询；`model_router_tool_run` 跑一个已核验的官方 CLI；`model_router_team_execute` 按依赖顺序执行可编辑工作包。可编辑任务需要干净的测试 Git 仓库，并经过宿主的工具审批。 体检、重跑和评价另有 `model_router_health`、`model_router_rerun_step`、`model_router_rate`，见下文。
|
|
50
|
+
0.15.0 工作台顶部概览显示已登记模型、工具检测和今日已记录 API 费用。按用途切换页面：
|
|
109
51
|
|
|
110
|
-
|
|
52
|
+
| 页面 | 操作内容 |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| **任务与执行** | 写任务、选规划模式、生成建议、预览只读执行、查看逐步骤历史。 |
|
|
55
|
+
| **模型配置** | 刷新/搜索官方模型目录，编辑每条准确路线的能力与价格档案。 |
|
|
56
|
+
| **官方工具** | 完成首次体检，检测/安装工具，使用交互终端。 |
|
|
57
|
+
| **预算与安全** | 设置路由、预算、复核策略，查看订阅状态和执行范围。 |
|
|
111
58
|
|
|
112
|
-
|
|
59
|
+
页面切换保留已挂载面板，安装任务和终端会话状态持续保留。
|
|
113
60
|
|
|
114
|
-
|
|
61
|
+
|
|
115
62
|
|
|
116
|
-
|
|
63
|
+
*本地 UI 演示实拍，使用示例模型、价格与体检数据；未调用真实模型或连接 Harness。团队工作包可展开查看目标、依赖和验收项。*
|
|
117
64
|
|
|
118
|
-
|
|
65
|
+
1. 先在 Harness 官方**模型**页配置供应商、模型和凭据。在**模型配置**页刷新目录。目录有记录不代表凭据、网络和模型权限已经可用。
|
|
66
|
+
2. 为参与比较的路线填写可选档案。质量分为你提供的 **0–100** 估值；输入/输出单价单位是 **USD / 百万 token**。不知道价格就留空，不要把未知填成零。
|
|
67
|
+
3. 在**任务与执行**写清交付物、约束与验收标准。**单任务**推荐一条路线；**团队分工**为足够复杂的任务拆依赖工作包；**指定模型**直接选一个准确路线，跳过其他模型比较。选团队模式不会自动启动团队。
|
|
68
|
+
4. 设置本次估算目标；`0` 表示不限制本次规划。点**生成路由建议**，结果直接出现在任务规划后方。核对路线、复杂度、费用、执行渠道，以及每包依赖和验收清单。
|
|
69
|
+
5. 需要实际只读执行时，使用**在工作台执行**，填写存在的工作区绝对路径（留空沿用上次运行）。先点**预览执行计划**，审阅当前路线和所有确认项，再明确确认执行。宿主启动前会再次检查；状态变化时可能要求重新确认。
|
|
70
|
+
6. 在**执行记录与子任务**查看实际通道、回答、错误、费用与评价。需要 CLI 修改文件时，在 Harness 官方会话中调用下方可编辑工具。
|
|
119
71
|
|
|
120
|
-
|
|
121
|
-
2. **要比较费用，先向下配置档案**：在“逐模型价格与能力”里选择准备使用的准确路线，填写自报质量评分（0–100）和核对过的输入/输出价格（均为 USD / 百万 token），按**保存此模型**；每条待比较路线分别保存。擅长标签和厂商 CLI 模型名可选。没有价格就留空，不要把未知写成零。
|
|
122
|
-
3. **写“任务描述”**：可以粘贴长提案，但最好把要交付的步骤写成编号条目，并写清验收标准。“单任务”只给单项路线建议；“团队分工”会把可执行需求拆成有依赖的工作包，最多六个显式执行包。“指定模型”不比较其他路线，整项任务都交给下拉框里选中的那一条。
|
|
123
|
-
4. **设置预算并生成**：“本次估算预算（USD）”中的 `10` 只是本地估价目标，`0` 表示规划不设预算；两者都**不会限制真实账号扣费**。点**生成路由建议**后，继续向下滚过“逐模型价格与能力”，找到新增的**路由建议**卡片。按钮不会启动模型。
|
|
124
|
-
5. **读结果**：先核对推荐 `provider/model`、复杂度、估算总成本、执行渠道与警告；团队模式再逐包核对目标、难度、依赖、建议模型、估价和验收项。`官方 CLI` 说明本机相应入口可托管；`模型目录 API` 说明可通过 Harness 模型目录调用，但不等于这个包能由插件的 CLI 团队执行器运行。修改任务、预算或档案后重新生成。
|
|
125
|
-
6. **只读任务可以直接在工作台执行**：路由建议下方的“**在工作台执行**”卡片沿用上面的任务描述和规划模式（单任务 / 团队分工 / 指定模型），可另选路由方案，并填写工作区绝对路径（留空则沿用上次运行的工作区，路径必须存在）。点**预览执行计划**后，宿主按 `model_router_execute` 的同一套逻辑生成计划（含超预算自动降级），显示预估费用、预算检查，以及**所有需要确认的原因**（超出预算、不经沙箱启动 CLI）合并在一处。按**全部确认并执行**之前不会调用任何模型；宿主执行前会再核对一次原因，期间有变化（例如预算或登录状态）会拒绝并要求重新确认。结果写入下方执行记录。
|
|
126
|
-
7. **可编辑任务另开官方会话**：在左侧点**新会话**并选好工作区。要按工作台结果执行，请求 `model_router_execute`；若只要某一个模型，同时给出该路线的 `provider` 和 `model`。`model_router_consult` 只做模型目录咨询。`model_router_tool_run` 与 `model_router_team_execute` 仍负责已核验 CLI 的可编辑任务。团队执行会按照**当前已就绪且支持所选模式的官方 CLI**重新规划，可能与页面上刚才的静态建议不同；它不会直接读取那张结果卡作为执行清单。
|
|
72
|
+
更改任务、模式、模型档案、目录或相关设置后，需要重新生成建议。更改执行输入会丢弃正在请求或已经返回的旧预览，必须重新预览当前请求才能确认执行。执行预览采用宿主当前状态，因此可能与早先的本地建议不同。
|
|
127
73
|
|
|
128
|
-
|
|
74
|
+
示例任务：
|
|
129
75
|
|
|
130
76
|
```text
|
|
131
|
-
|
|
132
|
-
1.
|
|
133
|
-
2.
|
|
134
|
-
3.
|
|
135
|
-
4.
|
|
136
|
-
验收：每项写明输入、输出文件名与检查方法。
|
|
77
|
+
审阅当前项目并制定改进计划。
|
|
78
|
+
1. 梳理入口文件与主要 UI 流程。
|
|
79
|
+
2. 检查宽屏和窄屏排版，列出布局问题。
|
|
80
|
+
3. 核查执行、订阅和费用边界。
|
|
81
|
+
4. 整合为带优先级、改动范围和验证方法的清单。
|
|
137
82
|
```
|
|
138
83
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
当前插件能规划短片任务，并通过已适配的官方**模型编程 CLI**处理它们有能力完成的文本或代码工作。**“生成路由建议”不会操作 Blender、ComfyUI、剪辑软件或导出视频。** 要交付成片，还需为相应创作软件提供可调用的工作流、素材、权限和人工验收。详见[工作台使用指南](docs/WORKBENCH_USER_GUIDE.zh.md)的单工具、团队和常见问题章节。
|
|
142
|
-
|
|
143
|
-
## 体检、成本与质量回路
|
|
144
|
-
|
|
145
|
-
工作台顶部按下面顺序展示这些能力。会话内对应的工具在括号里。
|
|
146
|
-
|
|
147
|
-
1. **开箱体检**（`model_router_health`）。第一次打开工作台时，会对注册表里的每个官方工具检查三件事：是否安装、已安装哪个版本（旁边显示厂商最新版，有新版本时提示“有新版本”）、是否已登录。插件不再固定版本：最新版本取自 npm registry（`<包名>/latest`）或 ZCode 官方下载页，缓存约 12 小时；离线或查询失败时只显示“最新版本未知”，不影响使用。新版本未经插件测试，解析器会尽量兼容输出格式变化，遇到问题请反馈。登录检查只跑很便宜的状态命令（超时很短），或只检查凭据文件是否存在（从不读取内容）：
|
|
148
|
-
|
|
149
|
-
| 工具 | 检测方式 | 登录方法 |
|
|
150
|
-
| --- | --- | --- |
|
|
151
|
-
| Claude Code | `claude auth status --json` | `claude auth login` |
|
|
152
|
-
| Codex | `codex login status` | `codex login` |
|
|
153
|
-
| Gemini CLI | `GEMINI_API_KEY`/`GOOGLE_API_KEY` 或 `~/.gemini/oauth_creds.json` | `gemini` |
|
|
154
|
-
| Kimi Code | `KIMI_API_KEY`/`MOONSHOT_API_KEY`，或 `~/.kimi-code/credentials/kimi-code.json`（`$KIMI_CODE_HOME`） | `kimi login` |
|
|
155
|
-
| MiMo Code | `MIMO_API_KEY`，或 `~/.local/share/mimocode/auth.json`（`$XDG_DATA_HOME`；该文件也可能只存了供应商 API Key，计费方式记为未知） | `mimo auth login` |
|
|
156
|
-
| Grok Build | `XAI_API_KEY`，或 `~/.grok/auth.json`（`$GROK_HOME`）。Windows 上 npm 全局目录不在 C 盘时，插件以 `GROK_HOME=<npm 全局目录>\.model-router-grok` 启动 Grok，体检会显示这个实际路径 | `grok login`（无浏览器时加 `--device-auth`）；使用该目录时运行 `$env:GROK_HOME='<路径>'; grok login` |
|
|
157
|
-
| MiniMax Code | `MINIMAX_API_KEY`，或不含密钥的状态文件 `~/.minimax/auth/prod/<cn\|global>/mcode-public/auth-state.json`（`$MINIMAX_DATA_DIR`）中的 `status`：`authenticated` → 已登录；`anonymous` → 未知（用 `mcode set-minimax-key` 保存的 API Key 仍可用） | `mcode login` |
|
|
158
|
-
| ZCode | 桌面应用，没有状态命令 → 未知。任何版本只要 `ZCode.exe` 带有北京智谱华章科技股份有限公司的有效 Authenticode 签名即可启用（其 CLI 脚本按签名构建首次使用时记录，详见下文） | 欢迎页选“连接 BigModel / Z.ai 继续使用”；GLM Coding Plan 在“模型设置 → BigModel”右上角选“编程套餐” |
|
|
159
|
-
|
|
160
|
-
文件路径取自各厂商官方发布包。找不到文件时显示“未知”而不是“未登录”，因为这些 CLI 也可以通过自定义供应商或（MiMo）免费匿名通道使用。体检不会发起登录。
|
|
161
|
-
- 点**一键安装最新版** / **更新到最新版 X**，从官方 registry 安装 `<包名>@latest`（ZCode：官方下载页上最新的签名安装器）。已安装版本高于官方最新正式版时不会降级。
|
|
162
|
-
- 未登录的工具点**去登录**，查看并复制登录命令。
|
|
163
|
-
- 体检结果缓存 10 分钟。路由会**立刻跳过未登录的 CLI**，直接走模型目录 API；以前 Codex 要等约 14 秒才失败回退。配置了对应 API Key 时不跳过。如果执行中 CLI 报出登录错误，也会把该工具标为未登录；但因为你本来在用它的订阅，之后同一路线的步骤会**暂停询问**（“订阅登录已失效……未自动改用 API Key”），不会悄悄改用 API Key，重启后依然如此（记录在 `state.json` 的 `authFailures`），直到该 CLI 再次以订阅成功运行。模型档案明确写了 `billing: "subscription-first"` 或 `"subscription-only"` 而 CLI 未登录时同样暂停询问。没有这两种迹象的未登录 CLI，以及未安装的 CLI，仍直接走 API。点“重新体检”可以刷新。
|
|
164
|
-
2. **路由决策看得见**。路由建议会显示推荐模型、路由方案、难度分和估算成本，以及执行渠道（官方 CLI 还是模型目录 API；未登录时标“CLI 未登录”）。执行记录里每一步都写明实际渠道。如果回退到 API，会显示脱敏后的真实错误：Claude JSON 的 `result`、Codex 的 `turn.failed.error.message`，或 stderr 片段。设置允许时可以**改派并重跑**到另一条已配置路线（`allowManualReassign`，默认开启）。
|
|
165
|
-
3. **成本控制**。“成本控制”卡片显示今日和本月已花费金额及进度条，并可设置**每日/每月预算**（USD，`0` 表示不限）。
|
|
166
|
-
- 执行前，用本次预估金额检查预算。
|
|
167
|
-
- `model_router_tool_run` 指定了 `provider`/`model` 路线时同样先预估、检查预算（未指定路线时 CLI 默认模型没有单价，只在预算已用完时暂停）；超预算返回 `paused-budget`，确认后以 `confirmOverBudget: true` 重新调用。
|
|
168
|
-
- 执行后，记录实际费用：优先用 CLI 回报的费用（Claude 的 `total_cost_usd`；Grok 在服务端回报完整费用时的 `total_cost_usd`；MiMo 每步的 `cost`），否则用 token 用量乘以“模型价格与能力配置”里的单价。token 用量来自 Claude、Codex、Gemini、Grok（`end` 事件）、MiMo（`step-finish`）和 MiniMax（`exec.result.usage`）；Kimi 与 ZCode 的无界面输出不含用量。没有单价时只记录 token 数。
|
|
169
|
-
- 超出预算时的处理由 `overBudgetAction` 决定：`downgrade`（默认）先改用“省钱优先”重新规划，仍超出就暂停；`pause` 直接暂停，询问你是否继续。会话里继续需要传 `confirmOverBudget=true`，宿主会再弹出一次审批。同一次执行需要多项确认时（修改文件、改用 API Key、超出预算、不经沙箱启动 CLI），会合并到**同一个**审批提示里逐条列出。
|
|
170
|
-
- **只有走 API 计费的花费计入预算**：模型目录 API 调用，或官方 CLI 使用 API Key（插件注入的、环境变量里的，或体检发现 CLI 本身用 API Key 登录）的调用。
|
|
171
|
-
- 官方 CLI 用**订阅账号登录**、没有 API Key 时（例如 Claude Pro/Max、ChatGPT 登录的 Codex），CLI 回报的金额或按单价折算的金额只显示为“**订阅参考费用（按 API 价折算）**”，**不计入**每日/每月预算。成本卡片和执行记录会同时显示“计入预算”的金额和订阅参考费用。工具卡片会标出各 CLI 是“订阅账号登录”还是“API Key 计费”。
|
|
172
|
-
- 判断不了登录方式时（例如 Kimi 等没有状态命令的 CLI、团队执行器启动的 CLI），只要没有检测到对应的 API Key 环境变量，就按订阅登录处理。
|
|
173
|
-
- 路由执行对所有厂商按[订阅优先规则](#订阅优先额度用尽才切换-api-key)：先用订阅，只有额度用尽或限流才把该步骤切换到 API Key，切换后的花费计入预算。
|
|
174
|
-
4. **预设方案**（`routingPreset`）。可选**省钱优先 / 均衡 / 效果优先**，默认是均衡。方案会调整质量、成本和速度三者的权重，并把替代模型必须达到的质量门槛下调或上调 0.04。均衡和以前的算法完全相同。
|
|
175
|
-
5. **子任务可视化**（`model_router_rerun_step`）。团队分工的工作包按依赖关系分列，显示成依赖图（DAG）。`model_router_execute`、`model_router_team_execute` 和 `model_router_tool_run` 的每次执行都会写入执行记录，并标明类型（路由执行 / 团队执行 / 单工具调用）。每一步都标有状态：完成、已回退、失败或依赖未完成；团队执行在某一步失败后停止，后面的步骤显示为“依赖未完成”。点**重跑此步**只重跑失败的那一步，以及依赖它的未完成步骤，已完成的步骤保留原结果，并作为重跑的依赖上下文。
|
|
176
|
-
- 路由执行：都可以单步重跑，也可以改派。
|
|
177
|
-
- 团队执行：**只读**团队运行可以单步重跑（同样经过签名执行器和 Harness 沙箱）。**可编辑**（`workspace-write`）团队运行如果是**在某一步失败后停止**的，可以点“**在新工作区续跑**”：从当前仓库新建一个独立工作树，先套用原工作树里之前步骤的改动，再运行失败步骤及其未完成的下游，成功后照常整合合并补丁。需要审批、工作区干净且仍停在原运行的基线提交（否则拒绝），并且记录来自本版本（记录了基线提交）。已经整合或待人工整合的运行不能单步重跑；可编辑运行中已成功的步骤也不能改派（改动会被套用两次）。
|
|
178
|
-
- 单工具调用：失败的 `model_router_tool_run` 可以点“**重新执行此调用**”（packageId 为 `direct`），沿用原工具、任务、模式和模型，记录为通过 `rerunOf` 关联的新运行；可编辑调用会从当前仓库的新工作树重新开始，同样需要审批。
|
|
179
|
-
6. **安全边界**。“安全边界”卡片和插件设置页会逐条列出每条路线可读、可写的范围，以及是否经过 Harness 沙箱：
|
|
180
|
-
- 只读执行不写文件；
|
|
181
|
-
- 修改文件的执行在独立 Git 工作树里进行，需要宿主审批；
|
|
182
|
-
- 在 Linux/macOS 上直接启动无界面 CLI 时没有 Harness 进程沙箱，`confirmUnsandboxedCli`（默认开启）会在启动前先询问你。
|
|
183
|
-
7. **质量回路**（`model_router_rate`）。`reviewMode` 可以设为 `off`、`sample` 或 `always`；`sample` 按 `reviewSampleRate` 的比例抽检。开启后，会让更强的已配置模型复核便宜模型的输出，并把结论写进执行记录。你可以对每个结果点 👍/👎。评价会以收缩平均的方式，给对应 `provider/model` 的质量分加一个微调，范围最多 ±0.04，作用于以后的路由。
|
|
184
|
-
|
|
185
|
-
**本地数据（默认开启）**：执行记录**默认自动保存在本机**，没有开关。保存位置是 `~/.dsh/model-router/state.json`（若设置了 `DSH_HOME`，则在 `$DSH_HOME/model-router/state.json`）。内容包括：
|
|
186
|
-
- 体检结果、订阅额度状态（哪些订阅额度已用尽、预计何时恢复），以及执行中订阅登录失效的 CLI；
|
|
187
|
-
- 最近 200 次执行（路由执行、团队执行、单工具调用）的**完整任务文本**（最多 2 万字）和**每步答案摘要**（每步最多 4000 字）；
|
|
188
|
-
- 工作区路径、路由决策、费用和评价。
|
|
189
|
-
|
|
190
|
-
这个文件只在本机，不会上传，也不包含 API Key。如果任务里有敏感内容，请留意这个文件；需要清除时直接删除它，或删掉其中的 `runs` 数组。
|
|
191
|
-
|
|
192
|
-
多个宿主进程可以共用同一个 DSH 目录：每次写入都会先获取 `state.json.lock`，重新读取文件、合并本次改动，再原子替换，并发执行不会丢记录。其他进程写入的订阅额度标记和运行时登录失效（包括清除）会在下一次调用时生效，无需重启（文件的 mtime/大小/inode 变化时才重新读取）。文件无法解析时会保留为 `state.json.corrupt-<时间>`，工作台和 `model_router_health`（`notices`）在 7 天内显示提醒；需要时可从备份中恢复历史。
|
|
193
|
-
|
|
194
|
-
**当前限制**：
|
|
195
|
-
- Kimi 与 ZCode 的无界面输出不含 token 用量，相应步骤显示“订阅登录，未回报可折算的用量”或“费用未知”。
|
|
196
|
-
- ZCode 的登录状态仍为“未知”（没有状态命令）；MiniMax 只有 API Key 或没有状态文件时也显示“未知”。Kimi/MiMo/Grok/MiniMax 的检测只说明凭据或状态文件存在，不代表令牌仍然有效。
|
|
197
|
-
- 工作台只能发起**只读**执行；可编辑任务仍需在会话中用 `model_router_tool_run` 或 `model_router_team_execute` 开始。
|
|
198
|
-
- 这些界面通过了构建检查、单元测试，以及用真实客户端包 + 模拟宿主桥接的无头浏览器检查，还没有在真实 Harness 桌面里验证。
|
|
199
|
-
|
|
200
|
-
## 订阅优先：额度用尽才切换 API Key
|
|
201
|
-
|
|
202
|
-
除按量付费的 API Key 外，很多厂商都有编程订阅：Claude Pro/Max、ChatGPT 套餐（Codex）、Gemini、Kimi Code、MiniMax Token Plan、GLM Coding Plan（智谱 / Z.ai）等。路由的规则是：
|
|
203
|
-
|
|
204
|
-
> **有订阅就先用订阅；只有订阅额度用尽或触发限流时，同一步骤才改用 API Key。**
|
|
205
|
-
|
|
206
|
-
**两种订阅方式：**
|
|
207
|
-
|
|
208
|
-
| 方式 | 怎么识别 | 怎么运行 |
|
|
209
|
-
| --- | --- | --- |
|
|
210
|
-
| **官方 CLI 账号登录**（`cli-login`） | 路线的供应商对应一个官方 CLI（Claude Code、Codex、Gemini CLI、Kimi Code、MiniMax Code、GLM 的 ZCode 等），体检发现已登录订阅账号。 | 启动 CLI 时**去掉所有 API Key 环境变量**（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`/`CODEX_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`KIMI_API_KEY`/`MOONSHOT_API_KEY`、`MINIMAX_API_KEY`、`ZAI_API_KEY` 等），也不注入 Key，只能按订阅计费。 |
|
|
211
|
-
| **编程套餐 Key 路线**（`plan-key`） | Harness 里一个以套餐地址和套餐 Key 配置的供应商，在模型档案中设 `subscription: "plan-key"`。供应商 ID 形如 `glm-coding-plan`、`kimi-code`、`minimax-token-plan` 时会自动识别；档案设置优先。 | 先通过模型目录调用套餐路线；`apiRoute` 指定套餐额度用尽时使用的按量付费路线。 |
|
|
212
|
-
|
|
213
|
-
套餐路线在 Harness 的**模型**页按普通 Anthropic 兼容或 OpenAI 兼容服务添加，填写厂商文档中的套餐地址和套餐 Key（插件不读取、不保存 Key）：
|
|
214
|
-
|
|
215
|
-
| 套餐 | Anthropic 兼容地址（Claude Code 方式） | OpenAI 兼容地址 |
|
|
216
|
-
| --- | --- | --- |
|
|
217
|
-
| GLM Coding Plan | `https://open.bigmodel.cn/api/anthropic`（国际版 `https://api.z.ai/api/anthropic`） | `https://open.bigmodel.cn/api/coding/paas/v4`（国际版 `https://api.z.ai/api/coding/paas/v4`）；不要用通用的 `/api/paas/v4`，那个扣账户余额 |
|
|
218
|
-
| Kimi Code | `https://api.kimi.com/coding/` | `https://api.kimi.com/coding/v1`，模型 `kimi-for-coding` |
|
|
219
|
-
| MiniMax Token Plan | `https://api.minimaxi.com/anthropic`（国际版 `https://api.minimax.io/anthropic`） | — |
|
|
220
|
-
|
|
221
|
-
请先核对各套餐条款：部分厂商（例如 GLM Coding Plan 常见问题）说明套餐额度只在其支持的编程工具中使用，其他 API 用途需开通标准 API 服务。地址和模型 ID 会变化，请以厂商文档为准。
|
|
222
|
-
|
|
223
|
-
**档案字段**（“逐模型价格与能力”或 `modelProfilesJson`）：
|
|
84
|
+
插件负责规划及委派文字/代码任务；它本身不渲染视频、生成图片或控制创作软件。完整操作见[工作台指南](docs/WORKBENCH_USER_GUIDE.zh.md)。
|
|
224
85
|
|
|
225
|
-
|
|
226
|
-
[
|
|
227
|
-
{ "provider": "glm-coding-plan", "model": "glm-4.6", "subscription": "plan-key",
|
|
228
|
-
"apiRoute": { "provider": "zhipu", "model": "glm-4.6" } },
|
|
229
|
-
{ "provider": "anthropic", "model": "claude-sonnet-4-5", "billing": "subscription-first" },
|
|
230
|
-
{ "provider": "deepseek", "model": "deepseek-chat", "billing": "api-only" }
|
|
231
|
-
]
|
|
232
|
-
```
|
|
86
|
+
## 官方会话工具
|
|
233
87
|
|
|
234
|
-
|
|
235
|
-
- `subscription`：`plan-key`、`cli-login` 或 `none`（始终按 API 计费）；省略表示自动判断。
|
|
236
|
-
- `apiRoute`：只用于 `plan-key` 路线，填模型目录中的准确路线。路由直接选中这条 API 路线时，套餐还有额度也会先用套餐。
|
|
88
|
+
在官方 Harness 会话里明确请求使用这些工具；访问本地文件前先选择正确工作区。
|
|
237
89
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
|
241
|
-
|
|
|
242
|
-
|
|
|
243
|
-
|
|
|
244
|
-
|
|
|
245
|
-
|
|
|
246
|
-
|
|
|
247
|
-
|
|
|
248
|
-
|
|
|
249
|
-
|
|
250
|
-
识别到后，该订阅**标记为额度已用尽，直到厂商给出的恢复时间**（`resets_at`、`resets_in_seconds`、`retry in Xs`、GLM 的重置时间、Claude 的“resets 3:45pm”）；没给时间时按 `subscriptionCooldownMinutes`（默认 60 分钟）暂停，无时间的限流只暂停 1 分钟。**同一步骤立即改用 API Key 重试**，后续步骤在恢复前直接跳过这份订阅。执行记录会写明计费渠道（`billing: subscription | api`）和原因，例如 **“订阅额度已用尽（预计 10-2 18:30 恢复），已切换 API Key。”** 状态保存在 `state.json` 的 `quota` 中，重启后仍有效。
|
|
90
|
+
| 工具 | 作用 |
|
|
91
|
+
| --- | --- |
|
|
92
|
+
| `model_router_routes` | 列出官方已配置路线；不验证账号和网络。 |
|
|
93
|
+
| `model_router_plan` | 本地生成 `single` 或 `team` 计划。 |
|
|
94
|
+
| `model_router_consult` | 通过模型 API 向一个已配置模型征求意见，可能计费。 |
|
|
95
|
+
| `model_router_execute` | 只读执行路由计划，或执行明确指定的 `provider`/`model`，并留存结果。 |
|
|
96
|
+
| `model_router_tools` / `model_router_health` | 检查安装/入口，或体检版本、登录与计费状态。 |
|
|
97
|
+
| `model_router_tool_install` | 从固定官方来源安装一个注册表工具。 |
|
|
98
|
+
| `model_router_tool_run` | 运行单个支持的 CLI，选择只读或经审批的可编辑模式。 |
|
|
99
|
+
| `model_router_team_execute` | 按当前可执行 CLI 重新规划，按依赖顺序执行工作包。 |
|
|
100
|
+
| `model_router_rerun_step` | 重跑失败步骤及未完成下游，续跑符合条件的可编辑团队，或再次执行失败的单工具调用。 |
|
|
101
|
+
| `model_router_rate` | 为某个结果记录 `up`、`down`、`clear`。 |
|
|
251
102
|
|
|
252
|
-
|
|
103
|
+
会话命令为 `/router <任务>`、`/tools`、`/tools install|cancel <工具 ID>`。
|
|
253
104
|
|
|
254
|
-
|
|
105
|
+
只生成计划的参数示例：
|
|
255
106
|
|
|
256
107
|
```json
|
|
257
|
-
{
|
|
108
|
+
{"task":"评审项目架构并给出验收清单","mode":"team","budgetUsd":10}
|
|
258
109
|
```
|
|
259
110
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
**体检。** “订阅与 API Key”卡片（以及 `model_router_health` 的 `billing`）按供应商列出：计费方式、订阅来源、订阅状态（已登录订阅账号 / 编程套餐 Key 路线 / 仅 API Key 登录 / 未登录 / **额度已用尽，预计 X 恢复**），以及是否有可回退的 API Key 路线。登录检测时会去掉 API Key 环境变量，所以同时设了 API Key 也能识别 Claude、Codex 的账号登录。
|
|
263
|
-
|
|
264
|
-
**预算。** 所有厂商的订阅运行（CLI 账号登录或套餐 Key 路线）都只显示订阅参考费用、不计入预算；切换到 API Key 的运行计入每日/每月预算。
|
|
265
|
-
|
|
266
|
-
**限制。** `model_router_team_execute` 和 `model_router_tool_run` 只通过官方 CLI 修改文件，额度用尽时会记录（该步骤写明原因，之后的路由执行会跳过这份订阅），但**不会自动改用 API Key 重试**。Kimi Code、MiniMax Code 在 Linux/macOS 上没有可移植的只读适配器，在这些平台上请通过套餐 Key 路线使用它们的订阅。
|
|
267
|
-
|
|
268
|
-
## 路由算法：从输入到分配
|
|
111
|
+
单个 CLI 只读检查示例：
|
|
269
112
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
### 1. 判断复杂度并拆任务
|
|
273
|
-
|
|
274
|
-
令 `clip(x)=min(1,max(0,x))`。对任务文本计算：
|
|
275
|
-
|
|
276
|
-
```text
|
|
277
|
-
C = clip(
|
|
278
|
-
0.10
|
|
279
|
-
+ 0.30·clip(字符数 / 2200)
|
|
280
|
-
+ 0.18·clip(列表项数 / 8)
|
|
281
|
-
+ 0.28·clip(领域词命中数 / 5)
|
|
282
|
-
+ [含代码/工程词 ? 0.22 : 0]
|
|
283
|
-
+ [含高推理词 ? 0.20 : 0]
|
|
284
|
-
+ [含图像词 ? 0.12 : 0]
|
|
285
|
-
)
|
|
113
|
+
```json
|
|
114
|
+
{"tool":"codex","task":"检查仓库 UI 排版并列出问题；不要修改文件","mode":"read-only"}
|
|
286
115
|
```
|
|
287
116
|
|
|
288
|
-
|
|
117
|
+
指定目录路线时，`provider` 与 `model` 必须成对填写。厂商 CLI 模型名可能与 Harness ID 不同；只有在对应 CLI 验证后才设置 `cliModel` 或团队 `cliModelsJson`。ZCode 使用自身默认模型，不能逐次切换。多数 CLI 不回报可核验的实际模型 ID，需对照厂商运行记录。
|
|
289
118
|
|
|
290
|
-
|
|
119
|
+
CLI 团队是插件自有的顺序依赖执行器。Harness 内建 Agent Teams 的成员模型与生命周期仍由宿主管理。
|
|
291
120
|
|
|
292
|
-
|
|
121
|
+
## 官方工具与托管模式
|
|
293
122
|
|
|
294
|
-
|
|
123
|
+
| 注册表 ID | 工具 | 单工具/团队托管模式 |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| `kimi-code` | Kimi Code | 经审批的 `workspace-write` |
|
|
126
|
+
| `claude-code` | Claude Code | `read-only`、经审批的 `workspace-write` |
|
|
127
|
+
| `codex` | Codex CLI | `read-only`、经审批的 `workspace-write` |
|
|
128
|
+
| `minimax-code` | MiniMax Code | 经审批的 `workspace-write` |
|
|
129
|
+
| `mimo-code` | MiMo Code | `read-only`、经审批的 `workspace-write` |
|
|
130
|
+
| `grok-build` | Grok Build | `read-only`、经审批的 `workspace-write` |
|
|
131
|
+
| `gemini` | Gemini CLI | 路由执行的无界面适配器；不属于单工具/团队托管执行器 |
|
|
132
|
+
| `zcode` | ZCode | Windows；经审批的 `workspace-write` |
|
|
295
133
|
|
|
296
|
-
|
|
134
|
+
安装使用固定官方 npm 包的 `@latest`，或 ZCode 官方、经过发布者签名验证的 Windows 安装器。已安装版本比查询到的最新版更高时不会降级。最新版查询缓存约 12 小时；离线/查询失败时保持未知。厂商新版本没有自动获得本项目验证。ZCode 打开安装窗口后，仍需手动选目录并完成安装。
|
|
297
135
|
|
|
298
|
-
|
|
299
|
-
U = wq·质量 + wc·成本得分 + wl·(1 - 延迟估值)
|
|
300
|
-
+ ws·专长匹配 + wr·推理匹配 - wx·风险估值
|
|
301
|
-
- 关键程度·max(0, 质量下限 - 质量)
|
|
302
|
-
```
|
|
136
|
+
**已安装、可信入口就绪、账号已登录、模型有权限是不同状态。** 登录未知不代表已退出。在 Windows，托管入口按发布者签名或官方 npm tarball 校验；ZCode 另对签名构建中的脚本记录首次信任摘要。平台细则见[注册表](.dsh-plugin/shared/official-tool-registry.mjs)和[执行器](.dsh-plugin/shared/official-tool-executor.mjs)。
|
|
303
137
|
|
|
304
|
-
|
|
305
|
-
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
306
|
-
| 简单 | 0.28 | **0.45** | 0.14 | 0.04 | 0.07 | 0.02 |
|
|
307
|
-
| 均衡 | 0.40 | 0.26 | 0.10 | 0.09 | 0.10 | 0.05 |
|
|
308
|
-
| 复杂 | **0.48** | 0.14 | 0.06 | 0.14 | 0.11 | 0.07 |
|
|
309
|
-
| 整合 | **0.58** | 0.08 | 0.04 | 0.08 | 0.16 | 0.06 |
|
|
138
|
+
`model_router_execute` 的固定无界面适配器为 Claude、Codex 和 Gemini；其他供应商经模型目录 API 或适用的订阅路线执行。CLI 缺失/不可用时可回退 API；真正尝试后的订阅失败按下方策略处理。
|
|
310
139
|
|
|
311
|
-
|
|
140
|
+
可编辑执行要求干净 Git 仓库、Harness 审批与进程沙箱。修改先在独立工作树进行，执行成功且原仓库仍干净并匹配时才整合源码补丁；执行或整合失败会明确报告。Git 忽略的输出另行检查。只读参数不一定把可读文件限制在工作区，尤其需在**安全边界**核对 Codex 的较大可读范围。
|
|
312
141
|
|
|
313
|
-
|
|
142
|
+
### 官方工具终端
|
|
314
143
|
|
|
315
|
-
|
|
144
|
+
在**官方工具 → 官方工具终端**选择系统终端或已安装 CLI、交互/登录方式和存在的工作区绝对路径，核对启动确认后运行。ZCode 是桌面应用，不属于终端目标。
|
|
316
145
|
|
|
317
|
-
|
|
146
|
+
终端**不经过 Harness 沙箱**，继承 Host 用户的登录环境、代理及 API Key 环境变量。输入的命令可以按该用户权限读取/修改文件。终端与路由执行的审批和计费流程分别处理。
|
|
318
147
|
|
|
319
|
-
|
|
148
|
+
可选依赖 `@lydell/node-pty` 提供真实伪终端；加载失败时显示管道模式，全屏界面、尺寸同步与方向键可能不可用。最多同时运行四个会话；无人读取约两分钟会结束，单会话最长六小时。完成后明确结束会话；关闭工作台或卸载插件也会终止进程。
|
|
320
149
|
|
|
321
|
-
|
|
322
|
-
预计费用 USD =
|
|
323
|
-
((普通输入token × 输入单价)
|
|
324
|
-
+ (缓存读取token × 缓存读取单价)
|
|
325
|
-
+ (缓存写入token × 缓存写入单价)
|
|
326
|
-
+ (预计输出token × 输出单价)) / 1,000,000
|
|
327
|
-
```
|
|
150
|
+
插件不持久化终端输入/输出，仅保存会话元数据。选中文字时 Ctrl+C 复制，否则中断；Ctrl+Shift+V 粘贴。
|
|
328
151
|
|
|
329
|
-
|
|
152
|
+
## 成本、订阅与质量
|
|
330
153
|
|
|
331
|
-
|
|
154
|
+
- **预算**：本次规划目标与每日/月度执行检查分别生效。超预算可尝试省钱方案或暂停确认；缺少价格保持费用未知。它们是本机估算与核算机制，不是厂商账单的硬上限。
|
|
155
|
+
- **订阅优先**：默认先使用检测到的 CLI 订阅账号或配置的编程套餐路线。尝试 CLI 订阅时去掉 API Key 环境变量。`billing` 可设 `subscription-first`、`api-only`、`subscription-only`；`subscription` 可设 `cli-login`、`plan-key`、`none`。
|
|
156
|
+
- **回退**：识别到额度用尽/限流后，将订阅标记为冷却，并可按策略及可用性用已配置 API 路线重试该路由步骤。其他已尝试的订阅失败默认暂停（`onSubscriptionFailure: "ask"`），在历史中选择 API 重试、重试订阅或取消。单工具/团队托管执行不会自动转 API 重试。
|
|
157
|
+
- **核算**：API 费用计入预算；订阅单独展示按 API 单价折算的参考费用。实际用量可来自 CLI 自报金额，或 token 用量乘你提供的单价；真实消费以厂商账单为准。0.15.0 保留被裁剪历史和被重试结果替换的费用累计，避免重跑或清理详细历史抹掉此前消费；旧版本已经丢弃的费用无法反推恢复。
|
|
158
|
+
- **质量**：强模型复核可设 `off`、`sample`、`always`，会增加真实调用。用户评价对准确路线的后续质量分作小幅调整，归一化分数最多 ±0.04。
|
|
332
159
|
|
|
333
|
-
|
|
160
|
+
编程套餐 Key 与端点留在 Harness 官方供应商设置里。`plan-key` 档案可指定一个准确、已登记的 `apiRoute` 作为回退；模型档案不接收凭据或任意命令。套餐资格及使用条款须向厂商核对。
|
|
334
161
|
|
|
335
|
-
|
|
336
|
-
| --- | ---: | ---: | --- |
|
|
337
|
-
| `cheap-provider/Flash Custom` | 79/100 | 0.10 / 0.20 | 摘要与提取 |
|
|
338
|
-
| `strong-provider/Reasoning Custom` | 97/100 | 5 / 25 | 推理与代码 |
|
|
162
|
+
## 路由算法：从输入到分配
|
|
339
163
|
|
|
340
|
-
|
|
164
|
+
这是可重复的本地启发式规划，不是对任务成功率的保证：
|
|
341
165
|
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
- 最后验证架构安全性
|
|
347
|
-
```
|
|
166
|
+
1. 根据文本估计任务类型/复杂度，必要时拆成分析、执行、验证、整合工作包。
|
|
167
|
+
2. 仅比较官方已配置路线，覆盖准确路线的用户档案，并尽可能筛选模态和质量约束。
|
|
168
|
+
3. 按路由方案比较质量、预估价格、延迟、专长、推理适配与风险。
|
|
169
|
+
4. 剪除被其他路线支配的候选，在有限范围搜索依赖分配；质量约束放宽、证据不足和无法分配的包会显示提示。
|
|
348
170
|
|
|
349
|
-
|
|
171
|
+
预估费用为 token 用量乘 USD/百万 token 单价，支持可选缓存价。质量资料可能来自用户、提供的基准数据或目录启发式，目录提示不等于实测成功率。图像路线仍需真实输入能力；当前路由执行以文本为主，不是通用多模态素材制作流水线。
|
|
350
172
|
|
|
351
|
-
|
|
173
|
+
实现见 [router.mjs](.dsh-plugin/shared/router.mjs)、[harness-plan.mjs](.dsh-plugin/shared/harness-plan.mjs) 和 [routing-presets.mjs](.dsh-plugin/shared/routing-presets.mjs)。
|
|
352
174
|
|
|
353
|
-
##
|
|
175
|
+
## 数据保存与隐私
|
|
354
176
|
|
|
355
|
-
|
|
177
|
+
模型档案和偏好保存在 Harness 插件设置中。运行状态位于 `<DSH_HOME>/model-router/state.json`，默认 `~/.dsh/model-router/state.json`；包括体检/引导、订阅冷却、评价、最多 200 条近期运行和 50 条终端元数据。
|
|
356
178
|
|
|
357
|
-
|
|
358
|
-
| --- | --- |
|
|
359
|
-
| Kimi Code | 官方 npm 包最新版；无界面模式只允许经审批的独立 Git 工作区可编辑任务。 |
|
|
360
|
-
| Claude Code | 官方 npm 包最新版；支持只读及可编辑模式。 |
|
|
361
|
-
| Codex CLI | 官方 npm 包最新版；支持只读及可编辑模式。 |
|
|
362
|
-
| MiniMax Code | 官方 npm 包最新版；Windows 原生依赖安装失败时原样运行官方安装脚本兜底；只允许经审批的独立 Git 工作区可编辑任务。 |
|
|
363
|
-
| MiMo Code | 官方 npm 包最新版；支持只读及可编辑模式。 |
|
|
364
|
-
| Grok Build | 官方 npm 包最新版；支持只读及可编辑模式。 |
|
|
365
|
-
| ZCode | 官方下载页上最新的、带智谱有效签名的 Windows 安装器；用户在原厂窗口选目录；只允许经审批的独立 Git 工作区可编辑任务。 |
|
|
366
|
-
| Gemini CLI | 官方 npm 包 `@google/gemini-cli` 最新版。无界面任务使用 `gemini -p`；签名沙箱入口不启动它。 |
|
|
367
|
-
|
|
368
|
-
保留的、与版本无关的安全校验（逐版本哈希已删除）：
|
|
369
|
-
|
|
370
|
-
| 工具 | 插件启动前核验 |
|
|
371
|
-
| --- | --- |
|
|
372
|
-
| Codex、Claude Code（Windows） | 有效 Authenticode 签名，发布者为 `OpenAI OpCo, LLC` / `Anthropic, PBC`（Claude 受限参数仍要求 ≥ 2.1.259） |
|
|
373
|
-
| ZCode（Windows） | `ZCode.exe` 由北京智谱华章科技股份有限公司签名（不限版本，版本号取自签名文件）；`resources/glm/.node-bundle-meta.json` 指向 `zcode.cjs`；未签名的 `zcode.cjs` 按签名构建首次使用时记录摘要，同一构建下内容变化则拒绝执行（`model-router/zcode-trust.json`） |
|
|
374
|
-
| ZCode 安装器 | 官方下载页给出的官方 CDN 地址、HTTPS、大小上限、Authenticode 发布者 |
|
|
375
|
-
| MiMo、Grok、MiniMax | 二进制/脚本没有签名：所有代码文件必须与**已安装版本**在官方 npm tarball 中的文件一致（tarball sha512 取自 registry.npmjs.org，结果缓存在 `model-router/npm-attestations.json`）。新版本首次运行需要联网一次。 |
|
|
179
|
+
0.15.0 还保存最多 90 个有记录的日期和 24 个月的费用汇总，仅包含金额/次数，不包含任务或回答内容。
|
|
376
180
|
|
|
377
|
-
|
|
181
|
+
执行历史含任务文本、回答摘录、路线、工作区、错误及费用。保存的任务最多 20,000 字符，每个回答最多 4,000 字符；重跑可能依赖截断后的上下文。模型档案不保存 API Key，终端不保存交互内容。实际执行仍会把所选任务/上下文发送给相应供应商或 CLI。
|
|
378
182
|
|
|
379
|
-
|
|
183
|
+
状态写入使用文件锁和原子替换；无法解析的文件保留为 `state.json.corrupt-<时间>` 并提示。迁移前备份状态/profile；分享历史或日志时先脱敏。
|
|
380
184
|
|
|
381
|
-
|
|
185
|
+
## 从克隆源码开发
|
|
382
186
|
|
|
383
|
-
|
|
384
|
-
| --- | --- | --- | --- |
|
|
385
|
-
| Anthropic / Claude | Claude Code | `claude -p --output-format json`，任务作为位置参数传入 | 已配置的 `ANTHROPIC_API_KEY`，否则使用 `claude` 自己的登录会话 |
|
|
386
|
-
| OpenAI | Codex CLI | `codex exec --json --sandbox read-only` | 已配置的 `OPENAI_API_KEY`，否则使用 `codex` 登录会话 |
|
|
387
|
-
| Google / Gemini | Gemini CLI | `gemini -p --output-format json`，标准输入作为补充上下文 | 已配置的 `GEMINI_API_KEY`，否则使用 Gemini CLI 已缓存的登录 |
|
|
388
|
-
| DeepSeek 及其他没有适配器的供应商 | 无 | 直接使用 Harness 模型目录 API | 使用宿主里已经配置的供应商凭据，插件不另存密钥 |
|
|
187
|
+
Git 仓库包含完整源码；npm 包是运行分发，不包含客户端源码、脚本、测试和实验工程。
|
|
389
188
|
|
|
390
|
-
|
|
189
|
+
需要 **Node.js 22.19+**、**pnpm 10.34.6**（`packageManager` 已固定）。在包含克隆目录的 PowerShell 中运行：
|
|
391
190
|
|
|
392
|
-
```
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
npm
|
|
191
|
+
```powershell
|
|
192
|
+
cd .\dsh-model-router
|
|
193
|
+
pnpm install --frozen-lockfile --strict-peer-dependencies
|
|
194
|
+
npm run build:client
|
|
195
|
+
npm test
|
|
196
|
+
npm run check:client
|
|
197
|
+
npm run pack:local
|
|
396
198
|
```
|
|
397
199
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
每条路线的 `execution` 可以是 `auto`（默认）、`official` 或 `api`。前两者都会先尝试官方工具；`api` 不启动 CLI。可编辑写文件仍使用 `model_router_tool_run` 或 `model_router_team_execute`，不由这次只读汇总改仓库。
|
|
401
|
-
|
|
402
|
-
`model_router_tool_run` 用于单工具调用；`model_router_team_execute` 为**插件自有的顺序 CLI 团队执行器**：按依赖运行，失败或回报模型不匹配即停。可编辑工作先在独立 Git worktree 执行，并在原仓库保持干净时整合；被 Git 忽略的输出需单独检查。官方 Harness Agent Teams 的成员生命周期与成员模型仍由宿主管理。
|
|
403
|
-
|
|
404
|
-
Harness 目录中的模型 ID 未必是厂商 CLI 接受的名字。逐模型设置可填写 `cliModel`；团队执行时临时的“工作包映射 > 工具映射 > 保存映射”。ZCode 不能逐次切换模型。多数 CLI 不回报可核验的实际模型 ID，执行后要对照厂商运行记录、权限和账单。Windows Harness 沙箱的 ACL 文件效果报告为部分隔离，涉及敏感仓库时应先用测试环境验证。
|
|
200
|
+
已在仓库目录时跳过第一行。安装包输出到 `dist`，在测试 profile 的桌面插件管理器中填写其绝对路径。单元测试通过不代表厂商登录、实际模型身份和扣费已验证。
|
|
405
201
|
|
|
406
|
-
|
|
202
|
+
无需启动 Harness 或厂商工具即可查看 UI：
|
|
407
203
|
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
- **固定启动目标**：客户端只能选择系统终端或注册表中的 CLI（以及其固定登录子命令），不能指定可执行文件、参数或环境变量。Windows 上原生 `.exe` 直接启动，npm 的 `.cmd` 包装经 `cmd.exe /d /s /c` 启动，只有 `.ps1` 时经 `powershell -File` 启动。
|
|
412
|
-
- **终端组件**：使用预编译、N-API 的 [`@lydell/node-pty`](https://www.npmjs.com/package/@lydell/node-pty) 伪终端（可选依赖，按平台下载预编译二进制，不需要编译工具，也没有安装脚本），已验证可在 Harness Desktop 宿主（Electron 44 以 Node 模式运行）中加载。无法加载时自动改用管道模式：程序看不到真实终端，全屏界面可能无法显示或拒绝启动，窗口大小不同步，方向键可能无效，输入由宿主回显；按行交互的登录命令和 PowerShell 可用。卡片会显示当前使用的模式。
|
|
413
|
-
- **传输**：输出通过插件现有 Typert 远程调用的长轮询读取（`terminalRead`）实时推送；按键（`terminalWrite`）和窗口大小（`terminalResize`）分别发送。
|
|
414
|
-
- **生命周期**：结束标签、关闭工作台面板、卸载或重新加载插件、退出 Harness 都会结束进程；约 2 分钟无人读取输出的会话会被结束；单个会话最长 6 小时；最多同时 4 个。
|
|
415
|
-
- **隐私**：输入和输出不会写入日志或保存。卡片中的历史（`state.json` 的 `terminalSessions`）只记录工具、方式、工作目录、开始/结束时间、时长、退出码和结束原因。
|
|
416
|
-
- **安装后需重启**：Harness 会立即加载新界面，但运行中的后台仍是旧插件代码；完全退出 Harness（包括托盘图标）并重新启动前，卡片会提示“插件后台版本较旧，请完全退出并重启 Harness”。
|
|
417
|
-
- **按键**：选中文字时 Ctrl+C 复制，否则发送中断；Ctrl+Shift+V 粘贴；拖动终端右下角调整高度。
|
|
418
|
-
|
|
419
|
-
## 可选安装 GAL
|
|
420
|
-
|
|
421
|
-
[DeepSeek Harness GAL](https://github.com/Alice-Marx/deepseek-harness-galgame)单独维护剧情引擎、立绘与场景、音乐、阅读设置、存档和自由模式。安装输入为 `@ljwei-stak/dsh-galgame@0.1.0`，详细操作见该仓库 README。模型路由安装包不再包含这些美术或剧情引擎，后续路由与 GAL 各自更新版本。
|
|
204
|
+
```powershell
|
|
205
|
+
npm run preview:ui
|
|
206
|
+
```
|
|
422
207
|
|
|
423
|
-
|
|
208
|
+
打开[本地预览](http://127.0.0.1:4173)。它使用模拟模型、工具和历史，提供有数据、空目录、错误、首次引导和延迟预览场景，用于检查布局和交互。模拟执行不调用供应商、不安装工具、不启动真实终端；它不等于 Host 集成验收。默认端口占用时可运行 `npm run preview:ui -- --port 4174`；修改客户端源码后刷新页面即可查看。
|
|
424
209
|
|
|
425
|
-
|
|
210
|
+
| 位置 | 用途 |
|
|
211
|
+
| --- | --- |
|
|
212
|
+
| `.dsh-plugin/index.mjs` | Host 插件、会话工具、设置、执行与远程处理。 |
|
|
213
|
+
| `.dsh-plugin/client/` | React 工作台源码与 CSS。 |
|
|
214
|
+
| `.dsh-plugin/shared/` | 路由、工具注册表/执行、计费、历史、状态与终端协议。 |
|
|
215
|
+
| `.dsh-plugin/client.js` | 生成的桌面客户端；修改客户端源码后需要重建。 |
|
|
216
|
+
| `scripts/` 与 `tests/` | 构建、打包、验证辅助脚本与回归测试。 |
|
|
217
|
+
| `experiment-plugin/` | 独立研究实验工程，不随当前路由插件发布。 |
|
|
218
|
+
| `docs/` 与带日期报告 | 用户文档与历史验证记录。 |
|
|
426
219
|
|
|
427
|
-
|
|
428
|
-
pnpm install --frozen-lockfile --strict-peer-dependencies
|
|
429
|
-
npm run build:client
|
|
430
|
-
npm test
|
|
431
|
-
npm run check:client
|
|
432
|
-
npm pack --pack-destination dist
|
|
433
|
-
```
|
|
220
|
+
`check:client` 在内存中重建并核对生成文件，`prepack` 会拒绝过期的客户端。pnpm 10 没有 `pnpm peers check`，使用上面的严格依赖安装。不可获取或不兼容的宿主 SDK 可影响本地集成验证；[setup-harness-dev.mjs](scripts/setup-harness-dev.mjs) 从明确指定的已安装 Host `node_modules` 链接缺少的 SDK，[start-harness-preview.mjs](scripts/start-harness-preview.mjs) 启动独立本地 Web Host profile。这些辅助方式不替代依赖核验与真实桌面验收。
|
|
434
221
|
|
|
435
|
-
|
|
222
|
+
旧兼容模块、研究资料和带日期报告保留供参考，不表示其中所有旧集成都在当前插件中启用。发布与同步遵循 [AGENTS.md](AGENTS.md)；复现发布内容时使用精确版本的包或经过验证的发布标签。
|
|
436
223
|
|
|
437
|
-
|
|
224
|
+
## 常见问题
|
|
438
225
|
|
|
439
|
-
|
|
226
|
+
| 情况 | 检查 |
|
|
227
|
+
| --- | --- |
|
|
228
|
+
| 没有路线/无法规划 | 先配置官方模型页，刷新目录，并等待工具检测结束。 |
|
|
229
|
+
| 费用未知 | 为比较的路线同时填写输入/输出 USD 单价。 |
|
|
230
|
+
| 工具已安装但不能执行 | 查看可信入口原因、平台/模式支持和安装来源。 |
|
|
231
|
+
| 登录/模型调用失败 | 核查厂商账号、CLI 登录、网络和模型权限；安装成功不等于可用。 |
|
|
232
|
+
| 提示后台版本较旧 | 完全退出 Harness（包括托盘），再启动。 |
|
|
233
|
+
| 预览与旧建议不同 | 目录、登录、额度或预算变化；重新审阅预览。 |
|
|
234
|
+
| 终端全屏界面不显示 | 检查使用 PTY 还是管道回退。 |
|
|
235
|
+
| 可编辑团队停止 | 先核对失败工作包与整合状态，再选择续跑或人工审阅工作树。 |
|
|
236
|
+
|
|
237
|
+
反馈请附宿主/插件版本、执行模式、工具状态和脱敏错误：[问题反馈](https://github.com/Alice-Marx/dsh-model-router/issues)。
|
|
440
238
|
|
|
441
239
|
许可证：[MIT](LICENSE)。
|