@kikkimo/claude-launcher 3.0.0 → 3.2.0

package/docs/superpowers/specs/2026-06-14-provider-model-upgrade-design.md

@@ -0,0 +1,292 @@
+# Provider 模型升级设计 — v3.2.0
+
+- **日期**：2026-06-14
+- **状态**：已批准（待实施）；经 Codex（GPT-5.5 / xhigh）评审 3 轮通过（round1/round2 修订 → round3 pass）
+- **影响文件**：`lib/presets/providers.js`、`lib/api-manager.js`（迁移逻辑）、`lib/launcher.js`（仅消费，无改动）、`lib/utils/model-upgrade-checker.js`（无逻辑改动）、`test/providers.test.js`、`test/env-vars-providers.test.js`、`test/api-manager.test.js`（新增迁移用例）、`package.json`、`CHANGELOG.md`
+
+## 背景
+
+claude-launcher 预置 9 个 Anthropic 兼容 API provider，模型定义集中在 `lib/presets/providers.js`。截至 2026-06-14，经核对各家官方 Claude Code 集成口径，以下 provider 的模型定义滞后：
+
+- **anthropic**：缺 `claude-opus-4-8`（当前最新停在 `claude-opus-4-7`）
+- **moonshot**：当前主模型 `kimi-k2.6` 已被官方主推的 `kimi-k2.7-code` 取代
+- **minimax（cn/global）**：缺 `MiniMax-M3`（2026-06-01 发布的 M 系列最新主模型）
+- **deepseek**：Haiku 档应为 `deepseek-v4-flash`（项目当前用 `deepseek-v4-flash[1m]`）
+- **zhipu / zai**：缺 `glm-5.2` / `glm-5.2[1m]`（当前最新停在 `glm-5.1`）
+
+此外，API 的 tier 默认值（`ANTHROPIC_DEFAULT_OPUS_MODEL` 等）在创建/编辑时由 provider template 计算并**持久化**，启动时直接消费（`launcher.js:getProviderEnvVars`）。provider template 升级后，已保存的旧配置不会自动刷新——本次必须一并设计迁移机制。
+
+## 目标
+
+1. 对齐 5 个 provider（anthropic、moonshot、minimax、deepseek、zhipu/zai）的模型定义到各家官方最新口径
+2. `versionAliases` 单跳收敛到当前旗舰，让升级检测对每个旧模型都生效
+3. 为 GLM 设计明确的 opus/sonnet/haiku 三档 tier 映射
+4. **新增**：provider template 升级后，已保存的 API 配置能自动刷新 tier 默认（保留用户手动覆盖）
+5. 同步更新测试断言与 CHANGELOG，保持既有不变量
+
+## 非目标
+
+- **仅维护 Claude 4 Opus/Sonnet/Haiku tier**：本次把 opus 系列升级到 `claude-opus-4-8`，**不把 Fable / Mythos 纳入** claude-launcher 的 provider 列表或 upgrade alias
+- 不增删 provider 列表本身
+- 不改动 `model-upgrade-checker` 的检测算法（继续沿用单跳 `versionAliases`）
+- `kimi_for_coding`（稳定别名 `kimi-for-coding`）与 `custom` 模板不变
+
+## 设计原则（由代码契约推导）
+
+| 原则 | 依据 | 对设计的要求 |
+|---|---|---|
+| **单跳收敛** | `getLatestModel(model, provider) === providers[provider].versionAliases[model] \|\| null`，无图遍历 | 每个旧模型必须**直接**指向最新旗舰，禁止链式中间跳（如 `4.5→4.7→5.1` 会被截断到 `4.7`） |
+| **旗舰豁免** | `test/providers.test.js` 不变量：`models[0]` 不得出现在 `versionAliases` 的 key 中 | 最新旗舰自身永不"可升级" |
+| **分档不升级** | haiku/快速档是有效产品线，非"过时" | `glm-5-turbo`、`deepseek-v4-flash`、`MiniMax-M2.x-highspeed` 等 haiku 档模型不设升级路径 |
+| **同档旧版升级** | 与 anthropic 既有模式一致（`opus-4-6→4-7`） | 旗舰/opus 系旧版引导升级到该档最新 |
+| **有 tier 角色的可选模型不升级** | GLM 的 `glm-5`、`glm-5.1` 是用户主动保留的可选项 | 不设升级路径；仅已下线的 `glm-4.5/4.6/4.7` 设 alias |
+
+## 升级收敛图
+
+每条均为单跳，最左目标为 `models[0]`（本设计定义的 provider target model），不出现在任何 alias key 中。
+
+```
+anthropic:   opus-4 / 4-1 / 4-5 / 4-6 / 4-7      ──►  claude-opus-4-8
+             sonnet-4 / 4-5 / 3-7-sonnet         ──►  claude-sonnet-4-6
+
+zhipu/zai:   glm-4.5 / 4.6 / 4.7                 ──►  glm-5.2[1m]
+             (glm-5 / glm-5.1 / glm-5-turbo 不升级：有 tier 角色)
+
+moonshot:    kimi-k2.6 / k2.5 / k2-thinking / k2-thinking-turbo
+             + kimi-k2-0711/0905/turbo-preview    ──►  kimi-k2.7-code
+
+minimax:     MiniMax-M2 / M2.1 / M2.5 / M2.7     ──►  MiniMax-M3
+             (-highspeed 变体不升级：担任 haiku 档)
+
+deepseek:    deepseek-chat                        ──►  deepseek-v4-flash
+             deepseek-reasoner                    ──►  deepseek-v4-pro[1m]
+             deepseek-v4-flash[1m]                ──►  deepseek-v4-flash   (兼容旧配置)
+```
+
+## tier 映射总表
+
+| Provider | Opus 档（最强） | Sonnet 档（默认/平衡） | Haiku 档（快速/subagent） | template 实现 |
+|---|---|---|---|---|
+| **anthropic** | `claude-opus-4-8` | `claude-sonnet-4-6` | `claude-haiku-4-5-20251001` | 现有 `find('opus'\|'sonnet'\|'haiku')`，不变 |
+| **zhipu / zai** | `glm-5.2[1m]` | `glm-5.2[1m]` | `glm-5-turbo` | **新增固定 tier template** |
+| **moonshot** | `kimi-k2.7-code` | `kimi-k2.7-code` | `kimi-k2.7-code` | `makeSingleTemplate()` |
+| **minimax** | `MiniMax-M3` | `MiniMax-M3` | 选 M3→M3；选 M2.x→M2.x-highspeed | 现有 `makeFastMapTemplate`，不变（M3 自动 fallback 自身） |
+| **deepseek** | `deepseek-v4-pro[1m]` | `deepseek-v4-pro[1m]` | `deepseek-v4-flash` | `makeFastMapTemplate({ 'deepseek-v4-pro[1m]': 'deepseek-v4-flash' })` |
+
+**GLM 新 template**（取代当前 `makeFastMapTemplate`）：Opus 与 Sonnet 同档（均用旗舰 `glm-5.2[1m]`），Haiku 固定为 `glm-5-turbo`。无论用户在 `/model` 选哪个模型作为 `CUSTOM_MODEL_OPTION`，三档标准固定，符合 Claude Code「tier 标准固定、CUSTOM 为当前选择」的语义。
+
+## 持久化迁移（template 漂移检测）
+
+**问题**：API 的 tier 默认值在创建/编辑时由 provider template 计算并持久化到 `modelEnvVars` / `_autoModelEnvVars` / `smallFastModel`，启动时由 `launcher.js:getProviderEnvVars` 直接消费。当前 `_normalizeApiFields`（`api-manager.js:131`）只在 `_autoModelEnvVars` **缺失**时重建，已有配置仅补缺失 key；只有编辑 model 时（`api-manager.js:521`）才按新 template 刷新。因此 provider template 升级后，已保存的 API（如 `glm-5.1`、`deepseek-v4-pro[1m]`、`claude-sonnet-4-6`）会继续使用旧 tier 默认——**provider 单测通过 ≠ 真实启动环境已升级**。
+
+**方案**：在 `_normalizeApiFields` 增加 template 漂移检测。加载时计算 `currentTemplate = provider.modelEnvTemplate.getValues(effectiveModel)`，与持久化的 `api._autoModelEnvVars` 比较：
+
+- **一致**（template 未变）：无操作，保持现状
+- **不一致**（template 升级，即本次升级后首次加载旧配置）：
+  - 对每个 `PREDEFINED_MODEL_ENV_KEYS`：若 `api.modelEnvVars[k] === api._autoModelEnvVars[k]`（仍等于旧 auto 快照、用户未手动覆盖）→ 刷新为 `currentTemplate[k]`
+  - `smallFastModel` 同理：若 `api.smallFastModel === api._autoModelEnvVars.smallFastModel` → 刷新为 `currentTemplate.smallFastModel`
+  - 更新 `api._autoModelEnvVars = { ...currentTemplate }`
+
+**不在此处调用 `saveConfig()`**——`_normalizeApiFields` 保持纯变更函数。漂移改写会改变 `modelEnvVars` / `_autoModelEnvVars` / `smallFastModel`，而 `_migrateApiEntry`（`api-manager.js:88`）的 before/after 比较已覆盖这三个字段，自动返回 `migrated=true`；构造函数（`api-manager.js:43-47`）据此统一 `saveConfig()` 持久化。该「保留用户手动覆盖」逻辑复用 `updateApiField(model)` 已验证模式（`api-manager.js:533-551`），仅把触发条件从「用户编辑 model」扩展为「template 漂移」。
+
+## 各 provider 目标态
+
+### anthropic
+
+```js
+const anthropicModels = [
+    'claude-opus-4-8',               // 新增 — models[0]
+    'claude-opus-4-7',
+    'claude-sonnet-4-6',
+    'claude-haiku-4-5-20251001',
+    'claude-sonnet-4-5',
+    'claude-opus-4-6',
+    'claude-opus-4-5',
+];
+// versionAliases
+{
+    'claude-opus-4':       'claude-opus-4-8',
+    'claude-opus-4-1':     'claude-opus-4-8',
+    'claude-opus-4-5':     'claude-opus-4-8',
+    'claude-opus-4-6':     'claude-opus-4-8',
+    'claude-opus-4-7':     'claude-opus-4-8',   // 新增
+    'claude-sonnet-4':     'claude-sonnet-4-6',
+    'claude-sonnet-4-5':   'claude-sonnet-4-6',
+    'claude-3-7-sonnet':   'claude-sonnet-4-6',
+}
+// name: 'Anthropic (Official)' 不变
+// modelEnvTemplate: 现有 find 逻辑不变（数组顺序保证 find('opus')→4-8, find('sonnet')→4-6）
+```
+
+> 数组顺序约束：`claude-opus-4-8` 必须在所有含 `opus` 的模型之前；`claude-sonnet-4-6` 必须在 `claude-sonnet-4-5` 之前，以保证 `find()` 命中最新。
+
+### zhipu / zai（二者镜像一致）
+
+```js
+// 新增 template factory
+function makeGlmTierTemplate() {
+    return {
+        getValues(model) {
+            return {
+                ANTHROPIC_CUSTOM_MODEL_OPTION: model,
+                ANTHROPIC_CUSTOM_MODEL_OPTION_NAME: model,
+                ANTHROPIC_DEFAULT_OPUS_MODEL:   'glm-5.2[1m]',
+                ANTHROPIC_DEFAULT_SONNET_MODEL: 'glm-5.2[1m]',
+                ANTHROPIC_DEFAULT_HAIKU_MODEL:  'glm-5-turbo',
+                CLAUDE_CODE_SUBAGENT_MODEL:     'glm-5-turbo',
+                smallFastModel:                 'glm-5-turbo',
+            };
+        },
+    };
+}
+
+// provider 定义（zhipu 与 zai 除 baseUrl/name 外完全一致）
+name: 'ZhiPu AI (GLM-5.2/5-Turbo) - 智谱清言',   // zai: 'Z.ai (GLM-5.2/5-Turbo) - ZhiPu Global'
+models: ['glm-5.2[1m]', 'glm-5.1', 'glm-5-turbo', 'glm-5'],   // opus→sonnet 备选→haiku→历史
+versionAliases: {
+    'glm-4.5': 'glm-5.2[1m]',
+    'glm-4.6': 'glm-5.2[1m]',
+    'glm-4.7': 'glm-5.2[1m]',
+    // glm-5 / glm-5.1 / glm-5-turbo 均不设 alias（有 tier 角色或为 haiku 档）
+},
+envVars: {
+    // ...原有项保留...
+    CLAUDE_CODE_AUTO_COMPACT_WINDOW: '1000000',   // 新增 — 配合 1M 上下文
+},
+modelEnvTemplate: makeGlmTierTemplate(),
+```
+
+> **来源说明（glm-5.2）**：`glm-5.2` / `glm-5.2[1m]` 依据项目维护者 2026-06-14 提供的官方 FAQ 口径（GLM Coding Plan 当前支持 GLM-5.2、GLM-5-Turbo、GLM-4.7、GLM-4.5-Air）。`[1m]` 为 1M 上下文标记，配套 `CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000`。`glm-5.1` 保留为可选模型（用户主动保留，不设升级路径）。当前代码中 `'glm-5-turbo': 'glm-5.1'` 这一将快速档误升级为旗舰的矛盾项一并移除。
+
+### moonshot
+
+```js
+name: 'Moonshot AI (Kimi-K2.7-Code)',
+baseUrl: 'https://api.moonshot.cn/anthropic',   // 不变
+models: ['kimi-k2.7-code'],
+versionAliases: {
+    'kimi-k2.6':              'kimi-k2.7-code',
+    'kimi-k2.5':              'kimi-k2.7-code',
+    'kimi-k2-thinking':       'kimi-k2.7-code',
+    'kimi-k2-thinking-turbo': 'kimi-k2.7-code',
+    'kimi-k2-0711-preview':   'kimi-k2.7-code',
+    'kimi-k2-0905-preview':   'kimi-k2.7-code',
+    'kimi-k2-turbo-preview':  'kimi-k2.7-code',
+},
+modelEnvTemplate: makeSingleTemplate(),   // thinking 不可关，单一旗舰，所有 tier 同模型
+envVars: {
+    // ...原有项保留（API_TIMEOUT_MS、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 等）...
+    ENABLE_TOOL_SEARCH: 'false',                  // 新增 — Kimi 官方 Claude Code 集成要求
+    CLAUDE_CODE_AUTO_COMPACT_WINDOW: '262144',    // 新增 — 配合 K2.7 的 256K 上下文
+},
+```
+
+> **来源说明（moonshot env vars）**：`ENABLE_TOOL_SEARCH=false` 与 `CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144` 依据 Kimi 官方 Claude Code 集成文档（CN: platform.kimi.com / Global: platform.kimi.ai）。K2.7 thinking 不可关闭、256K 上下文。这两个为 **provider-only 默认**——它们不在 `PREDEFINED_RUNTIME_KEYS` 白名单（`validators.js:138`），Runtime UI 不暴露，用户若需覆盖走 **Custom Vars**（`launcher.js:260-265` 已支持非预定义 key 覆盖 provider 默认）。**本次不扩展 Runtime UI 白名单**（避免牵动 validators / api-editor / i18n / 多个 runtime 测试，超出模型升级范围）。
+
+### minimax_cn / minimax_global（二者镜像一致）
+
+```js
+name: 'MiniMax CN (国内版)',   // global: 'MiniMax Global (国际版)'
+models: [
+    'MiniMax-M3',                  // 新增 — models[0]，所有 tier 均映射 M3
+    'MiniMax-M2.7',
+    'MiniMax-M2.7-highspeed',
+    'MiniMax-M2.5',
+    'MiniMax-M2.5-highspeed',
+    'MiniMax-M2.1',
+    'MiniMax-M2.1-highspeed',
+    'MiniMax-M2',
+],
+versionAliases: {
+    'MiniMax-M2':   'MiniMax-M3',
+    'MiniMax-M2.1': 'MiniMax-M3',
+    'MiniMax-M2.5': 'MiniMax-M3',
+    'MiniMax-M2.7': 'MiniMax-M3',   // 新增
+    // -highspeed 变体不设 alias（担任 haiku 档）
+},
+// modelEnvTemplate 不变：makeFastMapTemplate({ M2.x → M2.x-highspeed })
+//   M3 不在 fastMap 中 → fastMap[model] || model 回退到 M3 自身 = 所有 tier 映射 M3
+```
+
+### deepseek
+
+```js
+name: 'DeepSeek (V4-Pro/V4-Flash)',   // 不变
+models: [
+    'deepseek-v4-pro[1m]',   // 主力（Opus/Sonnet）
+    'deepseek-v4-flash',     // 快速/Haiku/subagent（去掉 [1m]，对齐官方 Haiku 口径）
+    'deepseek-chat',         // 兼容别名，2026-07-24 停用
+    'deepseek-reasoner',     // 兼容别名，2026-07-24 停用
+],
+versionAliases: {
+    'deepseek-chat':         'deepseek-v4-flash',
+    'deepseek-reasoner':     'deepseek-v4-pro[1m]',
+    'deepseek-v4-flash[1m]': 'deepseek-v4-flash',   // 兼容旧配置
+},
+modelEnvTemplate: makeFastMapTemplate({ 'deepseek-v4-pro[1m]': 'deepseek-v4-flash' }),
+// envVars 不变
+```
+
+> **来源说明（deepseek `[1m]`）**：`deepseek-v4-pro[1m]` 为 Claude Code 官方集成示例的主模型写法（`[1m]`=1M 上下文变体，非笔误）；Haiku 档用 `deepseek-v4-flash`（无 `[1m]`）对齐官方示例。旧别名 `deepseek-chat` / `deepseek-reasoner` 将于 2026-07-24 停用，保留为兼容 alias。
+
+### kimi_for_coding / custom — 不改动
+
+`kimi-for-coding` 是后端自动映射最新的稳定别名，保持原样。
+
+## 测试影响
+
+### `test/providers.test.js`
+
+- `zhipu: models list is correct` → `['glm-5.2[1m]', 'glm-5.1', 'glm-5-turbo', 'glm-5']`
+- `zhipu: name includes all current model families` → 含 `GLM-5.2`、`5-Turbo`
+- 删除 `zhipu: glm-5-turbo aliases to glm-5.1`（turbo 不再升级）
+- `zhipu: glm-4.7 aliases to ...` → 目标改为 `glm-5.2[1m]`；新增 `glm-5.2[1m] has no alias`、`glm-5.1 has no alias`
+- `moonshot: models list ...` → `['kimi-k2.7-code']`，`length === 1`
+- 所有 moonshot alias 目标 → `kimi-k2.7-code`；新增 `kimi-k2.7-code has no alias`
+- `minimax_cn: models list ...` → 含 `MiniMax-M3`，`length === 8`
+- `minimax_cn: MiniMax-M2.7 aliases to ...` → `MiniMax-M3`；新增 `MiniMax-M3 has no alias`
+- `anthropic: models include ...` → 含 `claude-opus-4-8`，`length === 7`
+- `anthropic: versionAliases map opus series to opus-4-7` → 改为 `opus-4-8`，并覆盖 `opus-4-7 → opus-4-8`
+- `deepseek: models include ...` → 含 `deepseek-v4-flash`（去 `[1m]`）
+- 新增 `moonshot: envVars includes ENABLE_TOOL_SEARCH / AUTO_COMPACT_WINDOW` 断言
+- 不变量测试 `models[0] ∉ versionAliases`：自动覆盖新旗舰，无需改
+
+### `test/env-vars-providers.test.js`
+
+- `anthropic model list trimmed` → `length === 7`，含 `claude-opus-4-8`
+- `anthropic versionAlias opus-4-6 → opus-4-7` → `opus-4-8`
+- `anthropic template: tier-based assignment` → 选 `claude-sonnet-4-6` 时 `OPUS = claude-opus-4-8`
+- `deepseek alias chat → v4-flash` → `deepseek-v4-flash`（去 `[1m]`）
+- `deepseek template: pro model → flash` → `HAIKU/SUBAGENT/smallFast = deepseek-v4-flash`
+- 新增 GLM tier template 测试：`getValues('glm-5.2[1m]')` → `OPUS = SONNET = glm-5.2[1m]`、`HAIKU = glm-5-turbo`；`getValues('glm-5')` → tier 标准仍为 `glm-5.2[1m]`/`glm-5-turbo`，`CUSTOM = glm-5`
+- 新增 moonshot provider-default vs Custom Vars 覆盖优先级测试：`getProviderEnvVars()` 默认输出 `ENABLE_TOOL_SEARCH=false`；当 `customEnvVars.ENABLE_TOOL_SEARCH='true'` 时输出 `'true'`（验证 `launcher.js:260-265` 合并优先级）
+
+### `test/api-manager.test.js`（新增迁移用例）
+
+覆盖**真实加载路径**（`_migrateApiEntry` / `loadConfig`），而非仅直调 `_normalizeApiFields`：
+
+- 构造旧配置（`provider=zhipu, model=glm-5.1, _autoModelEnvVars=<旧 glm-5.1 template 快照>`），经 `_migrateApiEntry` 后：
+  - `api.modelEnvVars.ANTHROPIC_DEFAULT_OPUS_MODEL === 'glm-5.2[1m]'`（漂移刷新）
+  - `api.modelEnvVars.ANTHROPIC_DEFAULT_HAIKU_MODEL === 'glm-5-turbo'`
+  - `api._autoModelEnvVars` 已更新为新 template 快照
+  - `_migrateApiEntry` 返回 `true`（migrated），证明会触发构造函数 `saveConfig()`
+- 用户手动覆盖保留：旧配置中 `modelEnvVars.ANTHROPIC_DEFAULT_HAIKU_MODEL` 被手动设为 `'glm-5.1'`（≠ 旧 auto）→ 漂移刷新后**保持** `'glm-5.1'` 不变
+- 集成断言：上述旧配置经 `getProviderEnvVars()` 输出含 `ANTHROPIC_DEFAULT_OPUS_MODEL=glm-5.2[1m]`
+- 无漂移场景：`_autoModelEnvVars` 已等于当前 template → `_migrateApiEntry` 返回 `false`，不改写任何字段
+
+## 版本与 CHANGELOG
+
+- `package.json` → `3.2.0`
+- CHANGELOG `[3.2.0]` 段：
+  - **Added**：`claude-opus-4-8`（anthropic）、`kimi-k2.7-code`（moonshot）、`MiniMax-M3`（minimax）、`glm-5.2[1m]`（zhipu/zai）
+  - **Added**：provider template 漂移检测——升级后首次加载旧配置自动刷新 tier 默认（保留用户手动覆盖）
+  - **Changed**：GLM 改用固定 tier template（Opus=Sonnet=`glm-5.2[1m]`、Haiku=`glm-5-turbo`）；DeepSeek Haiku 档对齐为 `deepseek-v4-flash`；moonshot 收敛为单一旗舰 `kimi-k2.7-code`，旧模型转为升级别名，新增 `ENABLE_TOOL_SEARCH`/`CLAUDE_CODE_AUTO_COMPACT_WINDOW`；zhipu/zai 新增 `CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000`
+  - **Removed**：moonshot 主列表移除 `kimi-k2.5/k2-thinking/k2-thinking-turbo`（保留为升级别名）
+
+## 验收标准
+
+1. `npm test` 全部通过
+2. 对每个 provider，`getLatestModel(<每个旧模型>, provider)` 返回该 provider 的本设计定义 target model（或对 haiku/有角色模型返回 `null`）
+3. 对每个 provider，`getLatestModel(models[0], provider) === null`（旗舰豁免）
+4. `model-upgrade-checker.checkAllApiUpgrades()` 对一个配置了旧模型（如 `glm-4.7`、`kimi-k2.6`、`MiniMax-M2.7`、`claude-opus-4-7`）的 API 能正确检出升级建议
+5. **迁移**：加载一个升级前保存的旧配置（如 `provider=zhipu, model=glm-5.1`），`getProviderEnvVars()` 输出新的 tier 默认值（`OPUS=glm-5.2[1m]`、`HAIKU=glm-5-turbo`）；用户手动覆盖的字段保持不变