dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-relative-coordinates/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "CUA relative coordinates accept integers from 0 to 999 and reject the former endpoint 1000."
+---
+
+# CUA relative coordinates use 0–999
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `cua` tool and application/window object methods now accept integers from 0 to 999 when `relative: true`. The previous range was 0 to 1000. Coordinates still use thousandths: divide by 1000, scale to window dimensions, and clamp inside the window. Values from 0 to 999 keep their existing positions. This affects `click`, `hover`, `scroll`, and both `drag` endpoints. Absolute screenshot pixels and AX element indices are unchanged.
+
+## Migration
+
+1. Update scripts and prompts that generate relative coordinates. Keep existing values from 0 to 999 unchanged. Replace the old endpoint 1000 with 999, for example with `Math.min(oldValue, 999)` for valid old coordinates. On larger windows, 999 can land farther inside than the former endpoint 1000.
+2. Read fresh window state, then invoke the affected action with integer coordinates in 0–999. Verify the result with a fresh observation. Relative values of 1000, negative values, and fractions are rejected before native input.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-relative-coordinates/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "CUA 相对坐标接受 0～999 的整数，并拒绝原端点 1000。"
+---
+
+# CUA 相对坐标使用 0～999
+
+[English](guide.md) | 中文
+
+## 变更
+
+`cua` 工具和应用或窗口对象方法在 `relative: true` 时接受 0～999 的整数，原范围为 0～1000。坐标仍使用千分比：除以 1000 后按窗口尺寸缩放，并限制在窗口内。0～999 的坐标保持原有落点。这影响 `click`、`hover`、`scroll` 和 `drag` 的起终点。绝对截图像素和 AX 元素编号保持原有行为。
+
+## 迁移
+
+1. 更新生成相对坐标的脚本和提示。0～999 的现有数值保持不变。将旧端点 1000 改为 999，例如对原本合法的旧坐标使用 `Math.min(oldValue, 999)`。在较大的窗口中，999 可能比原端点 1000 更靠内。
+2. 读取新的窗口状态后，使用 0～999 的整数坐标调用相应动作，再读取新状态验证结果。相对坐标为 1000、负数或小数时，会在原生输入前被拒绝。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/file-drag-callbacks/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.1-rc.2/file-drag-callbacks/guide.md
+/:
+  en: 9af755cc45c2291b
+  zh: 3c4053dd22a8263c
+/supply-file-preparation-callbacks-to-image-views:
+  en: 52816e83f1c07873
+  zh: fd96927a64d80a3c
+/supply-file-preparation-callbacks-to-image-views/change:
+  en: f790da179b0f64b4
+  zh: 7640190a12fd6796
+/supply-file-preparation-callbacks-to-image-views/migration:
+  en: 02f27032b22dae7c
+  zh: 242a3b6779ad4c4b

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/file-drag-callbacks/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Custom image factories and Markdown image delegates must supply file preparation callbacks."
+---
+
+# Supply file preparation callbacks to image views
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The published `conversation.images.content` Factory now requires a `fileDrag` inject member, and `MarkdownDelegate.fileImages` requires the same callbacks. `ChatViewInjected` also gains `fileDrag`. Custom registrations that construct these values must update before compilation succeeds. The shipped Web and Desktop compositions provide `@deepseek-ai/dsh-client-ui-file-drag`; custom compositions must provide the service and its feedback slot. Existing image label fields are unchanged.
+
+## Migration
+
+1. Include `@deepseek-ai/dsh-client-ui-file-drag` in the custom client composition, together with locale, the slot renderer, and a shell declaring `shell.overlay`. Declare `fileDrag` in each consumer plugin’s `inject` list.
+2. Pass `ctx.fileDrag.actions` as `fileDrag` when registering `conversation.images.content`, assembling `ChatViewInjected`, or constructing `MarkdownDelegate.fileImages`. The callbacks prepare Blob or URL content and report localized failures; components receive them explicitly. Optional `resourceAddress(path)` supplies a Session resource reference for authorized Desktop source reuse.
+3. Custom composer implementations can receive `ctx.fileDrag.read` through their own inject interface to accept application-local tokens. The `conversation.input.attachments` slot’s public props remain unchanged; only the shipped attachment implementation requires this callback. Accept internal drops in the composer region and retain ordinary `dataTransfer.files` handling for external files.
+4. Rebuild custom packages and verify an image drag into the composer. Confirm the original filename and bytes and that dropping back on the source does not add an attachment. See the [file-drag plugin](../../../../packages/client/ui-file-drag/README.md) for ownership and browser limitations.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/file-drag-callbacks/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "自定义图片 Factory 和 Markdown 图片委托必须提供文件准备回调。"
+---
+
+# 为图片视图提供文件准备回调
+
+[English](guide.md) | 中文
+
+## 变更
+
+已发布的 `conversation.images.content` Factory 现在要求 `fileDrag` 注入成员，`MarkdownDelegate.fileImages` 也要求相同回调。`ChatViewInjected` 同样新增 `fileDrag`。构造这些值的自定义注册必须更新才能通过编译。内置 Web 和 Desktop 组合提供 `@deepseek-ai/dsh-client-ui-file-drag`；自定义组合必须提供该服务及其反馈插槽。已有图片文案字段不变。
+
+## 迁移
+
+1. 在自定义客户端组合中加载 `@deepseek-ai/dsh-client-ui-file-drag`，同时提供 locale、插槽渲染器和声明 `shell.overlay` 的外壳。在每个消费插件的 `inject` 列表中声明 `fileDrag`。
+2. 注册 `conversation.images.content`、组装 `ChatViewInjected` 或构造 `MarkdownDelegate.fileImages` 时，将 `ctx.fileDrag.actions` 作为 `fileDrag` 传入。回调负责准备 Blob 或 URL 内容及报告本地化失败；组件显式接收它们。可选的 `resourceAddress(path)` 提供 Session 资源引用，以便 Desktop 经授权后复用源文件。
+3. 自定义输入框实现可通过自己的注入接口接收 `ctx.fileDrag.read`，以接受应用内令牌。`conversation.input.attachments` 插槽的公开 props 不变；只有内置附件实现要求该回调。内部投放仅在输入框范围接受，外部文件保留普通 `dataTransfer.files` 处理。
+4. 重新构建自定义包，验证图片拖入输入框后的原始文件名和字节，并确认拖回源图不会增加附件。所有权和浏览器限制见[文件拖放插件](../../../../packages/client/ui-file-drag/README.zh.md)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/headless-policy-composition/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.1-rc.2/headless-policy-composition/guide.md
+/:
+  en: 610cf36c44391560
+  zh: 7fdfc8873482071b
+/configure-policy-when-replacing-headless-startup:
+  en: 2fb959361985dd4e
+  zh: ebd14ca868ed7ddf
+/configure-policy-when-replacing-headless-startup/change:
+  en: 85378b0c14641e84
+  zh: e7e859c5e59e737a
+/configure-policy-when-replacing-headless-startup/migration:
+  en: 8d315115e046638b
+  zh: 7736ddaa79f77206

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/headless-policy-composition/guide.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "Headless compositions that disable the command-line provider must supply their sandbox policy configuration directly."
+---
+
+# Configure policy when replacing headless startup
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The headless bundle reads `--add-dir` through `headlessStartup` before activating its sandbox policy. An overlay that disables `headless-startup` must also remove that dependency from `sandbox-policy`. Otherwise the policy and its dependent tools remain pending. Ordinary `dsh headless` invocations need no configuration change.
+
+## Migration
+
+1. In the overlay that disables `headless-startup`, supply the policy directly. Retain any existing policy settings in this replacement config:
+
+   ```yaml
+   - id: sandbox-policy
+     inject: []
+     config:
+       mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
+       workspaceRoot: !!js process.cwd()
+   ```
+
+2. If the overlay keeps command-line startup but replaces `headless-runner` or `sandbox-policy`, retain their `headlessStartup` bindings from the [headless bundle](../../../../packages/bundle/headless/cordis.patch.yml).
+3. Launch a small task through the custom profile and verify that its tools activate. If startup remains enabled, pass `--add-dir` and check that a write to the selected directory succeeds.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/headless-policy-composition/guide.zh.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "禁用命令行提供方的 Headless 组合必须直接提供沙箱策略配置。"
+---
+
+# 替换 headless startup 时配置策略
+
+[English](guide.md) | 中文
+
+## 变更
+
+headless 组合包在激活沙箱策略前，通过 `headlessStartup` 读取 `--add-dir`。禁用 `headless-startup` 的 overlay 也必须从 `sandbox-policy` 移除该依赖，否则策略及其依赖工具会保持 pending 状态。普通 `dsh headless` 调用无需修改配置。
+
+## 迁移
+
+1. 在禁用 `headless-startup` 的 overlay 中直接提供策略。在此替换配置中保留已有策略设置：
+
+   ```yaml
+   - id: sandbox-policy
+     inject: []
+     config:
+       mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
+       workspaceRoot: !!js process.cwd()
+   ```
+
+2. 如果 overlay 保留命令行 startup，但替换了 `headless-runner` 或 `sandbox-policy`，请保留 [headless 组合包](../../../../packages/bundle/headless/cordis.patch.yml)中的 `headlessStartup` 绑定。
+3. 通过自定义配置档运行一个小任务并确认工具已激活。如果保留 startup，请传入 `--add-dir`，并检查对所选目录的写入是否成功。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/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.1-rc.2/model-badge-package-removal/guide.md
+/:
+  en: e3db78299cefc568
+  zh: 0c1892abef438638
+/the-ui-deepseek-model-label-1017-package-is-removed:
+  en: 772b7e3479b2e52b
+  zh: 9d7a225cf77c2664
+/the-ui-deepseek-model-label-1017-package-is-removed/change:
+  en: 48543e623bac7b47
+  zh: a22640ced4b587fa
+/the-ui-deepseek-model-label-1017-package-is-removed/migration:
+  en: 3e366a0f2daf220c
+  zh: 859d6bc103213809

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The fixed 1017 model badge package is removed; model badges come from the DeepSeek model listing."
+---
+# The `ui-deepseek-model-label-1017` package is removed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` and its `ui-deepseek-model-label-1017` row in the Web bundle are removed, and the package receives no further releases. The composer model selector shows the badge that the DeepSeek `GET /models` listing declares for a model; without a declared badge, `DeepSeek-V4.1-Flash` shows no `1017`. A profile patch that disables or edits the removed row matches no entry, so boot warns that the entry is not found and skips the patch.
+
+## Migration
+
+1. Delete the patch whose `id` is `ui-deepseek-model-label-1017`, with its `disabled` or other fields, from `$DSH_HOME/profiles/<profile>/cordis.patch.yml` and from any overlay passed with `--patch`.
+2. Remove `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` from the dependencies of any package that lists it.
+3. To change how model names or badges render, contribute to the `conversation.input.model.label` slot; its owner props carry the catalog `model.badge` ([label extensions](../../../../packages/client/ui-model-selection/README.md#use-this-package)).
+4. Restart DSH and confirm that boot reports no missing `ui-deepseek-model-label-1017` entry.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "固定的 1017 模型角标包已移除，模型角标改由 DeepSeek 模型列表下发。"
+---
+# `ui-deepseek-model-label-1017` 包已移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` 及其在 Web bundle 中的 `ui-deepseek-model-label-1017` 条目已移除，该包不再发布新版本。composer 模型选择器显示 DeepSeek `GET /models` 列表为模型声明的角标；列表没有声明角标时，`DeepSeek-V4.1-Flash` 不再显示 `1017`。停用或修改该条目的 profile patch 不再匹配任何条目，启动时会警告找不到该条目并跳过这条 patch。
+
+## 迁移
+
+1. 从 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 以及通过 `--patch` 传入的 overlay 中，删除 `id` 为 `ui-deepseek-model-label-1017` 的 patch，连同其中的 `disabled` 或其他字段。
+2. 若有包在依赖中列出 `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017`，将其删除。
+3. 如需改变模型名称或角标的显示方式，向 `conversation.input.model.label` slot 注册组件；其 owner props 携带目录中的 `model.badge`（[名称扩展](../../../../packages/client/ui-model-selection/README.zh.md#use-this-package)）。
+4. 重启 DSH，确认启动输出中没有找不到 `ui-deepseek-model-label-1017` 条目的警告。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/new-session-blank-reuse/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.1-rc.2/new-session-blank-reuse/guide.md
+/:
+  en: 22fc9673ecfb83a7
+  zh: 8f73437381945374
+/new-session-returns-to-its-blank-session:
+  en: a169c9999df57111
+  zh: 64f09ffd5ea03a84
+/new-session-returns-to-its-blank-session/change:
+  en: 92a5464174d2614a
+  zh: dd25d30ce416ad39
+/new-session-returns-to-its-blank-session/migration:
+  en: 8e4c268720257098
+  zh: a0ade706d7e3c9a2

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/new-session-blank-reuse/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "New Session reuses a blank Session in the Workspace again instead of creating a fresh Agent on every call."
+---
+
+# New Session returns to its blank Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In 0.2.1-rc.2, New Session in Web and Desktop, and `uiWorkspace.startSession(workspaceId)` without options, created a fresh Session and Agent on every call ([earlier guide](../../v0.2.1-alpha.1/new-session-generations/guide.md)). The blank Session it left behind is hidden from the Session tree, so its unsent draft could no longer be reached.
+
+New Session now reuses the first unstarted, unarchived blank Session in the Workspace, which the Host switches to its default preset, and creates a Session only when none exists. `startSession` with options, `openWorkspace`, and `connectWorkspace` follow the same rule; a request that names an Agent preset skips blanks whose listed preset is a different one, so preset flows such as the Creator entries do not take over another preset's draft.
+
+A reused blank whose Agent is still loaded keeps the preset composition it was created with. New Session no longer guarantees the current preset definition.
+
+## Migration
+
+1. After changing a preset definition, start the conversation in a Session whose Agent was composed after the change, for example by restarting the Host before using New Session; a blank resumed after a restart composes the current definition.
+2. Client integrations that must not take over a blank listing another preset pass `{ agentPreset }` to `startSession`, `openWorkspace`, or `connectWorkspace`.
+3. To confirm, type a draft after New Session, open another Session, and use New Session again: the same blank opens with the draft.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/new-session-blank-reuse/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "新会话重新复用工作区内的空白 Session，不再每次都创建新的 Agent。"
+---
+
+# 新会话回到其空白 Session
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 0.2.1-rc.2 中，Web 和 Desktop 的新会话，以及不带选项的 `uiWorkspace.startSession(workspaceId)`，每次调用都创建新的 Session 和 Agent（[此前的指南](../../v0.2.1-alpha.1/new-session-generations/guide.zh.md)）。被留下的空白 Session 不在 Session 树中显示，因此其中未发送的草稿无法再回到。
+
+现在新会话复用工作区内第一个未开始、未归档的空白 Session，由 Host 切换到其默认 preset，没有空白 Session 时才创建。带选项的 `startSession`、`openWorkspace` 和 `connectWorkspace` 采用相同规则；指明 Agent preset 的请求会跳过列出其他 preset 的空白会话，因此创造模式入口等 preset 流程不会接管其他 preset 的草稿。
+
+被复用的空白会话若其 Agent 仍在加载状态，会保留创建时的 preset 装配。新会话不再保证使用当前的 preset 定义。
+
+## 迁移
+
+1. 更改 preset 定义后，在 Agent 于更改之后装配的 Session 中开始对话，例如先重启 Host 再使用新会话；重启后恢复的空白会话会按当前定义装配。
+2. 不能接管列出其他 preset 的空白会话的客户端集成，向 `startSession`、`openWorkspace` 或 `connectWorkspace` 传入 `{ agentPreset }`。
+3. 确认方式：新会话中输入草稿，打开另一个 Session，再使用新会话，应打开同一个空白会话并显示该草稿。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/node-24/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.1-rc.2/node-24/guide.md
+/:
+  en: 59f0a8ea5e09a902
+  zh: 2c4a18f247a8f36c
+/node-js-24-is-required:
+  en: 6de920b8f905304d
+  zh: 019e0df3bf4effe9
+/node-js-24-is-required/change:
+  en: ca2d29f4225a9883
+  zh: 13ec2ae202dd2e39
+/node-js-24-is-required/migration:
+  en: 375d422a3627042b
+  zh: 9455a6b87431050f

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/node-24/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DSH requires Node.js 24.9 or newer and no longer supports Node.js 22."
+---
+# Node.js 24 is required
+
+English | [中文](guide.zh.md)
+
+## Change
+
+DSH requires Node.js 24.9 or newer. The previous release also supported Node.js 22.19 and newer releases in the 22.x line. This change affects npm installations, source checkouts, and the Python SDK's explicit `DSH_RUNTIME_MODE=node` development carrier. Packaged desktop applications and the Python SDK's bundled executable provide their own runtime.
+
+## Migration
+
+1. Upgrade the Node.js installation used to start DSH to version 24.9 or newer. Update Node version pins in development environments, containers, and CI jobs.
+2. Run `node --version` in the same environment and confirm that it reports version 24.9 or newer.
+3. For a source checkout, run `pnpm install`. Start DSH with the profile you normally use and confirm that it starts successfully.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/node-24/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DSH 要求 Node.js 24.9 或更高版本，不再支持 Node.js 22。"
+---
+# 必须使用 Node.js 24
+
+[English](guide.md) | 中文
+
+## 变更
+
+DSH 要求 Node.js 24.9 或更高版本。上一版本还支持 Node.js 22.19 及 22.x 系列中的后续版本。此变更影响 npm 安装、源码检出，以及 Python SDK 显式指定 `DSH_RUNTIME_MODE=node` 的开发载体。打包的桌面应用和 Python SDK 的内置可执行文件自带运行时。
+
+## 迁移
+
+1. 将用于启动 DSH 的 Node.js 安装升级至 24.9 或更高版本。更新开发环境、容器和 CI 任务中固定的 Node 版本。
+2. 在同一环境中运行 `node --version`，确认版本为 24.9 或更高版本。
+3. 对于源码检出，运行 `pnpm install`。使用平常的 profile 启动 DSH，确认它能成功启动。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/official-bundle-lists/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.1-rc.2/official-bundle-lists/guide.md
+/:
+  en: d6f85fefe3671f5d
+  zh: 2719b3d5ba1b2120
+/import-bundle-lists-from-deepseek-ai-dsh-official-bundles:
+  en: 89f87bcf95ee4262
+  zh: 00bbb48605743bcc
+/import-bundle-lists-from-deepseek-ai-dsh-official-bundles/change:
+  en: 0d8984d9bead43c6
+  zh: 60939a14fcf1ba9a
+/import-bundle-lists-from-deepseek-ai-dsh-official-bundles/migration:
+  en: ef2f3d6258a3b2bb
+  zh: 65a79e9551f8b237

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/official-bundle-lists/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The bundle lists and profile templates move from @deepseek-ai/dsh-app-boot to @deepseek-ai/dsh-official-bundles."
+---
+
+# Import bundle lists from `@deepseek-ai/dsh-official-bundles`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-app-boot` no longer exports `PROFILE_TEMPLATES`, `ProfileTemplate`, `DEFAULT_PROFILE_BUNDLES`, `OPTIONAL_BUNDLES`, `ON_DEMAND_BUNDLES`, `OFFICIAL_ON_DEMAND_CATALOG`, or `OfficialBundleCatalogEntry`. The new published package `@deepseek-ai/dsh-official-bundles` exports them with unchanged values and types. Code that imports any of these names from `@deepseek-ai/dsh-app-boot` fails to compile or load. The `dsh` launcher, profiles, and bundle selection behave as before.
+
+## Migration
+
+1. Add `@deepseek-ai/dsh-official-bundles` to the `dependencies` of each package that imports one of these names.
+2. Change those imports from `@deepseek-ai/dsh-app-boot` to `@deepseek-ai/dsh-official-bundles`, for example `import { PROFILE_TEMPLATES } from '@deepseek-ai/dsh-official-bundles'`. Keep importing every other name, such as `initProfile` or `loadProfile`, from `@deepseek-ai/dsh-app-boot`.
+3. Run your type check or build; it succeeds when no import of a moved name from `@deepseek-ai/dsh-app-boot` remains. See the [package README](../../../../packages/util/official-bundles/README.md) for each list.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/official-bundle-lists/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "组合包列表和 profile 模板从 @deepseek-ai/dsh-app-boot 移至 @deepseek-ai/dsh-official-bundles。"
+---
+
+# 从 `@deepseek-ai/dsh-official-bundles` 导入组合包列表
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-app-boot` 不再导出 `PROFILE_TEMPLATES`、`ProfileTemplate`、`DEFAULT_PROFILE_BUNDLES`、`OPTIONAL_BUNDLES`、`ON_DEMAND_BUNDLES`、`OFFICIAL_ON_DEMAND_CATALOG` 和 `OfficialBundleCatalogEntry`。新发布的包 `@deepseek-ai/dsh-official-bundles` 导出它们，值和类型不变。从 `@deepseek-ai/dsh-app-boot` 导入这些名称的代码将无法编译或加载。`dsh` 启动器、profile 和组合包选择的行为不变。
+
+## 迁移
+
+1. 在每个导入这些名称的包的 `dependencies` 中加入 `@deepseek-ai/dsh-official-bundles`。
+2. 把这些导入从 `@deepseek-ai/dsh-app-boot` 改为 `@deepseek-ai/dsh-official-bundles`，例如 `import { PROFILE_TEMPLATES } from '@deepseek-ai/dsh-official-bundles'`。其他名称（如 `initProfile` 或 `loadProfile`）仍从 `@deepseek-ai/dsh-app-boot` 导入。
+3. 运行类型检查或构建；不再有从 `@deepseek-ai/dsh-app-boot` 导入已移动名称的代码时即通过。各列表的说明见[包 README](../../../../packages/util/official-bundles/README.zh.md)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/persistent-terminal-controls/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.1-rc.2/persistent-terminal-controls/guide.md
+/:
+  en: 2b63472f97a928a2
+  zh: 1db21d2ab8ee528a
+/manage-persistent-terminals-through-profile-configuration:
+  en: 39659f2e595dbb93
+  zh: 45b58c9ac1d0b006
+/manage-persistent-terminals-through-profile-configuration/change:
+  en: bdbdd9596d9f45ed
+  zh: e874ef3b122cea38
+/manage-persistent-terminals-through-profile-configuration/migration:
+  en: 87bdea56366ec097
+  zh: ed6add607169b1ba

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/persistent-terminal-controls/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Persistent-terminal bundle controls leave the Plugins page; profile configuration still enables and disables the bundle."
+---
+
+# Manage persistent terminals through profile configuration
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Web and Desktop no longer show the persistent-terminal bundle in Plugins lists or detail pages, including for profiles that already enabled it. The package and existing activation remain intact. The minimal preset's own persistent shell is independent of this bundle.
+
+## Migration
+
+1. To keep an existing selection, no action is required. To change it, open `$DSH_HOME/profiles/<name>/package.json`, where the default home is `~/.dsh` and `<name>` is the running profile, such as `web` or `desktop`.
+2. Remove `@deepseek-ai/dsh-experimental-terminal-bundle` from `dsh.profile.bundles` to disable it, or add it to enable it. Keep the other entries and dependencies intact.
+3. Restart the same profile to apply the selection. For a CLI-managed profile, run `dsh --profile <name> --dump-config`: the `optional-persistent-terminals` group is present only when the bundle is selected. See the [profile reference](../../../../apps/cli/reference/README.md#profile-boot).

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/persistent-terminal-controls/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "持久终端组合包开关移出插件页，仍可通过 profile 配置启用或关闭组合包。"
+---
+
+# 通过 profile 配置管理持久终端
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 和 Desktop 的插件列表和详情页不再显示持久终端组合包，包括此前已启用它的 profile。包及已有启用状态保持不变。minimal 预设自带的持久 shell 独立于此组合包。
+
+## 迁移
+
+1. 保留已有选择无需操作。如需更改，打开 `$DSH_HOME/profiles/<name>/package.json`，home 默认为 `~/.dsh`，`<name>` 是运行中的 profile，例如 `web` 或 `desktop`。
+2. 从 `dsh.profile.bundles` 中移除 `@deepseek-ai/dsh-experimental-terminal-bundle` 即可关闭，加入即可启用。保留其他条目和依赖。
+3. 重启同一个 profile 后生效。对于 CLI 管理的 profile，运行 `dsh --profile <name> --dump-config`：只有选中此组合包时，配置才包含 `optional-persistent-terminals` 分组。详见 [profile 参考](../../../../apps/cli/reference/README.zh.md#profile-boot)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-default-capacities/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.1-rc.2/pi-ai-default-capacities/guide.md
+/:
+  en: 61a3259e0c1e7893
+  zh: 0c96fdeebcb2368f
+/pi-ai-default-model-capacities:
+  en: cc30c7c81bcb89eb
+  zh: ee0b1b5f82676f9e
+/pi-ai-default-model-capacities/change:
+  en: a47430fe02282532
+  zh: 4f8d65358bb36431
+/pi-ai-default-model-capacities/migration:
+  en: ca3e5882f43f88c3
+  zh: 89d939f046a6ee1d

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-default-capacities/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Undescribed pi-ai models inherit larger context and output capacities unless the provider configures explicit defaults."
+---
+
+# pi-ai default model capacities
+
+English | [中文](guide.zh.md)
+
+## Change
+
+For models whose capacity is absent from both configuration and the installed catalog, `llm-pi-ai` raises `defaultContextWindow` from 262,144 to 1,000,000 tokens and `defaultMaxTokens` from 32,768 to 128,000 tokens. A larger assumed context window can delay automatic compaction. Explicit model capacities, catalog values, and provider defaults retain their precedence. The output-capacity fallback does not become a Harness request-level `maxTokens` default.
+
+## Migration
+
+1. Check the actual limits of custom endpoints. In the `llm-pi-ai` configuration in `cordis.patch.yml`, set `providers.<provider>.defaultContextWindow` and `providers.<provider>.defaultMaxTokens` when those limits differ. To retain the previous defaults, use `262144` and `32768` respectively.
+2. For models with different limits on the same provider, set `contextWindow` and `maxTokens` on their `providers.<provider>.models` entries. An explicitly configured model `maxTokens` also supplies the Harness request default.
+3. Reopen the profile configuration and confirm the saved numeric values. See the [provider configuration reference](../../../../packages/llm/llm-pi-ai/README.md).

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-default-capacities/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "配置和目录均未描述容量的 pi-ai 模型会继承更大的上下文与输出容量，除非提供方显式配置默认值。"
+---
+
+# pi-ai 默认模型容量
+
+[English](guide.md) | 中文
+
+## 变更
+
+对于配置和已安装目录均未提供容量的模型，`llm-pi-ai` 将 `defaultContextWindow` 从 262,144 提高到 1,000,000 tokens，将 `defaultMaxTokens` 从 32,768 提高到 128,000 tokens。更大的假定上下文窗口可能推迟自动压缩。显式模型容量、目录值和提供方默认值仍保留原有优先级。输出容量回退值不会成为 Harness 请求级 `maxTokens` 默认值。
+
+## 迁移
+
+1. 核对自定义端点的实际限制。如果限制不同，在 `cordis.patch.yml` 的 `llm-pi-ai` 配置中设置 `providers.<provider>.defaultContextWindow` 和 `providers.<provider>.defaultMaxTokens`。如需保留原默认值，分别填写 `262144` 和 `32768`。
+2. 同一提供方的模型限制不同时，在相应 `providers.<provider>.models` 条目上设置 `contextWindow` 和 `maxTokens`。显式配置的模型 `maxTokens` 同时提供 Harness 请求默认值。
+3. 重新打开 profile 配置，确认保存的数值。参见[提供方配置参考](../../../../packages/llm/llm-pi-ai/README.zh.md)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-model-catalog/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.1-rc.2/pi-ai-model-catalog/guide.md
+/:
+  en: 95f84e4861e282ee
+  zh: ee2bf9db07fcc61e
+/pi-ai-1-3-0-model-catalog-changes:
+  en: 201fd0e2296a9792
+  zh: a95449587c9e7e5c
+/pi-ai-1-3-0-model-catalog-changes/change:
+  en: 4e1d3521fd5f9dec
+  zh: 9978497665279e28
+/pi-ai-1-3-0-model-catalog-changes/migration:
+  en: 6f1313d45d05c97d
+  zh: a5d396d5c9316031

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-model-catalog/guide.md

@@ -0,0 +1,53 @@
+---
+kind: upgrade-guide
+description: "The pi-ai 1.3.0 catalog removes model IDs and lowers some model capacities."
+---
+
+# pi-ai 1.3.0 model catalog changes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The pi-ai dependency changes from 1.1.0 to 1.3.0. These chat model IDs leave the catalog. Stored `modelOverrides` report missing-catalog diagnostics; new overrides are rejected. Explicit `models` entries lose their catalog defaults.
+
+| Provider | Removed model IDs |
+|---|---|
+| `google-vertex` | `gemini-flash-latest`, `gemini-flash-lite-latest` |
+| `nvidia` | `moonshotai/kimi-k3`, `nvidia/nemotron-3-super-120b-a12b` |
+| `opencode` | `exo-free`, `fledge-alpha-free`, `ling-3.0-flash-fin-free`, `ling-3.1-flash-free` |
+| `opencode-go` | `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp`, `grok-4.6`, `minimax-m2.7` |
+| `openrouter` | `anthropic/claude-sonnet-4`, `apodex/apodex-1.1-mini:free`, `inclusionai/ling-3.0-flash-fin`, `inclusionai/ling-3.0-flash-sante:free`, `qwen/qwen-plus-2025-07-28`, `qwen/qwen3-235b-a22b`, `qwen/qwen3-30b-a3b-thinking-2507`, `qwen/qwen3-8b`, `qwen/qwen3-coder-plus`, `qwen/qwen3-max`, `qwen/qwen3-max-thinking`, `qwen/qwen3-vl-235b-a22b-thinking`, `qwen/qwen3-vl-32b-instruct`, `qwen/qwen3-vl-8b-thinking`, `qwen/qwen3.6-max-preview`, `sao10k/l3.1-euryale-70b`, `unbiased/pareto`, `unbiased/pareto-26.10-preview` |
+| `vercel-ai-gateway` | `alibaba/qwen-3.6-max-preview`, `alibaba/qwen3-235b-a22b-thinking`, `alibaba/qwen3-coder-plus`, `alibaba/qwen3-max`, `alibaba/qwen3-max-preview`, `alibaba/qwen3-vl-235b-a22b-instruct`, `alibaba/qwen3-vl-thinking`, `anthropic/claude-3-haiku`, `anthropic/claude-opus-4`, `inclusionai/ling-3.1-flash-free` |
+
+These catalog limits decrease. Values are tokens; `—` means that limit did not decrease. Explicit overrides still take precedence. `maxTokens` describes model capacity, not an implicit request limit.
+
+| Provider/model | New contextWindow / maxTokens |
+|---|---|
+| `anthropic/claude-sonnet-4-5` | 200000 / — |
+| `anthropic/claude-sonnet-4-5-20250929` | 200000 / — |
+| `openrouter/deepseek/deepseek-v4-flash` | 1048575 / 943717 |
+| `openrouter/inclusionai/ling-3.0-flash-vl` | 131072 / — |
+| `openrouter/meta-llama/llama-4-scout` | 131072 / — |
+| `openrouter/minimax/minimax-m2` | — / 131072 |
+| `openrouter/minimax/minimax-m2.5` | 198000 / 32768 |
+| `openrouter/minimax/minimax-m2.7` | — / 131072 |
+| `openrouter/moonshotai/kimi-k2-thinking` | — / 98304 |
+| `openrouter/nvidia/nemotron-3-ultra-550b-a55b` | 202800 / — |
+| `openrouter/openai/gpt-oss-120b` | — / 65536 |
+| `openrouter/qwen/qwen3-235b-a22b-thinking-2507` | 128000 / 16384 |
+| `openrouter/qwen/qwen3.5-35b-a3b` | 256000 / 16384 |
+| `openrouter/qwen/qwen3.8-2.4t-a95b` | 1000000 / — |
+| `openrouter/qwen/qwen3.8-27b` | 262144 / — |
+| `openrouter/~z-ai/glm-latest` | — / 131072 |
+| `radius/claude-sonnet-4-5` | 200000 / — |
+| `vercel-ai-gateway/alibaba/qwen3-coder` | — / 32768 |
+| `vercel-ai-gateway/deepseek/deepseek-v4.1-flash-fast` | — / 32768 |
+
+The `vercel-ai-gateway` model `alibaba/qwen-3-235b` is now non-reasoning. Protocol and effort changes have a [separate guide](../pi-ai-protocol-replay/guide.md).
+
+## Migration
+
+1. In Settings → Models, replace removed IDs with supported models. Check endpoints, capabilities, and prices; IDs have no automatic replacement.
+2. Update selections in `cordis.patch.yml`, preset patches, and affected Sessions. Remove obsolete `providers.<provider>.modelOverrides.<id>` entries and replace removed IDs in `providers.<provider>.models` lists. See the [configuration reference](../../../../packages/llm/llm-pi-ai/README.md).
+3. Review capacity and reasoning overrides against the endpoint's supported values. Start the profile, confirm the model has no configuration diagnostic, and send a short prompt.