dsh-plugin-guide 0.3.42 → 0.4.0

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/jsonl-persistence-plugin/guide.md
-/:
-  en: eff30513d0de970b
-  zh: c16a32f374bd07e1
-/mount-jsonl-persistence-through-its-plugin:
-  en: ae3ff407a497cf5c
-  zh: 1b71e651967b8255
-/mount-jsonl-persistence-through-its-plugin/change:
-  en: ea5defddc1a9b989
-  zh: 97902f22a4196b12
-/mount-jsonl-persistence-through-its-plugin/migration:
-  en: 93d9f202c59303e9
-  zh: c5ced26ed819d7c5

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "JSONL persistence uses a namespace plugin import; direct service-class construction and class type annotations must use the persistence service instead."
----
-
-# Mount JSONL persistence through its plugin
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`@deepseek-ai/dsh-session-persistence-jsonl` exports a function plugin through named `name`, `Config`, and `apply` exports, with no default export. Default imports, direct construction, subclassing, `instanceof`, and class type annotations are affected. The plugin retains listeners and handles through the consumer unloads triggered by removing this provider; concurrent root disposal remains unordered. The `sessionPersistence` service API, YAML configuration, and stored files remain unchanged.
-
-## Migration
-
-1. Replace the default import with `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`. Existing `ctx.plugin(JsonlSessionPersistence, config)` calls remain valid; replace direct construction with this mounting call. For dynamic imports, use the module namespace returned by `await import(...)` instead of its `.default`. Consumers declare `inject: ['sessionPersistence']` and access `ctx.sessionPersistence`.
-2. Use the `SessionPersistence` type from `@deepseek-ai/dsh-session-persistence` for service annotations. Replace concrete-class `instanceof` checks and subclasses with consumers of that service; the concrete JSONL class is private.
-3. Await plugin startup and confirm a session can be created, flushed, and reopened. Register asynchronous consumer cleanup in the scope that injects `sessionPersistence` so backend unloading waits for it.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "JSONL 持久化使用插件命名空间导入；直接构造服务类和类类型标注需要改用持久化服务。"
----
-
-# 通过插件挂载 JSONL 持久化
-
-[English](guide.md) | 中文
-
-## 变更
-
-`@deepseek-ai/dsh-session-persistence-jsonl` 通过命名导出的 `name`、`Config` 和 `apply` 提供函数插件，没有默认导出。默认导入、直接构造、继承、`instanceof` 和类类型标注会受到影响。插件会保留监听器和句柄，直到移除该提供者所触发的消费者卸载完成；根作用域的并发卸载仍不保证顺序。`sessionPersistence` 服务 API、YAML 配置和存储文件保持不变。
-
-## 迁移
-
-1. 将默认导入替换为 `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`。现有的 `ctx.plugin(JsonlSessionPersistence, config)` 调用仍然有效；将直接构造改为该挂载调用。动态导入直接使用 `await import(...)` 返回的模块命名空间，不再取其 `.default`。消费者声明 `inject: ['sessionPersistence']` 并访问 `ctx.sessionPersistence`。
-2. 服务类型标注使用 `@deepseek-ai/dsh-session-persistence` 的 `SessionPersistence` 类型。将针对具体类的 `instanceof` 检查和子类改为消费该服务；具体 JSONL 类是私有的。
-3. 等待插件启动完成，确认能够创建、flush 并重新打开会话。将消费者的异步清理注册到注入 `sessionPersistence` 的作用域中，以便后端卸载时等待它完成。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/mock-messages-events/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/mock-messages-events/guide.md
-/:
-  en: 50f48b2d699ff15d
-  zh: 3767619b47fd76fb
-/read-named-events-from-the-messages-mock-server:
-  en: d97603a00507734c
-  zh: 6cfec46c21e97b70
-/read-named-events-from-the-messages-mock-server/change:
-  en: f03d6e1d637f6397
-  zh: cabeac0144d33ac4
-/read-named-events-from-the-messages-mock-server/migration:
-  en: 7528082a3376359e
-  zh: 0e8eaad875394baa

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/mock-messages-events/guide.md

@@ -1,17 +0,0 @@
----
-kind: upgrade-guide
-description: "Messages mock streams publish named SSE events for native SDK consumers."
----
-
-# Read named events from the Messages mock server
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The next release makes `@deepseek-ai/dsh-llm-mock-server` emit the Messages event name beside each structured SSE payload. Native SDKs require these names to process message and content-block events. Consumers that accept only unnamed SSE messages must update their event handling. Scripted payloads, ordering, request capture, and chunk counts are unchanged; the deliberately malformed JSON behavior still sends its invalid data directly.
-
-## Migration
-
-1. Consume the named Messages events and parse their `data` fields. Do not filter the stream to unnamed events.
-2. Verify a complete text response, tool-call response, and the fault behaviors your test uses. The [mock server reference](../../../../packages/test-support/llm-mock-server/README.md) describes the available scripts.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/mock-messages-events/guide.zh.md

@@ -1,17 +0,0 @@
----
-kind: upgrade-guide
-description: "Messages 模拟流为原生 SDK 消费方发布具名 SSE 事件。"
----
-
-# 读取 Messages 模拟服务器的具名事件
-
-[English](guide.md) | 中文
-
-## 变更
-
-下一版本的 `@deepseek-ai/dsh-llm-mock-server` 在每个结构化 SSE 载荷旁发送 Messages 事件名。原生 SDK 需要这些名称才能处理消息与内容块事件。只接受无名 SSE 消息的消费方必须更新事件处理。脚本载荷、顺序、请求捕获与分片计数保持不变；刻意生成畸形 JSON 的行为仍直接发送无效数据。
-
-## 迁移
-
-1. 消费具名 Messages 事件并解析其 `data` 字段。不要将流过滤为仅含无名事件。
-2. 验证完整文本响应、工具调用响应和测试使用的故障行为。[模拟服务器参考](../../../../packages/test-support/llm-mock-server/README.zh.md)说明了可用脚本。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/native-subagent-bundle-tools/guide.md
-/:
-  en: 4e1c7b1bfb2ba5ca
-  zh: c3f5ac60d10a215f
-/native-subagent-bundles-include-global-tools:
-  en: 8f785a4b502f1f78
-  zh: 527952686410adba
-/native-subagent-bundles-include-global-tools/change:
-  en: 3432d6ba2ccf6492
-  zh: 41cdf90f9d5b330d
-/native-subagent-bundles-include-global-tools/migration:
-  en: 304dc5243b2f8159
-  zh: 38cd9aa136dc8009

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools/guide.md

@@ -1,31 +0,0 @@
----
-kind: upgrade-guide
-description: "Claude Code and Codex bundles add global delegation tools while retaining their package and row identities."
----
-
-# Native subagent bundles include global tools
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`@deepseek-ai/dsh-subagent-claude-code` and `@deepseek-ai/dsh-subagent-codex` keep their package names, bundle selections, provider row IDs, configuration, and native authentication. A selected bundle now also registers its delegation tool as a Host global tool, visible to every preset including minimal; previously the bundle registered only its provider. Live Agents see the tool from their next request after the bundle is enabled, and lose it after the bundle is switched off.
-
-The contributed Host rows are `tool-subagent-claude-code` and `tool-subagent-codex`. Later user layers can override their configuration or disabled state by row id. An override does not select an unselected bundle. A preset that registers its own tool with the same name shadows the global tool for its Agents.
-
-Delegation follows the shared managed-activation API: the tool returns a child ID, and completion arrives as a logged notice to the parent Agent. Remove obsolete `backgroundMode` settings; `maxDepth: provider-managed` remains supported for these native providers.
-
-## Migration
-
-1. Preserve selected bundle names, provider configuration, and authentication. Existing provider-only packages need **Update** in Plugins → Official to receive the tool-contributing bundle; restart when requested. To adopt a new provider, enable its card. [Installation targets](../../../../packages/boot/plugin-manager/README.md#use-this-package) follow the published DSH version or source checkout; equal version strings do not make an older registry package equivalent to a development link. Off only deselects; Remove remains separate.
-2. Configure the tool with an ordinary row patch. Configuration overrides still replace the complete configuration. For example, this keeps the Codex tool disabled while the provider stays registered:
-
-   ```yaml
-   - id: tool-subagent-codex
-     disabled: true
-   ```
-
-3. If a manual Host row registers the same tool name, remove that redundant row or disable the bundle's row. Verify the effective tool catalog in a Session.
-4. Plugin clients receive required `BundleInfo.official` and `BundleInfo.availability` fields; detail-slot `PluginPackageRef` receives them too. `official` identifies project maintenance, `availability` reports `installation`, `profile`, or `missing`, and `installed` still means a profile dependency declaration. Detail-slot readers that only display existing fields need no changes; constructors and exact validators must include the new fields. Optional `installTarget` identifies the offered version and registry or local-link spec.
-
-**Other profiles.** The bundle layers insert Host rows only, so headless, SDK, ACP, and custom profiles can select them as well. Profiles that keep the provider package without selecting its bundle can compose the same rows using the [Codex](../../../../packages/subagent/subagent-codex/README.md#exposing-the-tool) or [Claude Code](../../../../packages/subagent/subagent-claude-code/README.md#exposing-the-tool) example.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools/guide.zh.md

@@ -1,31 +0,0 @@
----
-kind: upgrade-guide
-description: "Claude Code 与 Codex bundle 添加全局委派工具，同时保留包名和行标识。"
----
-
-# 原生子代理 bundle 包含全局工具
-
-[English](guide.md) | 中文
-
-## 变更
-
-`@deepseek-ai/dsh-subagent-claude-code` 和 `@deepseek-ai/dsh-subagent-codex` 保留包名、bundle 选择、提供方行 ID、配置及原生认证。已选中的 bundle 现在还会把委派工具注册为 Host 全局工具，包括 minimal 在内的所有预设都可见；此前 bundle 只注册提供方。启用 bundle 后，运行中的 Agent 从下一次请求起即可看到该工具；关闭后则不再可见。
-
-贡献的 Host 行为 `tool-subagent-claude-code` 和 `tool-subagent-codex`。后续用户层可以按行 ID 覆盖其配置或禁用状态。覆盖不会选中未选中的 bundle。预设自行注册的同名工具会为其 Agent 遮蔽该全局工具。
-
-委派遵循共享的托管 activation API：工具返回子级 ID，完成结果通过已记录的通知发送给父 Agent。移除已废弃的 `backgroundMode` 设置；这些原生提供方仍支持 `maxDepth: provider-managed`。
-
-## 迁移
-
-1. 保留已选中的 bundle 名称、提供方配置和认证。已有仅提供方的包需要在插件 → 官方中**更新**才能获得贡献工具的 bundle；按提示重启。要使用新的提供方，启用其卡片。[安装目标](../../../../packages/boot/plugin-manager/README.zh.md#use-this-package)对应已发布的 DSH 版本或源码 checkout；版本字符串相同不代表旧注册表包等同于开发链接。关闭只取消选择；删除仍为独立操作。
-2. 使用普通行补丁配置该工具。配置覆盖仍会替换整份配置。例如，以下补丁在保留提供方注册的同时禁用 Codex 工具：
-
-   ```yaml
-   - id: tool-subagent-codex
-     disabled: true
-   ```
-
-3. 如果手动的 Host 行注册了同名工具，移除该重复行，或禁用 bundle 的贡献行。在 Session 中验证有效工具目录。
-4. 插件客户端收到必填的 `BundleInfo.official` 和 `BundleInfo.availability` 字段；详情 slot 的 `PluginPackageRef` 也会收到它们。`official` 标识项目维护，`availability` 表示 `installation`、`profile` 或 `missing`，`installed` 仍表示 profile 的依赖声明。只展示已有字段的详情 slot 读取方无需修改；构造方和精确校验器必须包含新增字段。可选的 `installTarget` 标识所提供的版本及注册表或本地链接 spec。
-
-**其他 profile。** 这些 bundle 层只插入 Host 行，因此 headless、SDK、ACP 和自定义 profile 也可以选择它们。保留提供方包而不选择其 bundle 的 profile，可以参考 [Codex](../../../../packages/subagent/subagent-codex/README.zh.md#exposing-the-tool) 或 [Claude Code](../../../../packages/subagent/subagent-claude-code/README.zh.md#exposing-the-tool) 示例组合相同的行。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/new-session-generations/guide.md
-/:
-  en: ad37e45180bc096f
-  zh: e44c85b10b1d9d4b
-/start-a-fresh-agent-with-new-session:
-  en: 5e4b26181326018f
-  zh: 99bc75dcd12bf647
-/start-a-fresh-agent-with-new-session/change:
-  en: 45a6960304768d90
-  zh: 4b105688ffdd36e1
-/start-a-fresh-agent-with-new-session/migration:
-  en: 4642b2a1aee12fb3
-  zh: 53ae60e9d612ab6b

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "New Session creates a fresh Agent instead of reusing an existing empty Session."
----
-
-# Start a fresh Agent with New Session
-
-English | [中文](guide.zh.md)
-
-## Change
-
-In Web and Desktop, New Session creates a fresh Session and Agent using the current preset definition. It previously reused an existing empty Session in the workspace, which could retain an earlier preset definition.
-
-Client calls to `uiWorkspace.startSession(workspaceId)` follow the same behavior. Workspace reconnection through `openWorkspace` or `connectWorkspace` still reuses an eligible blank. Calls with draft-preparation options preserve their existing reuse and content rules. Existing Agents retain their preset composition; global optional tools update on their next request when a bundle is switched.
-
-## Migration
-
-1. After changing a preset definition, use New Session to create an Agent with the current definition. Continue in an existing Session when its retained preset composition is intentional.
-2. Client integrations that reconnect a workspace should use `openWorkspace` or `connectWorkspace`. Keep explicit draft-preparation options when preparing an existing draft.
-3. Confirm that the new Agent uses the updated preset definition; no persisted Session files or profile patches need rewriting.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.zh.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "新会话会创建新的 Agent，不再复用已有空 Session。"
----
-
-# 通过新会话创建新的 Agent
-
-[English](guide.md) | 中文
-
-## 变更
-
-在 Web 和 Desktop 中，新会话按当前预设定义创建新的 Session 和 Agent。此前该操作会复用工作区内已有的空 Session，因而可能保留较早的预设定义。
-
-客户端调用 `uiWorkspace.startSession(workspaceId)` 采用相同行为。通过 `openWorkspace` 或 `connectWorkspace` 重连工作区时仍复用符合条件的空 Session。带草稿准备选项的调用保留已有复用与内容规则。已有 Agent 保留其预设组合；切换组合包后，全局可选工具会在其下一次请求时更新。
-
-## 迁移
-
-1. 更改预设定义后，通过新会话创建使用当前定义的 Agent。需要保留原预设组合时，继续使用已有 Session。
-2. 重连工作区的客户端集成应使用 `openWorkspace` 或 `connectWorkspace`。准备已有草稿时保留显式草稿准备选项。
-3. 确认新 Agent 使用更新后的预设定义；无需重写持久化 Session 文件或 profile patch。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/plugin-option-placement/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/plugin-option-placement/guide.md
-/:
-  en: 3f9b48b2230ec6e4
-  zh: c1aad0e9121d46a4
-/dsh-plugin-option-placement:
-  en: 3d717a2b7e9087d3
-  zh: e6004d015e6a4829
-/dsh-plugin-option-placement/change:
-  en: 15fe8cf74db0ba53
-  zh: c6ea1056aa7a6f77
-/dsh-plugin-option-placement/migration:
-  en: b7239597ebc4d970
-  zh: fa45f851cf1f3af1

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/plugin-option-placement/guide.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "dsh plugin reads --profile only before the forwarded pnpm arguments and prints its own help."
----
-
-# `dsh plugin` option placement
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`dsh plugin` reads `--profile` only before the forwarded pnpm arguments, which start at the first token it does not recognize, and it has its own help. Previously it accepted `--profile <name>` anywhere on the command line, had no help of its own, and forwarded `-h` and `--help` to pnpm from any position.
-
-When the forwarded arguments begin with the pnpm command, everything after that command now reaches pnpm verbatim, including `-h`, `--help`, and `--profile`. In any other position, including after a leading pnpm option such as `--filter <selector>`, `-h` or `--help` prints the `dsh plugin` help and exits 0. Scripts that place `--profile` after the pnpm command or after a leading pnpm option fail with `required option '--profile <name>' not specified`, and `dsh plugin --profile <name> --help` no longer prints pnpm's help.
-
-## Migration
-
-1. Move `--profile <name>` before every pnpm argument: replace `dsh plugin add <package> --profile <name>` with `dsh plugin --profile <name> add <package>`.
-2. Request pnpm's help for one command after that command, with any pnpm options after it too, as in `dsh plugin --profile <name> add --help`. For pnpm's general help, forward `help`: `dsh plugin --profile <name> help`.
-3. Confirm that `dsh plugin --help` prints `Usage: dsh plugin [options] [args...]` and that the commands from steps 1 and 2 reach pnpm.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/plugin-option-placement/guide.zh.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "dsh plugin 只在被转发的 pnpm 参数之前读取 --profile，并提供自己的帮助。"
----
-
-# `dsh plugin` 选项位置
-
-[English](guide.md) | 中文
-
-## 变更
-
-`dsh plugin` 只在被转发的 pnpm 参数之前读取 `--profile`，被转发的参数从它无法识别的第一个 token 开始；它还提供自己的帮助。此前它接受出现在命令行任意位置的 `--profile <name>`，没有自己的帮助，并且无论 `-h` 和 `--help` 位于何处都会转发给 pnpm。
-
-被转发的参数以 pnpm 命令开头时，该命令之后的所有内容现在都会原样交给 pnpm，包括 `-h`、`--help` 和 `--profile`。在其他任何位置，包括位于 `--filter <selector>` 等开头的 pnpm 选项之后，`-h` 或 `--help` 都会打印 `dsh plugin` 的帮助并以 0 退出。把 `--profile` 写在 pnpm 命令或开头的 pnpm 选项之后的脚本会因 `required option '--profile <name>' not specified` 而失败，`dsh plugin --profile <name> --help` 也不再打印 pnpm 的帮助。
-
-## 迁移
-
-1. 把 `--profile <name>` 移到所有 pnpm 参数之前：将 `dsh plugin add <package> --profile <name>` 改为 `dsh plugin --profile <name> add <package>`。
-2. 查看某个 pnpm 命令的帮助时，把帮助选项和其他 pnpm 选项都写在该命令之后，例如 `dsh plugin --profile <name> add --help`。查看 pnpm 的总体帮助时转发 `help`：`dsh plugin --profile <name> help`。
-3. 确认 `dsh plugin --help` 打印 `Usage: dsh plugin [options] [args...]`，并且第 1、2 步中的命令能够到达 pnpm。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/python-optional-resources/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/python-optional-resources/guide.md
-/:
-  en: d6baeff3354ba733
-  zh: 54e736a9718228f8
-/download-optional-python-runtime-resources-explicitly:
-  en: b9a46f870d69cf79
-  zh: 1ed1da9167fad3b1
-/download-optional-python-runtime-resources-explicitly/change:
-  en: 92d45d6f2a499e9b
-  zh: d4560da85fc5cfbf
-/download-optional-python-runtime-resources-explicitly/migration:
-  en: 0f0b15be52301aed
-  zh: 646d7b47069714d4

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/python-optional-resources/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Python runtime wheels require explicit downloads for Office conversion and bundled authoring environments."
----
-
-# Download optional Python runtime resources explicitly
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Python runtime wheels omit the Office sidecar and authoring interpreters and libraries. SDK startup does not download them. Office operations require an explicit download; the authoring environment and conversion engine can be selected independently. The SDK still packages the normal `dsh` CLI and requires no system Node.js.
-
-## Migration
-
-1. Before processing Office files, call `deepseek_harness_runtime.download_office()`. Before using the bundled authoring environment, call `deepseek_harness_runtime.download_primary_runtime()`. Both reuse completed caches and return absolute paths.
-2. For offline deployment, prepare the cache with the matching runtime release on the target platform and copy it to that platform's deployment. Set `DSH_RESOURCE_CACHE` to its absolute root before downloads and SDK startup. See the [runtime reference](../../../../python/sdk-runtime/README.md).
-3. Start the SDK and confirm the required resources are available. `deepseek_harness_runtime.resolve_office_launch_args()` checks the Office CLI paths without downloading. Existing `DSH_PRIMARY_RUNTIME` paths remain supported; an empty value disables the authoring query. Profile patches can independently disable `skill-office`.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/python-optional-resources/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Python 运行时 wheel 的 Office 转换与内置创作环境需要显式下载。"
----
-
-# 显式下载可选 Python 运行时资源
-
-[English](guide.md) | 中文
-
-## 变更
-
-Python 运行时 wheel 不包含 Office sidecar、创作解释器和库。SDK 启动不会下载这些资源。Office 操作需要显式下载；创作环境和转换引擎可以独立选择。SDK 仍打包常规 `dsh` CLI，无需系统 Node.js。
-
-## 迁移
-
-1. 处理 Office 文件前调用 `deepseek_harness_runtime.download_office()`。使用内置创作环境前调用 `deepseek_harness_runtime.download_primary_runtime()`。两者复用完整缓存并返回绝对路径。
-2. 离线部署时，在目标平台使用匹配的运行时发布版本准备缓存，并将其复制到该平台的部署环境。下载和启动 SDK 前，将 `DSH_RESOURCE_CACHE` 设为缓存的绝对根目录。详见[运行时参考](../../../../python/sdk-runtime/README.zh.md)。
-3. 启动 SDK 并确认所需资源可用。`deepseek_harness_runtime.resolve_office_launch_args()` 检查 Office CLI 路径，不执行下载。既有 `DSH_PRIMARY_RUNTIME` 路径仍受支持；空值禁用创作环境查询。Profile patch 可独立禁用 `skill-office`。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/python-ptc-sandbox/guide.md
-/:
-  en: 37441fc2c29e3ee9
-  zh: de434de0f9da7d40
-/python-ptc-applies-the-shared-file-sandbox:
-  en: 655754b417fa8699
-  zh: 5571cb25b6621c07
-/python-ptc-applies-the-shared-file-sandbox/change:
-  en: a4575a117b53ce7c
-  zh: 2ea9f832b2179537
-/python-ptc-applies-the-shared-file-sandbox/migration:
-  en: faaefac69870d31f
-  zh: 08398580b7e3ac62

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.md

@@ -1,21 +0,0 @@
----
-kind: upgrade-guide
-description: "Python PTC compositions require sandbox services, and direct Python file operations follow the resolved file policy."
----
-
-# Python PTC applies the shared file sandbox
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`@deepseek-ai/dsh-experimental-ptc-runtime-python` requires `sandbox` and `sandboxPolicy`. Previously, direct Python file operations ran without confinement and the provider rejected explicit `sandboxPolicy` inputs. It now applies the shared policy to each program and reports confinement in `PtcRunResult.sandbox`. A restricted run fails with `sandbox-unavailable` when confinement cannot be established.
-
-This affects custom compositions that select the Python runtime. Shipped profiles continue to use the Node runtime. Python remains local to macOS or Linux; its configured resource budgets and unsupported per-call timeout overrides remain unchanged.
-
-## Migration
-
-1. In the `cordis.yml` or profile patch that selects the Python runtime, retain the existing shared sandbox services. If they are absent, mount `@deepseek-ai/dsh-sandbox-local` and `@deepseek-ai/dsh-sandbox-policy` with its required `@deepseek-ai/dsh-session-projection` service. See the [Python runtime requirements](../../../../packages/experimental/ptc-runtime-python/README.md#use-this-package).
-2. Set the shared `sandbox-policy` row's `mode` and `workspaceRoot` for agentless calls. Its default mode is `read-only`; `workspace-write` permits workspace writes. PTC tool calls use the Session's resolved policy and directory. Do not add a separate Python-only sandbox setting.
-3. Direct service callers use `runtime.run(runtime.resolve(request))`; pass a trusted `sandboxPolicy` only when an explicit override is required. Model-facing `run_code` uses the existing approval flow for a one-call wider mode, without changing nested tools' permissions or replaying the program automatically.
-4. Verify a program can write inside the intended workspace under `workspace-write`, fails to write outside it, and returns `result.sandbox.mode` and `result.sandbox.enforcement`. Under `read-only`, direct file writes fail. Inspect `sandbox-unavailable` separately from a denied file operation and repair the local sandbox installation before retrying.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.zh.md

@@ -1,21 +0,0 @@
----
-kind: upgrade-guide
-description: "Python PTC 组合需要沙箱服务，且直接 Python 文件操作遵循已解析文件策略。"
----
-
-# Python PTC 应用共享文件沙箱
-
-[English](guide.md) | 中文
-
-## 变更
-
-`@deepseek-ai/dsh-experimental-ptc-runtime-python` 需要 `sandbox` 和 `sandboxPolicy`。此前，直接 Python 文件操作不受约束，提供方拒绝显式 `sandboxPolicy` 输入。现在，它为每个程序应用共享策略，并通过 `PtcRunResult.sandbox` 报告约束情况。无法建立约束时，受限运行以 `sandbox-unavailable` 失败。
-
-这影响选择 Python 运行时的自定义组合。已发布 profile 继续使用 Node 运行时。Python 仍限于本地 macOS 或 Linux；其配置的资源预算保持不变，仍不支持单次 timeout 覆盖。
-
-## 迁移
-
-1. 在选择 Python 运行时的 `cordis.yml` 或 profile patch 中，保留已有共享沙箱服务。若尚未提供，挂载 `@deepseek-ai/dsh-sandbox-local` 和 `@deepseek-ai/dsh-sandbox-policy`，以及后者所需的 `@deepseek-ai/dsh-session-projection` 服务。参见 [Python 运行时要求](../../../../packages/experimental/ptc-runtime-python/README.zh.md#use-this-package)。
-2. 为无 Agent 调用设置共享 `sandbox-policy` 行的 `mode` 和 `workspaceRoot`。默认模式是 `read-only`；`workspace-write` 允许工作区写入。PTC 工具调用使用 Session 的已解析策略和目录。不要新增 Python 专用沙箱设置。
-3. 直接服务调用方使用 `runtime.run(runtime.resolve(request))`；仅在需要显式覆盖时传入可信 `sandboxPolicy`。面向模型的 `run_code` 通过现有审批流程为一次调用扩大权限，不改变嵌套工具的权限，也不自动重放程序。
-4. 验证程序在 `workspace-write` 下可以写入预期工作区、写入工作区外时失败，并返回 `result.sandbox.mode` 和 `result.sandbox.enforcement`。在 `read-only` 下，直接文件写入失败。将 `sandbox-unavailable` 与文件操作被拒绝区分处理，修复本地沙箱安装后再重试。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/session-title-adapters/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/session-title-adapters/guide.md
-/:
-  en: 4f9ba8c8ed040a83
-  zh: aabc458063878004
-/prepare-custom-title-routes:
-  en: cab86bb2cc427297
-  zh: 7a14e268bf53fc73
-/prepare-custom-title-routes/change:
-  en: 278f593203887bbb
-  zh: 72949b90220f4a6f
-/prepare-custom-title-routes/migration:
-  en: b7c439680f8a1ec8
-  zh: 82b4243cb1b2ef0a

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/session-title-adapters/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "Custom title routes require registered adapters and reasoning efforts in increasing order."
----
-
-# Prepare custom title routes
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Model-backed session titles prepare their requests through `ctx.llm.prepareCall()`. Compositions that serve title routes only through `llm/stream` middleware must also register an adapter. Custom adapters must list selectable reasoning efforts from least to greatest, rather than in arbitrary display order. Title policy selects the first entry through a configuration function. Existing concrete `prepareCall()` inputs remain valid.
-
-## Migration
-
-1. Register the title route with `ctx.llm.registerAdapter()`. Replay compositions can configure the existing `llm-replay` plugin's `providers` list.
-2. In the adapter's model metadata, order `reasoning.efforts` from least to greatest selectable effort. Apply the same order to replay models' `reasoningEfforts`. Keep the configured default independent of list order. Omit reasoning metadata when the route has no selectable controls.
-3. Generate a title and check that `session/title-llm-request` records the selected effort and a provider title is saved. Existing Session records without that optional field remain readable.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/session-title-adapters/guide.zh.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "自定义标题路由要求注册适配器，并按递增顺序排列推理强度。"
----
-
-# 准备自定义标题路由
-
-[English](guide.md) | 中文
-
-## 变更
-
-模型生成的会话标题通过 `ctx.llm.prepareCall()` 准备请求。仅通过 `llm/stream` 中间件提供标题路由的组合还必须注册适配器。自定义适配器必须将可选推理强度从低到高排列，而不是使用任意显示顺序。标题策略通过配置函数选择首个条目。现有具体 `prepareCall()` 输入仍然有效。
-
-## 迁移
-
-1. 通过 `ctx.llm.registerAdapter()` 注册标题路由。回放组合可配置现有 `llm-replay` 插件的 `providers` 列表。
-2. 在适配器的模型元数据中，将 `reasoning.efforts` 按可选强度从低到高排列。回放模型的 `reasoningEfforts` 使用同一顺序。配置默认值保持独立于列表顺序。路由没有可选控制时省略推理元数据。
-3. 生成标题，确认 `session/title-llm-request` 记录了所选强度，且提供方标题已保存。不含该可选字段的现有 Session 记录仍可读取。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/session-title-provider-strategy/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/session-title-provider-strategy/guide.md
-/:
-  en: 08f294cc358eaffb
-  zh: 46ef86d9f933ea58
-/migrate-session-title-providers:
-  en: c9e33d3bdc0595c6
-  zh: 55a049680ff8ae9b
-/migrate-session-title-providers/change:
-  en: 3a8d72fb2c793d51
-  zh: 9acc89004dd31096
-/migrate-session-title-providers/migration:
-  en: ea9efdc5234c0541
-  zh: 845d80a7c6c05672

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/session-title-provider-strategy/guide.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "Session-title providers register directly, own their strategy settings, and share only prepared execution."
----
-
-# Migrate session-title providers
-
-English | [中文](guide.zh.md)
-
-## Change
-
-`@deepseek-ai/dsh-session-title-llm` no longer exports `registerSessionTitleLlmProvider`, `generateSessionTitleWithLlm`, or `SessionTitleLlmMessageSelector`. `SessionTitleLlmConfig` now holds only execution controls (`maxInputBytes`, `maxOutputTokens`, `timeoutMs`, and the optional `provider`/`model` pair); `targetWords` and `targetCjkCharacters` moved into each provider's own `Config`. Each provider owns its system instruction, message framing, title parsing, reasoning selection, and output interpretation, registers directly with `ctx.sessionTitle.register()`, and calls `executeSessionTitleLlm(ctx, config, request, providerId, { system, input, messageSeqs, selectReasoningEffort })`. That function returns the assembled content blocks, the terminal finish, and the used model route. `SessionTitleProviderRequest` gains an optional `currentTitle` snapshot.
-
-## Migration
-
-1. Replace a `registerSessionTitleLlmProvider(...)` call with a direct `ctx.sessionTitle.register({ id, automatic, generate })`; keep the same `id` and cadence.
-2. In `generate(request)`, build your own system prompt and user input, pass a `selectReasoningEffort` function, then call `executeSessionTitleLlm` with `{ system, input, messageSeqs, selectReasoningEffort }`.
-3. Reject a `tool-calls` or `max-tokens` terminal finish and tool-call blocks; derive the title from the text blocks.
-4. Read `request.currentTitle` when the strategy should preserve an accepted provider title; it is absent before any title.
-5. Generate a title and confirm the saved result plus the exact `session/title-llm-request` record.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/session-title-provider-strategy/guide.zh.md

@@ -1,20 +0,0 @@
----
-kind: upgrade-guide
-description: "会话标题提供方直接注册、拥有自己的策略设置，并只共享准备好的执行。"
----
-
-# 迁移会话标题提供方
-
-[English](guide.md) | 中文
-
-## 变更
-
-`@deepseek-ai/dsh-session-title-llm` 不再导出 `registerSessionTitleLlmProvider`、`generateSessionTitleWithLlm` 或 `SessionTitleLlmMessageSelector`。`SessionTitleLlmConfig` 现在只包含执行控制（`maxInputBytes`、`maxOutputTokens`、`timeoutMs` 以及可选的 `provider`/`model` 对）；`targetWords` 与 `targetCjkCharacters` 已移入各提供方自己的 `Config`。各提供方拥有自己的系统指令、消息封装、标题解析、推理选择与输出解释，直接通过 `ctx.sessionTitle.register()` 注册，并调用 `executeSessionTitleLlm(ctx, config, request, providerId, { system, input, messageSeqs, selectReasoningEffort })`。该函数返回组装后的内容块、终止结束原因与所用模型路由。`SessionTitleProviderRequest` 新增可选的 `currentTitle` 快照。
-
-## 迁移
-
-1. 把 `registerSessionTitleLlmProvider(...)` 调用替换为直接 `ctx.sessionTitle.register({ id, automatic, generate })`；保持相同的 `id` 与节奏。
-2. 在 `generate(request)` 中构建自己的系统提示词与用户输入，传入 `selectReasoningEffort` 函数，然后用 `{ system, input, messageSeqs, selectReasoningEffort }` 调用 `executeSessionTitleLlm`。
-3. 拒绝 `tool-calls` 或 `max-tokens` 终止结束原因与工具调用块；从文本块派生标题。
-4. 当策略需要保留已接纳的提供方标题时读取 `request.currentTitle`；任何标题被接纳前该值为缺省。
-5. 生成一次标题，确认保存的结果以及确切的 `session/title-llm-request` 记录。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/ssh-helper-launch/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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-alpha.1/ssh-helper-launch/guide.md
-/:
-  en: ece09d74b8b3da0e
-  zh: 4762937e93aa8bf0
-/ssh-helper-and-ptc-launch-configuration:
-  en: e757aad6a0030eb3
-  zh: 2f87638444248a40
-/ssh-helper-and-ptc-launch-configuration/change:
-  en: 7e78555e386835b1
-  zh: 5a0d9de8e1312682
-/ssh-helper-and-ptc-launch-configuration/migration:
-  en: 33f5268892e099c9
-  zh: c97f51289a61d323

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/ssh-helper-launch/guide.md

@@ -1,19 +0,0 @@
----
-kind: upgrade-guide
-description: "SSH and Node PTC configurations use explicit launch modes, and SSH clients require a matching protocol-2 helper."
----
-
-# SSH helper and PTC launch configuration
-
-English | [中文](guide.zh.md)
-
-## Change
-
-Custom SSH compositions must update their `cordis.yml` and installed helper together. `dsh-ssh` replaces top-level `node`, `bootstrapPath` and `bootstrapHash` with `launch`, and requires SSH protocol 2. `dsh-ptc-runtime-node` replaces `nodeExecutable` and `bootstrapPath` with `launch`. The connection's `nodeExecutable` and `bootstrapPath` getters are replaced by `ptcLaunch`.
-
-## Migration
-
-1. For a script helper, move `node`, `bootstrapPath` and `bootstrapHash` under `launch: { kind: node-script }`. Keep `helper`, `helperHash`, `host` and `workspace` at their existing locations. Install the matching helper script and update `helperHash`; update the bootstrap and its hash together when configured.
-2. For a packaged helper, extract the complete archive and set `launch: { kind: executable }`, `helper` to the executable's absolute remote path, and `helperHash` to its digest from `manifest.json`.
-3. Configure the remote PTC provider with `launch: ctx.ssh.ptcLaunch` in the composition's existing JavaScript configuration. For an explicitly configured local Node worker, use `launch: { kind: 'node-script', executable: previousNodeExecutable, bootstrapPath: previousBootstrapPath }`. Omitted local launch configuration still selects the current process's runtime.
-4. Start the configured profile and exercise a remote file read, a process command and a PTC call. A protocol or digest mismatch requires updating the installed helper and its configuration together. See the [SSH deployment requirements](../../../../packages/ssh/ssh/README.md#use-this-package).