dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/session-header-menu/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Custom Web compositions must provide context menus for Session actions, and export dialogs now remain visible across Session switches."
+---
+
+# Session Header menus and export dialogs
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The browser half of `@deepseek-ai/dsh-session-log-export` requires `contextMenus` to contribute copy, download, and feedback actions. Custom Web compositions without a context-menu provider must add one or these client actions cannot activate. The default Web composition already includes it. The Header More button belongs to `ui-conversation`, so removing the export plugin does not remove other registered Header actions such as Open in. The button hides when no Header-menu providers are registered.
+
+Download dialogs are mounted in the root `shell.overlay`, rather than a Session Header. They identify the exported Session and remain visible when the user switches Sessions. Downloads may run concurrently, but dialogs appear one at a time in request order; closing one shows the next and does not cancel its download. Host export routes and the `/export` command are unchanged.
+
+## Migration
+
+1. Add `@deepseek-ai/dsh-client-ui-context-menu` to custom Web compositions that lack it, with the menu package's required services. See [context-menu composition](../../../../packages/client/ui-context-menu/README.md#use-this-package). Keep `ui-conversation` for the Session Header and the shell's root overlay for download feedback. Default Web profiles need no configuration change.
+2. Custom client code using `SessionLogDownloadDialogProps` must use root-overlay runtime props instead of Session-header props and remove the `request` injection. `SessionLogDownloadEntry` includes an `order` value; the dialog reads Session identities and ordering from `bySession`.
+3. Restart the profile. Confirm that Header More contains the registered actions, Open in remains after disabling the export plugin, and starting downloads for two Sessions presents their dialogs in request order even after switching Sessions.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/session-header-menu/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "自定义 Web 组合必须为会话操作提供右键菜单服务，导出弹窗在切换 Session 后仍保持显示。"
+---
+
+# 会话头部菜单与导出弹窗
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-log-export` 的浏览器半包需要 `contextMenus` 提供复制、下载和反馈操作。没有右键菜单提供者的自定义 Web 组合必须补充，否则这些客户端操作无法激活。默认 Web 组合已包含提供者。头部更多按钮由 `ui-conversation` 持有，因此移除导出插件不会移除其他已注册的头部操作，例如在应用中打开。没有注册任何头部菜单提供者时，按钮隐藏。
+
+下载弹窗挂载于根级 `shell.overlay`，不再位于 Session Header。弹窗标明正在导出的 Session，切换 Session 后仍然显示。多个下载可以并行进行，但弹窗按发起顺序一次展示一个；关闭当前弹窗会展示下一个，不取消其下载。Host 导出路由及 `/export` 命令不变。
+
+## 迁移
+
+1. 自定义 Web 组合缺少提供者时，添加 `@deepseek-ai/dsh-client-ui-context-menu` 并提供菜单包要求的服务。参见[右键菜单组合](../../../../packages/client/ui-context-menu/README.zh.md#use-this-package)。保留 `ui-conversation` 以提供会话头部，以及 shell 的根级 overlay 以展示下载反馈。默认 Web profile 无需修改配置。
+2. 使用 `SessionLogDownloadDialogProps` 的自定义客户端代码需改用根级 overlay runtime props，不再使用 Session Header props，并移除 `request` 注入。`SessionLogDownloadEntry` 包含 `order` 值；弹窗从 `bySession` 读取 Session 身份与顺序。
+3. 重启 profile，确认头部更多菜单包含已注册的操作，禁用导出插件后仍可在应用中打开，并确认两个 Session 的下载弹窗按发起顺序显示，切换 Session 后仍然保留。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/subagent-explicit-reasoning/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Subagent reasoning overrides require an explicit provider and model, and explicit routes use model-default reasoning when effort is omitted."
+---
+
+# Subagent reasoning overrides require an explicit route
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Delegation tools with model selection enabled reject `reasoning_effort` unless the same call supplies both `provider` and `model`. Previously, an effort-only call could use a configured or inherited route. The rejection occurs before child creation.
+
+An explicit provider/model pair without `reasoning_effort` uses the selected model's default effort, including when the pair matches the parent or configured child route. Previously, the unchanged route could retain a configured or parent effort. Omitting all three tool fields preserves the configured child defaults and existing fallback behavior.
+
+## Migration
+
+1. Update prompts, skills, and tool-call producers that send only `reasoning_effort`: include the authorized `provider` and `model`, or omit all three fields to use the default child selection. Query `list_subagent_models` for authorized routes and supported effort ids.
+2. To preserve a specific effort while selecting a route, pass it explicitly as `reasoning_effort`.
+3. Confirm an effort-only call returns a missing-route error without starting a child. For a complete route, check the child's logged `request/header` configuration: an omitted effort follows that model's default rather than the parent's selected effort.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/subagent-explicit-reasoning/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "subagent 推理强度覆盖要求显式指定提供方和模型，显式路由省略强度时使用模型默认值。"
+---
+
+# subagent 推理强度覆盖要求显式路由
+
+[English](guide.md) | 中文
+
+## 变更
+
+启用模型选择的委派工具要求同一次调用同时提供 `provider` 和 `model`，否则拒绝 `reasoning_effort`。此前，仅指定强度的调用可以使用配置或继承的路由。拒绝发生在创建子级之前。
+
+显式提供提供方／模型组合但省略 `reasoning_effort` 时，使用所选模型的默认强度，即使该组合与父级或配置的子级路由相同。此前，路由不变时可能保留配置或父级强度。省略全部三个工具字段时，仍保留配置的子级默认值与现有回退行为。
+
+## 迁移
+
+1. 更新仅发送 `reasoning_effort` 的提示、skill 和工具调用生成方：补齐已授权的 `provider` 和 `model`，或省略全部三个字段以使用默认子级选择。通过 `list_subagent_models` 查询已授权路由与支持的强度 ID。
+2. 选择路由时若要保留某个强度，显式传入 `reasoning_effort`。
+3. 确认仅指定强度的调用返回缺少路由的错误，且没有启动子级。对于完整路由，检查子级日志中的 `request/header` 配置：省略强度时应采用该模型的默认值，而不是父级选择的强度。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-credential-modes/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DeepSeek web search and fetch take their endpoint from the DeepSeek model route; the shared baseURL, apiKeyEnv, and apiKey fields are removed in favor of per-capability fields."
+---
+
+# DeepSeek web search and fetch follow the DeepSeek model route
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Previously, the DeepSeek Search API and Fetch API (`web-deepseek-api`) sent their credential to one shared `baseURL` (default `https://api.deepseek.com/v1/tools`): the account token when the Session's latest model request used the `deepseek-account` route and the user was signed in, otherwise the key under `apiKeyEnv` (default `DEEPSEEK_API_KEY`) or a literal `apiKey`. Now each capability follows the same route rule but takes the endpoint from the route: on `deepseek-account` the account token goes to the account route's origin with `/v1/tools`; otherwise, including a signed-out account conversation, the key under the `apiKeyEnv` of the `deepseek-official` route goes to that route's origin with `/v1/tools`, so `DEEPSEEK_BASE_URL` now moves Search and Fetch too. Without a `deepseek-official` route, `DEEPSEEK_API_KEY` goes to `https://api.deepseek.com/v1/tools`; a mounted route whose settings do not resolve fails the operation instead. The `baseURL`, `apiKeyEnv`, and `apiKey` fields are removed; stored values load without error and are ignored. Setting either `searchBaseURL` or `searchApiKeyEnv` (`fetchBaseURL` or `fetchApiKeyEnv` for Fetch) pins that capability to its own endpoint (default `https://api.deepseek.com/v1/tools`) and key (default `DEEPSEEK_API_KEY`) and never sends the account token. These fields are YAML-only. Users without those YAML fields, without `DEEPSEEK_BASE_URL`, and without a custom model base URL see no change.
+
+## Migration
+
+1. Users who set `baseURL`, `apiKeyEnv`, or a literal `apiKey` on the `web-deepseek-api` row: for each of Search and Fetch, compare the old endpoint and key with what the route now sends, the origin of the DeepSeek model provider's base URL with `/v1/tools` and that provider's `apiKeyEnv`. When both match, remove the old fields. Otherwise set the pair, `searchBaseURL` with `searchApiKeyEnv` (`fetchBaseURL` with `fetchApiKeyEnv`), to the old endpoint and key reference, setting both fields even when one old value equals the route's: an unset field of the pair falls back to `https://api.deepseek.com/v1/tools` or `DEEPSEEK_API_KEY`, never to the route's value. For a literal `apiKey`, store it in the credential store or the launching environment under a reference and use that reference. A pinned capability never sends the account token. Confirm: `dsh` starts, and a search and a fetch reach the intended endpoint without a credential error.
+2. Users with `DEEPSEEK_BASE_URL` or a custom base URL on the DeepSeek model provider whose host does not serve `/v1/tools`: set the same pair to `https://api.deepseek.com/v1/tools` and the reference of a key that endpoint accepts. Confirm: a search returns results.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-credential-modes/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DeepSeek 网页搜索与获取从 DeepSeek 模型路由取得端点；共享的 baseURL、apiKeyEnv 与 apiKey 字段已移除，改用按能力区分的字段。"
+---
+
+# DeepSeek 网页搜索与获取跟随 DeepSeek 模型路由
+
+[English](guide.md) | 中文
+
+## 变更
+
+过去，DeepSeek Search API 与 Fetch API（`web-deepseek-api`）把凭据发往同一个共享的 `baseURL`（默认 `https://api.deepseek.com/v1/tools`）：会话最近一次模型请求使用 `deepseek-account` 路由且用户已登录时发送账号令牌，否则发送 `apiKeyEnv`（默认 `DEEPSEEK_API_KEY`）下的密钥或字面 `apiKey`。现在每个能力沿用相同的路由规则，但端点取自路由：在 `deepseek-account` 上把账号令牌发往账号路由的 origin 加 `/v1/tools`；其他情况（包括未登录的账号会话）把 `deepseek-official` 路由 `apiKeyEnv` 下的密钥发往该路由的 origin 加 `/v1/tools`，因此 `DEEPSEEK_BASE_URL` 现在也会改变 Search 与 Fetch 的端点。没有 `deepseek-official` 路由时，把 `DEEPSEEK_API_KEY` 发往 `https://api.deepseek.com/v1/tools`；已挂载的路由设置无法解析时，操作直接失败。`baseURL`、`apiKeyEnv` 与 `apiKey` 字段已移除；已保存的值可以正常加载，但会被忽略。只要设置 `searchBaseURL` 或 `searchApiKeyEnv` 中的任一项（Fetch 为 `fetchBaseURL` 或 `fetchApiKeyEnv`），就会把该能力固定到其自己的端点（默认 `https://api.deepseek.com/v1/tools`）和密钥（默认 `DEEPSEEK_API_KEY`），且从不发送账号令牌。这些字段只能在 YAML 中设置。没有设置这些 YAML 字段、没有设置 `DEEPSEEK_BASE_URL`、也没有自定义模型基础地址的用户不受影响。
+
+## 迁移
+
+1. 在 `web-deepseek-api` 条目上设置过 `baseURL`、`apiKeyEnv` 或字面 `apiKey` 的用户：对 Search 与 Fetch 分别比较原端点和密钥与路由现在发送的值，即 DeepSeek 模型提供方基础地址的 origin 加 `/v1/tools`，以及该提供方的 `apiKeyEnv`。两者都一致时，删除旧字段。否则把成对字段 `searchBaseURL` 与 `searchApiKeyEnv`（Fetch 为 `fetchBaseURL` 与 `fetchApiKeyEnv`）设为原端点和原密钥引用；即使其中一个原值与路由的值相同，也要两个字段都设置：成对字段中未设置的一项回退到 `https://api.deepseek.com/v1/tools` 或 `DEEPSEEK_API_KEY`，不会继承路由的值。设置过字面 `apiKey` 时，把该值以某个引用存入凭据存储或启动环境，并使用该引用。单独配置的能力从不发送账号令牌。确认：`dsh` 正常启动，且搜索和抓取都到达预期端点，没有凭据错误。
+2. 设置了 `DEEPSEEK_BASE_URL` 或为 DeepSeek 模型提供方设置了自定义基础地址、且该主机不提供 `/v1/tools` 的用户：把同一对字段设为 `https://api.deepseek.com/v1/tools` 和该端点接受的密钥引用。确认：搜索返回结果。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-default-provider/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The shipped Search default moves from legacy Messages search to the DeepSeek Search API, and the optional Exa and Perplexity search packages are removed."
+---
+
+# Search defaults to the DeepSeek Search API; Exa and Perplexity are removed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Previously, the shared base composition set `web.searchProvider` to `deepseek-official`: each search was an auxiliary Messages request to `web-search-deepseek`'s endpoint, sending `Perform a web search for the query: <query>` to `deepseek-v4-flash` with a server-side `web_search` tool, billed as model tokens. Now it sets `deepseek-search-api`: each search is one direct request to the DeepSeek Search API, without a model request, and may incur Search API charges instead of model tokens. That request sends `query`, `count`, `need_content: false`, and, unless `web-deepseek-api.sendOriginalQuestion` is `false`, the user's latest prompt cut to 128 characters as `ori_question`. Its credential and endpoint follow the [DeepSeek model route](../web-search-credential-modes/guide.md). Compositions that set `web.searchProvider` themselves see no change, and Fetch still defaults to `http`.
+
+The optional packages `@deepseek-ai/dsh-web-search-exa` (provider `exa`) and `@deepseek-ai/dsh-web-search-perplexity` (provider `perplexity`) are removed. A row naming either package no longer loads, and `searchProvider: exa` or `searchProvider: perplexity` names no provider.
+
+## Migration
+
+1. To keep legacy Messages search, set `searchProvider: deepseek-official` in the `config` of the `@deepseek-ai/dsh-web` row, or select DeepSeek (legacy) in the Web search provider menu on the Web search and fetch settings page. Confirm: that menu shows DeepSeek (legacy), and a search appends a `web/deepseek-search-llm-request` event to the Session log.
+2. Deployments that mounted Exa or Perplexity: delete the `@deepseek-ai/dsh-web-search-exa` or `@deepseek-ai/dsh-web-search-perplexity` row from `cordis.yml` or the profile patch, remove `EXA_API_KEY` or `PERPLEXITY_API_KEY` if nothing else uses it, and set `searchProvider` to `deepseek-search-api` or `deepseek-official`, or delete it to take the default. Confirm: `dsh` starts without a load error for either package, the Web search provider menu shows the chosen provider, and a search returns results.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-default-provider/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "交付的 Search 默认值从旧版 Messages 搜索改为 DeepSeek Search API，可选的 Exa 与 Perplexity 搜索包已移除。"
+---
+
+# Search 默认使用 DeepSeek Search API；Exa 与 Perplexity 已移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+过去，共享的基础组合把 `web.searchProvider` 设为 `deepseek-official`：每次搜索都是发往 `web-search-deepseek` 端点的一次辅助 Messages 请求，以 `Perform a web search for the query: <query>` 调用带服务端 `web_search` 工具的 `deepseek-v4-flash`，按模型 token 计费。现在它设为 `deepseek-search-api`：每次搜索是一次直接发往 DeepSeek Search API 的请求，不调用模型，可能产生 Search API 费用而非模型 token 费用。该请求发送 `query`、`count`、`need_content: false`，并且除非 `web-deepseek-api.sendOriginalQuestion` 为 `false`，还会把用户最近一条提示截取前 128 个字符作为 `ori_question` 发送。其凭据和端点跟随 [DeepSeek 模型路由](../web-search-credential-modes/guide.zh.md)。自行设置了 `web.searchProvider` 的组合不受影响，Fetch 仍默认为 `http`。
+
+可选包 `@deepseek-ai/dsh-web-search-exa`（提供方 `exa`）与 `@deepseek-ai/dsh-web-search-perplexity`（提供方 `perplexity`）已移除。指名任一包的条目不再能加载，`searchProvider: exa` 或 `searchProvider: perplexity` 也不再对应任何提供方。
+
+## 迁移
+
+1. 要继续使用旧版 Messages 搜索，在 `@deepseek-ai/dsh-web` 条目的 `config` 中设置 `searchProvider: deepseek-official`，或在「网页搜索与获取」设置页的「网页搜索提供方」菜单中选择 DeepSeek（旧版）。确认：该菜单显示 DeepSeek（旧版），且每次搜索都会向会话日志追加一个 `web/deepseek-search-llm-request` 事件。
+2. 挂载过 Exa 或 Perplexity 的部署：从 `cordis.yml` 或 profile 补丁中删除 `@deepseek-ai/dsh-web-search-exa` 或 `@deepseek-ai/dsh-web-search-perplexity` 条目；若 `EXA_API_KEY` 或 `PERPLEXITY_API_KEY` 不再被其他地方使用，一并移除；再把 `searchProvider` 设为 `deepseek-search-api` 或 `deepseek-official`，或删除该字段以采用默认值。确认：`dsh` 启动时没有这两个包的加载错误，「网页搜索提供方」菜单显示所选提供方，且搜索返回结果。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/chat-process-activity-context/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Chat ProcessActivity gains a context category, and the running activity uses RunningProcessActivity."
+---
+
+# Chat `ProcessActivity` adds `context`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ProcessActivity`, exported from `@deepseek-ai/dsh-client-ui-chat/client`, gains the member `context`. A closed process group whose members are all Context injections reports it as its only category. `ProcessActivitySummary.running` is now typed as the new exported `RunningProcessActivity`, which excludes `context`. This affects extensions that switch exhaustively over `ProcessActivity` or map every member to a label or icon.
+
+## Migration
+
+1. Add a `context` branch wherever code handles every `ProcessActivity` member, for example in a `Record<ProcessActivity, …>` or a `switch` ending in `assertNever`.
+2. Type values read from `summary.running` as `RunningProcessActivity` when they need not cover `context`.
+3. Run the extension's typecheck and confirm it compiles without a missing-member error.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/chat-process-activity-context/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Chat 的 ProcessActivity 新增 context 类别，运行中活动改用 RunningProcessActivity。"
+---
+
+# Chat `ProcessActivity` 新增 `context`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-chat/client` 导出的 `ProcessActivity` 新增成员 `context`。成员全部为上下文注入的已结束过程组以它作为唯一类别。`ProcessActivitySummary.running` 的类型改为新导出的 `RunningProcessActivity`，该类型不含 `context`。对 `ProcessActivity` 做穷尽 switch 或为每个成员映射文案、图标的扩展受影响。
+
+## 迁移
+
+1. 在处理全部 `ProcessActivity` 成员的位置补上 `context` 分支，例如 `Record<ProcessActivity, …>` 或以 `assertNever` 结尾的 `switch`。
+2. 读取 `summary.running` 且无需覆盖 `context` 的值，类型改为 `RunningProcessActivity`。
+3. 运行扩展的类型检查，确认没有缺少成员的编译错误。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-kit-package/guide.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "`@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf`, renaming its service, Remote methods, exported types, and configuration row."
+---
+
+# `@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Office conversion provider moved from `@deepseek-ai/dsh-office-to-pdf` to `@deepseek-ai/dsh-office-kit`. Compositions, plugins, and Clients that name the old package, service, Remote methods, or exported symbols are affected:
+
+| Old | New |
+|---|---|
+| `cordis.yml` row `id: office-to-pdf`, `name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`, `name: '@deepseek-ai/dsh-office-kit'`; configuration keys are unchanged |
+| `ctx.officeToPdf` | `ctx.officeKit` |
+| Remote `officeToPdf/render`, `officeToPdf/generation` | `officeKit/render`, `officeKit/generation` |
+| `OfficeToPdf` | `OfficeKit` |
+| `OfficeToPdfError`, `OfficeToPdfErrorCode` | `OfficeKitError`, `OfficeKitErrorCode` |
+| `OfficeToPdfGeneration` | `OfficeKitGeneration` |
+| `OfficeToPdfRequest`, `OfficeToPdfResult`, `OfficeToPdfPriority`, `OfficeToPdfKey` | `OfficeKitRequest`, `OfficeKitResult`, `OfficeKitPriority`, `OfficeKitKey` |
+
+The `document-render/failed` Remote error, `RenderedDocumentBytes`, `OfficeSourceKey`, and `OfficeExtension` keep their names. The `/types` and `/remote` entries remain.
+
+The provider previously failed to load when LibreOffice Kit was absent. It now registers without Kit; each conversion that needs a converter rejects with `OfficeKitError` code `unavailable` and locates Kit again, so installing Kit later takes effect without reloading the provider.
+
+## Migration
+
+1. In `cordis.yml`, patches, and overlays, change the row `id: office-to-pdf` to `id: office-kit` and its `name` to `'@deepseek-ai/dsh-office-kit'`. Keep its `config` block unchanged.
+2. Replace the dependency `@deepseek-ai/dsh-office-to-pdf` with `@deepseek-ai/dsh-office-kit` in `package.json`, and update import specifiers, including `/types` and `/remote`.
+3. Rename `ctx.officeToPdf`, Remote method names, and the exported symbols listed above.
+4. Code that treated a load failure of the conversion row as "Kit absent" now checks for `OfficeKitError` with code `unavailable` from conversion instead.
+5. Confirm the migration by searching the project for `office-to-pdf`, `officeToPdf`, and `OfficeToPdf`, then opening a DOCX file in the Web document preview.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-kit-package/guide.zh.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "`@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf`，其服务、Remote 方法、导出类型和配置行随之改名。"
+---
+
+# `@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf`
+
+[English](guide.md) | 中文
+
+## 变更
+
+Office 转换提供方从 `@deepseek-ai/dsh-office-to-pdf` 移到 `@deepseek-ai/dsh-office-kit`。引用旧包、服务、Remote 方法或导出符号的组合、插件和 Client 受到影响：
+
+| 旧名 | 新名 |
+|---|---|
+| `cordis.yml` 行 `id: office-to-pdf`、`name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`、`name: '@deepseek-ai/dsh-office-kit'`；配置项不变 |
+| `ctx.officeToPdf` | `ctx.officeKit` |
+| Remote `officeToPdf/render`、`officeToPdf/generation` | `officeKit/render`、`officeKit/generation` |
+| `OfficeToPdf` | `OfficeKit` |
+| `OfficeToPdfError`、`OfficeToPdfErrorCode` | `OfficeKitError`、`OfficeKitErrorCode` |
+| `OfficeToPdfGeneration` | `OfficeKitGeneration` |
+| `OfficeToPdfRequest`、`OfficeToPdfResult`、`OfficeToPdfPriority`、`OfficeToPdfKey` | `OfficeKitRequest`、`OfficeKitResult`、`OfficeKitPriority`、`OfficeKitKey` |
+
+Remote 错误 `document-render/failed`、`RenderedDocumentBytes`、`OfficeSourceKey` 和 `OfficeExtension` 保持原名。`/types` 和 `/remote` 入口仍然保留。
+
+原先 LibreOffice Kit 缺失时提供方加载失败。现在没有 Kit 时提供方照常注册；每次需要转换器的转换都以代码为 `unavailable` 的 `OfficeKitError` 拒绝，并重新定位 Kit，因此之后安装的 Kit 无需重新加载提供方即可生效。
+
+## 迁移
+
+1. 在 `cordis.yml`、patch 和 overlay 中，把 `id: office-to-pdf` 行改为 `id: office-kit`，并把其 `name` 改为 `'@deepseek-ai/dsh-office-kit'`。`config` 块保持不变。
+2. 在 `package.json` 中用 `@deepseek-ai/dsh-office-kit` 替换依赖 `@deepseek-ai/dsh-office-to-pdf`，并更新导入路径，包括 `/types` 和 `/remote`。
+3. 按上表重命名 `ctx.officeToPdf`、Remote 方法名和导出符号。
+4. 原先把转换行加载失败视为“Kit 缺失”的代码，改为检查转换返回的、代码为 `unavailable` 的 `OfficeKitError`。
+5. 在项目中搜索 `office-to-pdf`、`officeToPdf` 和 `OfficeToPdf` 确认已无残留，然后在 Web 文档预览中打开一个 DOCX 文件，确认迁移完成。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-operation-tools/guide.md

@@ -0,0 +1,49 @@
+---
+kind: upgrade-guide
+description: "The `office-render`, `office-recalculate`, and `office-export-pdf` skills, the skill-office `node` and `cli` keys, and two Office CLI environment variables are removed; Office operations use skill-activated tools."
+---
+
+# Office operation skills are replaced by Office tools
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-skill-office` no longer registers the `office-render`, `office-recalculate`, and `office-export-pdf` skills; it registers the `office` router and the `office-docx`, `office-pptx`, and `office-xlsx` authoring skills. After an Office skill loads, the model calls [`office_render`, `office_convert`, and `office_recalculate`](../../../../packages/document/tool-office/README.md) from the following step.
+
+Configuration changes:
+
+| Removed | Replacement |
+|---|---|
+| `skill-office` keys `node` and `cli` | None; Office tools convert in the Host |
+| `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE` | None; no component reads them |
+| `DSH_BUNDLED_PRIMARY_RUNTIME` | `DSH_PRIMARY_RUNTIME` |
+
+`skill-office` gains `pythonEnvironment`. Its default, `'workspace-dependencies'`, directs the Python skills to `load_workspace_dependencies`; a composition without `@deepseek-ai/dsh-tool-workspace-dependencies` must set `'user'`. [Office skill resources](../office-skill-resources/guide.md) covers the removal of `DSH_BUNDLED_OFFICE_SKILLS`.
+
+The Office tools parse untrusted documents with the native LibreOffice Kit engine in the Host process, outside the shell sandbox and PTC permissions, with the Host user's permissions; the filesystem backend still authorizes inputs. The `office-kit` row gains `outputDirectory` (default `$DSH_HOME/office-kit/outputs`), `outputRetentionMs`, and `maxOutputStoreBytes`.
+
+The Web profile, and the SDK profile without a primary runtime, list the Office skills in the first request context and `/` menu.
+
+This affects users and prompts of the removed skills, compositions and launchers setting the removed keys or variables, `assetRoot` skill copies, saved `standard` or `ptc` presets, deployments relying on the shell sandbox for document parsing, and tests pinning the first request context or `/` menu.
+
+## Migration
+
+1. Replace each removed skill with loading `office` and calling the matching tool:
+   - `office-render`: `office_render`;
+   - `office-recalculate`: `office_recalculate` with `format: "xlsx"` or `"ods"`;
+   - `office-export-pdf`: `office_convert` with `format: "pdf"`.
+2. Remove `node` and `cli` from every `skill-office` row in `cordis.yml`, patches, and overlays. Set `pythonEnvironment: user` unless the composition mounts `@deepseek-ai/dsh-tool-workspace-dependencies`.
+3. Compositions that mount `@deepseek-ai/dsh-skill-office` without the shipped bundles also mount `@deepseek-ai/dsh-office-kit` and `@deepseek-ai/dsh-tool-office`.
+4. In launchers, stop setting `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE`, and rename `DSH_BUNDLED_PRIMARY_RUNTIME` to `DSH_PRIMARY_RUNTIME`. The Python SDK prefers a set or inherited `DSH_PRIMARY_RUNTIME`, even empty, over its download cache; unset it to use the cache.
+5. In a copy referenced by `assetRoot`, replace the four remaining folders with the installed package's `assets/` and delete the three removed skill folders.
+6. A `standard` or `ptc` preset saved from the Agent Preset editor replaces the shipped plugin list, so its Sessions lack the Office tools. Add this row to the saved list, or to `config.plugins` of the `preset-standard` or `preset-ptc` row in `$DSH_HOME/profiles/<profile>/cordis.patch.yml` (`<profile>`: `web` or `desktop`):
+
+   ```yaml
+   - id: tool-office
+     name: '@deepseek-ai/dsh-tool-office'
+   ```
+
+7. Deployments that require sandboxed document parsing omit `@deepseek-ai/dsh-tool-office`.
+8. Update expected first request contexts and `/` menus with the Office skills.
+9. Confirm: in a new `standard` or `ptc` Session, send `/office`, then a separate PDF export request; it produces an `office_convert` call that returns a temporary PDF path or the `unavailable` message.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-operation-tools/guide.zh.md

@@ -0,0 +1,49 @@
+---
+kind: upgrade-guide
+description: "删除 `office-render`、`office-recalculate` 和 `office-export-pdf` 技能、skill-office 的 `node` 和 `cli` 配置键，以及两个 Office CLI 环境变量；Office 操作改用由技能激活的工具。"
+---
+
+# Office 操作技能由 Office 工具取代
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-skill-office` 不再注册 `office-render`、`office-recalculate` 和 `office-export-pdf` 技能，只注册 `office` 路由技能，以及 `office-docx`、`office-pptx` 和 `office-xlsx` 编写技能。加载 Office 技能后，模型从下一步起调用 [`office_render`、`office_convert` 和 `office_recalculate`](../../../../packages/document/tool-office/README.zh.md)。
+
+配置变化：
+
+| 已删除 | 替代 |
+|---|---|
+| `skill-office` 配置键 `node` 和 `cli` | 无；Office 工具在 Host 中转换 |
+| `DSH_BUNDLED_OFFICE_CLI` 和 `DSH_BUNDLED_OFFICE_NODE` | 无；不再有组件读取它们 |
+| `DSH_BUNDLED_PRIMARY_RUNTIME` | `DSH_PRIMARY_RUNTIME` |
+
+`skill-office` 新增 `pythonEnvironment`。默认值 `'workspace-dependencies'` 让 Python 技能调用 `load_workspace_dependencies`；没有挂载 `@deepseek-ai/dsh-tool-workspace-dependencies` 的组合必须设为 `'user'`。`DSH_BUNDLED_OFFICE_SKILLS` 的删除见 [Office 技能资源](../office-skill-resources/guide.zh.md)。
+
+Office 工具在 Host 进程内用原生 LibreOffice Kit 引擎解析不可信的文档，不受 shell 沙箱和 PTC 权限约束，并具有 Host 用户的权限；输入仍由文件系统后端授权。`office-kit` 条目新增 `outputDirectory`（默认 `$DSH_HOME/office-kit/outputs`）、`outputRetentionMs` 和 `maxOutputStoreBytes`。
+
+Web profile，以及没有 primary runtime 的 SDK profile，会在首次请求上下文和 `/` 菜单中列出 Office 技能。
+
+受影响的有：使用已删除技能的用户和提示词，设置了已删除配置键或环境变量的组合和启动器，`assetRoot` 技能副本，已保存的 `standard` 或 `ptc` 预设，依赖 shell 沙箱解析文档的部署，以及固定了首次请求上下文或 `/` 菜单的测试。
+
+## 迁移
+
+1. 把每个已删除的技能替换为加载 `office` 并调用对应工具：
+   - `office-render`：`office_render`；
+   - `office-recalculate`：`office_recalculate`，`format` 为 `"xlsx"` 或 `"ods"`；
+   - `office-export-pdf`：`office_convert`，`format` 为 `"pdf"`。
+2. 从 `cordis.yml`、patch 和 overlay 的所有 `skill-office` 行中删除 `node` 和 `cli`。除非组合挂载了 `@deepseek-ai/dsh-tool-workspace-dependencies`，否则设置 `pythonEnvironment: user`。
+3. 不使用随发行版 bundle、自行挂载 `@deepseek-ai/dsh-skill-office` 的组合，同时挂载 `@deepseek-ai/dsh-office-kit` 和 `@deepseek-ai/dsh-tool-office`。
+4. 在启动器中不再设置 `DSH_BUNDLED_OFFICE_CLI` 和 `DSH_BUNDLED_OFFICE_NODE`，并把 `DSH_BUNDLED_PRIMARY_RUNTIME` 改名为 `DSH_PRIMARY_RUNTIME`。Python SDK 优先使用环境中设置或继承的 `DSH_PRIMARY_RUNTIME`（空值也一样），其次才是下载缓存；要使用缓存，请取消设置该变量。
+5. 在 `assetRoot` 引用的副本中，用已安装包 `assets/` 下的对应目录替换其余四个目录，并删除三个已删除技能的目录。
+6. 在 Agent 预设编辑器中保存过的 `standard` 或 `ptc` 预设会替换随发行版提供的插件列表，因此其 Session 没有 Office 工具。把下面这一行加入已保存的列表，或加入 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 中 `preset-standard` 或 `preset-ptc` 行的 `config.plugins`（`<profile>`：`web` 或 `desktop`）：
+
+   ```yaml
+   - id: tool-office
+     name: '@deepseek-ai/dsh-tool-office'
+   ```
+
+7. 需要在沙箱中解析文档的部署不挂载 `@deepseek-ai/dsh-tool-office`。
+8. 更新首次请求上下文和 `/` 菜单的预期结果，使其包含 Office 技能。
+9. 确认：在 `standard` 或 `ptc` 的新 Session 中发送 `/office`，再另发一条导出 PDF 的请求；该请求会产生一次 `office_convert` 调用，返回临时 PDF 路径或 `unavailable` 消息。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-skill-resources/guide.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: "`DSH_BUNDLED_OFFICE_SKILLS` and the `office-skills/` resource directories are removed; Office skills load from the `skill-office` package's assets."
+---
+
+# Office skills load from the packaged assets
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Web and SDK profiles no longer set `assetRoot` on the `skill-office` row, so [`@deepseek-ai/dsh-skill-office`](../../../../packages/skill/skill-office/README.md) reads the Office skills from its packaged `assets/` in every deployment:
+
+| Removed | Replacement |
+|---|---|
+| `DSH_BUNDLED_OFFICE_SKILLS` | `assetRoot` in a profile patch, or same-name filesystem skills |
+| Desktop `resources/runtime/office-skills/` | The skill package inside `resources/app.asar` |
+| Python runtime wheel `<platform>-<arch>/office-skills/` | The skill package inside the runtime executable |
+| `office-skills/` beside `primary-runtime/` in `pnpm run prepare:primary-runtime` output and the downloaded authoring payload | None |
+
+`pythonEnvironment` and its values are unchanged. This affects launchers that set `DSH_BUNDLED_OFFICE_SKILLS`, tools that read or edit skill files in those directories, and container images that copy `office-skills/` beside `primary-runtime/`.
+
+## Migration
+
+1. Stop setting `DSH_BUNDLED_OFFICE_SKILLS`. To keep a custom skill directory, set `assetRoot` in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`. A patch replaces the row's whole `config`, so also set `pythonEnvironment: user` unless the profile mounts `workspace-dependencies`, which requires a nonempty `DSH_PRIMARY_RUNTIME` in Desktop and the SDK:
+
+   ```yaml
+   - id: skill-office
+     config:
+       assetRoot: /absolute/path/to/office-skills
+       pythonEnvironment: user
+   ```
+
+2. Alternatively, place a skill named `office`, `office-docx`, `office-pptx`, or `office-xlsx` in a [project or user skill directory](../../../../packages/skill/skill-filesystem/README.md); filesystem skills take precedence over the bundled skills with the same name.
+3. Remove steps that copy or read `office-skills/` in Desktop resources, Python wheels, or prepared primary-runtime payloads. Containers copy only `primary-runtime/` and keep `DSH_PRIMARY_RUNTIME` pointing at it.
+4. Confirm: in a new Session, load `office-docx`; its result names a base directory under the skill package's `assets/`, under the configured `assetRoot`, or in the overriding skill directory.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-skill-resources/guide.zh.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: "`DSH_BUNDLED_OFFICE_SKILLS` 和 `office-skills/` 资源目录被删除；Office 技能从 `skill-office` 包的 assets 加载。"
+---
+
+# Office 技能从包内 assets 加载
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 和 SDK profile 不再为 `skill-office` 行设置 `assetRoot`，因此 [`@deepseek-ai/dsh-skill-office`](../../../../packages/skill/skill-office/README.zh.md) 在所有部署中都从包内 `assets/` 读取 Office 技能：
+
+| 已删除 | 替代 |
+|---|---|
+| `DSH_BUNDLED_OFFICE_SKILLS` | profile patch 中的 `assetRoot`，或同名文件系统技能 |
+| Desktop `resources/runtime/office-skills/` | `resources/app.asar` 内的技能包 |
+| Python 运行时 wheel 的 `<platform>-<arch>/office-skills/` | 运行时可执行程序内的技能包 |
+| `pnpm run prepare:primary-runtime` 输出和下载的创作载荷中与 `primary-runtime/` 同级的 `office-skills/` | 无 |
+
+`pythonEnvironment` 及其取值不变。受影响的有：设置 `DSH_BUNDLED_OFFICE_SKILLS` 的启动器，读取或编辑上述目录中技能文件的工具，以及把 `office-skills/` 复制到 `primary-runtime/` 旁边的容器镜像。
+
+## 迁移
+
+1. 不再设置 `DSH_BUNDLED_OFFICE_SKILLS`。要继续使用自定义技能目录，在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 中设置 `assetRoot`。patch 会替换该行的整个 `config`，因此除非 profile 挂载了 `workspace-dependencies`（Desktop 和 SDK 都要求 `DSH_PRIMARY_RUNTIME` 非空），还要设置 `pythonEnvironment: user`：
+
+   ```yaml
+   - id: skill-office
+     config:
+       assetRoot: /absolute/path/to/office-skills
+       pythonEnvironment: user
+   ```
+
+2. 也可以在[项目或用户技能目录](../../../../packages/skill/skill-filesystem/README.zh.md)中放置名为 `office`、`office-docx`、`office-pptx` 或 `office-xlsx` 的技能；文件系统技能优先于同名内置技能。
+3. 删除从 Desktop 资源、Python wheel 或准备好的主运行时载荷中复制或读取 `office-skills/` 的步骤。容器只复制 `primary-runtime/`，并让 `DSH_PRIMARY_RUNTIME` 继续指向它。
+4. 确认：在新 Session 中加载 `office-docx`，其结果给出的基础目录位于技能包的 `assets/` 下、所配置的 `assetRoot` 下，或覆盖它的技能目录中。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/subagent-names/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "Subagent control and Team task tools address agents by name, list_agents rows change, and subagent catalogs write payload version 3."
+---
+
+# Subagent tools address agents by name
+
+English | [中文](guide.zh.md)
+
+## Change
+
+New subagents have sibling-unique names in their creator's `subagent/catalog`. The root is `lead`; descendant names are paths such as `reviewer/checker`. The [subagent runtime](../../../../packages/subagent/subagent/README.md#agent-names) defines naming rules. Historical children keep their Session ids. Scripts, PTC, SDK callers, and transcripts must adopt these changes:
+
+- `send_message({ agent_id, message })` becomes `send_message({ agent, message })`, and `interrupt_agent({ agent_id })` becomes `interrupt_agent({ agent })`. `agent` accepts a name or a Session id. A call that still passes `agent_id` fails argument validation.
+- `subagent`, `subagent_fork`, and `subagent_oar` accept an optional `name`. They return `started subagent <name>` with result `{ kind: 'activation', name }`.
+- `list_agents` returns `{ name, status, description? }` rows instead of rows with `kind`, `id`, `label`, `parent`, `depth`, and `reason`. Unreadable branches report `corrupt`, `unsupported`, or `unavailable` as `status`. Text rows read `<name> [<status>] — <description>`.
+- Team task results replace `ownerId` with `owner`, the owner's name. `team_task_list` and `team_task_update` accept a name as `owner`. To list tasks without an owner, use `unowned: true` instead of `owner: "unowned"`.
+- Local and parent-delivered external creation write `subagent/catalog` payload version 3. Releases before this one reject catalogs that contain it, so they cannot open Sessions that create subagents after upgrading. See the [persistence acknowledgement](../../../persistence-changes/2026-11-02-subagent-catalog-names.md).
+- `SubagentActivation` has a required `name` field, and `SubagentActivationSpec` accepts an optional `name`.
+
+## Migration
+
+1. In scripts, PTC programs, and SDK calls, rename the `agent_id` argument of `send_message` and `interrupt_agent` to `agent`. Pass the name that `list_agents` or the start receipt reports; a saved Session id still works.
+2. Update parsers of `list_agents` output to read `name`, `status`, and `description`. Only complete named paths encode creators: the prefix before the last `/`, or `lead` without `/`. Unnamed children or ancestors cause Session-id fallback; these rows expose neither creator nor depth.
+3. Update Team task consumers to read `owner` instead of `ownerId`. Host code that calls `ctx.agentTeams` still reads `ownerId`; display `ownerName ?? ownerId`. New assignments persist optional `ownerName`; historical records remain unchanged. Older projections reject named tasks; see the [acknowledgement](../../../persistence-changes/2026-11-02-team-task-owner-names.md).
+4. Read `name` instead of `subagentId` from delegation tool results. Update recorded transcripts or fixtures that contain `agent_id` arguments, `started subagent <Session id>` receipts, identity runtime context text, `Agent <Session id> sent a message` signatures, `Background subagent <Session id>` notices, or the earlier `list_agents` rows. Signatures and notices now use names.
+5. Add `name` when constructing `SubagentActivation` values. Code that reads catalog rows can read the optional `name` field.
+6. Upgrade every process that opens the same Session store before creating subagents. Older releases cannot open Sessions that contain catalog payload version 3.
+7. To confirm the change, start a subagent with `name: "reviewer"` and check that the receipt reads `started subagent reviewer`, that `list_agents` lists `reviewer`, and that `send_message({ agent: "reviewer", message })` succeeds.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/subagent-names/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "Subagent 控制工具和 Team 任务工具按名称寻址 agent，list_agents 行格式改变，subagent 目录写入第 3 版载荷。"
+---
+
+# Subagent 工具按名称寻址 agent
+
+[English](guide.md) | 中文
+
+## 变更
+
+新 subagent（子智能体）在创建者的 `subagent/catalog` 中拥有同级唯一的名称。根为 `lead`；后代名称是 `reviewer/checker` 这样的路径。[subagent 运行时](../../../../packages/subagent/subagent/README.zh.md#agent-names)定义名称规则。升级前创建的子级继续以 Session id 作为名称。脚本、PTC、SDK 调用方和 transcript（文本记录）需要适配以下变更：
+
+- `send_message({ agent_id, message })` 改为 `send_message({ agent, message })`，`interrupt_agent({ agent_id })` 改为 `interrupt_agent({ agent })`。`agent` 接受名称或 Session id。仍传入 `agent_id` 的调用无法通过参数校验。
+- `subagent`、`subagent_fork` 和 `subagent_oar` 接受可选的 `name`。它们返回 `started subagent <name>`，结果为 `{ kind: 'activation', name }`。
+- `list_agents` 返回 `{ name, status, description? }` 行，取代含 `kind`、`id`、`label`、`parent`、`depth` 和 `reason` 的行。不可读分支以 `status` 报告 `corrupt`、`unsupported` 或 `unavailable`。文本行格式为 `<name> [<status>] — <description>`。
+- Team 任务结果以 `owner`（所有者名称）取代 `ownerId`。`team_task_list` 和 `team_task_update` 的 `owner` 接受名称。查询无所有者任务时，用 `unowned: true` 替代 `owner: "unowned"`。
+- 本地创建和父级投递的外部创建写入第 3 版 `subagent/catalog` 载荷。本版本之前的发布会拒绝包含该载荷的目录，因此无法打开升级后创建过 subagent 的 Session。参见[持久化确认记录](../../../persistence-changes/2026-11-02-subagent-catalog-names.zh.md)。
+- `SubagentActivation` 新增必需字段 `name`，`SubagentActivationSpec` 接受可选的 `name`。
+
+## 迁移
+
+1. 在脚本、PTC 程序和 SDK 调用中，将 `send_message` 和 `interrupt_agent` 的 `agent_id` 参数改名为 `agent`。传入 `list_agents` 或启动回执报告的名称；已保存的 Session id 仍可使用。
+2. 更新 `list_agents` 输出的解析器，读取 `name`、`status` 和 `description`。只有完整命名路径编码创建者：最后一个 `/` 之前的前缀，不含 `/` 时为 `lead`。未命名的子级或祖先导致回退到 Session id；这些行既不提供创建者，也不提供深度。
+3. 更新 Team 任务消费方，读取 `owner` 而非 `ownerId`。调用 `ctx.agentTeams` 的 host 代码仍读取 `ownerId`；展示时读取 `ownerName ?? ownerId`。新分配会持久化可选的 `ownerName`，历史记录保持不变。旧投影会拒绝带名称的任务；参见[确认记录](../../../persistence-changes/2026-11-02-team-task-owner-names.zh.md)。
+4. 从委派工具结果读取 `name` 而非 `subagentId`。更新包含 `agent_id` 参数、`started subagent <Session id>` 回执、身份运行时上下文文本、`Agent <Session id> sent a message` 署名、`Background subagent <Session id>` 通知或旧 `list_agents` 行的录制 transcript 或 fixture。署名和通知现在使用名称。
+5. 构造 `SubagentActivation` 值时添加 `name`。读取目录行的代码可读取可选的 `name` 字段。
+6. 在创建 subagent 之前，升级所有打开同一 Session 存储的进程。旧版本无法打开包含第 3 版目录载荷的 Session。
+7. 验证迁移：以 `name: "reviewer"` 启动一个 subagent，确认回执为 `started subagent reviewer`，`list_agents` 列出 `reviewer`，且 `send_message({ agent: "reviewer", message })` 成功。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/account-notification-fields/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "Generic account notification APIs replace bonus-specific methods and notification requests use the Harness domain."
+---
+
+# Update account notification consumers
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`DeepSeekAccount.getNotifications()` and `account/getNotifications` replace `getUnnotifiedBonuses()`. They return `AccountNotificationBatch.notifications` with opaque string `id`, `createdAt`, nullable `displayUntil`, localized `title` and `body`, ordered `actions`, and optional JSON `data`. The batch also requires `nextPollAfterSeconds`, projected from the wire field `next_poll_after`. Bonus metadata belongs in `data`; the bonus-specific types and fields are removed. `reportNotificationEvent()` replaces `ackBonusNotified()` and takes `(id, event, client)` to report `displayed`, `cta_clicked`, or `dismissed` using the notification ID. `getNotificationContent()` reads localized content by notification ID, including consumed notifications, without changing consumption.
+
+`DeepSeekAccount.watch()` and `account/watch` emit `AccountUpdate` items containing `type` and the complete `state`. Initial subscription and login progress use `snapshot`; credential writes and removal use `credentials-changed`.
+
+The account provider adds `harnessOrigin`, defaulting to `https://harness.deepseek.com`, for notification list, content, and events. `platformOrigin` retains its `https://platform.deepseek.com` default for login, profile, balance, logout, external navigation, and native embedded pages. Grant issuer checks still use `platformOrigin`.
+
+`ui-account-notifications` owns notifications; `ui-settings-account` supplies its account state, refresh events, and presentation slot.
+
+## Migration
+
+1. Read account state from `update.state`. A `credentials-changed` event or new Remote-stream generation clears notification state and restarts polling when signed in; progress snapshots retain it. Update providers, Remote consumers, and fixtures to use the new fields, opaque string IDs, and required delay in seconds. List decoding skips malformed or unsupported notifications individually; malformed envelopes still fail the request.
+2. Remove notification account-ID arguments and the batch accountId field. `getNotificationContent(id, client)` and `reportNotificationEvent(id, event, client)` use the current token directly, without a profile preflight. Credential changes end old requests, cards, and polls; late replies are discarded. Report each event once; valid `acked: true` and `acked: false` responses both finish the attempt. Failed reports keep local card state and are not retried. Report `displayed` after presentation, `cta_clicked` for every non-dismiss action with no action ID, and only `dismissed` after explicit close. Action clicks retain the card and execute without waiting for the report; closing before presentation does not generate a display event; expiry and account cleanup do not count as dismissal. Refresh current cards through `getNotificationContent()` when the language changes; retain their position and avoid another display event.
+3. Remove `bonusAckRetryDelayMs` and `bonusAckRetryMaxDelayMs` from `ui-settings-account` configuration; event reporting has no retry settings. A failed report does not undo the current interaction or retry that report. If a later list offers a closed notification again, the client displays it again.
+4. Keep existing `platformOrigin` configuration. Private deployments and loopback fixtures set `harnessOrigin` to their notification service origin. Confirm only list, content, and events use that origin; login, profile, balance, logout, and pages retain `platformOrigin`.
+5. Load `@deepseek-ai/dsh-client-ui-account-notifications` beside account settings. Set its new `notificationPollIntervalMs` option when the ten-minute initial interval is unsuitable. Move notification-state and reporting consumers to the new plugin. Verify both plugins share one account stream, including after notification-plugin reload.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/account-notification-fields/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "通用账号通知 API 替换赠金专用方法，通知请求改用 Harness 域名。"
+---
+
+# 更新账号通知使用方
+
+[English](guide.md) | 中文
+
+## 变更
+
+`DeepSeekAccount.getNotifications()` 和 `account/getNotifications` 替换 `getUnnotifiedBonuses()`，返回的 `AccountNotificationBatch.notifications` 包含不透明字符串 `id`、`createdAt`、可为 null 的 `displayUntil`、本地化的 `title` 与 `body`、有序的 `actions`，以及可选 JSON `data`。批次还要求提供 `nextPollAfterSeconds`，由接口字段 `next_poll_after` 投影。赠金元数据放入 `data`；赠金专用类型和字段移除。`reportNotificationEvent()` 替换 `ackBonusNotified()`，接收 `(id, event, client)`，以通知 ID 上报 `displayed`、`cta_clicked` 或 `dismissed` 事件。`getNotificationContent()` 按通知 ID 读取本地化内容，支持已消费通知，不改变消费状态。
+
+`DeepSeekAccount.watch()` 和 `account/watch` 发出包含 `type` 和完整 `state` 的 `AccountUpdate`。首次订阅和登录进度使用 `snapshot`；凭据写入和删除使用 `credentials-changed`。
+
+账号提供者新增 `harnessOrigin`，默认值为 `https://harness.deepseek.com`，用于通知 list、content 和 events。`platformOrigin` 保留 `https://platform.deepseek.com` 默认值，用于登录、资料、余额、退出登录、外部导航和原生内嵌页面。授权来源仍按 `platformOrigin` 校验。
+
+`ui-account-notifications` 负责通知；`ui-settings-account` 提供已有账号状态、刷新事件和展示插槽。
+
+## 迁移
+
+1. 从 `update.state` 读取账号状态。收到 `credentials-changed` 事件或 Remote 流进入新一代连接时，清空通知状态，已登录时重启轮询；进度快照保留当前轮询。更新提供者、Remote 使用方和测试夹具，使用新字段、不透明字符串 ID 和必填的秒数间隔。列表解码逐条跳过格式错误或不支持的通知；列表外层格式错误仍使请求失败。
+2. 移除通知方法的账号 ID 参数和批次的 accountId 字段。`getNotificationContent(id, client)` 和 `reportNotificationEvent(id, event, client)` 直接使用当前 token，不前置查询资料。凭据变化后终止旧请求、卡片与轮询，并丢弃迟到的响应。每次事件只上报一次；有效的 `acked: true` 和 `acked: false` 均结束本次尝试。上报失败保留本地卡片状态，不重试。展示后上报 `displayed`，所有非 dismiss 操作点击都上报 `cta_clicked`，不携带 action ID，主动关闭仅上报 `dismissed`。点击业务按钮保留卡片并立即执行操作，不等待上报；尚未展示就关闭时不补报展示事件；过期和账号清理不计为主动关闭。切换语言时，通过 `getNotificationContent()` 刷新当前卡片，保留位置，不重复上报展示事件。
+3. 从 `ui-settings-account` 配置中移除 `bonusAckRetryDelayMs` 和 `bonusAckRetryMaxDelayMs`；事件上报没有重试配置。上报失败不撤销当前交互，也不重试该次上报。后续列表再次返回已关闭通知时，客户端会再次展示。
+4. 保留已有的 `platformOrigin` 配置。私有部署和本机测试夹具将 `harnessOrigin` 设为各自的通知服务来源。确认仅 list、content 和 events 使用该来源；登录、资料、余额、退出登录和页面保留 `platformOrigin`。
+5. 在账号设置旁加载 `@deepseek-ai/dsh-client-ui-account-notifications`。初始十分钟间隔不适用时，设置其新增的 `notificationPollIntervalMs` 选项。将通知状态及上报使用方迁移到新插件。确认两个插件共用一条账号流，包括重载通知插件之后。