mingdao-harness 0.6.16 → 0.6.17

package/docs/CONFIG.md

@@ -379,6 +379,9 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 `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` 用正则匹配名字，能力（上下文窗口、单次输出上限、工具调用、
@@ -423,6 +426,105 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 - 完全不属于任何家族的线上新模型（例如非 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.16",
+  "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, pickFamilyModel, 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';
 
@@ -139,6 +139,19 @@ function applyCachedModelDefaults(/** @type {any} */ cfg) {
   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 **同时**表示「不存在」与「读不出来」。凡是要**写**配置的调用点，
@@ -146,7 +159,7 @@ function applyCachedModelDefaults(/** @type {any} */ cfg) {
  * @returns {any} */
 export function loadConfig() {
   const r = readConfigStrict();
-  return r.ok ? applyCachedModelDefaults(r.data) : null;
+  return r.ok ? applyModelLabels(applyCachedModelDefaults(r.data)) : null;
 }
 
 /**
@@ -173,7 +186,7 @@ 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();

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, modelPreset, familyRepresentative, pickFamilyModel, modelCapabilityUnknown } 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';
@@ -1137,6 +1137,11 @@ export async function resolveRoutingDefaults(/** @type {any} */ cfg, { force = f
 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;
@@ -1156,9 +1161,18 @@ export async function availableModels(/** @type {any} */ cfg, /** @type {any} */
         : preset
           ? `${n} — ${preset.label}`
           : `${n}（线上最新；能力未知（新版本），仍可选用）`;
+      // 显示名与 API id 分离：label 可以来自 config.modelLabels，请求仍用 name/id。
+      const displayLabel = modelDisplayLabel(modelLabels, n);
       out.push({
         name: n,
-        label,
+        // 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 的既有语义（前端/旧测试读它）：不在任何内置模式表里。家族命中不等于 dynamic。
@@ -1184,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,
@@ -1201,9 +1220,12 @@ 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,

package/src/models.js

@@ -422,6 +422,100 @@ export function modelPreset(/** @type {any} */ name) {
   return /** @type {any} */ (MODELS)[n] || null;
 }
 
+// ---------- 模型显示别名（v0.6.20 §3.69）：只影响界面，绝不参与出网请求 ----------
+//
+// 为什么要有：厂家的「官方宣传名 / 构建名」与 API 实际 id 可能不是一回事。实测（2026-10）：
+//   GET  https://api.deepseek.com/v1/models  → ["deepseek-flash", "deepseek-v4-pro"]
+//   POST chat {model:"deepseek-flash"}       → 200
+//   POST chat {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."}
+// 也就是说宣传名**既不会出现在 /models 里，也不能用于请求**。想让它显示在界面上，只能用
+// 「显示别名」：`config.modelLabels = { "<API id>": "<显示名>" }`，出网 model 字段一律仍是 id。
+//
+// 约束：非法项**忽略并 warn**，绝不抛错/阻断启动（配置写坏一个字不应让整个应用起不来）。
+/** 显示名长度上限（字符）：够放「DeepSeek-V4.1-Flash 1017（官方宣传名）」，又不撑破下拉。 */
+export const MODEL_LABEL_MAX_LENGTH = 80;
+
+/** 已经告警过的非法项（同一进程只提醒一次，避免每次 loadConfig 都刷屏）。 */
+const warnedModelLabels = new Set();
+
+/** @param {string} detail */
+function warnModelLabel(detail) {
+  if (warnedModelLabels.has(detail)) return;
+  warnedModelLabels.add(detail);
+  console.warn(
+    `[MingDao] ⚠ config.modelLabels 已忽略非法项：${detail}（显示别名只影响界面，不影响请求；非法项不会阻断启动）`
+  );
+}
+
+/**
+ * 校验并归一化 `config.modelLabels`。
+ *
+ * 规则：
+ *  - key（API 实际 id）必须是非空字符串（去空白后）；
+ *  - value（显示名）必须是字符串、去空白后非空、长度 ≤ maxLength；
+ *  - 非法项**忽略并 warn**（同一项只提醒一次），不抛错、不阻断启动。
+ *
+ * 注意：这里只做「显示名」的清洗，**绝不**把结果写回 `config.model` /
+ * `config.routing.*`，也绝不被拼进请求体的 `model` 字段。
+ *
+ * @param {any} raw 用户配置里的原始值（任意类型都安全）
+ * @param {{maxLength?: number, warn?: boolean}} [opts]
+ * @returns {Record<string, string>} 干净的 `{ "<API id>": "<显示名>" }`
+ */
+export function normalizeModelLabels(raw, { maxLength = MODEL_LABEL_MAX_LENGTH, warn = true } = {}) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  if (raw == null) return out;
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    if (warn) warnModelLabel('modelLabels 必须是对象（形如 { "deepseek-flash": "显示名" }）');
+    return out;
+  }
+  for (const [rawKey, rawValue] of Object.entries(raw)) {
+    const key = String(rawKey).trim();
+    if (!key) {
+      if (warn) warnModelLabel(`键为空（原值 ${JSON.stringify(rawKey)}）`);
+      continue;
+    }
+    // 原型污染防线：JSON.parse 出来的 `__proto__` 是 own property，直接写进普通对象会改原型。
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      if (warn) warnModelLabel(`键名 "${key}" 不安全`);
+      continue;
+    }
+    if (typeof rawValue !== 'string') {
+      if (warn) warnModelLabel(`"${key}" 的显示名必须是字符串（实际是 ${typeof rawValue}）`);
+      continue;
+    }
+    const value = rawValue.trim();
+    if (!value) {
+      if (warn) warnModelLabel(`"${key}" 的显示名为空`);
+      continue;
+    }
+    if (value.length > maxLength) {
+      if (warn) warnModelLabel(`"${key}" 的显示名过长（${value.length} > ${maxLength} 字符）`);
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * 取某个 API id 的显示名：命中 `config.modelLabels` 用别名，否则**回退到 id 本身**。
+ * 只用于展示；出网请求的 `model` 字段一律用 id（见 availableModels 的 id/label 分离）。
+ * @param {any} modelLabels 原始或已归一化的 modelLabels（非法值自动回退 id）
+ * @param {any} id API 实际模型 id
+ * @returns {string}
+ */
+export function modelDisplayLabel(/** @type {any} */ modelLabels, /** @type {any} */ id) {
+  const key = String(id ?? '');
+  if (!key) return key;
+  // 归一化一次（warn=false）：既防 `{id: 123}` 之类原始值漏进界面，又不会在此处重复告警
+  const clean = normalizeModelLabels(modelLabels, { warn: false });
+  return Object.prototype.hasOwnProperty.call(clean, key) ? clean[key] : key;
+}
+
 /** 该名字的能力是否**未经验证**（家族能匹配但版本比已核对规格新，或完全不属于任何家族）。 */
 export function modelCapabilityUnknown(/** @type {any} */ name) {
   const preset = modelPreset(name);