mingdao-harness 0.6.15 → 0.6.17

package/docs/CONFIG.md

@@ -373,6 +373,158 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 
 长期偏好仍走用户记忆（`AGENTS.md`，见上），不受此开关影响。
 
+## 模型名称以 API 为准（v0.6.19，§3.67）
+
+**仓库不维护具体版本号，只维护「家族能力 / 定价模式」。** 官方改名、升版本（例如
+`deepseek-v4-flash` → `deepseek-flash` → `DeepSeek-V4.1-Flash 1017` → 未来的 V4.2/V5）
+**不需要改代码**：模型名一律以 `GET /v1/models` 实时返回的官方名为准。
+
+> 官方**宣传名**（如 `DeepSeek-V4.1-Flash 1017`）与实际 API id（如 `deepseek-flash`）不一致时，
+> **不要**把它写进请求：用下面的「显示别名 `config.modelLabels`」，请求仍用 API id。
+
+### 家族模式表
+
+`src/models.js` 的 `MODEL_FAMILIES` 用正则匹配名字，能力（上下文窗口、单次输出上限、工具调用、
+视觉）与定价挂在**模式**上：
+
+| 家族 | 匹配（大小写 / 空格 / 连字符 / 版本号无关） | 典型官方名 |
+| --- | --- | --- |
+| `pro` | `deepseek` + 可选版本 + `pro` | `DeepSeek-V4.1-Pro 1017` |
+| `flash` | `deepseek` + 可选版本 + `flash` | `DeepSeek-V4.1-Flash 1017` |
+| `vision` | `deepseek` + 可选版本 + `flash` + `vision` | `DeepSeek-V4.1-Flash-Vision 1017` |
+
+- 精确 id 只作为**已知别名**存在（如旧名 `deepseek-v4-flash`），老配置与历史会话照常可用；
+  路由比较前会归一化到家族代表名，不会因为厂家改名而静默失效。
+- 比已核对规格更新的版本（例如 `DeepSeek-V4.2-Flash 1101`）**仍可选中**，列表会标
+  「能力未知（新版本）」并按家族规格保守估算上下文与价格；需要精确规格时用
+  `customModels.<模型名>.contextWindow` / `config.pricing.overrides` 覆盖。
+
+### 默认值如何解析
+
+默认模型（新建配置、WebUI 模型下拉、自动路由的 planner / executor）在**运行时**按下列顺序解析：
+
+1. 用户显式配置优先：`config.model`、`config.routing.planner`、`config.routing.executor`；
+2. 否则从**当前 API 名单**里按家族挑官方名：planner → `pro` 家族，executor → `flash` 家族，
+   多个版本并存时取最高版本；
+3. 名单里没有对应家族、或 API 不可达时，才退回**内置家族代表名**，并输出提示：
+   - 服务端日志：`[MingDao] ⚠ … 默认模型走兜底 …`
+   - WebUI / HTTP：`GET /api/models` 与 `GET /api/state` 的 `note` 字段，离线时
+     `offlineFallback: true`，文案为「离线兜底：模型名可能不是最新的」。
+
+离线时模型列表使用内置家族代表名（不是最新官方版本），并在每个条目上标
+「离线兜底」；连上 API 后刷新即恢复官方名。
+
+**自定义端点不主动探测。** `provider: "custom"`（以及未内置的服务商）不会收到
+`GET /models` 请求——很多自定义网关只实现 chat，空 body 的 `/models` 请求会让它们直接崩。
+这类端点的默认 planner / executor 用家族代表名兜底，需要指定时在 `config.routing.*`
+里写端点自己的模型名。
+
+### 旧名与自定义模型
+
+- 旧名（`deepseek-v4-flash`、`deepseek-flash`、`deepseek-v4-pro`、`deepseek-v4-flash-vision-exp`）
+  仍可作为 `--model` / `config.model` 的取值；能力与定价照旧按家族解析。
+- 完全不属于任何家族的线上新模型（例如非 DeepSeek 命名）仍会出现在列表里，可直接选中；
+  能力未知时按远程模型保守默认（上下文 128k）估算，可用 `customModels` 显式覆盖。
+
+### 显示别名 `config.modelLabels`（v0.6.20，§3.69）
+
+**厂家的「官方宣传名 / 构建名」不等于 API id，不能拿去请求。** 实测（2026-10，真机）：
+
+```text
+GET  https://api.deepseek.com/v1/models
+→ ["deepseek-flash", "deepseek-v4-pro"]
+
+POST /v1/chat/completions {"model":"deepseek-flash"}
+→ 200（响应 model = "deepseek-flash"）
+
+POST /v1/chat/completions {"model":"DeepSeek-V4.1-Flash 1017"}
+→ 400 {"message":"The supported API model names are deepseek-flash, deepseek-v4-pro,
+                    but you passed DeepSeek-V4.1-Flash 1017."}
+```
+
+也就是说：`DeepSeek-V4.1-Flash 1017` **既不会出现在 `/models` 里，也不能用于请求**。
+界面想显示官方宣传名，只能用「显示别名」——它**只影响渲染**，绝不参与出网请求的
+`model` 字段（`config.model` / `config.routing.*` / 请求体 `model` 始终是 API id）。
+
+```json
+{
+  "model": "deepseek-flash",
+  "modelLabels": {
+    "deepseek-flash": "DeepSeek-V4.1-Flash 1017",
+    "deepseek-v4-pro": "DeepSeek-V4.1-Pro 1017"
+  }
+}
+```
+
+校验规则（`src/models.js` 的 `normalizeModelLabels`，在 `loadConfig()` 时执行）：
+
+| 规则 | 非法时的行为 |
+| --- | --- |
+| `modelLabels` 必须是对象（不能是数组 / null / 字符串） | 整个字段忽略 + `console.warn` |
+| key（API id）去空白后必须非空 | 该项忽略 + `console.warn` |
+| value 必须是字符串、去空白后必须非空 | 该项忽略 + `console.warn` |
+| value 长度 ≤ 80 字符（`MODEL_LABEL_MAX_LENGTH`） | 该项忽略 + `console.warn` |
+| key 为 `__proto__` / `constructor` / `prototype` | 该项忽略 + `console.warn`（原型污染防线） |
+
+非法项**不会阻断启动**（配置写坏一个字不该让应用起不来）；同一非法项每个进程只提醒一次。
+合法映射的值会去掉首尾空白后生效。
+
+接口形状（`GET /api/models` 与 `GET /api/state` 的 `models[]`，**服务商线上模型**条目）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `id` | API 实际 id（出网请求用它） |
+| `name` | 同 `id`（保留给现有前端的选择 value，选择逻辑不变） |
+| `label` | 显示名：`modelLabels[id]`；没有映射时**回退 `id`** |
+| `labelSource` | 仅当 `label !== id` 时为 `"config"`（显示名来自 `config.modelLabels`） |
+| `detail` | 能力 / 来源说明（原来的组合标签：离线兜底、能力未知、来源标注） |
+
+`config.customModels` 的条目保持既有的「名字 — 用户标签（来源）」展示——它们不是官方
+API id，不参与 `modelLabels`（其条目仍带 `id`，等于自定义模型名）。
+
+回归：`test/model-names.js` 第 ⑧ 组断言 + `test/mutate/batch37-model-labels.mjs`（10/10 全中）。
+
+### TODO（UI：显示别名落地，待另一道 / 下一轮实现；本次不改 UI 文件）
+
+> 本次（v0.6.20 §3.69）只做内核 / 接口 / 文档；`src/web/app.js`、`src/web/index.html` 由并行
+> UI 线持有（P1 已合入 `878d4cb`），故以下三处**尚未落地**。行号为 `878d4cb` 时；
+> 后续改动会漂移，请以 `o.value=m.name; o.textContent=m.name; o.title=m.label` 等代码锚点为准。
+
+1. **模型选择器显示 `label`、`title` 显示 API id**（只改显示，不改选择逻辑）
+   - 位置：`src/web/app.js` 两处重复的选项渲染（`:1859` 与 `:2189`），锚点
+     `o.value=m.name; o.textContent=m.name; o.title=m.label;`。
+   - 建议改法：
+     ```js
+     const id = m.id || m.name;
+     const label = m.label || id;
+     const o = document.createElement('option');
+     o.value = id;                                   // 选择 / 请求仍用 API id
+     o.textContent = label;                          // 界面显示官方宣传名
+     o.title = 'API id: ' + id + (m.detail ? ' · ' + m.detail : '');
+     if (id === j.model) o.selected = true;
+     ```
+   - 期望效果：下拉显示 `DeepSeek-V4.1-Flash 1017`；悬浮提示能对上
+     `API id: deepseek-flash · （能力/来源说明）`；选择后提交的仍是 id。
+2. **会话设置一行小字（仅当 `label !== id` 时出现）**
+   - `src/web/index.html`：会话设置的模型行（`:653` 已有 `ssModelLabel` / `ssModelId`），
+     在 `ssModelSrc` 后加：
+     ```html
+     <div class="ss-src" id="ssModelAliasHint" hidden>显示名来自 config.modelLabels，请求使用 API id。</div>
+     ```
+   - `src/web/app.js`：`renderSessionSettings()` 中 `set('#ssModelId', ...)` 附近加：
+     ```js
+     const hint = $('#ssModelAliasHint');
+     if (hint) hint.hidden = !(md.label && md.label !== md.name);
+     ```
+     （`md` 即已有的 `modelDisplay(当前模型条目)`，`app.js:966`。）
+   - 期望效果：配了映射的模型显示这行说明，没配时不出现。
+3. **设置页说明文案（不是新表单）**
+   - `src/web/index.html`：`模型与 API Key` 标题下（`:757`）加一条
+     `cfg-hint`（带 `data-kw` 便于设置搜索命中，不新增任何输入框）：
+     ```html
+     <div class="cfg-hint" data-kw="模型 id 官方名 宣传名 modelLabels 显示名">模型 id 以 API 返回为准；官方宣传名可在 <code>config.modelLabels</code> 里映射为显示名（请求仍用 API id）。</div>
+     ```
+
 ## 自定义模型（WebUI 添加后落盘的结构）
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/src/config.js

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { PROVIDERS, modelPreset, providerPreset, DEFAULT_MODEL, DEFAULT_PLANNER_MODEL, DEFAULT_EXECUTOR_MODEL } from './models.js';
+import { PROVIDERS, modelPreset, providerPreset, pickFamilyModel, normalizeModelLabels, DEFAULT_MODEL, DEFAULT_PLANNER_MODEL, DEFAULT_EXECUTOR_MODEL } from './models.js';
 import { setStoredKey, resolveApiKey, maskKey } from './credentials.js';
 import { atomicWriteFileSync } from './atomic-write.js';
 
@@ -87,6 +87,71 @@ export function quarantineCorruptConfig(reason) {
   return dest;
 }
 
+/**
+ * 同步读取 model-cache.json 里某服务商的线上名单（最近一次 `GET /models` 的结果）。
+ * `ensureMinimalConfig` / `loadConfig` 都是同步接口，无法 await 网络请求，用这份缓存
+ * 把「默认模型」对齐到 API 返回的官方名；缓存为空时才用家族代表名兜底并告警。
+ * @param {string} provider
+ * @returns {string[]}
+ */
+function cachedModelNames(provider) {
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(mingdaoHome(), 'model-cache.json'), 'utf8'));
+    const list = j?.[provider]?.models;
+    return Array.isArray(list) ? list.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+let warnedCachedFallback = false;
+function warnCachedFallback(/** @type {string} */ what, /** @type {string} */ rep) {
+  if (warnedCachedFallback) return;
+  warnedCachedFallback = true;
+  console.warn(`[MingDao] ⚠ ${what} 没有可用的 API 官方名缓存：暂用内置家族代表名 ${rep}（兜底，模型名可能不是最新的；连上 API 后会自动刷新）。`);
+}
+
+/**
+ * v0.6.19（§3.67）：把配置里的**缺省**模型补成 API 名单里的官方名。
+ * 只补缺省值，绝不覆盖用户显式写下的模型名/路由（用户意图优先）。
+ * @param {any} cfg
+ */
+function applyCachedModelDefaults(/** @type {any} */ cfg) {
+  if (!cfg || typeof cfg !== 'object') return cfg;
+  const provider = String(cfg.provider || 'deepseek');
+  const cached = cachedModelNames(provider);
+  if (!cfg.model) {
+    const m = pickFamilyModel(cached, 'flash');
+    if (m) cfg.model = m;
+  }
+  if (cfg.routing && cfg.routing.enabled) {
+    if (!cfg.routing.planner) {
+      const p = pickFamilyModel(cached, 'pro');
+      cfg.routing.planner = p || DEFAULT_PLANNER_MODEL;
+      if (!p) warnCachedFallback('routing.planner', DEFAULT_PLANNER_MODEL);
+    }
+    if (!cfg.routing.executor) {
+      const e = pickFamilyModel(cached, 'flash');
+      cfg.routing.executor = e || DEFAULT_EXECUTOR_MODEL;
+      if (!e) warnCachedFallback('routing.executor', DEFAULT_EXECUTOR_MODEL);
+    }
+  }
+  return cfg;
+}
+
+/**
+ * 校验显示别名（v0.6.20 §3.69）：`config.modelLabels` 只影响界面显示，**不参与任何出网请求**。
+ * 非法项忽略并 warn（不阻断启动）；非对象/空值也在 normalizeModelLabels 里统一处理。
+ * 返回的是同一个对象（就地归一化），不新建配置副本。
+ * @param {any} cfg
+ */
+function applyModelLabels(/** @type {any} */ cfg) {
+  if (cfg && typeof cfg === 'object' && Object.prototype.hasOwnProperty.call(cfg, 'modelLabels')) {
+    cfg.modelLabels = normalizeModelLabels(cfg.modelLabels);
+  }
+  return cfg;
+}
+
 /** 读取配置对象（不存在/损坏返回 null）；返回值为用户可编辑的任意 JSON 配置，类型不定
  *
  * 注意（v0.6.3 / H-7）：null **同时**表示「不存在」与「读不出来」。凡是要**写**配置的调用点，
@@ -94,7 +159,7 @@ export function quarantineCorruptConfig(reason) {
  * @returns {any} */
 export function loadConfig() {
   const r = readConfigStrict();
-  return r.ok ? r.data : null;
+  return r.ok ? applyModelLabels(applyCachedModelDefaults(r.data)) : null;
 }
 
 /**
@@ -121,12 +186,16 @@ export function loadConfigForWrite(why = '某个写配置的命令') {
  * 不再要求先去终端跑 mingdao init）。CLI 的 mingdao init 向导不受影响。 */
 export function ensureMinimalConfig() {
   const strict = readConfigStrict();
-  if (strict.ok && strict.data) return strict.data;
+  if (strict.ok && strict.data) return applyModelLabels(strict.data);
   // v0.6.3（H-7）：存在但读不出来 → 先备份再写，绝不让"首启自动建配置"吃掉用户配置
   if (strict.exists && !strict.ok) quarantineCorruptConfig(strict.error || '未知原因');
   ensureHome();
   const pp = PROVIDERS['deepseek'] || Object.values(PROVIDERS)[0];
-  const model = modelPreset(DEFAULT_MODEL) ? DEFAULT_MODEL : pp.models[0];
+  // v0.6.19（§3.67）：首选最近一次 API 名单里的 flash 官方名；没有缓存才用家族代表名。
+  // （首次运行还没填 Key，API 拉不到，此时代表名就是合理的兜底，后续拉到官方名会自动替换。）
+  const officialFlash = pickFamilyModel(cachedModelNames('deepseek'), 'flash');
+  const model = officialFlash || (modelPreset(DEFAULT_MODEL) ? DEFAULT_MODEL : pp.models[0]);
+  if (!officialFlash) warnCachedFallback('默认模型', model);
   const cfg = {
     provider: 'deepseek',
     model,
@@ -212,25 +281,28 @@ export async function runWizard(io) {
   if (models) io.print(`✓ API Key 验证通过：该服务商线上可用模型 ${models.length} 个。`);
   else if (verifyError) io.print('（已跳过验证，稍后可在 WebUI 设置面板「刷新模型」处再次校验）');
 
-  // ③ 选择模型（允许暂时跳过——不写 config.model，进入后默认用该服务商首个模型，/model 可随时换）
+  // ③ 选择模型（允许暂时跳过——跳过时默认用 **API 名单里的 flash 官方名**，/model 可随时换）
   let model = null;
   if (provider === 'custom') {
     const m = await io.ask('③ 模型名（可留空跳过，稍后 /model 再选）：');
     model = m.trim() || null;
   } else {
-    const options = [{ value: '__skip__', label: '暂时跳过（稍后 /model 再选）' }];
+    const options = [{ value: '__skip__', label: '暂时跳过（用 API 返回的官方默认名，/model 可换）' }];
     for (const m of models || pp.models) {
       const preset = modelPreset(m);
-      options.push({ value: m, label: preset ? `${m} — ${preset.label}` : m });
+      options.push({ value: m, label: preset ? `${m} — ${preset.label}` : `${m}（能力未知（新版本），仍可选用）` });
     }
     options.push({ value: '__custom__', label: '自定义模型名（手动输入）' });
     const choice = await io.choose('③ 选择模型：', options);
-    if (choice === '__skip__') model = null;
+    if (choice === '__skip__') model = pickFamilyModel(models || [], 'flash');
     else if (choice === '__custom__') model = (await io.ask('模型名：')).trim() || null;
     else model = choice;
   }
+  const chosenPreset = model ? modelPreset(model) : null;
   if (model) io.print(`✓ 已选择模型：${model}`);
   else io.print('✓ 已跳过模型选择：进入后自动使用该服务商默认模型，输入 /model 可随时切换。');
+  if (chosenPreset?.capabilityUnknown) io.print('⚠ 该模型是 API 返回的新版本：能力未知（按家族规格保守估算，仍可选用）。');
+  if (!models && provider !== 'custom') io.print('（未取得 API 模型名单：模型名用内置家族代表名——离线兜底，模型名可能不是最新的）');
 
   const perm = await io.choose('权限模式（写文件 / 执行命令时）：', [
     { value: 'ask', label: 'ask — 每次询问（推荐，最安全）' },
@@ -245,12 +317,19 @@ export async function runWizard(io) {
   ]);
 
   let routing = null;
-  if (modelPreset(DEFAULT_PLANNER_MODEL) && modelPreset(DEFAULT_EXECUTOR_MODEL)) {
+  // v0.6.19（§3.67）：路由默认名同样以 API 名单里的官方名为准（planner→pro 家族、executor→flash 家族）；
+  // 名单不可用才退回家族代表名，并在下面明确提示「兜底」。
+  const plannerDefault = pickFamilyModel(models || [], 'pro') || DEFAULT_PLANNER_MODEL;
+  const executorDefault = pickFamilyModel(models || [], 'flash') || DEFAULT_EXECUTOR_MODEL;
+  if (modelPreset(plannerDefault) && modelPreset(executorDefault)) {
     const routeChoice = await io.choose('自动模型路由（规划类任务→pro，执行类→flash）：', [
       { value: 'on', label: 'on — 开启（省钱又高效，推荐）' },
       { value: 'off', label: 'off — 关闭（始终用当前模型）' },
     ]);
-    if (routeChoice === 'on') routing = { enabled: true, planner: DEFAULT_PLANNER_MODEL, executor: DEFAULT_EXECUTOR_MODEL };
+    if (routeChoice === 'on') {
+      routing = { enabled: true, planner: plannerDefault, executor: executorDefault };
+      if (!models) io.print(`⚠ 路由默认名走兜底（未取得 API 名单）：planner=${plannerDefault} / executor=${executorDefault}——模型名可能不是最新的。`);
+    }
   }
 
   const preset = model ? modelPreset(model) : null;
@@ -274,7 +353,7 @@ export async function runWizard(io) {
     `服务商  ${provider}（${pp.label}）`,
     model ? `模型    ${model}` : '模型    （暂未选择，进入后 /model 随时切换）',
     `权限    ${perm} · 沙箱  ${sandbox}`,
-    `路由    ${routing ? '自动（pro⇄flash）' : '关闭'}`,
+    `路由    ${routing ? `自动（${routing.planner} ⇄ ${routing.executor}）` : '关闭'}`,
     `密钥    ${apiKey ? '凭证库 ' + maskKey(apiKey) : '环境变量 ' + (pp.envKey || 'MINGDAO_API_KEY')}`,
     `保存于  ${configPath()}`,
   ]);

package/src/cost-guard.js

@@ -125,7 +125,7 @@ export function checkCostGuard(modelName) {
     // P0-4（v0.4.5）：无价格数据时护栏无法累计——显式告警而非静默放行（绝不当「没花钱」）
     return {
       blocked: false,
-      message: '⚠ 费用护栏：当前模型无价格数据，今日费用无法累计、dailyLimitYuan 不生效——请在 config.pricing.overrides 为模型补充定价，或改用有价的 DeepSeek 模型（deepseek-v4-pro/flash）。',
+      message: '⚠ 费用护栏：当前模型无价格数据，今日费用无法累计、dailyLimitYuan 不生效——请在 config.pricing.overrides 为模型补充定价，或改用有价的 DeepSeek pro / flash 家族模型（具体名称以 API 返回的官方名为准）。',
     };
   }
   if (st.overLimit && st.action === 'block') {

package/src/help.js

@@ -56,7 +56,7 @@ export function helpLines({ variant = 'cli', home = '' } = {}) {
     ['  mingdao --continue         继续最近一次会话', null],
     ['  mingdao --journal          新会话带上最近会话日志（默认不注入，新会话全新开始）', null],
     ['  mingdao --resume           从会话列表选择恢复', null],
-    ['  mingdao --model <模型名>   指定模型，例如 deepseek-v4-pro', null],
+    ['  mingdao --model <模型名>   指定模型（pro / flash 家族；具体名称以 API 返回的官方名为准）', null],
     ...cliOnly,
     ['  mingdao init               初始化配置向导', null],
     ['  mingdao update [--check]   一键自更新（git 安装形态；--check 只对比版本）', null],

package/src/model-discovery.js

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import { safeFetchText } from './safe-fetch.js';
 import path from 'node:path';
 import { mingdaoHome, ensureHome } from './config.js';
-import { PROVIDERS, MODELS } from './models.js';
+import { PROVIDERS, modelPreset, familyRepresentative, pickFamilyModel, modelCapabilityUnknown, normalizeModelLabels, modelDisplayLabel } from './models.js';
 import { getStoredKey } from './credentials.js';
 import { isLocalBaseUrl, resolveModelCaps } from './model-caps.js';
 import { resolveProviderConfig, acquireLocalSlot, localQueueTimeoutMs } from './providers/index.js';
@@ -1005,6 +1005,128 @@ export function isDiscoveredModel(/** @type {any} */ name, /** @type {string} */
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// v0.6.19（§3.67）：**默认模型 = API 实时返回的官方名**
+//
+// 以前 DEFAULT_MODEL / DEFAULT_PLANNER_MODEL 是写死的具体版本，厂家升版本就要改代码；
+// 现在默认值在运行时解析：
+//   ① 用户显式配置（config.routing.planner/executor、config.model）优先——不覆盖用户意图；
+//   ② 否则从该服务商当前 `/models` 名单里按**家族模式**挑（planner→pro、executor→flash）；
+//   ③ 名单里没有该家族 / API 不可达时，才退回家族代表名，并明确提示「兜底」。
+// 提示会出现在 console.warn（服务端日志）与 /api/models 的 note 字段（界面 banner 可读）。
+// ---------------------------------------------------------------------------
+
+/** 离线兜底提示（测试与界面共用同一句，避免两处漂移）。 */
+export const OFFLINE_MODEL_NOTE = '离线兜底：模型名可能不是最新的（API 不可达，已使用内置家族代表名）';
+
+/** 角色 → 家族（planner 用 pro，executor/model 用 flash）。 */
+export const MODEL_ROLE_FAMILY = /** @type {Record<string, string>} */ ({ planner: 'pro', executor: 'flash', model: 'flash' });
+
+/** 兜底告警只打一次/角色，避免每轮刷屏（但**不能不打**，否则用户不知道用的是旧名）。 */
+const warnedFallback = new Set();
+
+function warnFallback(/** @type {string} */ role, /** @type {string} */ reason, /** @type {string} */ model) {
+  const key = `${role}:${reason}`;
+  if (warnedFallback.has(key)) return;
+  warnedFallback.add(key);
+  console.warn(`[MingDao] ⚠ ${role} 默认模型走兜底（${reason}）：使用内置家族代表名 ${model}——模型名可能不是最新的，请检查 API 连通性/密钥。`);
+}
+
+/**
+ * 把模型列表里「离线兜底 / 能力未知」的条目标成一句提示，供 /api/models 与界面 banner 使用。
+ * @param {any} models
+ * @returns {string|null}
+ */
+export function modelsCatalogNote(/** @type {any} */ models) {
+  const list = Array.isArray(models) ? models : [];
+  if (list.some((m) => m && m.offlineFallback === true)) return OFFLINE_MODEL_NOTE;
+  const unknown = list.filter((m) => m && m.capabilityUnknown === true).length;
+  if (unknown) return `${unknown} 个模型是 API 返回的新版本：能力未知（按家族规格保守估算，仍可选用）`;
+  return null;
+}
+
+/**
+ * 解析某个角色的默认模型（**以 API 实时返回的官方名为准**）。
+ * @param {any} cfg
+ * @param {'planner'|'executor'|'model'} [role]
+ * @param {{force?: boolean}} [opts]
+ * @returns {Promise<{model: string, role: string, family: string, source: 'config'|'api'|'fallback', official: boolean, fallback: boolean, offline: boolean, note: string|null}>}
+ */
+export async function resolveDefaultModel(/** @type {any} */ cfg, /** @type {any} */ role = 'executor', { force = false } = {}) {
+  const r = String(role || 'executor');
+  const family = MODEL_ROLE_FAMILY[r] || 'flash';
+  const explicit = r === 'planner' ? cfg?.routing?.planner : r === 'executor' ? cfg?.routing?.executor : cfg?.model;
+  if (explicit) {
+    return {
+      model: String(explicit),
+      role: r,
+      family,
+      source: 'config',
+      official: false,
+      fallback: false,
+      offline: false,
+      note: null,
+    };
+  }
+  const provider = String(cfg?.provider || 'deepseek');
+  // 既有策略（v0.6.13）：**自定义端点不主动探测 `GET /models`**——真实世界里很多自定义网关
+  // 只实现 chat，`/models` 可能返回空 body/非 JSON（e2e-web 的 mock 就会因此 JSON.parse 崩）。
+  // 自定义端点/未内置的服务商还没有可枚举的名单元数据，直接走家族代表名兜底（不发任何请求）。
+  if (provider === 'custom' || !/** @type {any} */ (PROVIDERS)[provider]) {
+    const rep = familyRepresentative(family);
+    return {
+      model: rep,
+      role: r,
+      family,
+      source: 'fallback',
+      official: false,
+      fallback: true,
+      offline: false,
+      note: `自定义端点/未内置服务商不主动探测 /models，使用内置家族代表名 ${rep}（可用 config.routing.* 显式指定端点自己的模型名）`,
+    };
+  }
+  let fetched = /** @type {any} */ ({ error: '该服务商未设置 API Key' });
+  try {
+    fetched = await fetchProviderModels(cfg, provider, { force });
+  } catch (/** @type {any} */ e) {
+    fetched = { error: String(e?.message || e) };
+  }
+  if (Array.isArray(fetched?.models) && fetched.models.length) {
+    const picked = pickFamilyModel(fetched.models, family);
+    if (picked) {
+      return {
+        model: picked,
+        role: r,
+        family,
+        source: 'api',
+        official: true,
+        fallback: false,
+        offline: false,
+        note: null,
+      };
+    }
+    const rep = familyRepresentative(family);
+    const note = `兜底：API 列表里没有 ${family} 家族模型，改用内置家族代表名 ${rep}`;
+    warnFallback(r, 'API 列表无匹配家族', rep);
+    return { model: rep, role: r, family, source: 'fallback', official: false, fallback: true, offline: false, note };
+  }
+  const rep = familyRepresentative(family);
+  warnFallback(r, String(fetched?.error || '未知原因'), rep);
+  return { model: rep, role: r, family, source: 'fallback', official: false, fallback: true, offline: true, note: OFFLINE_MODEL_NOTE };
+}
+
+/**
+ * 一次解析 planner + executor 的默认值（WebUI 开启自动路由时调用）。
+ * @param {any} cfg
+ * @param {{force?: boolean}} [opts]
+ */
+export async function resolveRoutingDefaults(/** @type {any} */ cfg, { force = false } = {}) {
+  const [planner, executor] = await Promise.all([resolveDefaultModel(cfg, 'planner', { force }), resolveDefaultModel(cfg, 'executor', { force })]);
+  const fellBack = [planner, executor].filter((x) => x.fallback);
+  const note = planner.offline || executor.offline ? OFFLINE_MODEL_NOTE : fellBack.length ? fellBack.map((x) => x.note).filter(Boolean).join('；') : null;
+  return { planner, executor, offline: planner.offline || executor.offline, note };
+}
+
 // 合并可用模型列表：只含已设置 Key 的服务商；动态名单优先、预设回退；自定义模型恒在。
 //
 // v0.6.13（B）：**每个条目都要能看出"来自哪个服务商/端点"**。此前自定义条目只有
@@ -1015,25 +1137,60 @@ export function isDiscoveredModel(/** @type {any} */ name, /** @type {string} */
 export async function availableModels(/** @type {any} */ cfg, /** @type {any} */ currentModel) {
   const out = [];
   const seen = new Set();
+  // v0.6.20（§3.69）：显示别名只用于界面。官方 /models 条目的 `label` 是**显示名**
+  // （`config.modelLabels[id]`，没有映射就回退 id），`id`/`name` 才是 API 实际 id。
+  // 原来的能力/来源说明保留到 `detail` 字段（下拉 title / 提示可读）。
+  // 出网请求的 model 字段只从 config.model / state.modelName 取，**永不**从 label 取。
+  const modelLabels = normalizeModelLabels(cfg?.modelLabels, { warn: false });
   for (const [pname, pp] of Object.entries(PROVIDERS)) {
     if (pname === 'custom') continue;
     if (!providerHasKey(pname)) continue;
     const dynamic = await fetchProviderModels(cfg, pname);
+    // §3.67：拉取失败时用内置名单，但必须**明确标成离线兜底**——
+    // 否则界面会把这些可能过期的名字当成「官方实时名单」展示。
+    const offline = Boolean(dynamic?.error) && !dynamic?.models?.length;
     const names = dynamic.models?.length ? dynamic.models : pp.models || [];
     for (const n of names) {
       if (seen.has(n)) continue;
       seen.add(n);
-      const preset = /** @type {any} */ (MODELS)[n];
+      // 家族模式优先：`DeepSeek-V4.1-Flash 1017` 这类 API 官方名不在精确表里，但能力照样可解析。
+      const preset = modelPreset(n);
+      const capabilityUnknown = modelCapabilityUnknown(n);
+      const label = offline
+        ? `${n} — ${preset ? preset.label : '能力未知（新版本/非家族）'}（离线兜底，模型名可能不是最新的）`
+        : preset
+          ? `${n} — ${preset.label}`
+          : `${n}（线上最新；能力未知（新版本），仍可选用）`;
+      // 显示名与 API id 分离：label 可以来自 config.modelLabels，请求仍用 name/id。
+      const displayLabel = modelDisplayLabel(modelLabels, n);
       out.push({
         name: n,
-        label: preset ? `${n} — ${preset.label}` : `${n}（线上最新）`,
+        // v0.6.20（§3.69）：显式保留 API 实际 id（前端 title 用「API id: <id>」随时对上 API）
+        id: n,
+        // label 是**给人看的显示名**；没有配 modelLabels 时就是 id 本身。
+        label: displayLabel,
+        // 原 label 的能力/来源说明（离线兜底、能力未知、来源标注）挪到这里，信息不丢。
+        detail: label,
+        // 只有"映射生效、显示名 != id"时才标来源，避免把自定义条目的组合展示名也误标成 config。
+        ...(displayLabel !== n ? { labelSource: 'config' } : {}),
         provider: pname,
         providerLabel: pp.label,
-        dynamic: !(/** @type {any} */ (MODELS))[n],
+        // dynamic 的既有语义（前端/旧测试读它）：不在任何内置模式表里。家族命中不等于 dynamic。
+        dynamic: !preset,
         // 来源标注（B）：内置预设 vs 服务商线上名单——两者都是"该服务商自己的模型"
         official: Boolean(preset),
+        family: preset?.family || null,
+        capabilityUnknown,
+        offlineFallback: offline,
+        // 这一行保持原样：既有变异批 batch28 以它作锚点；离线来源在下一行覆盖。
         source: preset ? 'preset' : 'discovered',
-        sourceLabel: preset ? `内置预设 · ${pp.label}` : `线上名单 · ${pp.label}`,
+        ...(offline ? { source: 'offline' } : {}),
+        sourceLabel: offline
+          ? `离线兜底 · ${pp.label}`
+          : preset
+            ? `线上名单 · ${pp.label}（家族模式匹配）`
+            : `线上名单 · ${pp.label}`,
+        note: offline ? OFFLINE_MODEL_NOTE : capabilityUnknown ? '能力未知（新版本）：按家族规格保守估算，仍可选用' : undefined,
       });
     }
   }
@@ -1041,10 +1198,15 @@ export async function availableModels(/** @type {any} */ cfg, /** @type {any} */
     if (seen.has(cmName)) continue;
     seen.add(cmName);
     const src = customSourceOf(cfg, cmName);
+    // 自定义条目保留既有组合展示名（来源必须在展示名里，且 test/smoke §139 以此为准）；
+    // modelLabels 只映射服务商 /models 的官方 id，不改变自定义条目。
+    const customLabel = `${cmName} — ${cm.label || '自定义模型'}（${src.sourceLabel}）`;
     out.push({
       name: cmName,
+      id: cmName,
       // 展示名里也带上来源（不只是 title/tooltip）：下拉标题行、设置面板、日志三处一致
-      label: `${cmName} — ${cm.label || '自定义模型'}（${src.sourceLabel}）`,
+      label: customLabel,
+      detail: customLabel,
       provider: 'custom',
       providerLabel: src.providerLabel,
       custom: true,
@@ -1058,14 +1220,19 @@ export async function availableModels(/** @type {any} */ cfg, /** @type {any} */
     });
   }
   if (currentModel && !out.some((m) => m.name === currentModel)) {
+    const currentLabel = `${currentModel}（当前配置）`;
     out.unshift({
       name: currentModel,
-      label: `${currentModel}（当前配置）`,
+      id: currentModel,
+      label: currentLabel,
+      detail: currentLabel,
       provider: 'current',
       providerLabel: '当前',
       official: false,
       source: 'current',
       sourceLabel: '当前配置（不在任何已知名单里）',
+      family: modelPreset(currentModel)?.family || null,
+      capabilityUnknown: modelCapabilityUnknown(currentModel),
       note: '该名称不在任何服务商名单/自定义条目里——只是 config.json 里当前写着的模型名。',
     });
   }