dsh-primer 0.4.4 → 0.4.6

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/subagent-interrupt-default/guide.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "Built-in configurations disable interrupt_agent for subagents and Team mode."
+---
+
+# Built-in configurations disable agent interruption
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The base bundle and the Web `standard`, `cordis`, and `ptc` presets now set `config.interrupt: false` on their `tool-subagent-control` rows. Models using these configurations no longer receive `interrupt_agent`, including in Team mode. Messaging, discovery, inbox waiting, and the subagent service interruption API remain available. The plugin's own default remains `true`; independent compositions that omit the setting retain interruption.
+
+## Migration
+
+Keep `interrupt: false` to retain the built-in behavior. To restore interruption:
+
+1. Edit `$DSH_HOME/profiles/<profile>/cordis.patch.yml`. For base-backed profiles such as `headless`, `sdk`, and `acp`, append:
+
+   ```yaml
+   - id: tool-subagent-control
+     config:
+       interrupt: true
+   ```
+
+2. For `web` or `desktop`, instead override each required declaration: `preset-standard`, `preset-cordis`, or `preset-ptc`. Copy that declaration's complete `config` from the installed `@deepseek-ai/dsh-web-app` bundle's `presets/<name>.patch.yml` (source: [standard](../../../../packages/bundle/web-app/presets/standard.patch.yml), [cordis](../../../../packages/bundle/web-app/presets/cordis.patch.yml), [ptc](../../../../packages/bundle/web-app/presets/ptc.patch.yml)). If your profile already overrides the declaration, edit that override to preserve your customizations. A patch replaces the whole `config`: retain `id`, `order`, and the entire `plugins` list, including the `delegation` group. Within that group's `config`, change the `tool-subagent-control` row's `config.interrupt` to `true`. Use the declaration's outer ID as the patch target, following [Change a shipped preset](../../../../packages/preset/agent-preset/skills/dsh-doc/references/compositions.md#change-a-shipped-preset). A top-level patch targeting `tool-subagent-control` does not reach the preset's child row; it only changes the disabled Host row. Leave that Host row disabled.
+3. Restart the profile and create a new Session using the changed preset; existing Sessions retain their preset revision. Confirm that the model's tool definitions include `interrupt_agent`, `send_message`, `list_agents`, and `wait_agent`.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/subagent-interrupt-default/guide.zh.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "内置配置关闭普通 subagent 和 Team 模式的 interrupt_agent。"
+---
+
+# 内置配置关闭 agent 中断
+
+[English](guide.md) | 中文
+
+## 变更
+
+base 组合包及 Web 的 `standard`、`cordis`、`ptc` preset 现在为各自的 `tool-subagent-control` 行设置 `config.interrupt: false`。使用这些配置的模型不再获得 `interrupt_agent`，也包括 Team 模式。消息、发现、收件箱等待和 subagent 服务的中断 API 仍然可用。插件自身的默认值仍为 `true`；省略该设置的独立组合仍提供中断工具。
+
+## 迁移
+
+保留 `interrupt: false` 可维持内置行为。如需恢复中断工具：
+
+1. 编辑 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`。对于 `headless`、`sdk`、`acp` 等基于 base 的 profile，追加：
+
+   ```yaml
+   - id: tool-subagent-control
+     config:
+       interrupt: true
+   ```
+
+2. 对于 `web` 或 `desktop`，改为覆盖需要启用的声明行：`preset-standard`、`preset-cordis` 或 `preset-ptc`。从已安装的 `@deepseek-ai/dsh-web-app` 组合包的 `presets/<name>.patch.yml` 中复制该声明的完整 `config`（源码：[standard](../../../../packages/bundle/web-app/presets/standard.patch.yml)、[cordis](../../../../packages/bundle/web-app/presets/cordis.patch.yml)、[ptc](../../../../packages/bundle/web-app/presets/ptc.patch.yml)）。如果 profile 已经覆盖该声明，编辑已有覆盖以保留自定义配置。patch 会替换整个 `config`：保留 `id`、`order` 和完整的 `plugins` 列表，包括 `delegation` 组。在该组的 `config` 内，将 `tool-subagent-control` 行的 `config.interrupt` 改为 `true`。以声明的外层 ID 为 patch 目标，写法参见[修改内置 preset](../../../../packages/preset/agent-preset/skills/dsh-doc/references/compositions.md#change-a-shipped-preset)。顶层以 `tool-subagent-control` 为目标的 patch 无法修改 preset 内的子行，只会修改已禁用的 Host 行。保持该 Host 行禁用。
+3. 重启 profile，并使用修改后的 preset 创建新 Session；已有 Session 保留原 preset 修订。确认模型的工具定义包含 `interrupt_agent`、`send_message`、`list_agents` 和 `wait_agent`。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-backend-cleanup-error/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/terminal-backend-cleanup-error/guide.md
+/:
+  en: 91597636f5a71894
+  zh: 02d2517952d86cfd
+/terminalbackendcleanuperror-extends-terminalerror:
+  en: cb11df977825904b
+  zh: 080f157e78942a9d
+/terminalbackendcleanuperror-extends-terminalerror/change:
+  en: bf3bd46faf910ff0
+  zh: fd47d6e58f467a1e
+/terminalbackendcleanuperror-extends-terminalerror/migration:
+  en: 85fe7dd354cf8657
+  zh: e39dc4ce137aeb13

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-backend-cleanup-error/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "TerminalBackendCleanupError extends TerminalError instead of AggregateError and carries the CLEANUP_FAILED code."
+---
+
+# `TerminalBackendCleanupError` extends `TerminalError`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-terminal` exports `TerminalBackendCleanupError`, which a PTY backend throws when startup failed and cleaning its partial resources also failed. It previously extended `AggregateError`. It now extends `TerminalError`, so it is a `HarnessError` with code `CLEANUP_FAILED`, and a tool result that carries it records `error.name` `TerminalBackendCleanupError` and `error.code` `CLEANUP_FAILED`. The constructor, the `name`, `spawnError`, `cleanupError`, and the `errors` list in that order are unchanged; `errors` is typed `readonly unknown[]` instead of `any[]`. `cause` is a new `AggregateError` of the same two failures. `error instanceof AggregateError` is now `false`.
+
+Backends and consumers that only construct the error, read `spawnError` or `cleanupError`, or test `instanceof TerminalBackendCleanupError` are unaffected.
+
+## Migration
+
+1. Replace `error instanceof AggregateError` checks meant for this error with `error instanceof TerminalBackendCleanupError`, or with `error.code === 'CLEANUP_FAILED'` on a `TerminalError`.
+2. Where TypeScript code reads members of `error.errors` without narrowing, narrow each `unknown` element before use, or read `spawnError` and `cleanupError`.
+3. Confirm with `pnpm exec tsc --noEmit` in the consuming project, and check that a startup cleanup failure still reaches the handling path.

package/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-bundle-sidebar-backend/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/terminal-bundle-sidebar-backend/guide.md
+/:
+  en: 785e5093e3550fe6
+  zh: 1d83c93daacf9b2e
+/persistent-terminals-open-in-the-web-sidebar:
+  en: f2ce8bce4d8fb13e
+  zh: c7270e6a1480b0cb
+/persistent-terminals-open-in-the-web-sidebar/change:
+  en: 05818c97f3e32442
+  zh: 249a6ce6f6b80f0d
+/persistent-terminals-open-in-the-web-sidebar/migration:
+  en: 1fe14dab0b4e5056
+  zh: 4afffad398f7a18b

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/web-search-billing/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/web-search-billing/guide.md
+/:
+  en: d5f047c8126e2039
+  zh: 921852a96d5fdaf2
+/deepseek-web-search-and-fetch-choose-their-credential-by-billing:
+  en: 5b4ad8a6553f2017
+  zh: 33d0dbee4bbadad8
+/deepseek-web-search-and-fetch-choose-their-credential-by-billing/change:
+  en: c479258a05c03e30
+  zh: 9479ed43eebd03c2
+/deepseek-web-search-and-fetch-choose-their-credential-by-billing/migration:
+  en: f02650a1b0730ecf
+  zh: e6ddb011af754005

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/window-drag-regions/guide.md
+/:
+  en: 3733ed8d0c40fb64
+  zh: f886cd8c61db2bd8
+/explicit-window-regions-for-custom-client-overlays:
+  en: bf86e50c82443b79
+  zh: 4b7a14fa9c3e60b7
+/explicit-window-regions-for-custom-client-overlays/change:
+  en: a3c55aed10fdeeb8
+  zh: dd628088de04631f
+/explicit-window-regions-for-custom-client-overlays/migration:
+  en: cb177bbf9687f49a
+  zh: c39c94a2d36416b2

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/user/develop/framework/events.i18n.yaml

@@ -33,8 +33,8 @@
   en: 18070de55501a230
   zh: 0a34d22dc2662599
 /event-system/cordis-events-and-session-records:
-  en: 93102b27250eea35
-  zh: a97a0197f785a4aa
+  en: 866ef8c0f99b2e8a
+  zh: 14c9b69b27ffd850
 /event-system/event-listeners-are-effects:
   en: b7cc96734661caef
   zh: 442ec0da611cf644

package/references/official-docs/docs/user/develop/framework/events.md

@@ -101,7 +101,7 @@ declare module '@deepseek-ai/cordis' {
 
 ## Cordis events and session records
 
-Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
+Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
 
 `turn/*`, `step/*`, `tool/call`, `tool/result`, and `compaction/*` are durable session-event types, not same-named Cordis events. To observe them, listen to `session/event` and inspect `event.type`.
 

package/references/official-docs/docs/user/develop/framework/events.zh.md

@@ -101,7 +101,7 @@ declare module '@deepseek-ai/cordis' {
 
 ## Cordis 事件与会话记录
 
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.zh.md)上生成的 `cordis-surface` 区块。
+Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.zh.md)上生成的 `cordis-surface` 区块。
 
 `turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compaction/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
 

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.i18n.yaml

@@ -3,8 +3,8 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/dynamic-cordis.md
 /configure-persistent-plugins-from-a-prompt:
-  en: 9503745724cbe962
-  zh: 985513234a4eda31
+  en: d50e336357663f75
+  zh: 4364e91403387e2a
 /configure-persistent-plugins-from-a-prompt/connect-an-mcp-server:
   en: f9fefda94ba8a005
   zh: f1a9a977a0732fc0

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.md

@@ -2,7 +2,7 @@
 
 English | [中文](dynamic-cordis.zh.md)
 
-Creator mode provides [Plugin Manager](../../../../packages/boot/plugin-manager/README.md) and read-only [runtime inspection](../../../../packages/extensions/tool-cordis/README.md). Plugin configuration belongs to the current profile, affects its sessions, and survives process restarts.
+Standard and Creator modes provide [Plugin Manager](../../../../packages/boot/plugin-manager/README.md); Creator mode adds read-only [runtime inspection](../../../../packages/extensions/tool-cordis/README.md). Plugin configuration belongs to the current profile, affects its sessions, and survives process restarts.
 
 ## Connect an MCP server
 

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.zh.md

@@ -2,7 +2,7 @@
 
 [English](dynamic-cordis.md) | 中文
 
-创造模式提供 [Plugin Manager](../../../../packages/boot/plugin-manager/README.zh.md) 和只读[运行时检查](../../../../packages/extensions/tool-cordis/README.zh.md)。插件配置属于当前 profile，影响其会话，并在进程重启后保留。
+标准模式和创造模式提供 [Plugin Manager](../../../../packages/boot/plugin-manager/README.zh.md)；创造模式还提供只读[运行时检查](../../../../packages/extensions/tool-cordis/README.zh.md)。插件配置属于当前 profile，影响其会话，并在进程重启后保留。
 
 ## 连接 MCP 服务器
 

package/references/official-docs/docs/user/develop/practice/llm-adapter.i18n.yaml

@@ -30,5 +30,5 @@
   en: e05d4b0a901e8ef0
   zh: 9516cebb3e5c3692
 /llm-adapters/error-handling:
-  en: d54065c52caf7910
-  zh: 79b3ebc22a38286d
+  en: 08670c0bc7b8f494
+  zh: 37312af73d0acf91

package/references/official-docs/docs/user/develop/practice/llm-adapter.md

@@ -153,7 +153,7 @@ Compare the two shipped adapters to see the same harness contract implemented ov
 
 ## Error handling
 
-Adapters throw transport and protocol failures as `LlmError` values with stable codes. The agent loop preserves the error and code for diagnostics and policy; it does not convert an ordinary `Error` automatically. Every provider HTTP request must also merge `attributionHeaders()` and forward `options.signal`.
+Adapters throw transport and protocol failures as `LlmError` values with stable codes. `new LlmError` accepts only the built-in codes of `LLM_FAILURE_CODES`; an adapter's own code goes through `LlmError.fromFailure`. The agent loop preserves the error and code for diagnostics and policy; it does not convert an ordinary `Error` automatically. Every provider HTTP request must also merge `attributionHeaders()` and forward `options.signal`.
 
 ```ts
 import {
@@ -180,7 +180,7 @@ class HttpAdapter extends LlmAdapter {
       ...options.signal ? { signal: options.signal } : {},
     })
     if (!response.ok) {
-      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
+      throw LlmError.fromFailure({ message: `Provider API error: ${response.status}`, code: 'PROVIDER_HTTP_ERROR', status: response.status })
     }
     // A real adapter parses the response and emits the complete chunk sequence.
     yield { type: 'finish', reason: { kind: 'stop' } }

package/references/official-docs/docs/user/develop/practice/llm-adapter.zh.md

@@ -153,7 +153,7 @@ ctx.llm.registerAdapter(['my-provider'], adapter)
 
 ## 错误处理
 
-适配器应通过带稳定 code 的 `LlmError` 抛出传输和协议故障；agent loop（智能体循环）会保留该错误及其 code，用于诊断和策略处理。不要依赖普通 `Error` 被自动转换。每个提供方 HTTP 请求还必须合并 `attributionHeaders()`，并传递 `options.signal`。
+适配器应通过带稳定 code 的 `LlmError` 抛出传输和协议故障。`new LlmError` 只接受 `LLM_FAILURE_CODES` 中的内置 code；适配器自己的 code 通过 `LlmError.fromFailure` 抛出。agent loop（智能体循环）会保留该错误及其 code，用于诊断和策略处理。不要依赖普通 `Error` 被自动转换。每个提供方 HTTP 请求还必须合并 `attributionHeaders()`，并传递 `options.signal`。
 
 ```ts
 import {
@@ -180,7 +180,7 @@ class HttpAdapter extends LlmAdapter {
       ...options.signal ? { signal: options.signal } : {},
     })
     if (!response.ok) {
-      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
+      throw LlmError.fromFailure({ message: `Provider API error: ${response.status}`, code: 'PROVIDER_HTTP_ERROR', status: response.status })
     }
     // A real adapter parses the response and emits the complete chunk sequence.
     yield { type: 'finish', reason: { kind: 'stop' } }

package/references/official-docs/docs/user/guide/desktop-uninstall-cleanup.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for desktop-uninstall-cleanup.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/user/guide/desktop-uninstall-cleanup.md
+/uninstall-dsh-desktop:
+  en: bbd616011b211905
+  zh: 93b6146e97d9bb88
+/uninstall-dsh-desktop/1-uninstall-the-app:
+  en: 6ba6b5bc4153c3cd
+  zh: 36712b216d118155
+/uninstall-dsh-desktop/2-clean-up-local-data:
+  en: 459985c888cb631c
+  zh: 30771182f880e27b
+/uninstall-dsh-desktop/3-verify-cleanup:
+  en: 396bdba7cd24b278
+  zh: 2488dc9721081aee

package/references/official-docs/docs/user/guide/desktop-uninstall-cleanup.md

@@ -0,0 +1,60 @@
+# Uninstall DSH Desktop
+
+English | [中文](desktop-uninstall-cleanup.zh.md)
+
+Use this guide to uninstall DeepSeek Harness Desktop on macOS or Windows. Local data cleanup is optional.
+
+## 1. Uninstall the app
+
+Finish any commands using Desktop's bundled CLI. If you installed the `dsh` command through Desktop, first select **Manage dsh Command… → Remove** in the application menu. This removes Desktop's command registration without uninstalling independent CLI programs.
+
+Quit DeepSeek Harness, then uninstall it using your platform's procedure:
+
+- **macOS:** Delete the app from Applications in Finder.
+- **Windows:** Uninstall it through Settings → Apps → Installed apps on Windows 11, or Control Panel → Programs → Programs and Features.
+
+## 2. Clean up local data
+
+This step is optional. If you want to clean up local data, select the script for your platform below, then paste and run it in Terminal on macOS or PowerShell on Windows.
+
+The scripts permanently delete the current user's default Harness home and the Desktop data paths listed below, including sessions, credentials, settings, plugins, caches, and shared CLI state. If you configured `DSH_HOME`, inspect that directory separately before deleting it; the scripts still delete the default `~/.dsh`. Isolated development and test data directories are outside this cleanup scope.
+
+On Windows, the uninstaller normally removes the two application-data directories listed in the script but retains the Harness home. The script also handles those directories if uninstallation left files behind or retained app data.
+
+::: code-group
+
+```sh [macOS]
+sh -c '
+rm -rf -- \
+  "$HOME/.dsh" \
+  "$HOME/Library/Application Support/@deepseek-ai/dsh-desktop" \
+  "$HOME/Library/Logs/DeepSeek Harness" \
+  "$HOME/Library/Preferences/com.deepseek.dsh.plist" \
+  "$HOME/Library/Preferences/ByHost"/com.deepseek.dsh.ShipIt.*.plist \
+  "$HOME/Library/Caches/com.deepseek.dsh" \
+  "$HOME/Library/Caches/com.deepseek.dsh.ShipIt" \
+  "$HOME/Library/HTTPStorages/com.deepseek.dsh" \
+  "$HOME/Library/Caches/@deepseek-aidsh-desktop-updater" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh.helper"
+'
+```
+
+```powershell [Windows]
+$ErrorActionPreference = 'Stop'
+@(
+    (Join-Path $env:USERPROFILE '.dsh'),
+    (Join-Path $env:APPDATA '@deepseek-ai\dsh-desktop'),
+    (Join-Path $env:LOCALAPPDATA '@deepseek-aidsh-desktop-updater')
+) | ForEach-Object {
+    if (Test-Path -LiteralPath $_) {
+        Remove-Item -LiteralPath $_ -Recurse -Force
+    }
+}
+```
+
+:::
+
+## 3. Verify cleanup
+
+If you ran a cleanup script, confirm before reinstalling that the paths listed in it no longer exist. If the script reports an error, resolve it, rerun the script, and check all listed paths again. The Windows script stops at the first error, so later paths may remain.

package/references/official-docs/docs/user/guide/desktop-uninstall-cleanup.zh.md

@@ -0,0 +1,60 @@
+# 卸载 DSH 桌面端
+
+[English](desktop-uninstall-cleanup.md) | 中文
+
+本指南介绍如何在 macOS 或 Windows 上卸载 DeepSeek Harness 桌面端。清理本地数据是可选操作。
+
+## 1. 卸载应用
+
+先结束使用桌面端内置 CLI（命令行界面）的命令。如果曾通过 Desktop 安装 `dsh` 命令，请先在应用菜单中选择 **管理 dsh 命令… → 移除**。此操作移除桌面端的命令注册，不卸载独立安装的 CLI 程序。
+
+退出 DeepSeek Harness，然后按所在平台的方式卸载：
+
+- **macOS：** 在 Finder 的“应用程序”中删除应用。
+- **Windows：** 在 Windows 11 的“设置 → 应用 → 已安装的应用”，或“控制面板 → 程序 → 程序和功能”中卸载。
+
+## 2. 清理本地数据
+
+此步骤为可选操作。如果需要清理本地数据，请选择下方对应平台的脚本，在 macOS 的终端或 Windows 的 PowerShell 中粘贴运行。
+
+脚本会永久删除当前用户默认的 Harness 主目录及下方列出的 Desktop 数据路径，包括会话、凭据、设置、插件、缓存和与 CLI 共用的状态。如果配置了 `DSH_HOME`，删除前请单独检查该目录；脚本仍会删除默认的 `~/.dsh`。隔离的开发和测试数据目录不在此清理范围内。
+
+Windows 卸载程序通常会删除脚本中列出的两个应用数据目录，但保留 Harness 主目录。若卸载时有文件残留或保留了应用数据，脚本也会清理这些目录。
+
+::: code-group
+
+```sh [macOS]
+sh -c '
+rm -rf -- \
+  "$HOME/.dsh" \
+  "$HOME/Library/Application Support/@deepseek-ai/dsh-desktop" \
+  "$HOME/Library/Logs/DeepSeek Harness" \
+  "$HOME/Library/Preferences/com.deepseek.dsh.plist" \
+  "$HOME/Library/Preferences/ByHost"/com.deepseek.dsh.ShipIt.*.plist \
+  "$HOME/Library/Caches/com.deepseek.dsh" \
+  "$HOME/Library/Caches/com.deepseek.dsh.ShipIt" \
+  "$HOME/Library/HTTPStorages/com.deepseek.dsh" \
+  "$HOME/Library/Caches/@deepseek-aidsh-desktop-updater" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh.helper"
+'
+```
+
+```powershell [Windows]
+$ErrorActionPreference = 'Stop'
+@(
+    (Join-Path $env:USERPROFILE '.dsh'),
+    (Join-Path $env:APPDATA '@deepseek-ai\dsh-desktop'),
+    (Join-Path $env:LOCALAPPDATA '@deepseek-aidsh-desktop-updater')
+) | ForEach-Object {
+    if (Test-Path -LiteralPath $_) {
+        Remove-Item -LiteralPath $_ -Recurse -Force
+    }
+}
+```
+
+:::
+
+## 3. 验证清理结果
+
+如果运行了清理脚本，请在重新安装前确认脚本中列出的路径已不存在。如果脚本报错，请解决错误后重跑脚本，再次检查所有列出的路径。Windows 脚本会在首次报错时停止，后续路径可能仍未清理。

package/references/official-docs/docs/user/guide/index.i18n.yaml

@@ -15,5 +15,5 @@
   en: e1cb5a05bf6e109d
   zh: 8b181b0fecbc0517
 /use-the-web-ui/continue:
-  en: 6b244134309ca89c
-  zh: 971fa14939d88c6b
+  en: c28740683d2d9a01
+  zh: daf20f18e20be97f