dsh-plugin-dev-kb 1.4.0 → 1.5.1

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/native-subagent-bundle-tools/guide.zh.md

@@ -0,0 +1,31 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.zh.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/plugin-option-placement/guide.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/plugin-option-placement/guide.zh.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/python-optional-resources/guide.md

@@ -0,0 +1,18 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/python-optional-resources/guide.zh.md

@@ -0,0 +1,18 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.md

@@ -0,0 +1,21 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.zh.md

@@ -0,0 +1,21 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/session-title-adapters/guide.md

@@ -0,0 +1,18 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/session-title-adapters/guide.zh.md

@@ -0,0 +1,18 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/session-title-provider-strategy/guide.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/session-title-provider-strategy/guide.zh.md

@@ -0,0 +1,20 @@
+---
+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/kb/extra/upgrade-guide/v0.2.1-alpha.1/ssh-helper-launch/guide.md

@@ -0,0 +1,19 @@
+---
+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).

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/ssh-helper-launch/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "SSH 和 Node PTC 配置改用显式启动模式，SSH 客户端要求使用匹配的协议 2 helper。"
+---
+
+# SSH helper 与 PTC 启动配置
+
+[English](guide.md) | 中文
+
+## 变更
+
+自定义 SSH 组合必须一起更新 `cordis.yml` 和已安装的 helper。`dsh-ssh` 将顶层 `node`、`bootstrapPath` 和 `bootstrapHash` 替换为 `launch`，并要求 SSH 协议 2。`dsh-ptc-runtime-node` 将 `nodeExecutable` 和 `bootstrapPath` 替换为 `launch`。连接的 `nodeExecutable` 和 `bootstrapPath` getter 替换为 `ptcLaunch`。
+
+## 迁移
+
+1. 使用脚本 helper 时，将 `node`、`bootstrapPath` 和 `bootstrapHash` 移入 `launch: { kind: node-script }`。`helper`、`helperHash`、`host` 和 `workspace` 保持原位置。安装匹配的 helper 脚本并更新 `helperHash`；配置了 bootstrap 时，一起更新该文件及其摘要。
+2. 使用打包后的 helper 时，解压完整发行包，设置 `launch: { kind: executable }`，将 `helper` 设为可执行文件的远端绝对路径，将 `helperHash` 设为 `manifest.json` 中该文件的摘要。
+3. 在组合现有的 JavaScript 配置中，通过 `launch: ctx.ssh.ptcLaunch` 配置远端 PTC 提供方。显式配置本地 Node worker 时，使用 `launch: { kind: 'node-script', executable: previousNodeExecutable, bootstrapPath: previousBootstrapPath }`。省略本地启动配置时，仍选择当前进程的运行时。
+4. 启动配置好的 profile，执行一次远端文件读取、进程命令和 PTC 调用。出现协议或摘要不匹配时，需要一起更新已安装的 helper 及其配置。参见 [SSH 部署要求](../../../../packages/ssh/ssh/README.zh.md#use-this-package)。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/subagent-activations/guide.md

@@ -0,0 +1,59 @@
+---
+kind: upgrade-guide
+description: "Managed subagent activations replace foreground and Job-backed delegation, its configuration keys, and the published in-process driver."
+---
+
+# Migrate delegation to managed subagent activations
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-tool-subagent` removes `backgroundMode`, `enableRunInBackground`, and the model argument `run_in_background`. Every delegation now returns `{ kind: 'activation', subagentId }` after accepting the child, and the runtime delivers its final answer in a parent completion notice. Foreground results and `{ kind: 'background', jobId }` results are removed; subagents are no longer collected or stopped through `job_output` or `job_kill`.
+
+The published `@deepseek-ai/dsh-subagent-in-process-driver` package is removed. Local providers contribute creation inputs through `prepareContinuable()`; the subagent service owns execution. Spawn and Fork children can receive later messages, including after settlement when persistence and Session query are available. External providers execute once and do not accept follow-up messages.
+
+## Migration
+
+1. Remove `backgroundMode` and `enableRunInBackground` from `tool-subagent` rows in `cordis.yml`, profile patches, and overlays. Keep the provider and remaining configuration. For example:
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-tool-subagent'
+     config:
+       provider: spawn
+       toolName: subagent
+   ```
+
+   Local tool delegation requires Session persistence. Compose it with the [subagent service and provider](../../../../packages/subagent/subagent/README.md#use-this-package).
+
+2. Remove `run_in_background` from tool calls and update result consumers to read `subagentId`. Collect the completion notice instead of foreground output or a Job result. Use `interrupt_agent` to stop the current execution; use `send_message` only for local children when those control tools are composed.
+
+3. For host code that must await a result, replace `ctx.subagents.start()` or `startContinuable()` with `startActivation()` and caller delivery. Given a composed service and live parent:
+
+   ```ts
+   import type { Agent } from '@deepseek-ai/dsh-agent'
+   import type SubagentRuntime from '@deepseek-ai/dsh-subagent'
+
+   async function collect(subagents: SubagentRuntime, parent: Agent, signal: AbortSignal) {
+     const activation = await subagents.startActivation({
+       provider: 'spawn',
+       label: 'Review changes',
+       request: { parent, prompt: [{ type: 'text', text: 'Review these changes.' }] },
+       signal,
+       delivery: 'caller',
+     })
+     const result = await activation.result
+     await activation.dispose()
+     return result
+   }
+   ```
+
+   Caller delivery emits no parent completion notice. `result` settles after cleanup and includes `output`, `stopReason`, and optional `structured` and `diagnostic` values; inspect `stopReason` before treating it as success. The startup signal stops owning cancellation after publication: retain the receipt and call `dispose()` to cancel that exact activation. Cleanup failures are reported by `dispose()` separately from the captured result.
+
+4. Remove the driver dependency and imports, including `startInProcessRun`. Mount the existing Spawn or Fork provider and call the service as above. Custom local providers implement `prepareContinuable()` using the [provider API](../../../../docs/subsystems/subagent.md); there is no replacement standalone driver.
+
+   External providers keep `start()`, but each returned `SubagentRun.id` must be unique across parents, providers, and local Sessions in the runtime. Generate a fresh id for each execution instead of using a parent-local counter.
+
+   For `dsh-subagent-dsh-sdk`, update any separately configured `dshBin` runtime to support `session/wait`. For directory configuration, follow the [working-directory migration](../working-directory/guide.md).
+
+5. Confirm a delegation returns the activation result variant, its completion notice contains the final answer, and caller delivery returns the result without adding that notice. Confirm local children remain listed after completion and external children cannot be continued.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/subagent-activations/guide.zh.md

@@ -0,0 +1,59 @@
+---
+kind: upgrade-guide
+description: "受管理的子 agent activation 替代前台与 Job 后台委派、相关配置键和已发布的进程内驱动包。"
+---
+
+# 将委派迁移到受管理的子 agent activation
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-tool-subagent` 移除了 `backgroundMode`、`enableRunInBackground` 和模型参数 `run_in_background`。每次委派现在都会在接纳子 agent（智能体）后返回 `{ kind: 'activation', subagentId }`，运行时通过父级完成通知交付最终答案。前台结果和 `{ kind: 'background', jobId }` 结果已移除；子 agent 不再通过 `job_output` 或 `job_kill` 收集结果或停止。
+
+已发布的 `@deepseek-ai/dsh-subagent-in-process-driver` 包被移除。本地提供方通过 `prepareContinuable()` 提供创建输入，由子 agent 服务拥有执行过程。Spawn 和 Fork 子级可以接收后续消息；组合了持久化和 Session 查询服务时，结算后也能接收。外部提供方只执行一次，不接受后续消息。
+
+## 迁移
+
+1. 从 `cordis.yml`、配置文件补丁和覆盖文件中的 `tool-subagent` 配置项删除 `backgroundMode` 和 `enableRunInBackground`。保留提供方和其余配置。例如：
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-tool-subagent'
+     config:
+       provider: spawn
+       toolName: subagent
+   ```
+
+   本地工具委派需要 Session 持久化。将其与[子 agent 服务及提供方](../../../../packages/subagent/subagent/README.zh.md#use-this-package)一起组合。
+
+2. 从工具调用中删除 `run_in_background`，并将结果消费方改为读取 `subagentId`。收集完成通知，替代前台输出或 Job 结果。组合了相应控制工具时，使用 `interrupt_agent` 停止当前执行；`send_message` 仅用于本地子级。
+
+3. 对于必须等待结果的宿主代码，将 `ctx.subagents.start()` 或 `startContinuable()` 替换为 `startActivation()`，并选择调用方投递。以下示例假设服务已组合且父 agent 在线：
+
+   ```ts
+   import type { Agent } from '@deepseek-ai/dsh-agent'
+   import type SubagentRuntime from '@deepseek-ai/dsh-subagent'
+
+   async function collect(subagents: SubagentRuntime, parent: Agent, signal: AbortSignal) {
+     const activation = await subagents.startActivation({
+       provider: 'spawn',
+       label: 'Review changes',
+       request: { parent, prompt: [{ type: 'text', text: 'Review these changes.' }] },
+       signal,
+       delivery: 'caller',
+     })
+     const result = await activation.result
+     await activation.dispose()
+     return result
+   }
+   ```
+
+   调用方投递不会发送父级完成通知。`result` 在清理结束后结算，包含 `output`、`stopReason` 以及可选的 `structured` 和 `diagnostic` 值；将结果视为成功前先检查 `stopReason`。发布后，启动信号不再控制取消：保留回执，通过 `dispose()` 取消该次 activation。`dispose()` 单独报告清理失败，不替换已捕获的执行结果。
+
+4. 删除驱动包依赖及其导入，包括 `startInProcessRun`。挂载现有的 Spawn 或 Fork 提供方，并按上例调用服务。自定义本地提供方按[提供方 API](../../../../docs/subsystems/subagent.zh.md)实现 `prepareContinuable()`；没有替代的独立驱动包。
+
+   外部提供方保留 `start()`，但每次返回的 `SubagentRun.id` 必须在运行时内跨父级、提供方和本地 Session 保持唯一。为每次执行生成新的 id，替代父级独立计数器。
+
+   使用 `dsh-subagent-dsh-sdk` 时，将单独配置的 `dshBin` 运行时更新到支持 `session/wait` 的版本。 目录配置按照[工作目录迁移指南](../working-directory/guide.zh.md)调整。
+
+5. 确认委派返回 activation 结果变体，完成通知包含最终答案，且调用方投递返回结果而不添加该通知。确认本地子级在完成后仍可列出，外部子级不支持继续执行。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Subagent persona and toolFilter configuration is replaced by Agent Preset composition."
+---
+
+# Configure subagent composition through presets
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`dsh-tool-subagent` rejects `persona` and `toolFilter` configuration. New `SubagentStartRequest` values and provider capabilities no longer expose either field. In-process spawn selects a preset through `agentPreset`; its persona and tools come from that preset's plugins. Fork inherits the parent's preset and cannot independently change persona or restrict tools. Model and reasoning-effort options are unchanged.
+
+The shipped `standard`, `ptc`, and `cordis` delegation tools no longer hide `schedule_*` tools. Delegated callers still receive the existing execution refusal. Historical child Session descriptors retain their persona and tool restrictions when resumed.
+
+## Migration
+
+1. Remove `persona` and `toolFilter` from `dsh-tool-subagent` rows in your profile patches and custom presets. Update programmatic callers and provider capability declarations to remove the same fields.
+2. For spawn, define an Agent Preset containing `dsh-persona` and the required tool plugins, then set the delegation tool's `agentPreset` to its id. Use `allowedAgentPresets` to offer several declared presets to the parent model. Presets select plugin compositions; there is no replacement per-child tool-name filter.
+3. For fork, remove the overrides and accept the inherited composition. If the task needs a different composition, use spawn with a preset; it does not inherit the parent's conversation.
+4. Start a new Session and delegate a task. Confirm that the child uses the selected preset's persona and tools. Existing persisted child Sessions need no manual edits.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Subagent 的 persona 与 toolFilter 配置由 Agent Preset 组装替代。"
+---
+
+# 通过 preset 配置子 Agent 组装
+
+[English](guide.md) | 中文
+
+## 变更
+
+`dsh-tool-subagent` 拒绝 `persona` 与 `toolFilter` 配置。新的 `SubagentStartRequest` 和提供方能力声明也不再暴露这两个字段。进程内 spawn 通过 `agentPreset` 选择 preset，其 persona 与工具来自该 preset 的插件。fork 继承父方 preset，不能独立改变 persona 或限制工具。模型与推理强度选项保持不变。
+
+出货的 `standard`、`ptc` 和 `cordis` 委派工具不再隐藏 `schedule_*` 工具。委派调用方仍会收到已有的执行拒绝。历史子 Session 的 descriptor 在恢复时仍应用其 persona 与工具限制。
+
+## 迁移
+
+1. 从 profile patch 和自定义 preset 的 `dsh-tool-subagent` 行中移除 `persona` 与 `toolFilter`。同步从程序化调用方和提供方能力声明中移除这两个字段。
+2. 对于 spawn，定义包含 `dsh-persona` 和所需工具插件的 Agent Preset，再将委派工具的 `agentPreset` 设为其 id。使用 `allowedAgentPresets` 向父模型开放多个已声明 preset。preset 选择插件组合，不提供替代的逐子级工具名过滤器。
+3. 对于 fork，移除覆盖并接受继承的组合。如果任务需要不同组合，使用带 preset 的 spawn；它不继承父方对话。
+4. 启动新 Session 并委派任务，确认子级使用所选 preset 的 persona 与工具。已有持久化子 Session 无须手动修改。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/team-direct-inbox/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Agent Teams removes its pending-message limit and stops delivering historical queued mail."
+---
+
+# Agent Teams messages use target inboxes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The experimental Agent Teams plugin sends new messages directly to the target Agent inbox instead of retaining a separate Team mailbox. `send_message` returns only `{ "sent": true }`; it exposes neither a message ID nor an `accepted` or `queued` status. Acceptance does not confirm model processing or a synchronous storage flush. Failed sends are not retained for retry, and explicit resends are not deduplicated.
+
+The `maxPendingMessagesPerMember` configuration key is removed. Historical `team/message/queued` and `team/message/delivered` records remain readable, but queued messages that were not delivered before upgrading are never dispatched. Roster and task state remain durable.
+
+## Migration
+
+1. Before upgrading, let pending Team messages finish and confirm that their targets received them. After upgrading, explicitly resend any required undelivered message; check the target's history first to avoid duplicates. Do not edit historical Session records.
+2. Remove `maxPendingMessagesPerMember` from the `@deepseek-ai/dsh-experimental-agent-team` plugin configuration in your `cordis.yml` or overlays. There is no replacement Team queue limit; `maxMessageBytes` still bounds each complete sender-framed message.
+3. Update any consumer of `send_message` results to read `sent` instead of message IDs or delivery statuses, and handle send errors explicitly. Do not treat success as completed target work. The `ctx.agentTeams.sendMessage()` service still returns `messageId`.
+4. Start your Team-enabled profile, send a message to another member, and confirm that the tool returns `{ "sent": true }` and that the target receives it. Consult the [package reference](../../../../packages/experimental/agent-team/README.md#use-this-package) for delivery semantics.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/team-direct-inbox/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Agent Teams 移除待投递消息数量限制，并停止投递历史排队消息。"
+---
+
+# Agent Teams 消息使用目标收件箱
+
+[English](guide.md) | 中文
+
+## 变更
+
+实验性 Agent Teams 插件将新消息直接发送到目标 Agent 收件箱，不再保留独立的 Team 邮箱。`send_message` 仅返回 `{ "sent": true }`，不暴露消息 ID，也不返回 `accepted` 或 `queued` 状态。接收成功不表示模型已处理消息，也不保证同步刷新到存储。失败的发送不会保留以供重试，显式重发也不会去重。
+
+配置键 `maxPendingMessagesPerMember` 已移除。历史 `team/message/queued` 和 `team/message/delivered` 记录仍可读取，但升级前尚未投递的排队消息永远不会被派发。成员名单与任务状态仍然持久保存。
+
+## 迁移
+
+1. 升级前，让待投递的 Team 消息完成投递，并确认目标已收到。升级后，显式重发仍需处理的未投递消息；先检查目标历史，避免重复。不要编辑历史 Session 记录。
+2. 从 `cordis.yml` 或覆盖配置中 `@deepseek-ai/dsh-experimental-agent-team` 插件的配置移除 `maxPendingMessagesPerMember`。没有替代的 Team 队列限制；`maxMessageBytes` 仍限制包含发送者标识的完整消息大小。
+3. 更新所有读取 `send_message` 结果的调用方，改为读取 `sent` 而非消息 ID 或投递状态，并显式处理发送错误。不要把发送成功视为目标工作已完成。`ctx.agentTeams.sendMessage()` 服务仍返回 `messageId`。
+4. 启动启用 Team 的 profile，向其他成员发送消息，确认工具返回 `{ "sent": true }` 且目标收到消息。投递语义参见[包参考](../../../../packages/experimental/agent-team/README.zh.md#use-this-package)。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/terminal-command-labels/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Custom TerminalBlock consumers must provide localized accessible names for overflowing command lines."
+---
+
+# Terminal command labels
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`TerminalBlockLabels` from `@deepseek-ai/dsh-client-ui-primitives` requires a `commandLine(line: number): string` formatter. Previously, callers supplied no accessible name for command lines. Each horizontally overflowing line now uses this name for its keyboard-focusable group; lines that fit, including wrapped lines, add no Tab stop. This affects custom UI plugins that render `TerminalBlock`.
+
+## Migration
+
+1. Add `commandLine` to each labels object passed to `TerminalBlock`. The argument is the authored line number, starting at one.
+2. Return a localized name, such as “Command line 1”, through the plugin's locale dictionary. Keep the original command text separate from this name.
+3. Rebuild the plugin. Verify that a long command can receive keyboard focus and scroll with the arrow keys, and that a short or wrapped command adds no Tab stop.

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/terminal-command-labels/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "自定义 TerminalBlock 消费者必须为横向溢出的命令行提供本地化的无障碍名称。"
+---
+
+# 终端命令标签
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-primitives` 的 `TerminalBlockLabels` 要求提供 `commandLine(line: number): string` 格式化函数。此前，调用者不提供命令行的无障碍名称。现在，每条横向溢出的命令行使用这个名称标识可通过键盘聚焦的分组；能够完整显示的行（包括折行后的行）不会增加 Tab 停靠点。这会影响渲染 `TerminalBlock` 的自定义 UI 插件。
+
+## 迁移
+
+1. 为传给 `TerminalBlock` 的每个 labels 对象添加 `commandLine`。参数是原始命令文本的行号，从一开始。
+2. 通过插件的语言字典返回本地化名称，例如“命令第 1 行”。名称与原始命令文本分开保留。
+3. 重新构建插件。确认长命令可通过键盘聚焦并使用方向键滚动，短命令或折行后的命令则不会增加 Tab 停靠点。

package/kb/extra/upgrade-guide/v0.2.1-alpha.1/tool-presentation-mode/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Tool presentation accepts native or ptc; the mixed both mode is rejected."
+---
+
+# Select native or PTC tool presentation
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `mode` fields of `@deepseek-ai/dsh-tools` and `@deepseek-ai/dsh-agent-tool-presentation` accept only `native` or `ptc`. The `both` value is rejected. This also affects `DSH_TOOLS_MODE=both`, which supplies the tools configuration through the shipped profile patches.
+
+`native` exposes visible tools as direct function calls. `ptc` exposes `run_code`; programs call the visible tools through the generated SDK. Different agent presets can continue using different modes in the same application.
+
+## Migration
+
+1. In `cordis.yml`, profile `cordis.patch.yml`, or a custom overlay, replace `mode: both` with `mode: native` for direct calls or `mode: ptc` for program-based calls.
+2. Replace `DSH_TOOLS_MODE=both` with `DSH_TOOLS_MODE=native` or `DSH_TOOLS_MODE=ptc`. For preset-specific selection, update the preset's `@deepseek-ai/dsh-agent-tool-presentation` row instead.
+3. Update code that calls `ctx.tools.presentAs('both')` to select `native` or `ptc`. In PTC programs, keep calls inside `run_code`; do not emit the SDK function names as direct model tool calls.
+4. Start the affected profile and confirm that configuration loads. Native requests expose the permitted direct tools; PTC requests expose `run_code` and its SDK instructions.