dsh-plugin-guide 0.3.42 → 0.4.0

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "DeepSeekAccount.watch 默认不再通知 Platform 身份变化，订阅者必须显式启用。"
----
-
-# 显式订阅账号身份变化
-
-[English](guide.md) | 中文
-
-## 变更
-
-公开方法 `DeepSeekAccount.watch(signal)` 原先会在资料查询首次补齐或改变缓存的 Platform 用户 ID 时发出快照。现在默认仅通知账号状态变化。通过该流刷新 `getPlatformSession()` 的插件必须显式订阅身份变化。凭证替换和登录状态变化仍会通知所有订阅者。
-
-## 迁移
-
-1. 在刷新 Platform 会话或同步其用户 ID 的插件中查找 `deepseekAccount.watch(signal)` 调用。
-2. 将这些调用改为 `deepseekAccount.watch(signal, true)`。只需要登录和凭证状态的账号界面订阅保持不变。
-3. 确认 `getProfile()` 返回 ready 结果且用户 ID 首次出现或变化时，订阅被唤醒并重新读取 `getPlatformSession()`。重复读取同一 ID 不会再次发出身份通知。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-model-catalog/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-model-catalog/guide.md

@@ -1,27 +0,0 @@
----
-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.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-model-catalog/guide.zh.md

@@ -1,27 +0,0 @@
----
-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 账号，确认模型选择器列出账号模型、模型页显示账号已登录。被列出的模型拒绝的覆盖，或指向未知模型的覆盖，会作为该账号的诊断信息显示在模型页上。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/desktop-font-size-shortcuts/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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/desktop-font-size-shortcuts/guide.md
-/:
-  en: 0863e2ef201c6e98
-  zh: e7042cab4852e9c8
-/desktop-font-size-shortcuts-reserve-custom-key-combinations:
-  en: 7c82d9faadaec1e0
-  zh: 91d60eb7a660e1b3
-/desktop-font-size-shortcuts-reserve-custom-key-combinations/change:
-  en: cb025eb9ae5e18ae
-  zh: 094ec608c1ce4dad
-/desktop-font-size-shortcuts-reserve-custom-key-combinations/migration:
-  en: bc66077939ee3df3
-  zh: f8460bf5ec20ac58

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/desktop-font-size-shortcuts/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Desktop font-size shortcuts reserve key combinations previously available to custom shortcuts."
----
-
-# Desktop font-size shortcuts reserve custom key combinations
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Desktop reserves `Cmd`/`Ctrl` + `=` (including `Shift` + `=` for `+`) and `Cmd`/`Ctrl` + `-` to adjust text, code, and terminal font sizes together. Use `Cmd` on macOS and `Ctrl` on Windows and Linux. Custom bindings using these combinations, including overlapping two-key chords, remain saved but no longer execute. Web shortcut behavior is unchanged.
-
-## Migration
-
-1. Open Settings → General → Keyboard shortcuts in Desktop and find any custom binding marked as conflicting with a font-size shortcut.
-2. Record a nonconflicting combination for that action, or choose **Remove** to disable its keyboard shortcut. **Restore default** is available when the action's default does not conflict.
-3. Try the reassigned action, then press `Cmd`/`Ctrl` + `=` and `Cmd`/`Ctrl` + `-`. Confirm that all three font sizes change in Settings and remain saved after reopening Desktop.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/desktop-font-size-shortcuts/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "桌面端字号快捷键占用了原先可用于自定义快捷键的组合键。"
----
-
-# 桌面端字号快捷键占用部分自定义组合键
-
-[English](guide.md) | 中文
-
-## 变更
-
-桌面端保留 `Cmd`/`Ctrl` + `=`（包括输入 `+` 的 `Shift` + `=`）和 `Cmd`/`Ctrl` + `-`，用于一起调整正文、代码和终端字号。macOS 使用 `Cmd`，Windows 和 Linux 使用 `Ctrl`。使用这些组合键的自定义绑定，包括与其重叠的双键序列，仍会保存，但不再执行。Web 端快捷键行为不变。
-
-## 迁移
-
-1. 在桌面端打开「设置 → 通用 → 键盘快捷键」，找到标记为与字号快捷键冲突的自定义绑定。
-2. 为该操作录制不冲突的组合键，或选择「移除」禁用其快捷键。操作的默认快捷键不冲突时，也可以选择「恢复默认」。
-3. 尝试重新绑定的操作，再按 `Cmd`/`Ctrl` + `=` 和 `Cmd`/`Ctrl` + `-`。确认设置中的三组字号一起变化，并在重新打开桌面端后仍保留。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/from-default-profile-replaces-target/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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/from-default-profile-replaces-target/guide.md
-/:
-  en: 17654c5360fcf3d1
-  zh: 03277764a031a4e7
-/from-default-profile-replaces-an-existing-profile:
-  en: 8290bb3fe4ba89bc
-  zh: b653e97a607c8897
-/from-default-profile-replaces-an-existing-profile/change:
-  en: 0a8e90115d24ce6d
-  zh: fdc51cffdaf85d53
-/from-default-profile-replaces-an-existing-profile/migration:
-  en: 34ffdb02d05f4489
-  zh: 51663f79fe7f94bc

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/from-default-profile-replaces-target/guide.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "`--from-default-profile` now replaces an existing custom profile instead of refusing it."
----
-
-# `--from-default-profile` replaces an existing profile
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`dsh --profile <name> --from-default-profile <template>` used to fail with `profile "<name>" already exists` when the target profile existed, and refused a residual target directory. It now replaces the target directory with a fresh copy of the template every time, then boots it or, with a config-dump flag, prints the composition. The previous directory is deleted, including its `package.json` dependencies, installed `node_modules`, and `cordis.patch.yml`. Shipped profile names, in any letter case, are still rejected as targets.
-
-This affects anyone who repeats the command, such as `dsh rescue --from-default-profile web`, in scripts or shortcuts and expects later runs to keep the profile's plugins or patch.
-
-## Migration
-
-1. To boot an existing profile without resetting it, drop the option: run `dsh rescue` instead of `dsh rescue --from-default-profile web`.
-2. To keep local changes across a reset, copy `$DSH_HOME/profiles/<name>/cordis.patch.yml` before running the command, then reinstall the profile's plugins with `dsh plugin --profile <name> add <package>` and restore the patch.
-3. Confirm the migration: after `dsh rescue --from-default-profile web --help`, `$DSH_HOME/profiles/rescue/package.json` lists no dependencies.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/from-default-profile-replaces-target/guide.zh.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "`--from-default-profile` 现在会替换已存在的自定义 profile，而不是拒绝执行。"
----
-
-# `--from-default-profile` 会替换已存在的 profile
-
-[English](guide.md) | 中文
-
-## 变更
-
-此前目标 profile 已存在时，`dsh --profile <name> --from-default-profile <template>` 会以 `profile "<name>" already exists` 失败，残留的目标目录也会被拒绝。现在每次执行都会用模板的全新副本替换目标目录，然后启动它；带配置 dump flag 时则打印组合结果。原有目录会被删除，包括 `package.json` 中的依赖、已安装的 `node_modules` 和 `cordis.patch.yml`。任何大小写形式的随附 profile 名称仍不能作为目标。
-
-受影响的是在脚本或快捷方式中重复执行该命令（例如 `dsh rescue --from-default-profile web`），并期望后续执行保留该 profile 插件或 patch 的用户。
-
-## 迁移
-
-1. 要在不重置的情况下启动已存在的 profile，去掉该选项：运行 `dsh rescue`，而不是 `dsh rescue --from-default-profile web`。
-2. 要在重置后保留本地修改，先复制 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，执行命令后用 `dsh plugin --profile <name> add <package>` 重新安装该 profile 的插件，再恢复该 patch。
-3. 确认迁移结果：执行 `dsh rescue --from-default-profile web --help` 后，`$DSH_HOME/profiles/rescue/package.json` 中没有任何依赖。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/operator-connect/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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/operator-connect/guide.md
-/:
-  en: 4e3353e294abb4b0
-  zh: 86300d2f509ee4c7
-/select-interaction-participation-for-non-page-clients:
-  en: d1465a2b3240a12f
-  zh: ff9c76166146b2ff
-/select-interaction-participation-for-non-page-clients/change:
-  en: c0c9719880da8939
-  zh: 185d0aa4c2dfbd2f
-/select-interaction-participation-for-non-page-clients/migration:
-  en: c5691e130194dfac
-  zh: efa1a58ebdf97710

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/operator-connect/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Non-page Clients default to no forwarded interactions and use raw streams without browser recovery."
----
-
-# Select interaction participation for non-page clients
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Non-page Connection installations default to `interactions: 'none'`. They do not open `$events`, and `$on()` and the generation-recovery helper `$stream()` are unavailable in that mode. Generated unary and raw stream methods remain usable. Browser authentication, existing browser Cookies, the shared Peer, and recovery behavior are unchanged; browsers need no reauthentication.
-
-## Migration
-
-1. Exchange the launch token at `GET /connect?token=<launch-token>&interactions=none` with manual redirect handling. Keep the returned API Cookie in client-owned storage and use it for HTTP and the lifecycle WebSocket at the returned 302 Location. HTTP need not wait for the socket to open.
-2. For passive streaming, call the generated raw stream method directly rather than `$stream()`. After lifecycle-socket closure or Host restart, perform a new connect before retrying.
-3. If the caller intentionally answers forwarded interactions, request `interactions=answer` and install Connection with that same mode. Confirm passive callers are refused at both event endpoints while the answering caller can subscribe.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/operator-connect/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "非页面 Client 默认不参与转发交互，并使用不带浏览器恢复的原始流。"
----
-
-# 为非页面客户端选择交互参与模式
-
-[English](guide.md) | 中文
-
-## 变更
-
-非页面 Connection 安装默认 `interactions: 'none'`。该模式不打开 `$events`，也不提供 `$on()` 和代际恢复辅助方法 `$stream()`；生成的 unary 和原始流方法仍可使用。浏览器认证、既有 Cookie、共享 Peer 与恢复行为均不变，无需重新认证。
-
-## 迁移
-
-1. 使用手动重定向处理，在 `GET /connect?token=<launch-token>&interactions=none` 交换 launch token。将返回的 API Cookie 放在客户端独立存储中，供 HTTP 和返回的 302 Location 所指的生命周期 WebSocket 使用；HTTP 无需等待 socket 打开。
-2. 被动流调用直接使用生成的原始流方法，不使用 `$stream()`。生命周期连接关闭或 Host 重启后，重试前先重新 connect。
-3. 如果调用方确实要回答转发交互，请请求 `interactions=answer`，并用相同模式安装 Connection。确认被动调用方在两个事件端点被拒绝，而回答型调用方可以订阅。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/pi-ai-azure-provider/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-azure-provider/guide.md
-/:
-  en: 51d5b5b4d2fb1b8a
-  zh: 4dc9af2458a8fcac
-/azure-provider-route-rename:
-  en: 105c73820d057e28
-  zh: 91a7bfc5c282e164
-/azure-provider-route-rename/change:
-  en: d5ce9089d8aa7119
-  zh: f337926f85b01bc1
-/azure-provider-route-rename/migration:
-  en: 8fb23fbb8184fa00
-  zh: 8c44fb293a8dd70a

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/pi-ai-azure-provider/guide.md

@@ -1,19 +0,0 @@
----
-kind: upgrade-guide
-description: "The pi-ai Azure provider route is renamed from azure-openai-responses to azure."
----
-
-# Azure provider route rename
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The installed pi-ai catalog identifies the Azure provider as `azure` instead of `azure-openai-responses`. The `azure` route includes both Responses and Chat Completions models. The Responses API identifier remains `azure-openai-responses`, and the `AZURE_OPENAI_*` environment variables keep their names. Configurations and model selections that use the old provider key no longer resolve the Azure catalog.
-
-## Migration
-
-1. In the `llm-pi-ai` configuration in `$DSH_HOME/profiles/<profile>/cordis.patch.yml` or another supplying layer, rename `config.providers.azure-openai-responses` to `config.providers.azure`. Preserve its existing fields and any `apiKeyEnv` reference.
-2. Use catalog model IDs under `models`; map a custom Azure deployment name with `AZURE_OPENAI_DEPLOYMENT_NAME_MAP`. The mixed catalog cannot infer a protocol for a model ID absent from the catalog. An explicit route-level `api` overrides every model on that route; it does not select the Azure provider.
-3. Update explicit request/default provider selections to `azure`, and reselect an Azure model when continuing an existing Session. Configure the new Azure entry in Settings → Models if its key was stored for the old entry. Do not edit historical Session events.
-4. Confirm that Settings → Models offers `azure` and lists the expected models, then send a short request using the configured deployment.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/pi-ai-azure-provider/guide.zh.md

@@ -1,19 +0,0 @@
----
-kind: upgrade-guide
-description: "pi-ai 的 Azure 提供方路由从 azure-openai-responses 更名为 azure。"
----
-
-# Azure 提供方路由更名
-
-[English](guide.md) | 中文
-
-## 变更
-
-已安装的 pi-ai 目录使用 `azure` 标识 Azure 提供方，替代 `azure-openai-responses`。`azure` 路由同时包含 Responses 和 Chat Completions 模型。Responses API 标识仍为 `azure-openai-responses`，`AZURE_OPENAI_*` 环境变量名称也保持不变。使用旧提供方键的配置和模型选择无法再解析 Azure 目录。
-
-## 迁移
-
-1. 在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 或其他提供配置的层中，找到 `llm-pi-ai` 配置，将 `config.providers.azure-openai-responses` 改为 `config.providers.azure`。保留原有字段及任何 `apiKeyEnv` 引用。
-2. 在 `models` 中使用目录模型 ID；自定义 Azure 部署名称通过 `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` 映射。混合协议目录无法为目录外的模型 ID 推断协议。显式设置路由级 `api` 会覆盖该路由所有模型的协议，并不表示选择 Azure 提供方。
-3. 将显式请求及默认模型配置中的提供方改为 `azure`，继续现有 Session 时重新选择 Azure 模型。若密钥存储在旧条目下，请在“设置 → 模型”中配置新的 Azure 条目。不要修改历史 Session 事件。
-4. 确认“设置 → 模型”提供 `azure` 且列出预期模型，再向所配置的部署发送一条简短请求。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/pi-ai-model-discovery/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/pi-ai-model-discovery/guide.md

@@ -1,17 +0,0 @@
----
-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.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/pi-ai-model-discovery/guide.zh.md

@@ -1,17 +0,0 @@
----
-kind: upgrade-guide
-description: "指定了凭据的 pi-ai 路由在凭据配置之前隐藏其模型。"
----
-
-# pi-ai 路由缺少凭据时的模型可见性
-
-[English](guide.md) | 中文
-
-## 变更
-
-通过 `apiKeyEnv` 指定凭据的 pi-ai 路由，此前在凭据缺失时也会列出配置的模型，请求随后以 `MISSING_CREDENTIAL` 失败。现在凭据解析到之前，模型发现对这样的路由返回空目录，因此桌面端和 Web 隐藏它的分组。其他凭据错误（例如密钥格式错误）仍会让模型发现失败。使用提供方原生认证或未指定凭据的路由保留配置的目录。已保存或默认的选择不在目录中时，界面显示“请选择模型”，保存的选择保持不变。
-
-## 迁移
-
-1. 要使用这样的路由，请在设置 → 模型中配置密钥，或通过启动环境提供 `apiKeyEnv` 指定的凭据引用。
-2. 重新打开模型选择器，确认该路由的分组出现。自定义模型发现消费者必须处理配置凭据前的空目录；列出目录不代表远端 API 已接受密钥。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/plugin-install-over-installed/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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/plugin-install-over-installed/guide.md
-/:
-  en: 036db2d1004f0aa0
-  zh: fb026ec0af7949f6
-/installing-over-an-installed-plugin-package-is-refused-with-hmr:
-  en: a941bcec1d8f3b70
-  zh: ac5ca3517057a52c
-/installing-over-an-installed-plugin-package-is-refused-with-hmr/change:
-  en: e521f46141e8be0a
-  zh: 1d34929d5d90e466
-/installing-over-an-installed-plugin-package-is-refused-with-hmr/migration:
-  en: f72eeb19e689bbee
-  zh: 9ae1f049688edf38

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/plugin-install-over-installed/guide.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "With HMR, installing a package that is already installed fails with already-installed; an upgrade removes the package first."
----
-
-# Installing over an installed plugin package is refused with HMR
-
-English | [中文](guide.zh.md)
-
-## Change
-
-In a profile that runs HMR, which the shipped profiles do, `pluginManager.installBundle(spec)` used to run pnpm over a package the profile already depends on and report `restart-required` while the previous version kept running. It now fails before pnpm runs, with `application: 'failed'` and `error.code: 'already-installed'`, and changes no profile file, when the spec names an installed package: a registry name with or without a version, a local directory, or the git or tarball spec the dependency was saved with. Repeating an installation of the same spec fails the same way instead of reporting `changed: false`.
-
-This affects callers of `installBundle()` through the Host API and the remote client in `@deepseek-ai/dsh-api-remotes/client`, and the agent's `plugin_manager` tool (`install_bundle`). An installed package that cannot be removed, such as a bundle carrying plugin management, can no longer be installed over while HMR runs. The Web page's Update for an Official plugin removes the package and installs the new version itself. Without HMR, installing over an installed package still runs pnpm and reports `restart-required`.
-
-## Migration
-
-1. To install another version or location of an installed package, call `removeBundle(name)` first, then `installBundle(spec)`. For the agent tool, call `remove_bundle`, then `install_bundle`. The removal stops the bundle's plugins and drops its packages' mappings, so the new version is mapped afresh and starts without a restart.
-2. If code switches exhaustively over `ManagementError['code']`, handle the `already-installed` code.
-3. Confirm the migration: installing the package again returns `already-installed`, and after `removeBundle` the same `installBundle` call returns `applied` with the new `version`.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/plugin-install-over-installed/guide.zh.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "启用 HMR 时，安装已安装的包会以 already-installed 失败；升级需要先移除该包。"
----
-
-# 启用 HMR 时拒绝在已安装的插件包上再次安装
-
-[English](guide.md) | 中文
-
-## 变更
-
-在运行 HMR（热模块替换）的 profile 中（随附的 profile 都运行 HMR），`pluginManager.installBundle(spec)` 此前会对 profile 已依赖的包运行 pnpm，并在旧版本继续运行时报告 `restart-required`。现在当 spec 指向已安装的包时，它会在运行 pnpm 之前失败，返回 `application: 'failed'` 和 `error.code: 'already-installed'`，且不修改任何 profile 文件。这里的 spec 包括带或不带版本的注册表包名、本地目录，以及保存依赖时使用的 git 或 tarball spec。重复安装同一个 spec 也会以同样方式失败，不再报告 `changed: false`。
-
-受影响的调用方包括：通过 Host API 调用 `installBundle()` 的代码、`@deepseek-ai/dsh-api-remotes/client` 中的远端客户端，以及 agent 的 `plugin_manager` 工具（`install_bundle`）。启用 HMR 时，不能再在无法移除的已安装包（例如带有插件管理的组合包）上安装。Web 页面上官方插件的“更新”操作会自行移除该包并安装新版本。未启用 HMR 时，在已安装的包上安装仍会运行 pnpm 并报告 `restart-required`。
-
-## 迁移
-
-1. 要安装已安装包的其他版本或其他位置，先调用 `removeBundle(name)`，再调用 `installBundle(spec)`。使用 agent 工具时，先调用 `remove_bundle`，再调用 `install_bundle`。移除操作会停止该 bundle 的插件，并删除其各个包的映射，因此新版本会重新建立映射，无需重启即可启动。
-2. 如果代码对 `ManagementError['code']` 做穷尽 switch，需要处理 `already-installed`。
-3. 确认迁移结果：再次安装该包返回 `already-installed`；执行 `removeBundle` 后，同样的 `installBundle` 调用返回 `applied` 和新的 `version`。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/sdk-minimal-image-compaction/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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/sdk-minimal-image-compaction/guide.md
-/:
-  en: 5fc67054b45f1734
-  zh: 0cb92b2e036dfb67
-/sdk-minimal-image-reading-and-automatic-compaction:
-  en: 1b0161d44c885284
-  zh: 5babee2ad7dc2571
-/sdk-minimal-image-reading-and-automatic-compaction/change:
-  en: 42d90c20c9549611
-  zh: f904303bea2a60a8
-/sdk-minimal-image-reading-and-automatic-compaction/migration:
-  en: e944f28ce8c2ef8d
-  zh: 3bd5fd84a02e5866

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/sdk-minimal-image-compaction/guide.md

@@ -1,32 +0,0 @@
----
-kind: upgrade-guide
-description: "The sdk-minimal default tool roster adds read_image and automatically summarizes older context."
----
-
-# SDK-minimal image reading and automatic compaction
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`sdk-minimal` advertises `read_image` alongside its persistent shell and `working_directory`. Automatic compaction sends an additional model request to summarize older history when context pressure reaches the configured threshold. The complete Session log remains stored as uncompressed JSONL. Images that exceed the route budget are permanently replaced by attachment/path placeholders so the request can retry. SDK prompt text does not execute `/compact`.
-
-Clients that pin tool names, benchmark prompt size, or count model requests must account for these defaults. Image reading requires an adapter route that declares image input. See the [bundle reference](../../../../packages/bundle/sdk-minimal/README.md) for configuration and model effects.
-
-## Migration
-
-1. Accept the new defaults, or place this patch in `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml` to retain the previous default tools and disable automatic compaction:
-
-```yaml
-- id: tool-fs
-  config:
-    read: false
-    readImage: false
-    write: false
-    edit: false
-- id: compaction-basic
-  config:
-    auto: false
-```
-
-2. Launch a fresh SDK runtime. Without additional user plugins, its model requests contain the persistent `bash` or `pwsh` tool and `working_directory`; it sends no automatic summarization requests.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/sdk-minimal-image-compaction/guide.zh.md

@@ -1,32 +0,0 @@
----
-kind: upgrade-guide
-description: "sdk-minimal 默认工具清单新增 read_image，并自动生成较早上下文的摘要。"
----
-
-# SDK-minimal 图片读取与自动压缩
-
-[English](guide.md) | 中文
-
-## 变更
-
-`sdk-minimal` 在持久 shell 和 `working_directory` 之外公布 `read_image`。上下文压力达到配置阈值时，自动压缩会额外发起模型请求，生成较早历史的摘要。完整 Session 日志仍存储为未压缩 JSONL。图片超出路由预算时会被永久替换为包含附件与路径的占位文本，以便重试请求。SDK 提示词文本不会执行 `/compact`。
-
-固定工具名称、基准提示词大小或统计模型请求数的客户端必须考虑这些默认行为。图片读取需要适配器路由声明支持图片输入。配置与模型影响见[组合包参考](../../../../packages/bundle/sdk-minimal/README.zh.md)。
-
-## 迁移
-
-1. 接受新增默认能力，或将以下 patch 写入 `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml`，保留原有默认工具并关闭自动压缩：
-
-```yaml
-- id: tool-fs
-  config:
-    read: false
-    readImage: false
-    write: false
-    edit: false
-- id: compaction-basic
-  config:
-    auto: false
-```
-
-2. 启动新的 SDK 运行时。未额外配置用户插件时，模型请求包含持久 `bash` 或 `pwsh` 工具及 `working_directory`；不会发起自动摘要请求。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/stored-credentials-precedence/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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/stored-credentials-precedence/guide.md
-/:
-  en: 9fc8377bd2d6e38c
-  zh: b77fd76aeee0f592
-/a-stored-key-takes-precedence-over-an-exported-variable:
-  en: 0d002196a3f19850
-  zh: 7dcbbb6a44216f01
-/a-stored-key-takes-precedence-over-an-exported-variable/change:
-  en: 4ac6ffc5e782f765
-  zh: 51a69db953708bd3
-/a-stored-key-takes-precedence-over-an-exported-variable/migration:
-  en: d4f534f82476b5e9
-  zh: 5371eaaae96a3759

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/stored-credentials-precedence/guide.md

@@ -1,25 +0,0 @@
----
-kind: upgrade-guide
-description: "Stored credentials now precede environment fallbacks when the store is mounted; the shipped headless profile omits stored authentication."
----
-
-# A stored key takes precedence over an exported variable
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Earlier releases used an exported environment variable before the `refs` entry with the same name in `$DSH_HOME/.credentials.yaml` (`~/.dsh/.credentials.yaml` by default). This applied to `DEEPSEEK_API_KEY=… dsh`, a shell profile export, a CI secret, and a container `-e` value. While the name was exported, the Models page could not save a key for it.
-
-Now the stored entry wins. The exported variable applies only while the file stores no value for that name, and `$cwd/.env` and `$DSH_HOME/.env` still apply only after both. The Models page can save and replace a key while the name is exported.
-
-The shipped `headless` profile instead disables the credential store, authorization and DeepSeek account provider. It uses the launch environment, project `.env`, then Harness-home `.env`, and leaves `.credentials.yaml` untouched. Saved API keys and sign-ins no longer authenticate headless jobs by default. Web, SDK and ACP retain the store.
-
-You are affected when a harness home stores a value under `refs` and the process that launches `dsh` exports the same name. This includes a container that mounts such a home. Requests now use the stored key instead of the exported one. A CI job or container that starts with a fresh harness home, without `.credentials.yaml`, is not affected. The [stored credential precedence](../../../../.agents/notes/implemented/architecture/2026-10-09-stored-credential-precedence.md) Agent Note records the reason.
-
-## Migration
-
-1. Compare the names under `refs` in `$DSH_HOME/.credentials.yaml` with the variables that your shell, CI job, or container exports. A name that appears in only one place needs no action.
-2. For each name that appears in both places, keep the stored key if it is the account you want. Otherwise, delete the name's line under `refs`. A running harness reloads the file, so the next request reads the exported variable without a restart.
-3. For a headless job, export the required key and run `dsh headless "<task>"`. To keep using a saved key or sign-in, apply the three-row [headless restoration patch](../../../../packages/bundle/headless/README.md#credentials); restored storage also restores saved-first precedence. Existing profile, home or command overlays can override the shipped rows, so inspect `dsh headless --dump-config` when checking the effective composition.
-4. Confirm the intended request account and that the launching process exports a non-empty value where needed. Check names and presence without printing credential values. A headless run relying only on a saved credential now fails; restoring storage or supplying supported environment authentication resolves it.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/stored-credentials-precedence/guide.zh.md

@@ -1,25 +0,0 @@
----
-kind: upgrade-guide
-description: "挂载存储时，已保存凭据现在优先于环境后备；随附 headless profile 不挂载存储认证。"
----
-
-# 存储的密钥优先于导出的变量
-
-[English](guide.md) | 中文
-
-## 变更
-
-早期版本会先使用导出的环境变量，再使用 `$DSH_HOME/.credentials.yaml`（默认为 `~/.dsh/.credentials.yaml`）中同名的 `refs` 条目。这适用于 `DEEPSEEK_API_KEY=… dsh`、shell 配置文件中的导出、CI 机密和容器 `-e` 值。该名字被导出期间，Models 页面无法为其保存密钥。
-
-现在存储的条目优先。只有当文件没有为该名字存储值时，导出的变量才会生效；`$cwd/.env` 和 `$DSH_HOME/.env` 仍排在两者之后。即使该名字已被导出，Models 页面也可以保存和替换密钥。
-
-随附的 `headless` profile 则禁用凭据存储、authorization 和 DeepSeek account 提供方。它依次使用启动环境、项目 `.env` 和 Harness home `.env`，并保持 `.credentials.yaml` 原样。已保存 API 密钥和登录凭据默认不再为 headless 任务提供认证。Web、SDK 和 ACP 保留存储。
-
-如果某个 harness home 在 `refs` 下存储了值，而启动 `dsh` 的进程导出了同名变量，你就会受到影响。挂载了这类 home 的容器也包括在内。请求现在使用存储的密钥，而不是导出的密钥。以全新 harness home 启动、没有 `.credentials.yaml` 的 CI 作业或容器不受影响。[存储凭据优先级](../../../../.agents/notes/implemented/architecture/2026-10-09-stored-credential-precedence.zh.md) Agent Note 记录了原因。
-
-## 迁移
-
-1. 将 `$DSH_HOME/.credentials.yaml` 中 `refs` 下的名字，与 shell、CI 作业或容器导出的变量进行比较。只出现在其中一处的名字无需处理。
-2. 对同时出现在两处的名字，如果存储的密钥正是你要使用的账户，就保留它。否则，删除 `refs` 下该名字所在的行。运行中的 harness 会重新加载该文件，因此下一次请求无需重启即可读取导出的变量。
-3. 对 headless 任务，导出所需密钥并运行 `dsh headless "<task>"`。要继续使用已保存密钥或登录凭据，请应用三行配置的 [headless 恢复 patch](../../../../packages/bundle/headless/README.zh.md#credentials)；恢复存储也恢复已保存凭据优先。现有 profile、home 或命令覆盖可以覆盖随附行，因此核对有效组合时请查看 `dsh headless --dump-config`。
-4. 确认请求使用预期账户，并在需要时确认启动进程导出了非空值。只检查名字和是否存在，不要打印凭据值。仅依赖已保存凭据的 headless 运行现在会失败；恢复存储或提供受支持的环境认证即可解决。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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.3/plugin-engines-dsh/guide.md
-/:
-  en: 8b4090927cfab760
-  zh: 47917ce765e1930a
-/plugin-compatibility-reads-engines-dsh-first:
-  en: 99c73d9da5c7552d
-  zh: 9b7165d489c1960e
-/plugin-compatibility-reads-engines-dsh-first/change:
-  en: 3f4e014fb77f956b
-  zh: 33faefae854d381e
-/plugin-compatibility-reads-engines-dsh-first/migration:
-  en: 57676d075c62d8c9
-  zh: 460daff143c5d044