dsh-plugin-dev-kb 1.6.0 → 1.8.1

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.

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

@@ -0,0 +1,15 @@
+---
+kind: upgrade-guide
+description: "为上传较慢的 DeepSeek 网关保留较长的图片上传时限。"
+---
+# DeepSeek 图片上传时限
+
+[English](guide.md) | 中文
+
+## 变更
+
+`filesApiTimeoutMs` 的默认值从 60,000 毫秒缩短到 20,000 毫秒。上传超时后，下一次需要上传图片的请求直接使用内联图片。连续超时会使跳过的请求次数翻倍，上传成功后清零。
+
+## 迁移
+
+如果网关需要原先的时限，在当前配置的 `cordis.patch.yml` 中为 DeepSeek 提供方设置 `filesApiTimeoutMs: 60000`。已显式设置的值继续生效。运行 `dsh --profile <profile> --dump-config`，检查提供方条目中的值。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/experimental-tool-error-codes/guide.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "Experimental and hook plugin tool failures record error codes, NativeError, OarFailure, and StagehandDrainError become HarnessError subclasses, and browser cleanup rejects with BrowserSessionError."
+---
+
+# Experimental plugin failures carry error codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Tool failures from the CUA, browser-use, Cua Driver, worktree, Ralph, terminal, OAR subagent, Liveshare, Claude Code and Codex hook, and claude-code-mods plugins now record `error: { name, code }` on `tool/result`; previously most of these results had no `error`. The [package READMEs](../../../../packages/experimental/README.md) list each class and code.
+
+Code that handles these failures in-process sees these changes:
+
+- `NativeError` from `@deepseek-ai/dsh-cua` and `OarFailure` from `@deepseek-ai/dsh-experimental-subagent-oar` now extend `HarnessError` from `@deepseek-ai/dsh-error`. `NativeError` keeps its name, codes, and `CODE: message` text. `OarFailure` drops its `stage` and `category` fields; the same summary stays in `message`, and `code` names the stage. Cancellation before an OAR run starts rejects with a `DOMException` named `AbortError` instead of an `OarFailure`.
+- `StagehandDrainError` from `@deepseek-ai/dsh-experimental-browser-use-stagehand-native` now extends `StagehandError` and has the code `STAGEHAND_CLEANUP_FAILED`.
+- `SessionResources.dispose()` from `@deepseek-ai/dsh-experimental-browser-use-runtime` rejects with `BrowserSessionError` (`BROWSER_CLEANUP_FAILED`) whose `cause` is the `AggregateError` it previously threw; `instanceof AggregateError` no longer matches.
+- Liveshare guard functions return `{ reason, info }` instead of a reason string.
+- Argument failures that now throw `ToolArgsError` show `invalid arguments: ` before the message the model sees, and a CUA screenshot request for a model without image input shows `MODEL_DOES_NOT_SUPPORT_IMAGES: ` before its message.
+
+## Migration
+
+1. If analytics or retry rules read `tool/result` `error`, add the new names and codes from the package READMEs. Earlier Session logs keep results without `error`.
+2. Replace `instanceof AggregateError` checks on `SessionResources.dispose()` rejections with `instanceof BrowserSessionError` and read the individual failures from `error.cause.errors`.
+3. Replace reads of `OarFailure.stage` or `category` with `error.code`.
+4. If code catches `HarnessError` before `NativeError`, `OarFailure`, or `StagehandDrainError`, move the specific check first where the handling differs.
+5. Confirm with `pnpm run typecheck` and your own failure-path tests.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/experimental-tool-error-codes/guide.zh.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "Experimental 与 hook 插件的工具失败带上错误 code，NativeError、OarFailure 与 StagehandDrainError 改为 HarnessError 子类，浏览器清理失败改为以 BrowserSessionError 拒绝。"
+---
+
+# Experimental 插件的失败带上错误 code
+
+[English](guide.md) | 中文
+
+## 变更
+
+CUA、browser-use、Cua Driver、worktree、Ralph、终端、OAR 子 agent、Liveshare、Claude Code 与 Codex hook，以及 claude-code-mods 插件的工具失败现在会在 `tool/result` 上记录 `error: { name, code }`；此前这些结果大多没有 `error`。各[包 README](../../../../packages/experimental/README.zh.md) 列出了每个类和 code。
+
+在进程内处理这些失败的代码会看到以下变化：
+
+- `@deepseek-ai/dsh-cua` 的 `NativeError` 与 `@deepseek-ai/dsh-experimental-subagent-oar` 的 `OarFailure` 现在继承 `@deepseek-ai/dsh-error` 的 `HarnessError`。`NativeError` 的 name、code 与 `CODE: message` 文本不变。`OarFailure` 去掉了 `stage` 与 `category` 字段；同样的摘要保留在 `message` 中，`code` 标明阶段。OAR 运行开始前的取消改为以 name 为 `AbortError` 的 `DOMException` 拒绝，不再是 `OarFailure`。
+- `@deepseek-ai/dsh-experimental-browser-use-stagehand-native` 的 `StagehandDrainError` 现在继承 `StagehandError`，code 为 `STAGEHAND_CLEANUP_FAILED`。
+- `@deepseek-ai/dsh-experimental-browser-use-runtime` 的 `SessionResources.dispose()` 改为以 `BrowserSessionError`（`BROWSER_CLEANUP_FAILED`）拒绝，其 `cause` 是此前直接抛出的 `AggregateError`；`instanceof AggregateError` 不再成立。
+- Liveshare 的 guard 函数改为返回 `{ reason, info }`，不再返回原因字符串。
+- 改为抛出 `ToolArgsError` 的参数失败，模型看到的 message 前多了 `invalid arguments: `；为不支持图片输入的模型请求 CUA 截图时，message 前多了 `MODEL_DOES_NOT_SUPPORT_IMAGES: `。
+
+## 迁移
+
+1. 如果分析或重试规则读取 `tool/result` 的 `error`，按包 README 补充新的 name 与 code。较早的 Session 日志中这些结果仍没有 `error`。
+2. 把对 `SessionResources.dispose()` 拒绝值的 `instanceof AggregateError` 检查改为 `instanceof BrowserSessionError`，并从 `error.cause.errors` 读取各个失败。
+3. 把读取 `OarFailure.stage` 或 `category` 的代码改为读取 `error.code`。
+4. 如果代码在 `NativeError`、`OarFailure` 或 `StagehandDrainError` 之前捕获 `HarnessError`，在处理方式不同的地方把具体类的检查移到前面。
+5. 用 `pnpm run typecheck` 和自己的失败路径测试确认迁移完成。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/package-export-cleanup/guide.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: Update removed package subpaths; retained identity constructors remain available.
+---
+
+# Update removed package subpath imports
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Upgrading from v0.2.2-rc.2 removes the seven package subpaths below. Existing identity-only string constructors remain available at retained entrypoints; their implementations and branded type definitions are preserved. The `/types` entries re-export those types without runtime values. Persisted strings, Session formats, validation and ID generation do not change.
+
+| Removed subpath | Type import or supported replacement |
+|---|---|
+| `@deepseek-ai/dsh-commands/brand` | `@deepseek-ai/dsh-commands/types` |
+| `@deepseek-ai/dsh-browser-use/brand` | `@deepseek-ai/dsh-browser-use/types` |
+| `@deepseek-ai/dsh-computer-use/brand` | `@deepseek-ai/dsh-computer-use/types` |
+| `@deepseek-ai/dsh-jobs/brand` | `@deepseek-ai/dsh-jobs/types` |
+| `@deepseek-ai/dsh-llm/brand` | `@deepseek-ai/dsh-llm/types` |
+| `@deepseek-ai/dsh-tools/presentation` | Type imports from `@deepseek-ai/dsh-tools` |
+| `@deepseek-ai/dsh-file-reference-local/search` | The `fileReferences` service; no replacement public search helper |
+
+## Migration
+
+1. Move identifier type imports from the five `/brand` paths to the corresponding `/types` entries, using `import type`. These entries do not replace runtime constructor imports.
+2. For existing constructor calls from the removed paths, commands, jobs and LLM callers can import the retained constructor from the package root. Browser/computer provider-name constructors were not root exports; use `brandString<ProviderName>(value)` with the type from `/types`. Add `@deepseek-ai/dsh-brand` as a direct dependency when importing its runtime helper. Keep validation and UUID/counter generation where they already occur.
+
+   ```ts
+   import { brandString } from '@deepseek-ai/dsh-brand'
+   import type { BrowserUseProviderName } from '@deepseek-ai/dsh-browser-use/types'
+
+   const providerName = brandString<BrowserUseProviderName>('my-browser-provider')
+   ```
+
+3. Compile and run your plugin/SDK tests, then load plain-JavaScript fixtures under Node. Check for `ERR_PACKAGE_PATH_NOT_EXPORTED` and missing named-export errors; TypeScript checking alone does not cover `.mjs` consumers.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/package-export-cleanup/guide.zh.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: 更新已移除的包子路径；保留入口上的标识符构造函数仍可用。
+---
+
+# 更新已移除的包子路径导入
+
+[English](guide.md) | 中文
+
+## 变更
+
+从 v0.2.2-rc.2 升级会移除下列七个包子路径。既有字符串恒等构造函数在保留的入口上仍然可用，其实现和品牌类型定义均保留。`/types` 入口仅再导出这些类型，不导出运行时值。持久化字符串、Session 格式、校验和 ID 生成行为不变。
+
+| 已移除子路径 | 类型导入或受支持的替代方式 |
+|---|---|
+| `@deepseek-ai/dsh-commands/brand` | `@deepseek-ai/dsh-commands/types` |
+| `@deepseek-ai/dsh-browser-use/brand` | `@deepseek-ai/dsh-browser-use/types` |
+| `@deepseek-ai/dsh-computer-use/brand` | `@deepseek-ai/dsh-computer-use/types` |
+| `@deepseek-ai/dsh-jobs/brand` | `@deepseek-ai/dsh-jobs/types` |
+| `@deepseek-ai/dsh-llm/brand` | `@deepseek-ai/dsh-llm/types` |
+| `@deepseek-ai/dsh-tools/presentation` | 从 `@deepseek-ai/dsh-tools` 导入类型 |
+| `@deepseek-ai/dsh-file-reference-local/search` | 使用 `fileReferences` 服务；没有替代的公开搜索辅助值 |
+
+## 迁移
+
+1. 将标识符类型导入从五个 `/brand` 路径移至对应 `/types` 入口，并使用 `import type`。这些入口不能替代运行时构造函数导入。
+2. 对原来从已移除路径调用构造函数的代码，commands、jobs 和 LLM 调用方可以改从包根入口导入保留的构造函数。Browser/computer provider-name 构造函数原本不是根出口，应使用 `brandString<ProviderName>(value)` 并从 `/types` 导入类型。导入这个运行时辅助函数时，应将 `@deepseek-ai/dsh-brand` 加为直接依赖。保留原有位置上的校验和 UUID/计数器生成操作。
+
+   ```ts
+   import { brandString } from '@deepseek-ai/dsh-brand'
+   import type { BrowserUseProviderName } from '@deepseek-ai/dsh-browser-use/types'
+
+   const providerName = brandString<BrowserUseProviderName>('my-browser-provider')
+   ```
+
+3. 编译并运行插件/SDK 测试，再用 Node 加载纯 JavaScript fixture。检查是否出现 `ERR_PACKAGE_PATH_NOT_EXPORTED` 或缺少具名出口错误；仅靠 TypeScript 检查覆盖不到 `.mjs` 消费者。