dsh-plugin-guide 0.3.42 → 0.4.0

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

@@ -1,19 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-activations/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/subagent-activations/guide.md
-/:
-  en: 9ae9e5682ed3cd7e
-  zh: 7423fcb7aed1938a
-/migrate-delegation-to-managed-subagent-activations:
-  en: fcf5f06084f989d9
-  zh: 5e3e6a05786390dd
-/migrate-delegation-to-managed-subagent-activations/change:
-  en: 17add29d9f80674e
-  zh: 4d4050e99f019cca
-/migrate-delegation-to-managed-subagent-activations/migration:
-  en: d4269b2c58484a3d
-  zh: 0ae39476ecd330e6

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-activations/guide.md

@@ -1,59 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-activations/guide.zh.md

@@ -1,59 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/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/subagent-preset-composition/guide.md
-/:
-  en: 0351f79f0f7acc90
-  zh: c6815e557ffa1a2f
-/configure-subagent-composition-through-presets:
-  en: aab975172f278acf
-  zh: 4e6dad4ef487cc52
-/configure-subagent-composition-through-presets/change:
-  en: e758e1d0c34846db
-  zh: 93675aa1b3f7be4e
-/configure-subagent-composition-through-presets/migration:
-  en: 0ae5b3e77d8c4b83
-  zh: 746b44875e23dea6

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/guide.md

@@ -1,21 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/guide.zh.md

@@ -1,21 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/team-direct-inbox/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/team-direct-inbox/guide.md
-/:
-  en: d154c0e25274bb2f
-  zh: 7e59bdf067d2b141
-/agent-teams-messages-use-target-inboxes:
-  en: 04d7dcbdc1679eae
-  zh: 8b083641a9262d80
-/agent-teams-messages-use-target-inboxes/change:
-  en: 9968decf3dd340af
-  zh: 736a32caac4b5103
-/agent-teams-messages-use-target-inboxes/migration:
-  en: 7ffd442bfd55769e
-  zh: ffb11a143f11ce7f

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/team-direct-inbox/guide.md

@@ -1,21 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/team-direct-inbox/guide.zh.md

@@ -1,21 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/terminal-command-labels/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/terminal-command-labels/guide.md
-/:
-  en: 0722f826c1c12360
-  zh: 9b48ce197b6091f2
-/terminal-command-labels:
-  en: a75e371670f4ebc3
-  zh: cbad7dd538376e70
-/terminal-command-labels/change:
-  en: 0e386cd5b5d349dc
-  zh: c456641a3aa938b3
-/terminal-command-labels/migration:
-  en: 2044b801804a40aa
-  zh: 0f98e7da80e2f066

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/terminal-command-labels/guide.md

@@ -1,18 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/terminal-command-labels/guide.zh.md

@@ -1,18 +0,0 @@
----
-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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/tool-presentation-mode/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/tool-presentation-mode/guide.md
-/:
-  en: 123b457f6ec93005
-  zh: aa0366d7aae638ca
-/select-native-or-ptc-tool-presentation:
-  en: 493e892beb7aecb2
-  zh: 149d7678dde936bb
-/select-native-or-ptc-tool-presentation/change:
-  en: a72ed2baec1e7e5b
-  zh: a54c9b0c1e88829f
-/select-native-or-ptc-tool-presentation/migration:
-  en: 64379f963e886e64
-  zh: 18b46f7287598a9e

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/tool-presentation-mode/guide.md

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

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/tool-presentation-mode/guide.zh.md

@@ -1,21 +0,0 @@
----
-kind: upgrade-guide
-description: "工具呈现方式仅接受 native 或 ptc；混合的 both 模式会被拒绝。"
----
-
-# 选择原生或 PTC 工具呈现方式
-
-[English](guide.md) | 中文
-
-## 变更
-
-`@deepseek-ai/dsh-tools` 和 `@deepseek-ai/dsh-agent-tool-presentation` 的 `mode` 字段仅接受 `native` 或 `ptc`。`both` 值会被拒绝。这也影响 `DSH_TOOLS_MODE=both`，该环境变量通过随附的 profile 补丁提供工具配置。
-
-`native` 将可见工具公开为直接函数调用。`ptc` 公开 `run_code`，程序通过生成的 SDK 调用可见工具。同一应用中的不同 agent preset 仍可使用不同模式。
-
-## 迁移
-
-1. 在 `cordis.yml`、profile 的 `cordis.patch.yml` 或自定义覆盖文件中，将 `mode: both` 替换为用于直接调用的 `mode: native`，或用于程序调用的 `mode: ptc`。
-2. 将 `DSH_TOOLS_MODE=both` 替换为 `DSH_TOOLS_MODE=native` 或 `DSH_TOOLS_MODE=ptc`。若需按 preset 选择，请改为更新该 preset 的 `@deepseek-ai/dsh-agent-tool-presentation` 行。
-3. 将调用 `ctx.tools.presentAs('both')` 的代码改为选择 `native` 或 `ptc`。在 PTC 程序中，将调用保留在 `run_code` 内；不要将 SDK 函数名称作为模型的直接工具调用发出。
-4. 启动受影响的 profile，确认配置可加载。原生请求公开获准的直接工具；PTC 请求公开 `run_code` 及其 SDK 说明。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/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/web-listener-trust-config/guide.md
-/:
-  en: af5832d4e9eece99
-  zh: 8f97dad6921ed8a0
-/web-listener-and-trust-configuration-moves-to-webstartup:
-  en: de3788e700062659
-  zh: 9def0e8f38896304
-/web-listener-and-trust-configuration-moves-to-webstartup/change:
-  en: 19f901fb2974aab5
-  zh: b4ef886f85b61637
-/web-listener-and-trust-configuration-moves-to-webstartup/migration:
-  en: 30917eb37ead3e10
-  zh: fd1b26eada570dd3

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/guide.md

@@ -1,36 +0,0 @@
----
-kind: upgrade-guide
-description: "The Web profile replaces the `webRuntime` service and the `web-runtime` row's `trustedHosts` config with `webStartup`, and rejects a wildcard listener host."
----
-
-# Web listener and trust configuration moves to `webStartup`
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The Web profile no longer provides the `webRuntime` service, and the `web-runtime` row no longer declares a `trustedHosts` config value. A profile, overlay, or `--patch` file that injects `webRuntime` now waits for a service that never mounts, and an expression reading `ctx.webRuntime.trustedHosts` fails to evaluate, so the required Connection cannot start.
-
-The `web-startup` row provides one `webStartup` service carrying the invocation's `--trusted-host` authorities, and the `connection` row reads them from `ctx.webStartup.trustedHosts`. The listener host must also be one concrete IPv4 or IPv6 address of a local interface: `host: 0.0.0.0`, `--host ::`, and every other unspecified address are rejected at load, because binding every interface exposes the port to the network.
-
-## Migration
-
-1. Replace `inject: [webRuntime]` with `inject: [webStartup]` on every row that needs invocation trust.
-2. Replace `ctx.webRuntime.trustedHosts` expressions with `ctx.webStartup.trustedHosts`, and drop `ctx.webRuntime.lanAddresses`, which no longer exists.
-3. Rewrite the `connection` overlay for `webStartup`, and move any `trustedHosts` value that the `web-runtime` row carried into its expression. A patch replaces the matched row's whole `config`, so restate that config completely, and write an array-valued `!!js` expression as a quoted scalar:
-
-   ```yaml
-   # before
-   - id: connection
-     inject: [webRuntime]
-     config:
-       trustedHosts: !!js "['app.internal', ...ctx.webRuntime.trustedHosts]"
-   # after
-   - id: connection
-     inject: [webStartup]
-     config:
-       trustedHosts: !!js "['app.internal', ...ctx.webStartup.trustedHosts]"
-   ```
-
-4. Replace a wildcard `host` with one concrete address of a local interface. The bind IP itself is accepted by the Host fence with no `--trusted-host` entry; a proxy or DNS authority still needs one.
-5. Boot with the migrated overlay: `dsh --profile web --patch ./extra.yml --no-open` must print the `dsh web:` URL line and serve. A row still waiting on `webRuntime` leaves the required Connection pending and reports an activation failure, and a rejected `host` fails at load. `dsh --profile web --patch ./extra.yml --dump-config` prints the composed patch before boot. [The Web bundle README](../../../../packages/bundle/web-app/README.md) owns the composed rows.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/web-listener-trust-config/guide.zh.md

@@ -1,36 +0,0 @@
----
-kind: upgrade-guide
-description: "Web profile 用 `webStartup` 取代 `webRuntime` 服务与 `web-runtime` 行的 `trustedHosts` 配置，并拒绝通配监听地址。"
----
-
-# Web 监听与信任配置迁移到 `webStartup`
-
-[English](guide.md) | 中文
-
-## 变更
-
-Web profile 不再提供 `webRuntime` 服务，`web-runtime` 行也不再声明 `trustedHosts` 配置值。仍注入 `webRuntime` 的 profile、overlay 或 `--patch` 文件会等待一个永不挂载的服务，读取 `ctx.webRuntime.trustedHosts` 的表达式则会求值失败，导致必需的 Connection 无法启动。
-
-`web-startup` 行提供唯一的 `webStartup` 服务，携带本次调用的 `--trusted-host` authority；`connection` 行通过 `ctx.webStartup.trustedHosts` 读取它们。监听 host 现在也必须是本机网卡的一个具体 IPv4 或 IPv6 地址：`host: 0.0.0.0`、`--host ::` 及其他未指定地址都会在加载时被拒绝，因为绑定所有接口会把端口暴露到网络。
-
-## 迁移
-
-1. 将所有需要调用信任的行的 `inject: [webRuntime]` 换成 `inject: [webStartup]`。
-2. 将 `ctx.webRuntime.trustedHosts` 表达式换成 `ctx.webStartup.trustedHosts`，并删除已不存在的 `ctx.webRuntime.lanAddresses`。
-3. 按 `webStartup` 改写 `connection` overlay，并把原先由 `web-runtime` 行携带的 `trustedHosts` 值并入其表达式。patch 会整体替换所匹配行的 `config`，因此必须完整重述该配置；数组值的 `!!js` 表达式要写成带引号的标量：
-
-   ```yaml
-   # before
-   - id: connection
-     inject: [webRuntime]
-     config:
-       trustedHosts: !!js "['app.internal', ...ctx.webRuntime.trustedHosts]"
-   # after
-   - id: connection
-     inject: [webStartup]
-     config:
-       trustedHosts: !!js "['app.internal', ...ctx.webStartup.trustedHosts]"
-   ```
-
-4. 将通配 `host` 换成本机网卡的一个具体地址。所绑定的 IP 会被 Host 栅栏直接接受，无需 `--trusted-host`；代理或 DNS authority 仍需显式配置。
-5. 使用迁移后的 overlay 启动：`dsh --profile web --patch ./extra.yml --no-open` 必须打印 `dsh web:` URL 行并正常服务。仍在等待 `webRuntime` 的行会让必需的 Connection 保持 pending 并报告激活失败；被拒绝的 `host` 会在加载时失败。`dsh --profile web --patch ./extra.yml --dump-config` 可在启动前打印组合后的 patch。[Web 组合包 README](../../../../packages/bundle/web-app/README.zh.md)说明这些行。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/working-directory/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/working-directory/guide.md
-/:
-  en: bd716a636d3631a4
-  zh: 7a3a4de1d3669d57
-/migrate-working-directory-configuration-and-tool-presentation:
-  en: 0c783661ea6973cb
-  zh: 087e487812b4933b
-/migrate-working-directory-configuration-and-tool-presentation/change:
-  en: d2738fe9f819599d
-  zh: 4eaacaeadcd80adf
-/migrate-working-directory-configuration-and-tool-presentation/migration:
-  en: 01ae6e89e3312de8
-  zh: 503981500691b714

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/working-directory/guide.md

@@ -1,25 +0,0 @@
----
-kind: upgrade-guide
-description: "Session working directories replace built-in cwd configuration, and tool presentation metadata also runs for nested PTC calls."
----
-
-# Migrate working-directory configuration and tool presentation
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The next release removes the loop's built-in `{{cwd}}` prompt variable and the `cwd` configuration key from `@deepseek-ai/dsh-subagent-acp` and `@deepseek-ai/dsh-subagent-dsh-sdk`. Custom prompt templates that retain an unresolved `{{cwd}}` fail before a model request. A Session's current execution directory is supplied as required user context and is persisted separately from its original `Session.header.cwd`.
-
-New subagents use their start request's `cwd` when provided, otherwise they capture the parent's current directory. Existing processes keep their own directories. Changing the execution directory does not change the original project or grant additional write permissions.
-
-Tool `output.presentationMeta` also runs for successful nested PTC calls. Authors whose projection assumes only native top-level calls are affected. A projection error fails that nested call with `ToolOutputError`; canonical program values and model content remain unchanged.
-
-## Migration
-
-1. In home, profile, or invocation `personaSuffix` configuration and preset `suffix` fields, remove the directory clause that references `{{cwd}}`, retaining unrelated text. Omit or clear a suffix that becomes empty. The [working-directory service](../../../../packages/session/working-directory/README.md) supplies the directory context.
-2. Remove `config.cwd` from ACP and DSH-SDK subagent provider rows in your profile patches. To select a directory for one child, pass `cwd` in its [start request](../../../subsystems/subagent.md). To change the parent's execution directory, use `working_directory({ cd: "/absolute/project" })` before starting the child.
-3. Run `working_directory({})` in the affected Session and confirm the reported directory. Start a child without an override and check its execution directory; use an explicit start `cwd` when the child must use another checkout. Read `Session.header.cwd` only for original project identity or permission roots, rather than current-directory operations.
-4. Keep custom `output.presentationMeta` projections pure and return JSON-safe metadata from their arguments and canonical result. Exercise both a native call and a nested PTC call, and confirm the recorded metadata identifies the operation's actual target without changing its result.
-
-Dynamic context providers are evaluated again at request admission, after pre-step listeners and route preparation. Return current state without relying on one evaluation per step. Transform registered context inside its provider; admission refresh replaces its cached text while preserving assembly-only context contributions and the accepted system prompt, tool schemas, and variables.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/working-directory/guide.zh.md

@@ -1,25 +0,0 @@
----
-kind: upgrade-guide
-description: "Session 工作目录替代内置 cwd 配置，工具展示元数据也会在嵌套 PTC 调用中生成。"
----
-
-# 迁移工作目录配置与工具展示
-
-[English](guide.md) | 中文
-
-## 变更
-
-下一版本移除 loop 的内置 `{{cwd}}` 提示词变量，以及 `@deepseek-ai/dsh-subagent-acp` 和 `@deepseek-ai/dsh-subagent-dsh-sdk` 的 `cwd` 配置键。自定义提示词模板保留未解析的 `{{cwd}}` 时，会在模型请求发出前失败。Session 当前执行目录作为必需的 user context 提供，并与原始 `Session.header.cwd` 分开持久化。
-
-新子代理使用启动请求中显式提供的 `cwd`，未提供时捕获父代理的当前目录。已有进程保留各自的目录。切换执行目录不会改变原始项目，也不会授予额外写权限。
-
-工具 `output.presentationMeta` 也会在成功的嵌套 PTC 调用中运行。投影仅假设原生顶层调用的作者需要调整实现。投影异常会使该次嵌套调用以 `ToolOutputError` 失败；程序读取的规范值与模型内容不变。
-
-## 迁移
-
-1. 在 home、profile 或本次调用的 `personaSuffix` 配置，以及 preset 的 `suffix` 字段中，移除引用 `{{cwd}}` 的目录语句，保留其他文本。suffix 变为空时省略或清空该字段。[工作目录服务](../../../../packages/session/working-directory/README.zh.md)负责提供目录上下文。
-2. 从 profile patch 中的 ACP 与 DSH-SDK 子代理 provider 行移除 `config.cwd`。为单个子代理选择目录时，在其[启动请求](../../../subsystems/subagent.zh.md)中传入 `cwd`。改变父代理执行目录时，先调用 `working_directory({ cd: "/absolute/project" })`，再启动子代理。
-3. 在相关 Session 中调用 `working_directory({})` 并确认报告的目录。启动一个不带目录覆盖的子代理并检查其执行目录；子代理需要另一个 checkout 时，显式提供启动 `cwd`。仅用 `Session.header.cwd` 读取原始项目标识或权限根目录，当前目录操作使用工作目录服务。
-4. 保持自定义 `output.presentationMeta` 投影纯净，并从调用参数和规范结果返回可用于 JSON 的元数据。分别执行原生调用和嵌套 PTC 调用，确认记录的元数据指向操作的实际目标，同时不改变调用结果。
-
-动态上下文 provider 会在请求准入时再次求值，晚于 pre-step 监听器与路由准备。返回当前状态，不依赖每个步骤只求值一次。对已注册上下文的转换应在其 provider 内完成；准入刷新会替换缓存文本，同时保留仅由组装添加的上下文，以及已接纳的系统提示词、工具 schema 与变量。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/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.2/deepseek-account-identity-watch/guide.md
-/:
-  en: 7f67e85211e09294
-  zh: 989bd997224ba1d9
-/explicitly-subscribe-to-account-identity-changes:
-  en: c3ea4288a28acf1d
-  zh: 91483de64b303db0
-/explicitly-subscribe-to-account-identity-changes/change:
-  en: 1573d98d30b5eb0a
-  zh: 74b8281ab614773b
-/explicitly-subscribe-to-account-identity-changes/migration:
-  en: c0d458e4b471239e
-  zh: fa7fa792efeec570

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/guide.md

@@ -1,18 +0,0 @@
----
-kind: upgrade-guide
-description: "DeepSeekAccount.watch no longer includes Platform identity changes unless explicitly requested."
----
-
-# Explicitly subscribe to account identity changes
-
-English | [中文](guide.zh.md)
-
-## Change
-
-The public `DeepSeekAccount.watch(signal)` method previously emitted a snapshot when a profile read first supplied or changed the cached Platform user ID. It now emits account-state changes only by default. Plugins that use this stream to refresh `getPlatformSession()` must opt into identity changes. Credential replacement and sign-in state changes still notify every subscriber.
-
-## Migration
-
-1. Find calls to `deepseekAccount.watch(signal)` in plugins that refresh the Platform session or synchronize its user ID.
-2. Change those calls to `deepseekAccount.watch(signal, true)`. Leave account UI subscriptions that only need sign-in and credential state unchanged.
-3. Confirm that a ready `getProfile()` result whose user ID first appears or changes wakes the subscription and causes it to re-read `getPlatformSession()`. Repeated reads with the same ID do not emit another identity notification.