dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-rc.1/terminal-backend-cleanup-error/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "TerminalBackendCleanupError 改为继承 TerminalError 而非 AggregateError，并带 CLEANUP_FAILED 错误码。"
+---
+
+# `TerminalBackendCleanupError` 改为继承 `TerminalError`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-terminal` 导出的 `TerminalBackendCleanupError` 由 PTY 后端在启动失败且清理部分资源也失败时抛出。它原先继承 `AggregateError`，现在继承 `TerminalError`，因此是带 code `CLEANUP_FAILED` 的 `HarnessError`，携带它的工具结果会记录 `error.name` `TerminalBackendCleanupError` 和 `error.code` `CLEANUP_FAILED`。构造函数、`name`、`spawnError`、`cleanupError` 以及按原顺序排列的 `errors` 列表不变；`errors` 的类型由 `any[]` 改为 `readonly unknown[]`。`cause` 新增为同样两个失败组成的 `AggregateError`。`error instanceof AggregateError` 现在为 `false`。
+
+只构造该错误、读取 `spawnError` 或 `cleanupError`、或检查 `instanceof TerminalBackendCleanupError` 的后端与消费方不受影响。
+
+## 迁移
+
+1. 把针对该错误的 `error instanceof AggregateError` 检查改为 `error instanceof TerminalBackendCleanupError`，或对 `TerminalError` 检查 `error.code === 'CLEANUP_FAILED'`。
+2. TypeScript 代码未经收窄就读取 `error.errors` 元素成员时，先收窄每个 `unknown` 元素，或改为读取 `spawnError` 与 `cleanupError`。
+3. 在消费项目中运行 `pnpm exec tsc --noEmit` 确认通过，并检查启动清理失败仍会进入原有的处理路径。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/terminal-bundle-sidebar-backend/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The experimental terminal bundle opens Agent terminals in the Web sidebar and replaces its optional-terminal-bash and optional-terminal-pwsh rows with optional-terminal-panel."
+---
+# Persistent terminals open in the Web sidebar
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The **Persistent terminals** bundle (`@deepseek-ai/dsh-experimental-terminal-bundle`) used to run Agent terminals through `@deepseek-ai/dsh-terminal-bash`: a profile-free Bash on POSIX and PowerShell on Windows, invisible to the person, with sandbox-mode changes refused while one was open. Its `optional-persistent-terminals` group now mounts [`@deepseek-ai/dsh-terminal-panel`](../../../../packages/experimental/terminal-panel/README.md) instead. Each `terminal_open` becomes a sidebar tab running the execution environment's default shell with the person's startup files, or `pwsh` then `powershell` on Windows; the person can type into it and take it over. The bundle also registers `user_terminal_list` and `user_terminal_read`, and it requires the Web or Desktop composition, which mounts the terminal controller.
+
+Profile patches that target the removed `optional-terminal-bash` or `optional-terminal-pwsh` rows, or that configure `@deepseek-ai/dsh-terminal-bash` options such as `pollIntervalMs` through them, no longer apply. Headless or other compositions without the terminal controller no longer get a working `shell` backend from this bundle.
+
+## Migration
+
+1. In your profile patch (`cordis.patch.yml`), remove entries for the ids `optional-terminal-bash` and `optional-terminal-pwsh`. To tune the new backend, target `optional-terminal-panel` with [its configuration fields](../../../../packages/experimental/terminal-panel/README.md#use-this-package), for example `config: { timeoutMs: 60000 }` or `config: { readUserTerminals: false }`.
+2. For headless use, mount `@deepseek-ai/dsh-terminal`, `@deepseek-ai/dsh-terminal-bash` and `@deepseek-ai/dsh-tool-terminal` in your own patch instead of enabling the bundle.
+3. Confirm the migration by keeping `@deepseek-ai/dsh-experimental-terminal-bundle` in `dsh.profile.bundles` of `$DSH_HOME/profiles/<name>/package.json`, restarting that profile, and asking the Agent to open a terminal: a tab with an **Agent** badge appears in the sidebar.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/terminal-bundle-sidebar-backend/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "实验终端 bundle 改为在 Web 侧栏打开 Agent 终端，并用 optional-terminal-panel 行替换 optional-terminal-bash 和 optional-terminal-pwsh 行。"
+---
+# 持久终端改为在 Web 侧栏打开
+
+[English](guide.md) | 中文
+
+## 变更
+
+**持久终端** bundle（`@deepseek-ai/dsh-experimental-terminal-bundle`）原先通过 `@deepseek-ai/dsh-terminal-bash` 运行 Agent 终端：POSIX 上是不加载配置文件的 Bash，Windows 上是 PowerShell，人看不到这些终端，而且有终端打开时会拒绝切换沙箱模式。现在它的 `optional-persistent-terminals` 分组改为挂载 [`@deepseek-ai/dsh-terminal-panel`](../../../../packages/experimental/terminal-panel/README.zh.md)。每次 `terminal_open` 都会成为一个侧栏标签页，运行执行环境的默认 shell 并加载人的启动文件，Windows 上依次优先 `pwsh` 和 `powershell`；人可以在其中输入并接管。该 bundle 还会注册 `user_terminal_list` 和 `user_terminal_read`，并且需要挂载终端控制器的 Web 或 Desktop 组合。
+
+针对已移除的 `optional-terminal-bash` 或 `optional-terminal-pwsh` 行的 profile patch，以及借这些行配置 `@deepseek-ai/dsh-terminal-bash` 选项（例如 `pollIntervalMs`）的 patch，都不再生效。没有终端控制器的 headless 或其他组合，不再能从这个 bundle 得到可用的 `shell` 后端。
+
+## 迁移
+
+1. 在 profile patch（`cordis.patch.yml`）中删除针对 id `optional-terminal-bash` 和 `optional-terminal-pwsh` 的条目。如需调整新后端，请以 `optional-terminal-panel` 为目标，使用[它的配置字段](../../../../packages/experimental/terminal-panel/README.zh.md#use-this-package)，例如 `config: { timeoutMs: 60000 }` 或 `config: { readUserTerminals: false }`。
+2. 在 headless 中使用时，不要启用该 bundle，而是在自己的 patch 中挂载 `@deepseek-ai/dsh-terminal`、`@deepseek-ai/dsh-terminal-bash` 和 `@deepseek-ai/dsh-tool-terminal`。
+3. 确认 `$DSH_HOME/profiles/<name>/package.json` 的 `dsh.profile.bundles` 中保留 `@deepseek-ai/dsh-experimental-terminal-bundle`，重启该 profile，再让 Agent 打开一个终端，侧栏中出现带 **Agent** 徽标的标签页，即说明迁移完成。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/web-fetch-transport-error-codes/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Local HTTP fetch transport failures raise classified WEB_FETCH_* codes instead of WEB_PROVIDER_ERROR."
+---
+
+# Local HTTP fetch transport failures use classified codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The local HTTP fetch provider (`dsh-web-fetch-http`) previously raised `WEB_PROVIDER_ERROR` with the text `web fetch failed: TypeError: fetch failed` for every network failure before or during the response. It now raises one of `WEB_FETCH_DNS_FAILED`, `WEB_FETCH_CONNECTION_REFUSED`, `WEB_FETCH_CONNECTION_TIMEOUT`, `WEB_FETCH_CERTIFICATE_INVALID`, `WEB_FETCH_CONNECTION_INTERRUPTED`, `WEB_FETCH_NETWORK_UNREACHABLE`, or `WEB_FETCH_NETWORK_ERROR` for an unrecognized failure. The message names the failure class, the system error code, and the underlying error. The same code appears in the `error.code` of new `web_fetch` tool results. Callers of `ctx.web.fetch()` and readers of tool-result error codes that match `WEB_PROVIDER_ERROR` for network failures are affected. Other providers, and other `dsh-web-fetch-http` failures, are unchanged.
+
+## Migration
+
+1. Where code routes local fetch network failures on `WEB_PROVIDER_ERROR`, match the seven codes above instead.
+2. Do not parse the message text; it is diagnostic and may change.
+3. Confirm by fetching an unresolvable host, such as `http://example.invalid/`, and checking that the error code is `WEB_FETCH_DNS_FAILED`.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/web-fetch-transport-error-codes/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "本地 HTTP 抓取的传输故障改为抛出分类后的 WEB_FETCH_* 代码，而不是 WEB_PROVIDER_ERROR。"
+---
+
+# 本地 HTTP 抓取的传输故障使用分类代码
+
+[English](guide.md) | 中文
+
+## 变更
+
+本地 HTTP 抓取提供方（`dsh-web-fetch-http`）以前在响应之前或响应期间遇到任何网络故障时，都会抛出 `WEB_PROVIDER_ERROR`，文本为 `web fetch failed: TypeError: fetch failed`。现在它会抛出 `WEB_FETCH_DNS_FAILED`、`WEB_FETCH_CONNECTION_REFUSED`、`WEB_FETCH_CONNECTION_TIMEOUT`、`WEB_FETCH_CERTIFICATE_INVALID`、`WEB_FETCH_CONNECTION_INTERRUPTED`、`WEB_FETCH_NETWORK_UNREACHABLE` 之一；无法识别的故障则抛出 `WEB_FETCH_NETWORK_ERROR`。错误消息会写明故障类别、系统错误码和底层错误。新的 `web_fetch` 工具结果的 `error.code` 中也会出现相同的代码。受影响的是 `ctx.web.fetch()` 的调用方，以及对网络故障匹配 `WEB_PROVIDER_ERROR` 的工具结果错误码读取方。其他提供方，以及 `dsh-web-fetch-http` 的其他故障，均不受影响。
+
+## 迁移
+
+1. 如果代码按 `WEB_PROVIDER_ERROR` 路由本地抓取的网络故障，改为匹配上述七个代码。
+2. 不要解析错误消息文本；它仅用于诊断，可能会变化。
+3. 抓取一个无法解析的主机（例如 `http://example.invalid/`），确认错误码为 `WEB_FETCH_DNS_FAILED`。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/web-search-billing/guide.md

@@ -0,0 +1,41 @@
+---
+kind: upgrade-guide
+description: "DeepSeek Search and Fetch add per-capability billing and replace provider authentication fields with ordered credential sources."
+---
+
+# DeepSeek web search and fetch choose their credential by billing
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The DeepSeek Search and Fetch APIs (`web-deepseek-api`) previously used the signed-in account only in `deepseek-account` conversations; other conversations required an API key. New `searchBilling` and `fetchBilling` settings accept `auto` (default), `account`, or `api-key`. With `auto`, DeepSeek model routes behave as before; other conversations and operations outside a Session now use the signed-in account when no key exists. `account` uses only the account; `api-key` only the key. Non-empty `*BaseURL` or `*ApiKeyEnv` settings still take precedence. Other providers, including local HTTP fetch, are unaffected.
+
+In TypeScript, `DeepSeekSearchApiOptions` and `DeepSeekFetchApiOptions` lose their top-level `baseURL`. Their `auth` becomes `{ sources, missingCredentialMessage? }`. Each account or API-key source carries its own address; list order replaces the implicit account-first order. Direct provider constructors must migrate.
+
+With an `AbortSignal`, credential-read errors now retain the original `Error` as `cause` and its name in the diagnostic without an extra `Error:` wrapper. A resolver throwing a DOMException named `AbortError` now yields `WEB_ABORTED`, not `WEB_PROVIDER_ERROR`, even when that signal is not aborted. The no-signal path already behaves this way.
+
+## Migration
+
+1. To disable the new account fallback, set both capabilities to `api-key` on the `web-deepseek-api` row, or choose **DeepSeek API key** under **Plugins > Built-in plugin settings > Web search and fetch** when each DeepSeek API is selected:
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-web-deepseek-api'
+     config:
+       searchBilling: api-key
+       fetchBilling: api-key
+   ```
+
+   This also disables account billing in account conversations; it does not fully restore the old route-dependent behavior.
+2. Migrate direct `DeepSeekSearchApiProvider` and `DeepSeekFetchApiProvider` constructors. The table describes TypeScript options, not YAML settings:
+
+   | Old option | Replacement |
+   |---|---|
+   | `baseURL: base`, `auth.apiKey: key` | `auth.sources: [{ kind: 'api-key', baseURL: base, key }]` |
+   | `auth.resolveApiKey`, `auth.apiKeyEnv` | An API-key source with `key: { ref, configured, resolve }`. Keep the reference (`DEEPSEEK_API_KEY` when omitted); `configured()` checks presence without reading the value, and `resolve()` reads it. |
+   | `auth.account` | `{ kind: 'account', ...account }`; preserve its address and callbacks. Place it before the Key source to retain account-first behavior. |
+   | `auth.missingKeyMessage` | `auth.missingCredentialMessage` |
+   | `auth.invalidRoute` | `{ kind: 'misconfigured', message }` at the position of the invalid source; it fails only when reached. |
+
+3. Update error handling to recognize resolver `AbortError` as cancellation. Do not depend on the extra error wrapper or its diagnostic prefix.
+4. Confirm migrated constructors type-check. With the DeepSeek APIs selected and `api-key` billing, missing keys withhold their tools; configured keys allow requests. Local HTTP fetch remains unaffected.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/web-search-billing/guide.zh.md

@@ -0,0 +1,41 @@
+---
+kind: upgrade-guide
+description: "DeepSeek Search 与 Fetch 新增按能力选择的计费方式，并将提供方认证字段替换为有序凭据来源。"
+---
+
+# DeepSeek 网页搜索与获取按计费方式选择凭据
+
+[English](guide.md) | 中文
+
+## 变更
+
+DeepSeek Search 与 Fetch API（`web-deepseek-api`）过去只在 `deepseek-account` 会话中使用已登录账号；其他会话需要 API 密钥。新增的 `searchBilling` 与 `fetchBilling` 设置接受 `auto`（默认）、`account` 或 `api-key`。在 `auto` 下，DeepSeek 模型路由的行为不变；其他会话与会话之外的操作在没有密钥时改用已登录账号。`account` 只使用账号，`api-key` 只使用密钥。非空的 `*BaseURL` 或 `*ApiKeyEnv` 设置仍然优先。其他提供方（包括本地 HTTP 抓取）不受影响。
+
+在 TypeScript 中，`DeepSeekSearchApiOptions` 与 `DeepSeekFetchApiOptions` 移除了顶层 `baseURL`。其 `auth` 改为 `{ sources, missingCredentialMessage? }`。每个账号或 API 密钥来源携带自己的地址；列表顺序替代隐式的账号优先顺序。直接调用提供方构造函数的代码需要迁移。
+
+传入 `AbortSignal` 时，凭据读取错误现在保留原始 `Error` 作为 `cause`，诊断也保留其名称，不再额外包装一层 `Error:`。解析函数抛出名为 `AbortError` 的 DOMException 时，即使该 signal 未取消，现在也返回 `WEB_ABORTED`，而非 `WEB_PROVIDER_ERROR`。未传 signal 的路径原本就采用此行为。
+
+## 迁移
+
+1. 要禁用新增的账号回退，在 `web-deepseek-api` 行把两个能力都设为 `api-key`；也可以在**插件 > 内置插件配置 > 网页搜索与获取**中，选中相应的 DeepSeek API 后选择 **DeepSeek API Key**：
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-web-deepseek-api'
+     config:
+       searchBilling: api-key
+       fetchBilling: api-key
+   ```
+
+   这也会禁用账号会话中的账号计费，并不能完全恢复原来按路由选择的行为。
+2. 迁移直接调用 `DeepSeekSearchApiProvider` 与 `DeepSeekFetchApiProvider` 构造函数的代码。下表描述 TypeScript 选项，而非 YAML 设置：
+
+   | 原选项 | 替换方式 |
+   |---|---|
+   | `baseURL: base`、`auth.apiKey: key` | `auth.sources: [{ kind: 'api-key', baseURL: base, key }]` |
+   | `auth.resolveApiKey`、`auth.apiKeyEnv` | API 密钥来源的 `key: { ref, configured, resolve }`。保留原引用（省略时为 `DEEPSEEK_API_KEY`）；`configured()` 只检查是否存在，不读取值，`resolve()` 读取值。 |
+   | `auth.account` | `{ kind: 'account', ...account }`；保留其地址和回调。放在 Key 来源之前可保留账号优先行为。 |
+   | `auth.missingKeyMessage` | `auth.missingCredentialMessage` |
+   | `auth.invalidRoute` | 在无效来源的位置放置 `{ kind: 'misconfigured', message }`；只有轮到该项才失败。 |
+
+3. 更新错误处理，将解析函数的 `AbortError` 识别为取消。不要依赖额外的错误包装层或其诊断前缀。
+4. 确认迁移后的构造代码通过类型检查。选中 DeepSeek API 并使用 `api-key` 计费时，缺少密钥会隐藏相应工具；配置密钥后可以发请求。本地 HTTP 抓取不受影响。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Custom Client overlays that relied on global macOS no-drag exclusions must declare their window regions."
+---
+
+# Explicit window regions for custom Client overlays
+
+English | [中文](guide.zh.md)
+
+## Change
+
+After upgrading from 0.2.2-rc.1, macOS Desktop automatically excludes interactive controls only inside `data-window-drag` rows or `data-window-drag-controls` scopes. Previously, matching controls and ARIA roles anywhere in the application received `no-drag`. Custom Client plugins that relied on that rule for content covering a draggable header must now declare an exclusion. Ordinary scrollable content without an explicit region declaration contributes no region, so content clipped above its viewport no longer blocks header dragging.
+
+This affects custom overlays outside those scopes that cover a drag row. Controls already inside a marked row, overlays using shared primitives with their own exclusions, and components with explicit `no-drag` declarations need no migration. The rule applies only to macOS Desktop; plain Web and Windows behavior is unchanged.
+
+## Migration
+
+1. Inspect the JSX and CSS Modules of custom Client overlays that can cover a header. Check whether their interactive content relied on the previous automatic exclusion.
+2. For an interactive viewport without nested drag rows, put `data-window-drag-exclude` on its visible viewport element. This excludes the viewport's own rectangle and keeps clipped descendants out of the region calculation. For a container whose controls need separate exclusions, put `data-window-drag-controls` on their containing element. Overlays and containers with nested drag rows must declare their regions separately; follow the [window-region rules](../../../../packages/client/web/README.md#understand-the-implementation).
+3. Keep exclusions on visible owners rather than every focusable descendant. Use a shared `Modal` or `MenuSurface` for the corresponding overlay, or explicitly exclude the custom overlay's visible box. A body portal with no layout box needs an exclusion on its visible content.
+4. Load the updated plugin in macOS Desktop. Open the overlay over a header and confirm its controls act without dragging the window. Close it and confirm the header's blank area still drags; scroll the plugin's content out of view and confirm that clipped content does not block the header.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "依赖 macOS 全局 no-drag 排除的自定义 Client 浮层必须声明自己的窗口区域。"
+---
+
+# 自定义 Client 浮层显式声明窗口区域
+
+[English](guide.md) | 中文
+
+## 变更
+
+从 0.2.2-rc.1 升级后，macOS Desktop 仅自动排除 `data-window-drag` 行或 `data-window-drag-controls` 范围内的交互控件。此前，应用中任意位置匹配的控件和 ARIA role 都会获得 `no-drag`。自定义 Client 插件若依赖该规则使覆盖可拖动页头的内容保持可交互，现在必须声明排除。未显式声明区域的普通滚动内容不贡献区域，因此被裁剪到视口上方的内容不会再阻挡页头拖动。
+
+该变更影响这些范围之外、覆盖拖动行的自定义浮层。已位于标记行内的控件、使用自带排除的共享原语的浮层，以及已显式声明 `no-drag` 的组件无需迁移。规则仅适用于 macOS Desktop，普通 Web 和 Windows 行为不变。
+
+## 迁移
+
+1. 检查可能覆盖页头的自定义 Client 浮层的 JSX 与 CSS Modules，确认其交互内容是否依赖此前的自动排除。
+2. 对不含嵌套拖动行的交互视口，在可见视口元素上添加 `data-window-drag-exclude`。它仅排除视口自身矩形，使被裁剪的子元素不参与区域计算。若容器内的控件需要分别排除，在承载这些控件的元素上添加 `data-window-drag-controls`。浮层和含嵌套拖动行的容器必须单独声明区域，遵循[窗口区域规则](../../../../packages/client/web/README.zh.md#understand-the-implementation)。
+3. 在可见区域所有者上声明排除，不要逐个排除可聚焦子元素。对应浮层采用共享 `Modal` 或 `MenuSurface`，或显式排除自定义浮层的可见矩形。不产生布局矩形的 body portal 需在可见内容上声明排除。
+4. 在 macOS Desktop 加载更新后的插件，将浮层打开到页头上方，确认其控件正常生效且不会拖动窗口。关闭浮层后确认页头空白区域仍可拖动；将插件内容滚出可见区，确认被裁剪内容不会阻挡页头。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/client-module-metadata/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: Client artifact metadata and static library manifests require rebuilding custom browser bundles and updating direct static-artifact consumers.
+---
+
+# Client module metadata
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Client bundle registrations can carry `meta` beside `id`, `factory`, and optional `chunk`. The factory still returns the plugin or library exports. Metadata optionally contains `stylesheets`, a record keyed by each stylesheet's path within the owning package, such as `src/client/App.module.css`; each descriptor has `text(context)`, with `context.asset()` resolving carrier asset URLs. Compiled stylesheet imports no longer install DOM nodes during JavaScript factory execution.
+
+Static Client library index artifacts keep their named exports and add one more, `__$dsh_client_module_manifest`, carrying the same manifest; its factory returns the library's exports without the manifest. Their ESM imports and dynamic imports remain in the final Web build.
+
+Styles of `staticLinked` libraries, including `dsh-client-ui-primitives` and `dsh-client-ui-dockkit`, leave the Web shell's CSS file: the renderer installs them when the application mounts. Their CSS Modules class names change from `_<local>_<hash>` to `<hash>_<local>`. Generated style elements keep `data-plugin` with the owning package, add `data-path` with the stylesheet's path within that package, and no longer carry `data-plugin-css`.
+
+A bundle built with this preset loads on earlier DSH releases without its styles, because they ignore `meta`. Earlier-preset bundles still inject their own `<style data-plugin>` elements, which Modules no longer removes: disabling or live-replacing such a plugin leaves its styles until reload, and an earlier-preset replacement keeps the old text.
+
+The default startup order is unchanged: Modules constructs its Main environment from the existing loading hook, prefetch runs before Loader activation, and renderer installation adds materialized-module styles before the React root. Realm Registry and iframe providers are optional; there is no Isolation or Shadow DOM configuration in this change.
+
+## Migration
+
+1. Rebuild custom Client bundles with the matching `clientBundle` preset. Custom artifact generators that provide compiled CSS expose its descriptors through `meta`; artifacts without metadata can omit it. Do not add metadata to `factory()`'s returned business exports.
+2. Rebuild `staticLinked` libraries and the consuming shell together. Shell assembly reads the `__$dsh_client_module_manifest` export; plugin code keeps its existing package specifiers and obtains exports through the module loader's `require`. Code that enumerates a static library's namespace sees this additional key.
+3. Keep carrier asset resolution available through `context.asset()` when generating stylesheet text. Leave DOM installation to the renderer; module factories no longer own generated style tags.
+4. Verify that registrations do not evaluate metadata, CSS appears before the application root renders, lazy metadata appears only after its module materializes, and module replacement removes or updates the prior styles. The [module reference](../../../../packages/client/modules/README.md) and [renderer reference](../../../../packages/client/ui-renderer/README.md) define ownership and failure behavior.
+5. Replace selectors in custom CSS, user scripts, and tests that match generated class names such as `[class*="_header_"]` with `data-*` attributes or accessible roles, and `style[data-plugin-css]` with `style[data-plugin][data-path]`.
+6. Set the rebuilt plugin's `engines.dsh` minimum to the DSH release with this change. Reload the page after disabling or updating an earlier-preset plugin.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/client-module-metadata/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: Client 产物元信息和静态库 manifest 要求重新构建自定义浏览器 bundle，并更新直接消费静态产物的代码。
+---
+
+# Client 模块元信息
+
+[English](guide.md) | 中文
+
+## 变更
+
+Client bundle 注册可在 `id`、`factory` 和可选 `chunk` 之外携带 `meta`。factory 仍返回插件或库的导出。元信息可包含 `stylesheets`，即以样式在所属包内的路径（如 `src/client/App.module.css`）为键的字典；每份描述具有 `text(context)`，由 `context.asset()` 解析载体资源 URL。编译后的样式 import 不再在 JavaScript factory 执行期间安装 DOM 节点。
+
+静态 Client 库的 index 产物保留原有具名导出，并增加一个携带相同 manifest 的导出 `__$dsh_client_module_manifest`；其 factory 返回不含 manifest 的库导出。ESM import 和动态 import 仍留给最终 Web 构建。
+
+`staticLinked` 库（包括 `dsh-client-ui-primitives` 和 `dsh-client-ui-dockkit`）的样式不再进入 Web 外壳的 CSS 文件，改由 renderer 在应用挂载时安装。它们的 CSS Modules 类名从 `_<local>_<hash>` 变为 `<hash>_<local>`。生成的 style 元素仍以 `data-plugin` 携带所属包名，新增以 `data-path` 携带的包内样式路径，不再带 `data-plugin-css`。
+
+用本预设构建的 bundle 可以在较早的 DSH 版本上加载，但没有样式，因为较早版本会忽略 `meta`。用较早预设构建的 bundle 仍自行插入 `<style data-plugin>` 元素，Modules 不再删除它们：禁用或实时替换这类插件后，其样式保留到页面刷新；替换版本同样由较早预设构建时，页面保留旧样式文本。
+
+默认启动顺序不变：Modules 从原有加载 hook 建立 Main 环境，prefetch 在 Loader 激活前运行，renderer 在 React 根之前安装已物化模块的样式。Realm Registry 与 iframe 提供方是可选的；本次没有 Isolation 或 Shadow DOM 配置。
+
+## 迁移
+
+1. 使用配套版本的 `clientBundle` 预设重新构建自定义 Client bundle。自定义产物生成器通过 `meta` 提供编译 CSS 的描述；没有元信息的产物可省略它。不要把元信息加入 `factory()` 返回的业务导出。
+2. 同时重新构建 `staticLinked` 库和消费它的外壳。外壳组装读取 `__$dsh_client_module_manifest` 导出；插件代码保留原有包标识符，通过模块加载器的 `require` 取得导出。枚举静态库命名空间的代码会看到这个新增的键。
+3. 生成样式文本时通过 `context.asset()` 保留载体资源解析。DOM 安装交给 renderer，模块 factory 不再拥有生成的 style 标签。
+4. 确认登记不会求值元信息、CSS 在应用根渲染前出现、lazy 元信息只在对应模块物化后出现，以及模块替换会移除或更新旧样式。[模块参考](../../../../packages/client/modules/README.zh.md)和 [renderer 参考](../../../../packages/client/ui-renderer/README.zh.md)定义所有权与失败行为。
+5. 自定义 CSS、用户脚本和测试中匹配生成类名的选择器（如 `[class*="_header_"]`）改用 `data-*` 属性或无障碍角色，`style[data-plugin-css]` 改用 `style[data-plugin][data-path]`。
+6. 把重新构建的插件在 `engines.dsh` 中声明的最低版本设为包含本变更的 DSH 版本。禁用或更新用较早预设构建的插件后，刷新页面。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/connection-page-peer/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: WebServer routes require authentication by default, and default Token login moves to a Provider plugin.
+---
+
+# Token Provider and route admission migration
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Default Token verification and HTTP login exchanges move to `@deepseek-ai/dsh-host-authentication-token`. Connection removes BrowserAuth, `authorizeIndex`, `authenticatedUrl`, `requestRejection`, `ConnectionRequestRejection`, `peer(id)`, `createPeer.socketOwned`, `ConnectionAdmission`, and `admitConnection`. Token owns `/api/remote.mux` Socket claims through the post-admission `webserver/upgrade` waterfall. Cookie formats and `/connect` remain; valid v2 Cookies now also authenticate pages, without a page/API `purpose` field.
+
+WebServer registrations now accept `auth: 'anonymous' | 'required' | 'deny'` or a synchronous selector, defaulting to `required`. Previously public handlers, resources, fallbacks, and upgrades need explicit anonymous declarations. HTTP and upgrade handlers receive the admitted Peer as an optional trailing argument; resources keep their Peer argument. Connection source checks also apply to anonymous routes when its listener is active.
+
+## Migration
+
+1. Mount Token beside Connection and Credentials. Manually move `cookieMaxAgeDays` from `connection.config` to `authentication-token.config`. The old location has no effect and is neither migrated nor rejected; leaving Token's value unset uses 30 days.
+2. Audit `webServer.register`, `registerFallback`, and `registerUpgrade` calls. Direct administrative handlers also require an owner Peer. Keep authenticated access for protected routes; declare `auth: 'anonymous'` for credential-free assets and login endpoints, and `auth: 'deny'` for blocked routes. Convert a bare fallback handler to `{ handler, auth }` when changing its policy. Check `trustedHosts` for every intended authority, including public assets.
+3. Remove page adapters' `purpose` and repeated authentication calls. Consume the Peer passed to `(req, res, peer?)`, `(req, socket, head, peer?)`, or `resource(request, peer?)`. Render protected pages for that Peer. Trusted in-process `readResource(request, peer)` still uses its explicit Peer without source or Cookie checks, but respects `deny`.
+4. Keep `printUrl`, `openBrowser`, and `publicUrl` on WebApp. After readiness, WebApp emits `webserver/entry-url(baseUrl, entries)`; listeners append `{ label, url, open }`. WebApp prints entries in order and opens the first eligible one outside SSH. No entries means no output or opening. Token contributes its signed URL without depending on WebApp. Custom HTTP carriers retain `webserver/request` before routing.
+5. Providers inject `connection` and `connection.authentication`, retain their `createPeer({ principal, interactions })` results, and call `ctx.connection.authentication.register(provider)`. Keep `browserPeer` for trusted in-process use. Use `admit` instead of `requestRejection`. Without an authorization decision, `required` returns 503 and `anonymous` allows access.
+6. Emit all `webserver/*` events with the WebServer as thisArg, including `index-inject` and `entry-url`. Ordinary listeners follow `webServer` isolation; `global: true` opts out. Run upgrade middleware after admission, before protocol handling; await `next()`. Token claims its API Peers only on `/api/remote.mux`.
+7. Verify root Token login, existing Cookies, v2 page access, HTTP/WS, `/connect`, anonymous assets, and source-rejection 403. Duplicate mux Sockets still return 409; closing the owning Socket revokes credentials before Peer disposal. Only root Token queries exchange credentials. Token load failure grants no protected access.
+8. Update custom Desktop shell/Host pairs together: per-process credentials travel over private IPC before ready; main processes use `authenticationCookie` and the ordinary Host URL. Keep credentials out of the renderer. Desktop may also mount Token.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/connection-page-peer/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: WebServer 路由默认要求认证，默认 Token 登录迁入 Provider 插件。
+---
+
+# Token Provider 与路由准入迁移
+
+[English](guide.md) | 中文
+
+## 变更
+
+默认 Token 验证与 HTTP 登录交换迁入 `@deepseek-ai/dsh-host-authentication-token`。Connection 移除 BrowserAuth、`authorizeIndex`、`authenticatedUrl`、`requestRejection`、`ConnectionRequestRejection`、`peer(id)`、`createPeer.socketOwned`、`ConnectionAdmission` 与 `admitConnection`。Token 通过准入后的 `webserver/upgrade` waterfall 拥有 `/api/remote.mux` Socket 认领。Cookie 格式与 `/connect` 保持；有效 v2 Cookie 也可认证页面，不再有页面/API `purpose` 字段。
+
+WebServer 注册新增 `auth: 'anonymous' | 'required' | 'deny'` 或同步选择器，默认 `required`。此前公开的 handler、resource、回退与 upgrade 需要显式声明匿名。HTTP 与 upgrade handler 通过可选末尾参数接收准入 Peer；resource 保留已有 Peer 参数。Connection 监听器活动时，来源检查也适用于匿名路由。
+
+## 迁移
+
+1. 在 Connection 与 Credentials 旁挂载 Token。手动将 `cookieMaxAgeDays` 从 `connection.config` 移到 `authentication-token.config`。旧位置的值不生效，既不会自动迁移，也不会被拒绝；未配置 Token 的值时采用30天。
+2. 检查 `webServer.register`、`registerFallback` 与 `registerUpgrade` 调用。直接管理 handler 还必须要求 owner Peer。受保护路由保持认证要求；免凭据资源与登录端点声明 `auth: 'anonymous'`，禁止访问的路由声明 `auth: 'deny'`。改变裸回退 handler 策略时改为 `{ handler, auth }`。为所有预期 authority 检查 `trustedHosts`，包括公开资源。
+3. 移除页面适配器的 `purpose` 与重复认证调用。使用 `(req, res, peer?)`、`(req, socket, head, peer?)` 或 `resource(request, peer?)` 传入的 Peer，并为该 Peer 渲染受保护页面。可信进程内 `readResource(request, peer)` 仍使用显式 Peer，不检查来源或 Cookie，但遵守 `deny`。
+4. `printUrl`、`openBrowser` 与 `publicUrl` 保留在 WebApp。WebApp 就绪后触发 `webserver/entry-url(baseUrl, entries)`；监听器追加 `{ label, url, open }`。WebApp 按序打印入口，并在非 SSH 下打开首个允许自动打开的入口。没有入口就不输出、不打开。Token 贡献签名 URL，不依赖 WebApp。自定义 HTTP 载体在路由前保留 `webserver/request`。
+5. Provider 注入 `connection` 与 `connection.authentication`，保存 `createPeer({ principal, interactions })` 结果，并调用 `ctx.connection.authentication.register(provider)`。`browserPeer` 保留给可信进程内调用。使用 `admit` 替代 `requestRejection`。无人作出准入决策时，`required` 返回503，`anonymous` 允许访问。
+6. 发起所有 `webserver/*` 事件时传入 WebServer 作为 thisArg，包括 `index-inject` 与 `entry-url`。普通监听器遵循 `webServer` isolation；`global: true` 跳过过滤。在准入后、协议处理前运行 upgrade 中间件，并等待 `next()`。Token 仅在 `/api/remote.mux` 上认领自己的 API Peer。
+7. 验证根 Token 登录、已有 Cookie、v2 页面访问、HTTP/WS、`/connect`、匿名资源及来源拒绝403。重复 mux Socket 仍返回409；所属 Socket 关闭时先撤销凭据，再释放 Peer。只有根 Token query 执行凭据交换。Token 加载失败不授予受保护访问。
+8. 自定义 Desktop shell/Host 一同更新：每进程凭据在 ready 前通过私有 IPC 交付；主进程使用 `authenticationCookie` 与普通 Host URL。凭据不得进入 renderer。Desktop 也可挂载 Token。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cordis-root-and-intercept-metadata/guide.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Cordis 4.0.0-rc.12 replaces ctx.root with ctx[Context.root] and renames the service intercept-metadata API."
+---
+
+# `ctx[Context.root]` replaces `ctx.root`, and service intercept metadata is renamed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/cordis` now carries upstream Cordis 4.0.0-rc.12. Third-party plugins and services written against the previous release are affected:
+
+- `ctx.root` no longer exists. The root context is `ctx[Context.root]`; `Context.root` is a symbol exported on the `Context` class. Inside a plugin, reading `ctx.root` throws `cannot get property "root" without inject`.
+- `Service.config` becomes `Service.metadata`. A service declares its intercept type with `declare [Service.metadata]: T`.
+- `[Service.resolveConfig](base?, head?)` becomes `[Service.resolveIntercept]()`, which takes no arguments.
+- The global symbol `Symbol.for('cordis.metadata')` now keys `Service.metadata`. The method metadata that decorators such as `@Inject()` store moved to `symbols.decorator` (`Symbol.for('cordis.decorator')`).
+- A service's `Config.merge` hook is no longer called. Override `[Service.mergeIntercept](...values)` instead; it receives the values in increasing precedence.
+- Metadata a plugin declares in object-form `inject` now has the lowest precedence. Intercepts added with `ctx.intercept()` override it; previously the injected value overrode them.
+- A context created with `ctx.isolate(name)` no longer falls back to the enclosing plugin's injected `name`. Plugins started under it, and reads after its own provision is withdrawn, throw `cannot get property "<name>" without inject`.
+- A failed `ctx.parallel()` throws an `AggregateError` whose message names the event, and a fiber disposed while it was not active, such as a failed one, now settles to `FiberState.DISPOSED`.
+
+## Migration
+
+1. Replace every `ctx.root` with `ctx[Context.root]`, importing `Context` as a value from `@deepseek-ai/cordis`. Plain JavaScript without the import can read `ctx[Symbol.for('cordis.root')]`.
+2. In service classes, rename `declare [Service.config]` to `declare [Service.metadata]` and calls of `[Service.resolveConfig]()` to `[Service.resolveIntercept]()`. Replace `base` and `head` arguments by declaring the base value in `inject` and adding the override with `ctx.intercept()`.
+3. Where code reads or writes decorator method metadata through `symbols.metadata` or `Symbol.for('cordis.metadata')`, use `symbols.decorator` instead.
+4. Move a `Config.merge` implementation to a `[Service.mergeIntercept](...values)` method on the service class.
+5. Where a plugin relied on its `inject` metadata overriding an ancestor `ctx.intercept()`, set the value with `ctx.intercept()` at the plugin's context instead.
+6. Where code under `ctx.isolate(name)` needs the enclosing plugin's service, provide that service inside the isolated context or start the code from a context that is not isolated.
+7. Run your TypeScript build: references to `ctx.root`, `Service.config` and `Service.resolveConfig` fail to compile. Start the plugin and confirm that services resolve and logs keep their names.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cordis-root-and-intercept-metadata/guide.zh.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Cordis 4.0.0-rc.12 用 ctx[Context.root] 取代 ctx.root，并重命名服务拦截元数据 API。"
+---
+
+# `ctx[Context.root]` 取代 `ctx.root`，服务拦截元数据 API 重命名
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/cordis` 现在包含上游 Cordis 4.0.0-rc.12。针对上一版本编写的第三方插件和服务会受到以下影响：
+
+- `ctx.root` 不再存在。根上下文改为 `ctx[Context.root]`；`Context.root` 是 `Context` 类上导出的 symbol。在插件内读取 `ctx.root` 会抛出 `cannot get property "root" without inject`。
+- `Service.config` 改为 `Service.metadata`。服务用 `declare [Service.metadata]: T` 声明其拦截类型。
+- `[Service.resolveConfig](base?, head?)` 改为不带参数的 `[Service.resolveIntercept]()`。
+- 全局 symbol `Symbol.for('cordis.metadata')` 现在对应 `Service.metadata`。`@Inject()` 等装饰器存储的方法元数据改用 `symbols.decorator`（`Symbol.for('cordis.decorator')`）。
+- 服务的 `Config.merge` 钩子不再被调用。改为重写 `[Service.mergeIntercept](...values)`；它按优先级从低到高接收各个值。
+- 插件在对象形式的 `inject` 中声明的元数据现在优先级最低，用 `ctx.intercept()` 添加的拦截会覆盖它；此前是注入的值覆盖拦截。
+- 用 `ctx.isolate(name)` 创建的上下文不再回退到外层插件注入的 `name`。在其下启动的插件，以及在其自身提供撤回后的读取，都会抛出 `cannot get property "<name>" without inject`。
+- `ctx.parallel()` 失败时抛出的 `AggregateError` 的消息会注明事件名；在非活动状态下被销毁的 fiber（例如失败的 fiber）现在会进入 `FiberState.DISPOSED`。
+
+## 迁移
+
+1. 将所有 `ctx.root` 替换为 `ctx[Context.root]`，并从 `@deepseek-ai/cordis` 以值的形式导入 `Context`。无法导入的纯 JavaScript 可以读取 `ctx[Symbol.for('cordis.root')]`。
+2. 在服务类中，将 `declare [Service.config]` 改为 `declare [Service.metadata]`，将对 `[Service.resolveConfig]()` 的调用改为 `[Service.resolveIntercept]()`。原来的 `base` 参数改为在 `inject` 中声明，`head` 参数改为用 `ctx.intercept()` 添加。
+3. 如果代码通过 `symbols.metadata` 或 `Symbol.for('cordis.metadata')` 读写装饰器的方法元数据，改用 `symbols.decorator`。
+4. 将 `Config.merge` 的实现移到服务类的 `[Service.mergeIntercept](...values)` 方法中。
+5. 如果插件依赖其 `inject` 元数据覆盖祖先的 `ctx.intercept()`，改为在该插件的上下文上用 `ctx.intercept()` 设置该值。
+6. 如果 `ctx.isolate(name)` 之下的代码需要外层插件的服务，在隔离的上下文中提供该服务，或从未隔离的上下文启动这段代码。
+7. 运行 TypeScript 构建：引用 `ctx.root`、`Service.config` 和 `Service.resolveConfig` 的代码会编译失败。启动插件，确认服务可以解析，日志名称保持不变。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cua-agents-without-preset/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "A native CUA provider configured with a preset id now gives Agents without an Agent preset the cua_run_code tool."
+---
+
+# CUA gives Agents without a preset `cua_run_code`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+A native CUA provider whose `agentPreset` is a preset id, including the default `ptc`, registered no tool for an Agent that had joined no Agent preset, and nothing at all in a composition without the preset registry. Such an Agent now receives `cua_run_code` and its operation guidance. Agents on the configured preset still receive raw `cua`, Agents on other presets still receive `cua_run_code`, and `agentPreset: false` still registers raw `cua` globally.
+
+Hosts that create Agents without a preset are affected: the `sdk`, `sdk-minimal`, `headless`, and `acp` profiles and custom compositions. Web and Desktop sessions join a preset and do not change. An affected composition that mounts the provider with a preset id, directly or through the Computer Use bundle, observes:
+
+- The model request gains the `cua_run_code` schema and the CUA guidance.
+- Agent creation waits for the provider's dedicated program runtime; it rejects while that runtime or the `workingDirectory` service is unavailable, for example with `CUA program tool is unavailable`.
+- With `@deepseek-ai/dsh-tool-executor-ptc` mounted on the Host, programs see `tools.cua_run_code` inside `run_code`.
+
+## Migration
+
+1. To keep raw `cua`, called directly or as `tools.cua` under the PTC tool executor, set `agentPreset: false` under the provider entry's `config` in the profile patch or overlay. Preserve its other fields.
+2. To keep Computer Use away from these Agents, disable the provider entry or deselect the Computer Use bundle for that profile.
+3. Start a session and confirm the model's tool list: `cua_run_code` by default, `cua` after step 1, and neither after step 2.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cua-agents-without-preset/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "以 preset ID 配置的原生 CUA 提供方现在为未组合 Agent preset 的 Agent 提供 cua_run_code 工具。"
+---
+
+# CUA 为未组合 preset 的 Agent 提供 `cua_run_code`
+
+[English](guide.md) | 中文
+
+## 变更
+
+原生 CUA 提供方的 `agentPreset` 为 preset ID（包括默认值 `ptc`）时，以前不为未组合 Agent preset 的 Agent 注册工具，在不包含 preset 注册表的组合中则完全不注册。这类 Agent 现在获得 `cua_run_code` 及其操作指引。使用所配置 preset 的 Agent 仍获得原始 `cua`，使用其他 preset 的 Agent 仍获得 `cua_run_code`，`agentPreset: false` 仍全局注册原始 `cua`。
+
+受影响的是创建 Agent 时不组合 preset 的 Host：`sdk`、`sdk-minimal`、`headless` 和 `acp` profile，以及自定义组合。Web 和 Desktop 会话都会组合 preset，行为不变。受影响的组合如果直接或通过 Computer Use 组合包以 preset ID 挂载该提供方，会观察到：
+
+- 模型请求增加 `cua_run_code` 的 schema 和 CUA 指引。
+- 创建 Agent 时等待提供方的专用程序运行时；该运行时或 `workingDirectory` 服务不可用时创建失败，例如报告 `CUA program tool is unavailable`。
+- Host 挂载 `@deepseek-ai/dsh-tool-executor-ptc` 时，程序在 `run_code` 中看到 `tools.cua_run_code`。
+
+## 迁移
+
+1. 如需保留原始 `cua`（直接调用，或在 PTC 工具执行器下作为 `tools.cua` 调用），在 profile patch 或 overlay 的提供方条目 `config` 下设置 `agentPreset: false`，保留其他字段。
+2. 如需让这些 Agent 不使用 Computer Use，禁用提供方条目，或在该 profile 取消选择 Computer Use 组合包。
+3. 启动一个会话，确认模型的工具列表：默认包含 `cua_run_code`，执行第 1 步后包含 `cua`，执行第 2 步后两者都没有。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cua-macos-provider/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Update direct dependencies and configuration overrides for the renamed macOS Computer Use provider."
+---
+
+# macOS Computer Use provider name
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Computer Use bundle picks up the renamed macOS provider automatically. Direct dependencies and overrides use the following names.
+
+| Name | Previous | New |
+|---|---|---|
+| npm package | `@deepseek-ai/dsh-experimental-cua-macos` | `@deepseek-ai/dsh-cua-macos` |
+| Cordis plugin | `experimental-cua-macos` | `cua-macos` |
+| Bundle entry ID | `cua` | `cua-macos` |
+
+## Migration
+
+1. New versions are published under the new npm name. Update direct dependencies and imports to `@deepseek-ai/dsh-cua-macos` and refresh your lockfile. In custom Cordis compositions, update the provider's `name` if it references the old package.
+2. In home or profile `cordis.patch.yml` and other overlays targeting the bundled provider, change `id: cua` to `id: cua-macos`. Keep the whole existing `config`, including any `agentPreset`, `helperPath` or `sourceSigning` values. If an overlay still targets the old bundle entry, `--dump-config` reports `patch: entry "cua" not found` and the Loader skips that override. Source builds then use the default ad-hoc signature unless another entry supplies `sourceSigning`. macOS may ask for permission again after the helper is rebuilt. Custom compositions can keep their own entry IDs.
+3. On macOS with Computer Use enabled, run `dsh --profile web --dump-config` (substitute your profile). Check that the `cua-macos` entry loads the new package and has your expected configuration.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cua-macos-provider/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "更新直接依赖和配置中引用的 macOS Computer Use 提供方名称。"
+---
+
+# macOS Computer Use 提供方名称
+
+[English](guide.md) | 中文
+
+## 变更
+
+Computer Use 组合会自动加载改名后的 macOS 提供方。直接依赖或覆盖配置使用的名称如下。
+
+| 名称 | 旧值 | 新值 |
+|---|---|---|
+| npm 包 | `@deepseek-ai/dsh-experimental-cua-macos` | `@deepseek-ai/dsh-cua-macos` |
+| Cordis 插件 | `experimental-cua-macos` | `cua-macos` |
+| 组合配置行 ID | `cua` | `cua-macos` |
+
+## 迁移
+
+1. 后续版本使用新包名发布。将直接依赖和导入改为 `@deepseek-ai/dsh-cua-macos`，并更新锁文件。如果自定义 Cordis 配置的 `name` 引用了旧包，也要更新。
+2. 如果主目录或配置档的 `cordis.patch.yml` 及其他覆盖配置指向组合提供的 macOS 后端，将 `id: cua` 改为 `id: cua-macos`。保留完整的 `config`，包括已设置的 `agentPreset`、`helperPath` 和 `sourceSigning`。如果仍指向组合的旧配置行，`--dump-config` 会提示 `patch: entry "cua" not found`，Loader 会跳过这条覆盖配置。如果其他配置也没有指定 `sourceSigning`，源码构建会使用默认的临时签名，重新构建 helper 后，macOS 可能再次要求授权。自定义组合可以保留自行指定的配置行 ID。
+3. 在 macOS 上启用 Computer Use 后，运行 `dsh --profile web --dump-config`，将 `web` 换成实际使用的配置档。检查 `cua-macos` 行是否加载了新包，以及各项配置是否符合预期。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cua-partial-observations/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "macOS CUA returns marked partial AX observations and distinguishes observation failures from stale input snapshots."
+---
+# macOS CUA isolates unavailable AX branches
+
+English | [中文](guide.zh.md)
+
+## Change
+
+macOS `getState` previously rejected an entire AX read with `STALE_SNAPSHOT` when one traversed element became invalid. It now returns readable nodes, marks each unavailable branch in `tree` with `[One child could not be read.]`, and sets `hasUnreadableElements: true`. Markers have no element IDs; their contents are unknown. `truncated` still describes traversal limits independently. macOS omits `hasUnreadableElements` when no unreadable node or child-list entry was encountered; other providers may also omit the field.
+
+Invalid top-level roots no longer prevent reading healthy windows. Application-wide observations mark those roots unreadable, and a focus lookup that encounters an invalid root yields a null `focusedWindowId`. An invalid AX object that prevents resolving the requested observation scope returns `AX_OBSERVATION_UNAVAILABLE`. Encountering such an object while discovering an unresolved window or sheet rejects the read instead of publishing an empty complete snapshot. An AX `cannotComplete` failure during observation previously returned `NATIVE_ERROR`; it now also returns `AX_OBSERVATION_UNAVAILABLE`. Both failures retain the failing AX operation and native error code in the message. Permission, application/window identity, cancellation and other errors still reject the read. `STALE_SNAPSHOT` remains the error for expired or mismatched snapshots used by input operations.
+
+## Migration
+
+Update raw-tool consumers to preserve `hasUnreadableElements` and display the branch markers. Only use element IDs returned by the latest successful tree. Use a window screenshot to inspect unavailable contents; an incomplete tree does not establish that a control is absent.
+
+Handle `AX_OBSERVATION_UNAVAILABLE` separately from stale input snapshots. A failed refresh still invalidates the previous snapshot for its scope. Read fresh state or use a screenshot without automatically repeating preceding input. Confirm that a local invalid element returns marked partial state while communication and permission failures remain errors.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/cua-partial-observations/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "macOS CUA 返回带标记的部分 AX 观察，并区分观察失败与输入快照过期。"
+---
+# macOS CUA 隔离不可用的 AX 分支
+
+[English](guide.md) | 中文
+
+## 变更
+
+此前，macOS `getState` 在一个遍历元素失效时会以 `STALE_SNAPSHOT` 拒绝整次 AX 读取。现在返回可读节点，在 `tree` 中用 `[One child could not be read.]` 标记每个不可用分支，并设置 `hasUnreadableElements: true`。标记没有元素 ID，分支内容未知。`truncated` 仍独立表示遍历上限。未遇到不可读节点或子项列表条目时，macOS 省略 `hasUnreadableElements`；其他 provider 也可以省略此字段。
+
+顶层根节点失效不再阻止读取健康窗口。应用级观察将这些根节点标记为不可读，焦点查询遇到失效根节点时，`focusedWindowId` 为 null。观察准备阶段的失效 AX 对象导致请求范围无法确定时，返回 `AX_OBSERVATION_UNAVAILABLE`。发现未解析的窗口或 sheet 时遇到这类对象，读取会失败，不发布空的完整快照。观察期间 AX 返回 `cannotComplete` 时，此前返回 `NATIVE_ERROR`，现在也返回 `AX_OBSERVATION_UNAVAILABLE`。两类失败均在消息中保留失败的 AX 操作和原生错误码。权限、应用或窗口身份、取消及其他错误仍会拒绝读取。输入操作使用过期或不匹配的快照时，仍返回 `STALE_SNAPSHOT`。
+
+## 迁移
+
+更新原始工具调用方，保留 `hasUnreadableElements` 并显示分支标记。只使用最新成功树返回的元素 ID。通过窗口截图查看不可用内容；不完整树不能证明某个控件不存在。
+
+将 `AX_OBSERVATION_UNAVAILABLE` 与输入快照过期分开处理。刷新失败仍会使同一范围的旧快照失效。重新读状态或使用截图，不自动重复此前的输入。确认局部元素失效返回带标记的部分状态，而通信和权限失败仍返回错误。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/deepseek-files-timeout/guide.md

@@ -0,0 +1,15 @@
+---
+kind: upgrade-guide
+description: "Keep a longer image upload deadline on slow DeepSeek gateways."
+---
+# DeepSeek image upload timeout
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The default `filesApiTimeoutMs` falls from 60,000 to 20,000 milliseconds. After an upload times out, the adapter sends inline images for the next request that needs an upload. Further timeouts double the number of requests skipped. A successful upload resets the count.
+
+## Migration
+
+If your gateway needs the previous deadline, set `filesApiTimeoutMs: 60000` on the DeepSeek provider in the active profile’s `cordis.patch.yml`. Existing explicit values take effect as configured. Run `dsh --profile <profile> --dump-config` and check the value on the provider entry.