dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/kb/extra/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/guide.zh.md

@@ -0,0 +1,23 @@
+---
+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/kb/extra/upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired/guide.md

@@ -0,0 +1,22 @@
+---
+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/kb/extra/upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired/guide.zh.md

@@ -0,0 +1,22 @@
+---
+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/kb/extra/upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest/guide.md

@@ -0,0 +1,27 @@
+---
+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/kb/extra/upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest/guide.zh.md

@@ -0,0 +1,27 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/deepseek-model-discovery/guide.md

@@ -0,0 +1,17 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/deepseek-model-discovery/guide.zh.md

@@ -0,0 +1,17 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/desktop-test-auth-popup/guide.md

@@ -0,0 +1,18 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/desktop-test-auth-popup/guide.zh.md

@@ -0,0 +1,18 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/experimental-package-composition/guide.md

@@ -0,0 +1,28 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/experimental-package-composition/guide.zh.md

@@ -0,0 +1,28 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/instruction-home-override/guide.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/instruction-home-override/guide.zh.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.md

@@ -0,0 +1,18 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.zh.md

@@ -0,0 +1,18 @@
+---
+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。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JSONL persistence uses a namespace plugin import; direct service-class construction and class type annotations must use the persistence service instead."
+---
+
+# Mount JSONL persistence through its plugin
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-session-persistence-jsonl` exports a function plugin through named `name`, `Config`, and `apply` exports, with no default export. Default imports, direct construction, subclassing, `instanceof`, and class type annotations are affected. The plugin retains listeners and handles through the consumer unloads triggered by removing this provider; concurrent root disposal remains unordered. The `sessionPersistence` service API, YAML configuration, and stored files remain unchanged.
+
+## Migration
+
+1. Replace the default import with `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`. Existing `ctx.plugin(JsonlSessionPersistence, config)` calls remain valid; replace direct construction with this mounting call. For dynamic imports, use the module namespace returned by `await import(...)` instead of its `.default`. Consumers declare `inject: ['sessionPersistence']` and access `ctx.sessionPersistence`.
+2. Use the `SessionPersistence` type from `@deepseek-ai/dsh-session-persistence` for service annotations. Replace concrete-class `instanceof` checks and subclasses with consumers of that service; the concrete JSONL class is private.
+3. Await plugin startup and confirm a session can be created, flushed, and reopened. Register asynchronous consumer cleanup in the scope that injects `sessionPersistence` so backend unloading waits for it.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JSONL 持久化使用插件命名空间导入；直接构造服务类和类类型标注需要改用持久化服务。"
+---
+
+# 通过插件挂载 JSONL 持久化
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-persistence-jsonl` 通过命名导出的 `name`、`Config` 和 `apply` 提供函数插件，没有默认导出。默认导入、直接构造、继承、`instanceof` 和类类型标注会受到影响。插件会保留监听器和句柄，直到移除该提供者所触发的消费者卸载完成；根作用域的并发卸载仍不保证顺序。`sessionPersistence` 服务 API、YAML 配置和存储文件保持不变。
+
+## 迁移
+
+1. 将默认导入替换为 `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`。现有的 `ctx.plugin(JsonlSessionPersistence, config)` 调用仍然有效；将直接构造改为该挂载调用。动态导入直接使用 `await import(...)` 返回的模块命名空间，不再取其 `.default`。消费者声明 `inject: ['sessionPersistence']` 并访问 `ctx.sessionPersistence`。
+2. 服务类型标注使用 `@deepseek-ai/dsh-session-persistence` 的 `SessionPersistence` 类型。将针对具体类的 `instanceof` 检查和子类改为消费该服务；具体 JSONL 类是私有的。
+3. 等待插件启动完成，确认能够创建、flush 并重新打开会话。将消费者的异步清理注册到注入 `sessionPersistence` 的作用域中，以便后端卸载时等待它完成。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/mock-messages-events/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "Messages mock streams publish named SSE events for native SDK consumers."
+---
+
+# Read named events from the Messages mock server
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The next release makes `@deepseek-ai/dsh-llm-mock-server` emit the Messages event name beside each structured SSE payload. Native SDKs require these names to process message and content-block events. Consumers that accept only unnamed SSE messages must update their event handling. Scripted payloads, ordering, request capture, and chunk counts are unchanged; the deliberately malformed JSON behavior still sends its invalid data directly.
+
+## Migration
+
+1. Consume the named Messages events and parse their `data` fields. Do not filter the stream to unnamed events.
+2. Verify a complete text response, tool-call response, and the fault behaviors your test uses. The [mock server reference](../../../../packages/test-support/llm-mock-server/README.md) describes the available scripts.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/mock-messages-events/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "Messages 模拟流为原生 SDK 消费方发布具名 SSE 事件。"
+---
+
+# 读取 Messages 模拟服务器的具名事件
+
+[English](guide.md) | 中文
+
+## 变更
+
+下一版本的 `@deepseek-ai/dsh-llm-mock-server` 在每个结构化 SSE 载荷旁发送 Messages 事件名。原生 SDK 需要这些名称才能处理消息与内容块事件。只接受无名 SSE 消息的消费方必须更新事件处理。脚本载荷、顺序、请求捕获与分片计数保持不变；刻意生成畸形 JSON 的行为仍直接发送无效数据。
+
+## 迁移
+
+1. 消费具名 Messages 事件并解析其 `data` 字段。不要将流过滤为仅含无名事件。
+2. 验证完整文本响应、工具调用响应和测试使用的故障行为。[模拟服务器参考](../../../../packages/test-support/llm-mock-server/README.zh.md)说明了可用脚本。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools/guide.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Claude Code and Codex bundles add global delegation tools while retaining their package and row identities."
+---
+
+# Native subagent bundles include global tools
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-subagent-claude-code` and `@deepseek-ai/dsh-subagent-codex` keep their package names, bundle selections, provider row IDs, configuration, and native authentication. A selected bundle now also registers its delegation tool as a Host global tool, visible to every preset including minimal; previously the bundle registered only its provider. Live Agents see the tool from their next request after the bundle is enabled, and lose it after the bundle is switched off.
+
+The contributed Host rows are `tool-subagent-claude-code` and `tool-subagent-codex`. Later user layers can override their configuration or disabled state by row id. An override does not select an unselected bundle. A preset that registers its own tool with the same name shadows the global tool for its Agents.
+
+Delegation follows the shared managed-activation API: the tool returns a child ID, and completion arrives as a logged notice to the parent Agent. Remove obsolete `backgroundMode` settings; `maxDepth: provider-managed` remains supported for these native providers.
+
+## Migration
+
+1. Preserve selected bundle names, provider configuration, and authentication. Existing provider-only packages need **Update** in Plugins → Official to receive the tool-contributing bundle; restart when requested. To adopt a new provider, enable its card. [Installation targets](../../../../packages/boot/plugin-manager/README.md#use-this-package) follow the published DSH version or source checkout; equal version strings do not make an older registry package equivalent to a development link. Off only deselects; Remove remains separate.
+2. Configure the tool with an ordinary row patch. Configuration overrides still replace the complete configuration. For example, this keeps the Codex tool disabled while the provider stays registered:
+
+   ```yaml
+   - id: tool-subagent-codex
+     disabled: true
+   ```
+
+3. If a manual Host row registers the same tool name, remove that redundant row or disable the bundle's row. Verify the effective tool catalog in a Session.
+4. Plugin clients receive required `BundleInfo.official` and `BundleInfo.availability` fields; detail-slot `PluginPackageRef` receives them too. `official` identifies project maintenance, `availability` reports `installation`, `profile`, or `missing`, and `installed` still means a profile dependency declaration. Detail-slot readers that only display existing fields need no changes; constructors and exact validators must include the new fields. Optional `installTarget` identifies the offered version and registry or local-link spec.
+
+**Other profiles.** The bundle layers insert Host rows only, so headless, SDK, ACP, and custom profiles can select them as well. Profiles that keep the provider package without selecting its bundle can compose the same rows using the [Codex](../../../../packages/subagent/subagent-codex/README.md#exposing-the-tool) or [Claude Code](../../../../packages/subagent/subagent-claude-code/README.md#exposing-the-tool) example.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools/guide.zh.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Claude Code 与 Codex bundle 添加全局委派工具，同时保留包名和行标识。"
+---
+
+# 原生子代理 bundle 包含全局工具
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-subagent-claude-code` 和 `@deepseek-ai/dsh-subagent-codex` 保留包名、bundle 选择、提供方行 ID、配置及原生认证。已选中的 bundle 现在还会把委派工具注册为 Host 全局工具，包括 minimal 在内的所有预设都可见；此前 bundle 只注册提供方。启用 bundle 后，运行中的 Agent 从下一次请求起即可看到该工具；关闭后则不再可见。
+
+贡献的 Host 行为 `tool-subagent-claude-code` 和 `tool-subagent-codex`。后续用户层可以按行 ID 覆盖其配置或禁用状态。覆盖不会选中未选中的 bundle。预设自行注册的同名工具会为其 Agent 遮蔽该全局工具。
+
+委派遵循共享的托管 activation API：工具返回子级 ID，完成结果通过已记录的通知发送给父 Agent。移除已废弃的 `backgroundMode` 设置；这些原生提供方仍支持 `maxDepth: provider-managed`。
+
+## 迁移
+
+1. 保留已选中的 bundle 名称、提供方配置和认证。已有仅提供方的包需要在插件 → 官方中**更新**才能获得贡献工具的 bundle；按提示重启。要使用新的提供方，启用其卡片。[安装目标](../../../../packages/boot/plugin-manager/README.zh.md#use-this-package)对应已发布的 DSH 版本或源码 checkout；版本字符串相同不代表旧注册表包等同于开发链接。关闭只取消选择；删除仍为独立操作。
+2. 使用普通行补丁配置该工具。配置覆盖仍会替换整份配置。例如，以下补丁在保留提供方注册的同时禁用 Codex 工具：
+
+   ```yaml
+   - id: tool-subagent-codex
+     disabled: true
+   ```
+
+3. 如果手动的 Host 行注册了同名工具，移除该重复行，或禁用 bundle 的贡献行。在 Session 中验证有效工具目录。
+4. 插件客户端收到必填的 `BundleInfo.official` 和 `BundleInfo.availability` 字段；详情 slot 的 `PluginPackageRef` 也会收到它们。`official` 标识项目维护，`availability` 表示 `installation`、`profile` 或 `missing`，`installed` 仍表示 profile 的依赖声明。只展示已有字段的详情 slot 读取方无需修改；构造方和精确校验器必须包含新增字段。可选的 `installTarget` 标识所提供的版本及注册表或本地链接 spec。
+
+**其他 profile。** 这些 bundle 层只插入 Host 行，因此 headless、SDK、ACP 和自定义 profile 也可以选择它们。保留提供方包而不选择其 bundle 的 profile，可以参考 [Codex](../../../../packages/subagent/subagent-codex/README.zh.md#exposing-the-tool) 或 [Claude Code](../../../../packages/subagent/subagent-claude-code/README.zh.md#exposing-the-tool) 示例组合相同的行。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "New Session creates a fresh Agent instead of reusing an existing empty Session."
+---
+
+# Start a fresh Agent with New Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In Web and Desktop, New Session creates a fresh Session and Agent using the current preset definition. It previously reused an existing empty Session in the workspace, which could retain an earlier preset definition.
+
+Client calls to `uiWorkspace.startSession(workspaceId)` follow the same behavior. Workspace reconnection through `openWorkspace` or `connectWorkspace` still reuses an eligible blank. Calls with draft-preparation options preserve their existing reuse and content rules. Existing Agents retain their preset composition; global optional tools update on their next request when a bundle is switched.
+
+## Migration
+
+1. After changing a preset definition, use New Session to create an Agent with the current definition. Continue in an existing Session when its retained preset composition is intentional.
+2. Client integrations that reconnect a workspace should use `openWorkspace` or `connectWorkspace`. Keep explicit draft-preparation options when preparing an existing draft.
+3. Confirm that the new Agent uses the updated preset definition; no persisted Session files or profile patches need rewriting.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "新会话会创建新的 Agent，不再复用已有空 Session。"
+---
+
+# 通过新会话创建新的 Agent
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 Web 和 Desktop 中，新会话按当前预设定义创建新的 Session 和 Agent。此前该操作会复用工作区内已有的空 Session，因而可能保留较早的预设定义。
+
+客户端调用 `uiWorkspace.startSession(workspaceId)` 采用相同行为。通过 `openWorkspace` 或 `connectWorkspace` 重连工作区时仍复用符合条件的空 Session。带草稿准备选项的调用保留已有复用与内容规则。已有 Agent 保留其预设组合；切换组合包后，全局可选工具会在其下一次请求时更新。
+
+## 迁移
+
+1. 更改预设定义后，通过新会话创建使用当前定义的 Agent。需要保留原预设组合时，继续使用已有 Session。
+2. 重连工作区的客户端集成应使用 `openWorkspace` 或 `connectWorkspace`。准备已有草稿时保留显式草稿准备选项。
+3. 确认新 Agent 使用更新后的预设定义；无需重写持久化 Session 文件或 profile patch。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/plugin-option-placement/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "dsh plugin reads --profile only before the forwarded pnpm arguments and prints its own help."
+---
+
+# `dsh plugin` option placement
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`dsh plugin` reads `--profile` only before the forwarded pnpm arguments, which start at the first token it does not recognize, and it has its own help. Previously it accepted `--profile <name>` anywhere on the command line, had no help of its own, and forwarded `-h` and `--help` to pnpm from any position.
+
+When the forwarded arguments begin with the pnpm command, everything after that command now reaches pnpm verbatim, including `-h`, `--help`, and `--profile`. In any other position, including after a leading pnpm option such as `--filter <selector>`, `-h` or `--help` prints the `dsh plugin` help and exits 0. Scripts that place `--profile` after the pnpm command or after a leading pnpm option fail with `required option '--profile <name>' not specified`, and `dsh plugin --profile <name> --help` no longer prints pnpm's help.
+
+## Migration
+
+1. Move `--profile <name>` before every pnpm argument: replace `dsh plugin add <package> --profile <name>` with `dsh plugin --profile <name> add <package>`.
+2. Request pnpm's help for one command after that command, with any pnpm options after it too, as in `dsh plugin --profile <name> add --help`. For pnpm's general help, forward `help`: `dsh plugin --profile <name> help`.
+3. Confirm that `dsh plugin --help` prints `Usage: dsh plugin [options] [args...]` and that the commands from steps 1 and 2 reach pnpm.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/plugin-option-placement/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "dsh plugin 只在被转发的 pnpm 参数之前读取 --profile，并提供自己的帮助。"
+---
+
+# `dsh plugin` 选项位置
+
+[English](guide.md) | 中文
+
+## 变更
+
+`dsh plugin` 只在被转发的 pnpm 参数之前读取 `--profile`，被转发的参数从它无法识别的第一个 token 开始；它还提供自己的帮助。此前它接受出现在命令行任意位置的 `--profile <name>`，没有自己的帮助，并且无论 `-h` 和 `--help` 位于何处都会转发给 pnpm。
+
+被转发的参数以 pnpm 命令开头时，该命令之后的所有内容现在都会原样交给 pnpm，包括 `-h`、`--help` 和 `--profile`。在其他任何位置，包括位于 `--filter <selector>` 等开头的 pnpm 选项之后，`-h` 或 `--help` 都会打印 `dsh plugin` 的帮助并以 0 退出。把 `--profile` 写在 pnpm 命令或开头的 pnpm 选项之后的脚本会因 `required option '--profile <name>' not specified` 而失败，`dsh plugin --profile <name> --help` 也不再打印 pnpm 的帮助。
+
+## 迁移
+
+1. 把 `--profile <name>` 移到所有 pnpm 参数之前：将 `dsh plugin add <package> --profile <name>` 改为 `dsh plugin --profile <name> add <package>`。
+2. 查看某个 pnpm 命令的帮助时，把帮助选项和其他 pnpm 选项都写在该命令之后，例如 `dsh plugin --profile <name> add --help`。查看 pnpm 的总体帮助时转发 `help`：`dsh plugin --profile <name> help`。
+3. 确认 `dsh plugin --help` 打印 `Usage: dsh plugin [options] [args...]`，并且第 1、2 步中的命令能够到达 pnpm。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/python-optional-resources/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Python runtime wheels require explicit downloads for Office conversion and bundled authoring environments."
+---
+
+# Download optional Python runtime resources explicitly
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Python runtime wheels omit the Office sidecar and authoring interpreters and libraries. SDK startup does not download them. Office operations require an explicit download; the authoring environment and conversion engine can be selected independently. The SDK still packages the normal `dsh` CLI and requires no system Node.js.
+
+## Migration
+
+1. Before processing Office files, call `deepseek_harness_runtime.download_office()`. Before using the bundled authoring environment, call `deepseek_harness_runtime.download_primary_runtime()`. Both reuse completed caches and return absolute paths.
+2. For offline deployment, prepare the cache with the matching runtime release on the target platform and copy it to that platform's deployment. Set `DSH_RESOURCE_CACHE` to its absolute root before downloads and SDK startup. See the [runtime reference](../../../../python/sdk-runtime/README.md).
+3. Start the SDK and confirm the required resources are available. `deepseek_harness_runtime.resolve_office_launch_args()` checks the Office CLI paths without downloading. Existing `DSH_PRIMARY_RUNTIME` paths remain supported; an empty value disables the authoring query. Profile patches can independently disable `skill-office`.