dsh-plugin-guide 0.3.42 → 0.4.0

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/bundled-python-tests/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Bundled NumPy and pandas omit their upstream test suites."
----
-
-# NumPy and pandas upstream tests require a separate environment
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Desktop and Python SDK runtime distributions previously included NumPy and pandas test directories. Bundled distributions now omit those directories, so scripts importing their test modules or running their complete upstream suites need a separate installation. Data processing, Office authoring, `numpy.testing`, `pandas.testing`, and `pandas._testing` remain available.
-
-## Migration
-
-1. If your scripts import `numpy.*.tests` or `pandas.tests`, install the original NumPy and pandas distributions and their upstream testing dependencies in a separate Python environment. Keep that environment outside the managed Harness runtime directory, which upgrades replace.
-2. Run the affected scripts or upstream suites with that environment's interpreter. Scripts that use only library functionality or retained testing helpers require no changes.
-3. Confirm that the previously failing test-module imports and affected scripts succeed with the separate interpreter. The bundled versions are recorded in the [runtime lock](../../../../scripts/primary-runtime/lock.json).

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/bundled-python-tests/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "内置 NumPy 和 pandas 不包含其上游测试套件。"
----
-
-# NumPy 和 pandas 上游测试需要独立环境
-
-[English](guide.md) | 中文
-
-## 变更
-
-Desktop 和 Python SDK 运行时分发包此前包含 NumPy 和 pandas 测试目录。内置分发包现在裁剪这些目录，因此导入其测试模块或运行其完整上游测试套件的脚本需要独立安装环境。数据处理、Office 创作、`numpy.testing`、`pandas.testing` 和 `pandas._testing` 仍然可用。
-
-## 迁移
-
-1. 如果脚本导入 `numpy.*.tests` 或 `pandas.tests`，请在独立 Python 环境中安装原始 NumPy 和 pandas 分发包及其上游测试依赖。请将该环境放在 Harness 托管运行时目录之外，升级会替换托管目录。
-2. 使用该环境的解释器运行受影响的脚本或上游测试套件。仅使用库功能或保留的 testing 辅助 API 的脚本无需修改。
-3. 确认先前失败的测试模块导入及相关脚本均可在独立解释器中成功运行。随包版本记录在[运行时锁文件](../../../../scripts/primary-runtime/lock.json)中。

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/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.0-rc.2/primary-runtime-python-aliases/guide.md
-/:
-  en: a4f973e3aed3cbb1
-  zh: e33e5eb33838f82e
-/custom-python-runtime-aliases-must-target-a-sibling-interpreter:
-  en: c38fad48cd870c4c
-  zh: 49fff1636ca8c8fd
-/custom-python-runtime-aliases-must-target-a-sibling-interpreter/change:
-  en: 55f21ac0b9190e37
-  zh: 2d1c7aaa89ddfe19
-/custom-python-runtime-aliases-must-target-a-sibling-interpreter/migration:
-  en: 2839866a08be236d
-  zh: 11a01d35a7f396ce

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Custom primary-runtime payloads require relocatable Python interpreter aliases."
----
-
-# Custom Python runtime aliases must target a sibling interpreter
-
-English | [中文](guide.zh.md)
-
-## Change
-
-On macOS and Linux, `DSH_PRIMARY_RUNTIME` previously accepted interpreter links that resolved outside their payload or through other links. Payload validation now requires each linked `dependencies/python/bin/python` or `python3` to point directly to the regular sibling interpreter named for `runtime.json`'s Python major and minor version, such as `python3.12`. Regular command files remain supported, including those distributed in Python wheels. Windows is unchanged.
-
-## Migration
-
-1. For a custom payload, keep the versioned interpreter in `dependencies/python/bin/` and make `python` and `python3` relative links to its filename. The [runtime preparation instructions](../../../../packages/skill/tool-workspace-dependencies/README.md) list the required target and output arguments.
-2. Preserve relative links when copying prepared resources. With Node `fs.cp`, use `verbatimSymlinks: true`; wheel builders must materialize the command files because pip does not restore links. The native build smoke requires the prepared resource tree to retain both aliases.
-3. Confirm that `readlink` reports only the sibling filename for both aliases, then move the payload away from its build directory, point `DSH_PRIMARY_RUNTIME` at its new directory, and verify that `load_workspace_dependencies` and the returned Python command succeed.

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "自定义 primary-runtime payload 的 Python 解释器别名必须支持目录迁移。"
----
-
-# 自定义 Python 运行时别名必须指向同目录解释器
-
-[English](guide.md) | 中文
-
-## 变更
-
-在 macOS 和 Linux 上，`DSH_PRIMARY_RUNTIME` 之前接受指向 payload 外部或经过其他链接的解释器链接。现在，payload 校验要求 `dependencies/python/bin/python` 或 `python3` 的链接直接指向同目录的普通解释器文件，文件名由 `runtime.json` 中 Python 的主版本号和次版本号决定，例如 `python3.12`。普通命令文件仍受支持，包括 Python wheel 中分发的文件。Windows 不变。
-
-## 迁移
-
-1. 对于自定义 payload，将版本化解释器保留在 `dependencies/python/bin/` 中，并让 `python` 和 `python3` 以该文件名为目标建立相对链接。[运行时准备说明](../../../../packages/skill/tool-workspace-dependencies/README.zh.md)列出了必需的目标与输出参数。
-2. 复制准备好的资源时保留相对链接。使用 Node `fs.cp` 时设置 `verbatimSymlinks: true`；wheel 构建器必须将命令展开为普通文件，因为 pip 不会还原链接。本机构建冒烟检查要求准备好的资源目录保留两个别名。
-3. 确认 `readlink` 对两个别名都只返回同目录解释器的文件名，再将 payload 移离构建目录，将 `DSH_PRIMARY_RUNTIME` 指向新目录，验证 `load_workspace_dependencies` 和返回的 Python 命令均可成功执行。

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/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.0-rc.2/remove-runtime-invariants/guide.md
-/:
-  en: 3cb412fe69354a6b
-  zh: fbd2dd7abcd08ed7
-/runtime-invariant-plugins-are-removed:
-  en: 573fd5239a856cab
-  zh: edb2683d049a81b7
-/runtime-invariant-plugins-are-removed/change:
-  en: 58c246cfc02ab19d
-  zh: 4826b8cbb34e1363
-/runtime-invariant-plugins-are-removed/migration:
-  en: b42a35a30b792f84
-  zh: 0ddbccc4b93410a3

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/guide.md

@@ -1,23 +0,0 @@
----
-kind: upgrade-guide
-description: "The runtime invariant registry package and every package's `./invariant` subpath export are removed."
----
-
-# Runtime invariant plugins are removed
-
-English | [中文](guide.zh.md)
-
-## Change
-
-In v0.2.0-rc.2, `@deepseek-ai/dsh-invariants` provided the `ctx.invariants` service, and workspace packages such as `@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-agent`, `@deepseek-ai/dsh-scope`, and `@deepseek-ai/dsh-agent-loop` published `./invariant` companion plugins that registered checks with it. The `sdk-minimal` profile mounted five of these rows with ids `invariants`, `session-invariant`, `agent-invariant`, `scope-invariant`, and `agent-loop-invariant`.
-
-The next release no longer publishes `@deepseek-ai/dsh-invariants`, `InvariantRegistry`, `InvariantInstaller`, `InvariantFailure`, `InvariantError`, or any `<package>/invariant` subpath. The `sdk-minimal` profile no longer contains the five rows. The `credentials/reference-updated`, `credentials/record-updated`, `authorization/settled`, and `llm/adapters-updated` emitters contain and log every listener failure, including errors with `code: 'INVARIANT'`, instead of rethrowing them.
-
-A `cordis.yml`, patch, or overlay that names a removed module fails to load it. A patch that targets one of the five `sdk-minimal` ids logs `patch: entry <id> not found`. TypeScript code that imports a removed module or symbol no longer compiles.
-
-## Migration
-
-1. Delete rows whose `name` is `@deepseek-ai/dsh-invariants` or ends in `/invariant` from `cordis.yml`, `$DSH_HOME/profiles/<name>/cordis.patch.yml`, and `--patch` overlays.
-2. Delete patch entries that target the ids `invariants`, `session-invariant`, `agent-invariant`, `scope-invariant`, or `agent-loop-invariant`.
-3. Remove `@deepseek-ai/dsh-invariants` from `package.json` dependencies and delete imports of it and of `<package>/invariant` subpaths. A plugin that relied on a rethrown `INVARIANT` failure from one of the four emitters must report the failure through its own channel.
-4. Confirm: `dsh` starts the profile without a module-not-found error or `patch: entry ... not found` warning, and `tsc` reports no missing module or export.

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/guide.zh.md

@@ -1,23 +0,0 @@
----
-kind: upgrade-guide
-description: "运行时不变式注册表包和每个包的 `./invariant` 子路径导出均被移除。"
----
-
-# 运行时不变式插件被移除
-
-[English](guide.md) | 中文
-
-## 变更
-
-在 v0.2.0-rc.2 中，`@deepseek-ai/dsh-invariants` 提供 `ctx.invariants` 服务，`@deepseek-ai/dsh-session`、`@deepseek-ai/dsh-agent`、`@deepseek-ai/dsh-scope`、`@deepseek-ai/dsh-agent-loop` 等 workspace 包发布向该服务注册检查的 `./invariant` 配套插件。`sdk-minimal` profile 挂载其中五行，id 为 `invariants`、`session-invariant`、`agent-invariant`、`scope-invariant` 和 `agent-loop-invariant`。
-
-下一版本不再发布 `@deepseek-ai/dsh-invariants`、`InvariantRegistry`、`InvariantInstaller`、`InvariantFailure`、`InvariantError`，也不再发布任何 `<package>/invariant` 子路径。`sdk-minimal` profile 不再包含这五行。`credentials/reference-updated`、`credentials/record-updated`、`authorization/settled` 和 `llm/adapters-updated` 的发出方会隔离并记录每个监听器失败，包括 `code: 'INVARIANT'` 的错误，不再重新抛出。
-
-引用已移除模块的 `cordis.yml`、patch 或 overlay 无法加载该模块。指向上述五个 `sdk-minimal` id 之一的 patch 会记录 `patch: entry <id> not found`。导入已移除模块或符号的 TypeScript 代码无法编译。
-
-## 迁移
-
-1. 从 `cordis.yml`、`$DSH_HOME/profiles/<name>/cordis.patch.yml` 和 `--patch` overlay 中删除 `name` 为 `@deepseek-ai/dsh-invariants` 或以 `/invariant` 结尾的行。
-2. 删除指向 id `invariants`、`session-invariant`、`agent-invariant`、`scope-invariant` 或 `agent-loop-invariant` 的 patch 条目。
-3. 从 `package.json` 依赖中移除 `@deepseek-ai/dsh-invariants`，并删除对它和 `<package>/invariant` 子路径的导入。依赖上述四个发出方重新抛出 `INVARIANT` 失败的插件，必须通过自己的通道报告该失败。
-4. 确认：`dsh` 启动该 profile 时没有模块未找到错误或 `patch: entry ... not found` 警告，`tsc` 不再报告缺失的模块或导出。

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired/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.0-rc.2/schedule-bundle-retired/guide.md
-/:
-  en: 2b61d3edeb5cb9b3
-  zh: c8c19ac891de1483
-/automation-tasks-bundle-removed:
-  en: fb9d856d884313d9
-  zh: 6fa0d728f26c5f8e
-/automation-tasks-bundle-removed/change:
-  en: 0a35ea93af06452f
-  zh: 094dd5f6422bab8d
-/automation-tasks-bundle-removed/migration:
-  en: 04278f963f780cad
-  zh: f8e49107b3a5df07

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired/guide.md

@@ -1,22 +0,0 @@
----
-kind: upgrade-guide
-description: "The Automation tasks optional bundle is removed; the Web composition mounts Schedule itself."
----
-
-# Automation tasks bundle removed
-
-English | [中文](guide.zh.md)
-
-## Change
-
-In v0.2.0-rc.2, switching on Automation tasks in the Plugins page appended `@deepseek-ai/dsh-experimental-schedule-bundle` to `dsh.profile.bundles` in `$DSH_HOME/profiles/<name>/package.json`. That bundle inserted the `time-context`, `schedule`, and `ui-schedule` rows.
-
-The next release removes the bundle. `@deepseek-ai/dsh-web-app` mounts `schedule` and `ui-schedule` in every Web profile, and the `standard`, `cordis`, and `ptc` presets declare the clock reading and the four `schedule_*` tools; `minimal` declares neither ([details](../../../subsystems/schedule.md)).
-
-Loading a profile removes `@deepseek-ai/dsh-experimental-schedule-bundle` from its `dsh.profile.bundles` and rewrites `package.json`; other manifest fields are kept. Stored tasks and delivery records stay on disk and remain in use.
-
-## Migration
-
-1. Start `dsh` once with each affected profile; no manual edit is needed. A profile directory that another tool writes must drop the entry from `dsh.profile.bundles` itself.
-2. Keep overrides on `schedule` and `ui-schedule` in `cordis.patch.yml` or a `--patch` overlay; the Web composition carries those rows. A top-level override on `time-context` no longer matches a row, because the clock row belongs to the presets ([time-context](../../../../packages/context/time-context/README.md)); delete it.
-3. Confirm: `dsh.profile.bundles` no longer lists the bundle, the Plugins page shows no failed Automation tasks entry, and the sidebar shows Automation tasks with the previously stored reminders.

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired/guide.zh.md

@@ -1,22 +0,0 @@
----
-kind: upgrade-guide
-description: "“自动化任务”可选 bundle 已移除；Web 组合自行挂载 Schedule。"
----
-
-# “自动化任务” bundle 已移除
-
-[English](guide.md) | 中文
-
-## 变更
-
-在 v0.2.0-rc.2 中，在插件管理页开启“自动化任务”会把 `@deepseek-ai/dsh-experimental-schedule-bundle` 追加到 `$DSH_HOME/profiles/<name>/package.json` 的 `dsh.profile.bundles`。该 bundle 插入 `time-context`、`schedule` 和 `ui-schedule` 三行。
-
-下一版本移除该 bundle。`@deepseek-ai/dsh-web-app` 在每个 Web profile 中挂载 `schedule` 和 `ui-schedule`，`standard`、`cordis` 和 `ptc` preset 声明时钟读数和四个 `schedule_*` 工具；`minimal` 两者都不声明（[详情](../../../subsystems/schedule.zh.md)）。
-
-加载 profile 时会从其 `dsh.profile.bundles` 中删除 `@deepseek-ai/dsh-experimental-schedule-bundle` 并重写 `package.json`；其他 manifest 字段保持不变。已存储的任务和投递记录仍保留在磁盘上并继续使用。
-
-## 迁移
-
-1. 用每个受影响的 profile 启动一次 `dsh`，无需手动编辑。由其他工具写入的 profile 目录需要自行从 `dsh.profile.bundles` 删除该条目。
-2. 保留 `cordis.patch.yml` 或 `--patch` overlay 中针对 `schedule` 和 `ui-schedule` 的覆盖项；Web 组合包含这两行。顶层针对 `time-context` 的覆盖项不再匹配任何行，因为时钟行属于 preset（[time-context](../../../../packages/context/time-context/README.zh.md)）；请删除它。
-3. 确认：`dsh.profile.bundles` 不再列出该 bundle，插件管理页不再显示异常的“自动化任务”条目，且侧栏显示“自动化任务”并列出之前存储的提醒。

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest/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.0-rc.2/subpath-plugin-display-manifest/guide.md
-/:
-  en: 671d5c0f87811869
-  zh: 442229358c471ea8
-/subpath-plugins-read-subpath-icon-instead-of-subpath-package-json:
-  en: 4e7a5119af04d780
-  zh: e70b1fc5f253d6f4
-/subpath-plugins-read-subpath-icon-instead-of-subpath-package-json/change:
-  en: 4793cf77e0c3a9ba
-  zh: a4fbe548044af6e6
-/subpath-plugins-read-subpath-icon-instead-of-subpath-package-json/migration:
-  en: bd32f99339b4a69e
-  zh: b0d6b46724bc57cc

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest/guide.md

@@ -1,27 +0,0 @@
----
-kind: upgrade-guide
-description: "Subpath plugins no longer read display text or icons from an exported <subpath>/package.json; they use locale meta and <subpath>/icon."
----
-
-# Subpath plugins read `<subpath>/icon` instead of `<subpath>/package.json`
-
-English | [中文](guide.zh.md)
-
-## Change
-
-In v0.2.0-rc.2, Plugin Manager and Settings read a subpath plugin such as `my-plugins/search` through `my-plugins/search/package.json` when the package exported it: `name` and `description` filled missing locale fields, and `icon` supplied the row image. A subpath is not a package, so the next release never reads a `package.json` for it. Its title and description come only from `my-plugins/search/locale/*.json`, and its image comes from the exported `my-plugins/search/icon` resource. Package-root plugins keep their `package.json` text and `icon`; when `icon` is omitted, an exported `./icon` supplies the image. Authors of packages that export subpath `package.json` files are affected.
-
-## Migration
-
-1. Move the subpath manifest's `name` and `description` into `meta.title` and `meta.description` of the subpath locale files, and export them, for example `"./search/locale/*.json": "./locale/search/*.json"`.
-2. Replace the subpath manifest's `icon` with an icon export and publish its target:
-
-   ```json
-   {
-     "exports": { "./search/icon": "./assets/search.svg" },
-     "files": ["assets/search.svg"]
-   }
-   ```
-
-3. Remove the `./search/package.json` export and its file.
-4. Run `pnpm run verify-package-meta` in a DSH checkout, or open Plugin Manager, and confirm the subpath row shows its title, description, and image.

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest/guide.zh.md

@@ -1,27 +0,0 @@
----
-kind: upgrade-guide
-description: "子路径插件不再从导出的 <子路径>/package.json 读取展示文本和图标，改用 locale meta 和 <子路径>/icon。"
----
-
-# 子路径插件改读 `<子路径>/icon`，不再读 `<子路径>/package.json`
-
-[English](guide.md) | 中文
-
-## 变更
-
-在 v0.2.0-rc.2 中，插件管理页和设置页会在包导出 `my-plugins/search/package.json` 时，通过它读取 `my-plugins/search` 这样的子路径插件：`name` 和 `description` 补全缺失的 locale 字段，`icon` 提供行图片。子路径不是包，因此下一版本不再为它读取任何 `package.json`。其标题和描述只来自 `my-plugins/search/locale/*.json`，图片来自导出的 `my-plugins/search/icon` 资源。包根插件保留 `package.json` 文本和 `icon`；省略 `icon` 时，导出的 `./icon` 提供图片。受影响的是导出子路径 `package.json` 的包作者。
-
-## 迁移
-
-1. 将子路径清单的 `name` 和 `description` 移到子路径 locale 文件的 `meta.title` 和 `meta.description`，并导出这些文件，例如 `"./search/locale/*.json": "./locale/search/*.json"`。
-2. 用图标导出替换子路径清单的 `icon`，并发布其目标文件：
-
-   ```json
-   {
-     "exports": { "./search/icon": "./assets/search.svg" },
-     "files": ["assets/search.svg"]
-   }
-   ```
-
-3. 删除 `./search/package.json` 导出及其文件。
-4. 在 DSH 仓库中运行 `pnpm run verify-package-meta`，或打开插件管理页，确认子路径行显示标题、描述和图片。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/deepseek-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.1/deepseek-model-discovery/guide.md
-/:
-  en: 059ab5482d52d8b8
-  zh: 006b65489bc4ec70
-/deepseek-api-key-model-visibility:
-  en: 7b14dc7133967bfd
-  zh: 4f338ae1e8151feb
-/deepseek-api-key-model-visibility/change:
-  en: ab0b141fbb3167ab
-  zh: 918f4202223abe44
-/deepseek-api-key-model-visibility/migration:
-  en: 2fda36f7e543f1d0
-  zh: e8522f256de5adaa

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/deepseek-model-discovery/guide.md

@@ -1,17 +0,0 @@
----
-kind: upgrade-guide
-description: "DeepSeek API-key model discovery requires a configured credential."
----
-
-# DeepSeek API-key model visibility
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The `deepseek-official` route previously listed its configured models without an API key. It now returns an empty catalog when its credential is missing, so Desktop and Web hide the DeepSeek group. Model discovery reports malformed credentials and credential lookup failures. A saved or default selection absent from the catalog displays “Select model” without changing the stored selection. The independent DeepSeek account route still uses account login.
-
-## Migration
-
-1. To use the API-key route, configure its key in Settings → Models or supply the reference named by `apiKeyEnv` (default `DEEPSEEK_API_KEY`) through the launch environment.
-2. Reopen the model selector and confirm the DeepSeek group appears. Custom discovery consumers must handle an empty catalog before credentials are configured; listing models does not verify that the remote API accepts the key.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/deepseek-model-discovery/guide.zh.md

@@ -1,17 +0,0 @@
----
-kind: upgrade-guide
-description: "DeepSeek API Key 模型发现要求已配置凭据。"
----
-
-# DeepSeek API Key 模型可见性
-
-[English](guide.md) | 中文
-
-## 变更
-
-`deepseek-official` 路由此前在没有 API Key 时也会列出配置的模型。现在凭据缺失时返回空目录，因此桌面端和 Web 隐藏 DeepSeek 分组。模型发现会报告凭据格式错误和凭据读取失败。已保存或默认的选择不在目录中时，界面显示“请选择模型”，保存的选择保持不变。独立的 DeepSeek 账号路由仍使用账号登录。
-
-## 迁移
-
-1. 要使用 API Key 路由，请在设置 → 模型中配置密钥，或通过启动环境提供 `apiKeyEnv` 指定的凭据引用（默认为 `DEEPSEEK_API_KEY`）。
-2. 重新打开模型选择器，确认 DeepSeek 分组出现。自定义模型发现消费者必须处理配置凭据前的空目录；模型列出不代表远端 API 已接受密钥。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/desktop-test-auth-popup/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.1/desktop-test-auth-popup/guide.md
-/:
-  en: 97a3763818ba118c
-  zh: ba856458827cb637
-/enable-test-update-policy-authentication-dialogs-locally:
-  en: 33515a78d8b30d7a
-  zh: 6f821057b75e319e
-/enable-test-update-policy-authentication-dialogs-locally/change:
-  en: 21d23ef8d1d3599c
-  zh: 389633b096767f73
-/enable-test-update-policy-authentication-dialogs-locally/migration:
-  en: e6b3bc48daaa13b1
-  zh: df50a981844d3de6

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/desktop-test-auth-popup/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Desktop test builds require local opt-in before showing any Feishu update-policy authentication dialogs."
----
-
-# Enable test update-policy authentication dialogs locally
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Test builds previously offered Feishu login after an unauthenticated startup or manual update-policy check. All test authentication dialogs now default to disabled, including manual checks and mandatory-update refreshes. Test gateway cookies do not survive restart. With login disabled, a gateway requiring authentication cannot provide new mandatory-update decisions; enable the setting, restart and sign in to obtain them. Authentication failures retain any mandatory block already known in the same process; production policy requests and product account login are unchanged.
-
-## Migration
-
-1. Launch the updated application once to create `app.getPath('userData')/desktop/settings.json` if missing. Existing files are retained, and a missing field defaults to `false`. See [local desktop settings](../../../../apps/desktop/README.md#local-desktop-settings) for platform paths and error recovery.
-2. To permit Feishu login, set `updates.allowTestAuthPopupWindow` to `true` in that file, then fully quit and restart Desktop. An unauthenticated test-policy response can now offer login. Leave the default unchanged if no login dialogs are wanted.
-3. To disable dialogs again, set the field to `false` and restart. Startup and manual checks must not show Feishu authentication dialogs. Updates still query policy, and authentication failures do not clear a known mandatory block.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/desktop-test-auth-popup/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "桌面测试包需要在本地显式开启后，才能显示飞书更新策略鉴权弹窗。"
----
-
-# 在本地开启测试更新策略鉴权弹窗
-
-[English](guide.md) | 中文
-
-## 变更
-
-测试包此前会在启动或手动检查更新策略未通过鉴权后提供飞书登录入口。现在所有测试鉴权弹窗默认关闭，包括手动检查和强更刷新。测试网关 Cookie 不跨重启保存。禁止登录时，需要鉴权的网关无法提供新的强更决策；需开启设置、重启并登录后才能获取。鉴权失败仍保留同一进程中已知的强更阻塞；正式环境策略请求和产品账号登录保持不变。
-
-## 迁移
-
-1. 启动更新后的应用一次，在 `app.getPath('userData')/desktop/settings.json` 缺失时生成该文件。已有文件会保留，字段缺失时默认为 `false`。平台路径和错误恢复方法见[本地桌面设置](../../../../apps/desktop/README.zh.md#local-desktop-settings)。
-2. 如需允许飞书登录，在文件中将 `updates.allowTestAuthPopupWindow` 设为 `true`，然后完全退出并重启 Desktop。此时测试策略的未鉴权响应可以提供登录入口。不需要登录弹窗时保持默认值即可。
-3. 如需再次关闭弹窗，将字段设为 `false` 并重启。启动和手动检查均不得显示飞书鉴权弹窗。更新仍会查询策略，鉴权失败不会解除已知强更阻塞。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/experimental-package-composition/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.1/experimental-package-composition/guide.md
-/:
-  en: ba51914a407e33ae
-  zh: f0440eb120093d36
-/explicit-installation-and-composition-for-optional-capabilities:
-  en: 5a3fcd469d908d58
-  zh: df94cc0beddc20ef
-/explicit-installation-and-composition-for-optional-capabilities/change:
-  en: 3143b032a22268ec
-  zh: e55603836a24022a
-/explicit-installation-and-composition-for-optional-capabilities/migration:
-  en: e197a95e2e59af22
-  zh: dfdda504922c1dc5

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/experimental-package-composition/guide.md

@@ -1,28 +0,0 @@
----
-kind: upgrade-guide
-description: "Explicit installation, peer dependencies, and configuration for optional hooks, webhooks, tools, and skills."
----
-
-# Explicit installation and composition for optional capabilities
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The CLI and Python runtime omit the hook bridges from their installation dependencies, and the CLI omits the webhook pair. Base and the full Web presets omit dormant Ralph rows, and base omits its dormant badge row. A patch that only enables a removed row does not insert its plugin. Default active behavior, plugin registration names, tool names, and recorded Session event names remain unchanged.
-
-Package ownership and naming follow the [experimental package policy](../../../../scripts/experimental-package-policy.ts). Installation and composition are separate: installing a plugin package does not mount it, and a bundle must be selected before its contributed rows can be configured.
-
-## Migration
-
-1. Install any packages missing from the target profile together with their required peers. Profiles disable automatic peer installation. For example, run `dsh plugin --profile web add @deepseek-ai/dsh-hooks-claude-code @deepseek-ai/dsh-hook-protocol`. The Codex bridge needs the same protocol peer; the GitHub adapter needs `@deepseek-ai/dsh-webhook` alongside `@deepseek-ai/dsh-webhook-github`.
-2. Select an available bundle before overriding its rows. For a capability composed manually, replace an override of a removed row with a complete insertion. Add preset-local tools inside that preset's `config.plugins`, including the services they require. A Host badge insertion is:
-
-   ```yaml
-   - insert:
-       - id: skill-badge
-         name: '@deepseek-ai/dsh-skill-badge'
-   ```
-
-3. For GitHub review, use the example distributed with the adapter instead of the removed CLI example. Follow the [installed-profile instructions](../../../user/guide/github-review.md); keep customized rule modules inside the profile so their imports resolve its installed packages.
-4. Start the profile and confirm that its configured plugins activate without missing-package, missing-peer, or missing-row errors. Confirm the expected tool or skill is available in the intended Agent preset.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/experimental-package-composition/guide.zh.md

@@ -1,28 +0,0 @@
----
-kind: upgrade-guide
-description: "可选 hooks、webhooks、工具与技能所需的显式安装、peer 依赖和配置。"
----
-
-# 可选能力的显式安装与组合
-
-[English](guide.md) | 中文
-
-## 变更
-
-CLI 与 Python 运行时的安装依赖不再包含 hook 桥接，CLI 也不再包含 webhook 包对。Base 与完整 Web 预设省略休眠的 Ralph 行，base 也省略休眠的徽章行。仅启用已移除行的 patch 不会插入其插件。默认活动行为、插件注册名称、工具名称与已记录的 Session 事件名称保持不变。
-
-包归属和命名遵循[实验包策略](../../../../scripts/experimental-package-policy.ts)。安装与组合相互独立：安装插件包不会挂载它，必须先选择 bundle 才能配置其贡献的行。
-
-## 迁移
-
-1. 将目标 profile 缺少的包与所需 peer 一起安装。Profile 禁用自动 peer 安装。例如，运行 `dsh plugin --profile web add @deepseek-ai/dsh-hooks-claude-code @deepseek-ai/dsh-hook-protocol`。Codex 桥接需要相同的协议 peer；GitHub 适配器需要同时安装 `@deepseek-ai/dsh-webhook` 与 `@deepseek-ai/dsh-webhook-github`。
-2. 覆盖 bundle 的行之前先选择可用的 bundle。对于手动组合的能力，将覆盖已移除行的 patch 替换为完整插入。在预设的 `config.plugins` 中添加预设内工具及其所需服务。Host 徽章插入示例：
-
-   ```yaml
-   - insert:
-       - id: skill-badge
-         name: '@deepseek-ai/dsh-skill-badge'
-   ```
-
-3. GitHub review 使用适配器随附的示例，替代已删除的 CLI 示例。遵循[安装版 profile 说明](../../../user/guide/github-review.zh.md)；将定制规则模块保留在 profile 内，使其导入能解析该 profile 安装的包。
-4. 启动 profile，确认配置的插件激活时没有缺包、缺 peer 或缺行错误。确认预期工具或技能在目标 Agent 预设中可用。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/instruction-home-override/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.1/instruction-home-override/guide.md
-/:
-  en: 7081d888aedd32d2
-  zh: 167263e5e4e514cc
-/instruction-loading-resolves-one-harness-home:
-  en: b308584aa55910bd
-  zh: 910cc6b2b7f9b3ea
-/instruction-loading-resolves-one-harness-home/change:
-  en: afd003587be927b4
-  zh: 15dcd2ec55a5c968
-/instruction-loading-resolves-one-harness-home/migration:
-  en: 483d23f92ad84a8c
-  zh: 3c2648ebf2156b34

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/instruction-home-override/guide.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "The `agent-instructions` row no longer accepts `dshHome`; instruction loading always resolves the harness home from `$DSH_HOME` or `~/.dsh`."
----
-
-# Instruction loading resolves one harness home
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`@deepseek-ai/dsh-agent-instructions` removed its `dshHome` config field. The plugin resolves the harness home through `resolveDshHome()` from `@deepseek-ai/dsh-home-paths`, like every other harness consumer: the home is `$DSH_HOME` when it is set and non-blank, otherwise `~/.dsh`, with tilde expansion.
-
-A `cordis.yml`, profile patch, or `--patch` overlay that still sets `dshHome` on the `agent-instructions` row has no effect: the row keeps the stray key and the plugin ignores it, so instruction loading follows the process home. Other providers, such as `dsh-skill-filesystem` and `dsh-shell-env`, keep their own home fields; this removal covers the instruction loader only.
-
-## Migration
-
-1. Delete `dshHome` from the `agent-instructions` row in `cordis.yml`, `$DSH_HOME/cordis.patch.yml`, `$DSH_HOME/profiles/<profile>/cordis.patch.yml`, and any `--patch` overlay.
-2. Where the override pointed at a non-default home, export `DSH_HOME` for the process instead, so every harness consumer reads that home.
-3. Confirm with `dsh --profile <profile> --dump-config` that the `agent-instructions` row lists only its remaining fields, and that a new session's first request shows `Instructions from: $DSH_HOME/AGENTS.md` (or `~/.dsh/AGENTS.md`) when that file exists.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/instruction-home-override/guide.zh.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "`agent-instructions` 行不再接受 `dshHome`；指令加载始终从 `$DSH_HOME` 或 `~/.dsh` 解析 harness home。"
----
-
-# 指令加载只解析一个 harness home
-
-[English](guide.md) | 中文
-
-## 变更
-
-`@deepseek-ai/dsh-agent-instructions` 移除了 `dshHome` 配置字段。该插件通过 `@deepseek-ai/dsh-home-paths` 的 `resolveDshHome()` 解析 harness home，与 harness 其他消费方一致：`$DSH_HOME` 已设置且非空白时以它为准，否则使用 `~/.dsh`，并展开波浪号。
-
-`cordis.yml`、profile patch 或 `--patch` overlay 中 `agent-instructions` 行上残留的 `dshHome` 不再有任何效果：该行会保留这个多余键，插件忽略它，指令加载跟随进程 home。其他 provider（如 `dsh-skill-filesystem`、`dsh-shell-env`）保留各自的 home 字段；本次删除只覆盖指令加载器。
-
-## 迁移
-
-1. 从 `cordis.yml`、`$DSH_HOME/cordis.patch.yml`、`$DSH_HOME/profiles/<profile>/cordis.patch.yml` 以及任何 `--patch` overlay 的 `agent-instructions` 行中删除 `dshHome`。
-2. 若该覆盖原本指向非默认 home，改为在进程中导出 `DSH_HOME`，让所有 harness 消费方读取同一个 home。
-3. 用 `dsh --profile <profile> --dump-config` 确认 `agent-instructions` 行只剩其余字段，并确认新会话的首次请求在该文件存在时显示 `Instructions from: $DSH_HOME/AGENTS.md`（或 `~/.dsh/AGENTS.md`）。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/job-id-identity/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.1/job-id-identity/guide.md
-/:
-  en: d6fdce6b58c67691
-  zh: a103e5028f5442d0
-/background-job-ids-identify-one-execution:
-  en: 9b06780be69e93f6
-  zh: c33945fd584c6a23
-/background-job-ids-identify-one-execution/change:
-  en: 047ec9d0337bfc0b
-  zh: 1218472855e81189
-/background-job-ids-identify-one-execution/migration:
-  en: 08921c9c25218c83
-  zh: 7ff1d3ac63ae40ef

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "JobId now identifies one background execution across registry lifetimes."
----
-
-# Background job ids identify one execution
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The job registry returns `<kind>-<short-uuid>` instead of `<kind>-N`; the suffix is 16 lowercase UUID hex characters. The same `JobId` appears in live controls, `job/registered`, and `job/settled`; lifecycle records no longer carry `executionId`. The identifier remains owner-authorized. Existing Session histories remain unchanged and do not resume their jobs.
-
-## Migration
-
-1. Pass the exact id returned by a start result or `jobs.list()` to `job_output` and `job_kill`; use `job_output` with `wait: true` to wait. Remove code that constructs an id from the kind and an ordinal.
-2. Pair SDK lifecycle events by `data.jobId`. Remove imports of `JobExecutionId` and code that maps it to a process-local `jobId`.
-3. Verify a new job's registration and settlement contain the same `jobId`, and a later registry instance issues a different one.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "JobId 现在跨注册表生命周期标识一次后台执行。"
----
-
-# 后台 job id 标识一次执行
-
-[English](guide.md) | 中文
-
-## 变更
-
-job 注册表返回 `<kind>-<short-uuid>`，不再返回 `<kind>-N`；后缀是 UUID 的 16 位小写十六进制字符。运行期控制、`job/registered` 和 `job/settled` 使用同一个 `JobId`；生命周期记录不再携带 `executionId`。访问仍按所有者授权。已有 Session 历史保持原样，不会恢复其中的 job。
-
-## 迁移
-
-1. 把启动结果或 `jobs.list()` 返回的原始 id 传给 `job_output` 和 `job_kill`；等待时为 `job_output` 设置 `wait: true`。移除按 kind 和序号构造 id 的代码。
-2. 使用 `data.jobId` 配对 SDK 生命周期事件。移除 `JobExecutionId` 导入，以及将它映射为进程内 `jobId` 的代码。
-3. 核对新 job 的注册与结算含有相同 `jobId`，后续注册表实例发放不同 id。