docs: add upgrade guides for the account model catalog and pi-ai discovery

Users of v0.2.1-alpha.2 who saved an account catalog through the Models page editor must move single-model changes into modelOverrides, because a models field now stops llm-deepseek-account at load. pi-ai routes that name a missing credential now list no models.
2026-10-12 14:53:34 +08:00
1 parent 9b77d375e6
commit 0bcacef96e
@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-model-catalog/guide.md
+/:
+  en: 60a8441ae7ea6841
+  zh: 3715b44e11c5131b
+/deepseek-account-models-come-from-the-account-listing:
+  en: 2208c82c24d75a53
+  zh: fa6c53c925aae6f2
+/deepseek-account-models-come-from-the-account-listing/change:
+  en: bf4c84372b8b1316
+  zh: af1623701d19b62e
+/deepseek-account-models-come-from-the-account-listing/migration:
+  en: 7ce26a5a1926b292
+  zh: 35dfc17997834e4d
@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "The DeepSeek account route no longer accepts a models catalog; the account listing supplies its models and modelOverrides adjusts them."
+---
+
+# DeepSeek account models come from the account listing
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `deepseek-account` route previously read its model catalog from the `models` field of the `llm-deepseek-account` entry, which the Models page could edit for the account. The route now lists models from the account's `GET /models` endpoint, serves the built-in catalog until a listing loads, and accepts per-model adjustments only through `modelOverrides`; the Models page no longer offers an editor for this route. A listed model can require a newer DeepSeek Harness; such a model is hidden, and a request for it fails with `CLIENT_UPGRADE_REQUIRED`. A `models` field left in the entry, including one saved by the earlier Models page editor, stops the plugin at load with `llm-deepseek-account: models is no longer configurable`, and Desktop and Web show no account models until the field is removed. Signed-in accounts without a saved catalog need no action.
+
+## Migration
+
+1. Open `$DSH_HOME/profiles/<profile>/cordis.patch.yml` and find the entry with `id: llm-deepseek-account`.
+2. Delete its `models` field. For each model whose fields you changed, move only the changed fields under `modelOverrides.<model id>`:
+
+   ```yaml
+   - id: llm-deepseek-account
+     config:
+       modelOverrides:
+         deepseek-flash:
+           maxTokens: 131072
+   ```
+
+3. Restart DeepSeek Harness, sign in to the DeepSeek account, and confirm that the model selector lists the account models and the Models page shows the account as signed in. An override the listed model rejects, or one that names an unknown model, appears as the account's diagnostic on the Models page.
@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "DeepSeek 账号路由不再接受 models 目录；模型由账号的模型列表提供，单个模型通过 modelOverrides 调整。"
+---
+
+# DeepSeek 账号模型改由账号的模型列表提供
+
+[English](guide.md) | 中文
+
+## 变更
+
+`deepseek-account` 路由此前从 `llm-deepseek-account` 条目的 `models` 字段读取模型目录，模型页可以为账号编辑这份目录。现在该路由从账号的 `GET /models` 端点列出模型，在列表加载之前使用内置目录，单个模型只能通过 `modelOverrides` 调整；模型页不再为该路由提供编辑器。列表中的模型可以要求更新版本的 DeepSeek Harness，这样的模型会被隐藏，请求它时以 `CLIENT_UPGRADE_REQUIRED` 失败。条目中遗留的 `models` 字段，包括早先模型页编辑器保存的，会让插件在加载时报 `llm-deepseek-account: models is no longer configurable` 并停止，删除该字段之前桌面端和 Web 都不显示账号模型。没有保存过账号目录的已登录账号无需操作。
+
+## 迁移
+
+1. 打开 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`，找到 `id: llm-deepseek-account` 的条目。
+2. 删除其中的 `models` 字段。对改过字段的模型，只把改过的字段移到 `modelOverrides.<模型 id>` 下：
+
+   ```yaml
+   - id: llm-deepseek-account
+     config:
+       modelOverrides:
+         deepseek-flash:
+           maxTokens: 131072
+   ```
+
+3. 重启 DeepSeek Harness 并登录 DeepSeek 账号，确认模型选择器列出账号模型、模型页显示账号已登录。被列出的模型拒绝的覆盖，或指向未知模型的覆盖，会作为该账号的诊断信息显示在模型页上。
@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-alpha.2/pi-ai-model-discovery/guide.md
+/:
+  en: 40afcce4dbdcb337
+  zh: 33c5647441bd1dcb
+/pi-ai-model-visibility-without-a-credential:
+  en: 1bc74c0ce4085c3c
+  zh: 0a2be91b04c069c8
+/pi-ai-model-visibility-without-a-credential/change:
+  en: f92005c2a3d4645c
+  zh: 5bfb1685cdf3437c
+/pi-ai-model-visibility-without-a-credential/migration:
+  en: 26d72c82e5c60031
+  zh: 4b582d3e4d022dd8
@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "pi-ai routes that name a credential hide their models until the credential is configured."
+---
+
+# pi-ai model visibility without a credential
+
+English | [中文](guide.zh.md)
+
+## Change
+
+A pi-ai route that names a credential through `apiKeyEnv` previously listed its configured models while that credential was missing, and requests then failed with `MISSING_CREDENTIAL`. Model discovery now returns an empty catalog for such a route until the credential resolves, so Desktop and Web hide its group. Other credential errors, such as a malformed key, still fail model discovery. Routes that use the provider's native authentication or name no credential keep their configured catalog. A saved or default selection absent from the catalog displays “Select model” without changing the stored selection.
+
+## Migration
+
+1. To use such a route, configure its key in Settings → Models, or supply the reference its `apiKeyEnv` names through the launch environment.
+2. Reopen the model selector and confirm that the route's group appears. Custom model discovery consumers must handle an empty catalog before the credential is configured; a listed catalog does not mean that the remote API accepts the key.
@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "指定了凭据的 pi-ai 路由在凭据配置之前隐藏其模型。"
+---
+
+# pi-ai 路由缺少凭据时的模型可见性
+
+[English](guide.md) | 中文
+
+## 变更
+
+通过 `apiKeyEnv` 指定凭据的 pi-ai 路由，此前在凭据缺失时也会列出配置的模型，请求随后以 `MISSING_CREDENTIAL` 失败。现在凭据解析到之前，模型发现对这样的路由返回空目录，因此桌面端和 Web 隐藏它的分组。其他凭据错误（例如密钥格式错误）仍会让模型发现失败。使用提供方原生认证或未指定凭据的路由保留配置的目录。已保存或默认的选择不在目录中时，界面显示“请选择模型”，保存的选择保持不变。
+
+## 迁移
+
+1. 要使用这样的路由，请在设置 → 模型中配置密钥，或通过启动环境提供 `apiKeyEnv` 指定的凭据引用。
+2. 重新打开模型选择器，确认该路由的分组出现。自定义模型发现消费者必须处理配置凭据前的空目录；列出目录不代表远端 API 已接受密钥。