dsh-plugin-dev-kb 1.6.0 → 1.8.0

package/kb/extra/upgrade-guide/v0.2.1-rc.2/tool-executor-plugins/guide.zh.md

@@ -0,0 +1,35 @@
+---
+kind: upgrade-guide
+description: "工具执行模式从 dsh-tools 配置移至显式执行器插件。"
+---
+
+# 挂载工具执行器
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-tools` 保留工具注册和执行器选择，但加载时会拒绝已移除的 `mode` 和 `maxParallelSubCalls` 配置字段。原生和 PTC 执行分别要求 `@deepseek-ai/dsh-tool-executor-native` 或 `@deepseek-ai/dsh-tool-executor-ptc`。内置 profile 已挂载执行器，自定义组合必须添加一个。现有 `dsh-agent-tool-presentation` 选择器仍受支持，但已弃用。启用的 `tool-executor-native` 和 `tool-executor-ptc` 条目属于启动必需项；无效的执行器配置会终止启动。Web、headless 与 SDK 不再读取 `DSH_TOOLS_MODE`，均继承 base 的原生执行。
+
+## 迁移
+
+1. 保留 `dsh-tools` 条目并移除其执行配置。在目标部署或预设作用域挂载一个原生或 PTC 执行器。内置 profile 的补丁应修改执行器条目，而非 `tools` 条目。
+2. 把 `maxParallelSubCalls` 移到 PTC 执行器配置，并挂载兼容的 `ctx.ptcRuntime` 提供方。执行器将该服务声明为必需注入；缺少运行时会阻止启动，卸载运行时会撤回执行器。`agent-loop.maxParallelToolCalls` 和已保存的覆盖值保留原位，默认值为 `10`。循环向每个批次传入当前上限；实时修改从下一个批次生效，不再从下一个工具组生效。
+3. 自定义执行器实现 `describe` 和 `execute`。程序调用方传入原始 `calls` 和 `signal`，以及可选的 `agent` 和 `log: { turn, step }`；从 `results` 读取单次结果。不属于已提交模型步骤的调用应省略 `log`。
+4. 从 `@deepseek-ai/dsh-tool-executor-ptc` 导入 PTC SDK 渲染器和 `CodeRunFailedError`。用所选交互模式运行任务，确认工具结果出现在 Session 中。
+5. 从 `@deepseek-ai/dsh-tools/pipeline` 导入 `ToolExecutionPipeline` 和 `executeToolBatch`。完整执行（包括单次调用）使用批次；自定义调度器直接调用 `prepare`、`dispatch` 和 `complete`。把 `@deepseek-ai/dsh-tool-testkit` 添加为开发依赖，并从该包导入工具 fixture。工具注册表主入口不再导出这些成员。
+6. 从 `@deepseek-ai/dsh-tool-executor-ptc/types` 导入共享分派事件与 `ptc-mode` 消息来源声明；Client 代码使用其 `/client` 重导出。Host 策略扩展通过 `@deepseek-ai/dsh-tool-executor-ptc` 的 `import type` 获取 `PtcDispatchLog` 与 `tools/ptc-dispatch-log`。
+
+7. 从启动环境中移除 `DSH_TOOLS_MODE`。需要 PTC 时，将以下内容保存为 `ptc.yml` 并通过 `--patch` 加载；原生执行无需 overlay。同一补丁也适用于 `--profile web` 和 `--profile sdk`；TypeScript 和 Python SDK 客户端通过 `patches` 传入其路径。确认 PTC 模式下模型只收到 `run_code`。
+
+```yaml
+- id: tool-executor-native
+  disabled: true
+
+- id: tool-executor-ptc
+  disabled: false
+```
+
+```bash
+dsh --profile headless --patch ./ptc.yml "task"
+```

package/kb/extra/upgrade-guide/v0.2.1-rc.2/web-fetch-private-destinations/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "The HTTP fetch provider no longer rejects non-public destinations, and HttpFetchProvider no longer accepts an address resolver."
+---
+# `web_fetch` reaches private destinations
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-web-fetch-http` used to resolve each hostname, reject any loopback, private, link-local, or reserved answer with `WEB_BLOCKED_URL`, and pin the connection to the validated addresses. It now sends every request through the installed proxy policy and the system resolver, so `web_fetch` reaches loopback, private-network, and cloud metadata hosts. Fetches behind TUN-mode proxies with fake-IP DNS work without configuration.
+
+The package no longer exports `HttpFetchResolver`, and the `HttpFetchProvider` constructor takes only `HttpFetchLimits`.
+
+Deployments that relied on the provider to keep the model away from private services are affected, as is code that passed a resolver to `HttpFetchProvider`.
+
+## Migration
+
+1. If the model must not reach private destinations, confine the process's network access, add a `tools/pre-execute` policy that rejects those `web_fetch` URLs, or remove `@deepseek-ai/dsh-tool-web`'s fetch tool from the composition.
+2. Replace `new HttpFetchProvider(limits, resolveAddresses)` with `new HttpFetchProvider(limits)`. To direct a test request to a local server, put the server's address in the URL instead of overriding resolution.
+3. Confirm the migration with `pnpm run typecheck`; no reference to `HttpFetchResolver` remains.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/web-fetch-private-destinations/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "HTTP 抓取提供方不再拒绝非公开目标，HttpFetchProvider 也不再接受地址解析器。"
+---
+# `web_fetch` 可以访问私有目标
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-web-fetch-http` 以前会解析每个主机名，以 `WEB_BLOCKED_URL` 拒绝任何 loopback、私有、link-local 或保留地址，并把连接固定到已校验地址。现在它通过已安装的代理策略和系统解析器发送每个请求，因此 `web_fetch` 可以访问 loopback、内网与云元数据主机。使用 fake-IP DNS 的 TUN 模式代理之后，抓取无需配置即可工作。
+
+本包不再导出 `HttpFetchResolver`，`HttpFetchProvider` 构造函数只接受 `HttpFetchLimits`。
+
+依赖该提供方阻止模型访问私有服务的部署会受影响；向 `HttpFetchProvider` 传入解析器的代码也会受影响。
+
+## 迁移
+
+1. 如果模型不得访问私有目标，请限制进程的网络访问、添加拒绝这些 `web_fetch` URL 的 `tools/pre-execute` 策略，或从组合中移除 `@deepseek-ai/dsh-tool-web` 的抓取工具。
+2. 把 `new HttpFetchProvider(limits, resolveAddresses)` 替换为 `new HttpFetchProvider(limits)`。如需把测试请求指向本地服务器，请把服务器地址写进 URL，而不是覆盖解析。
+3. 用 `pnpm run typecheck` 确认迁移完成，且不再引用 `HttpFetchResolver`。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/webserver-index-peer/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "WebServer index rendering takes the Peer the page speaks for, and the `webserver/index-inject` event passes that Peer to listeners."
+---
+# WebServer index rendering takes a Peer
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`renderIndex(html)` and `collectIndexInjections()` on `ctx.webServer` from `@deepseek-ai/dsh-host-webserver` took no Peer, and every index carried the owner's access snapshot. They are now `renderIndex(html, peer)` and `collectIndexInjections(peer)`, and the `webserver/index-inject` event passes the same Peer as its second argument, so the remote-access snapshot in the index belongs to that Peer. Code that calls either method breaks at compile time; listeners that read only the table keep working.
+
+## Migration
+
+1. Pass the Peer the page speaks for to every `ctx.webServer.renderIndex(html)` and `ctx.webServer.collectIndexInjections()` call. A page served to the owner's browser passes `ctx.connection.browserPeer`.
+2. In a test that emits `webserver/index-inject` itself, pass a Peer after the table: `ctx.emit('webserver/index-inject', table, peer)`.
+3. Run your TypeScript build and confirm no call to either method reports a missing argument.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/webserver-index-peer/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "WebServer 渲染 index 时需要传入页面所代表的 Peer，`webserver/index-inject` 事件会把该 Peer 传给监听方。"
+---
+# WebServer 渲染 index 需要传入 Peer
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-host-webserver` 中 `ctx.webServer` 的 `renderIndex(html)` 与 `collectIndexInjections()` 不接收 Peer，每个 index 携带的都是 owner 的访问快照。现在它们改为 `renderIndex(html, peer)` 与 `collectIndexInjections(peer)`，`webserver/index-inject` 事件以第二个参数传入同一个 Peer，index 中的 remote-access 快照因此属于该 Peer。调用这两个方法的代码会在编译时报错；只读取表格的监听方不受影响。
+
+## 迁移
+
+1. 每处 `ctx.webServer.renderIndex(html)` 与 `ctx.webServer.collectIndexInjections()` 调用都传入页面所代表的 Peer。提供给 owner 浏览器的页面传入 `ctx.connection.browserPeer`。
+2. 自行 emit `webserver/index-inject` 的测试在表格之后传入一个 Peer：`ctx.emit('webserver/index-inject', table, peer)`。
+3. 运行 TypeScript 构建，确认这两个方法的调用都不再报缺少参数。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "Image read requests require a complete attachment reference and no longer check Session membership."
+---
+
+# Image read requests carry the complete attachment reference
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In 0.2.1-rc.3, `session/attachment` accepted `{ sessionId, attachmentId }` and searched the requested Session's history for the complete image reference. It now requires `{ sessionId, attachment: ref }`, where `ref` is an `ImageAttachmentRef` containing `attachmentId`, `mediaType`, `bytes`, `width`, and `height`. The Client's `session.readAttachment()` also takes the complete reference instead of an ID.
+
+The Host passes this reference to the existing `AttachmentStore.readImage(ref)`. It verifies the ID, actual format, byte length, width, and height against the stored object. The response remains `{ attachment, data }`, with base64 bytes in `data`. It preserves the supplied reference, including optional `name` and `originalDimensions`; those two fields are caller-supplied display information and are not verified against the file. Missing, corrupt, and mismatched objects fail explicitly.
+
+Connection authentication and Gateway permission checks still apply. Any identity authorized to call the endpoint for the supplied `sessionId` may read an image in the same store, including one referenced only by another Session or by no Session. The handler does not check image membership or Session existence and no longer returns `session/not-found` for an absent Session after authorization.
+
+## Migration
+
+1. Update wire calls from `{ sessionId, attachmentId: ref.attachmentId }` to `{ sessionId, attachment: ref }`, using the complete reference from the message image block. Update Client calls from `session.readAttachment(ref.attachmentId)` to `session.readAttachment(ref)`.
+2. Treat returned `name` and `originalDimensions` as the caller's display information. Only the ID, media type, byte length, width, and height are checked against the stored object.
+3. If your deployment depends on Session membership to isolate images, run separate Host instances with separate `DSH_HOME` directories before upgrading. The shipped composition does not select separate stores by Session within one Host. Gateway permissions govern endpoint invocation, not the image's Session membership.
+4. Confirm that an allowed request with a complete reference can read an image absent from the supplied Session, including when that Session does not exist. Denied Gateway requests, missing images, and references with mismatched intrinsic metadata must fail. Existing Session logs and stored images need no migration.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "图片读取请求必须携带完整附件引用，并且不再检查 Session 关联。"
+---
+
+# 图片读取请求需携带完整附件引用
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 0.2.1-rc.3 中，`session/attachment` 接收 `{ sessionId, attachmentId }`，并在请求中的 Session 历史里查找完整图片引用。现在，请求必须使用 `{ sessionId, attachment: ref }`，其中 `ref` 是包含 `attachmentId`、`mediaType`、`bytes`、`width` 和 `height` 的 `ImageAttachmentRef`。Client 的 `session.readAttachment()` 也改为接收完整引用，不再只接收 ID。
+
+Host 把该引用交给已有的 `AttachmentStore.readImage(ref)`，将 ID、实际格式、字节数、宽度和高度与存储对象校验。响应仍为 `{ attachment, data }`，`data` 包含 base64 字节。响应保留传入引用，包括可选的 `name` 和 `originalDimensions`；这两个字段是调用方提交的显示信息，不根据文件校验。对象缺失、损坏或与引用不符时会明确失败。
+
+连接身份认证和 Gateway 权限检查仍然适用。任何有权为请求中的 `sessionId` 调用该接口的身份，都可以读取同一存储中的图片，包括仅被其他 Session 引用或未被任何 Session 引用的图片。处理函数不检查图片关联或 Session 是否存在，授权通过后不再因 Session 不存在而返回 `session/not-found`。
+
+## 迁移
+
+1. 把 wire 调用从 `{ sessionId, attachmentId: ref.attachmentId }` 改为 `{ sessionId, attachment: ref }`，使用消息图片块中的完整引用。把 Client 调用从 `session.readAttachment(ref.attachmentId)` 改为 `session.readAttachment(ref)`。
+2. 把返回的 `name` 和 `originalDimensions` 视为调用方的显示信息。只有 ID、媒体类型、字节数、宽度和高度会与存储对象校验。
+3. 如果部署依赖 Session 关联来隔离图片，请在升级前改用独立 Host 实例及各自的 `DSH_HOME` 目录。随附组合不会在一个 Host 内按 Session 选择独立存储。Gateway 权限约束接口调用，不约束图片的 Session 关联。
+4. 确认获准调用的请求可以凭完整引用读取其 Session 中没有记录的图片，即使该 Session 不存在也可以读取。Gateway 拒绝的请求、缺失图片和固有元数据不符的引用必须失败。已有 Session 日志和存储图片无需迁移。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Computer Use needs permission for its own helper application instead of the terminal that launches DSH."
+---
+
+# Authorize the Computer Use helper
+
+English | [中文](guide.zh.md)
+
+## Change
+
+macOS Computer Use runs as `DSH Computer Use.app`, launched through LaunchServices. Accessibility and Screen Recording grants for a terminal or Desktop launcher do not grant access to this helper. Source preparation builds and signs the application; installed packages require the prepared application and its `current.json` receipt. A custom `helperPath` pointing at a bare native binary is no longer a supported native launch path.
+
+## Migration
+
+1. Restart DSH after upgrading the Computer Use package. In the Computer Use plugin page, grant Accessibility and Screen Recording access to `DSH Computer Use.app` when macOS requests it.
+2. Remove an obsolete `helperPath` override or `DSH_CUA_HELPER` value to use automatic preparation. For a custom build, point it to the executable at `DSH Computer Use.app/Contents/MacOS/dsh-cua-native` inside the complete application bundle.
+3. Confirm that the permission page identifies `DSH Computer Use.app` and both permissions are allowed before resuming native application tasks. Target-application consent remains required.
+4. If a terminal or Desktop launcher was granted these permissions only for Computer Use, revoke those obsolete grants in System Settings. Authorizing the helper does not revoke other applications’ existing permissions; programs the model runs still follow their launcher’s system permissions and the DSH sandbox policy.
+
+Source builds use ad-hoc signing and may need authorization again after code changes. Release packagers must preserve a stable Developer ID signing identity and notarize their distribution. See the [native build instructions](../../../../packages/experimental/cua-macos/native/README.md#build-and-service).

package/kb/extra/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Computer Use 需要给自己的 helper 应用授权，启动 DSH 的终端授权不再适用。"
+---
+
+# 给 Computer Use helper 授权
+
+[English](guide.md) | 中文
+
+## 变更
+
+macOS Computer Use 通过 LaunchServices 以 `DSH Computer Use.app` 运行。终端或 Desktop 启动器的辅助功能和屏幕录制授权不赋予 helper 权限。源码准备会构建并签名应用；安装版需要预构建的应用及 `current.json` 记录。自定义 `helperPath` 指向裸原生二进制的启动方式不再受支持。
+
+## 迁移
+
+1. 升级 Computer Use 包后重启 DSH。在 Computer Use 插件页按 macOS 提示，给 `DSH Computer Use.app` 授予辅助功能和屏幕录制权限。
+2. 删除过时的 `helperPath` 覆盖配置或 `DSH_CUA_HELPER` 值，使用自动准备。使用自定义构建时，将其指向完整应用包内的 `DSH Computer Use.app/Contents/MacOS/dsh-cua-native` 可执行文件。
+3. 恢复原生应用任务前，确认权限页显示 `DSH Computer Use.app`，且两项权限均已允许。具体目标应用仍需另行许可。
+4. 若终端或 Desktop 启动器的这两项权限只用于 Computer Use，可在系统设置中撤销这些旧授权。给 helper 授权不会撤销其他应用已有的权限；模型运行的程序仍遵循启动器的系统权限和 DSH 沙箱策略。
+
+源码构建使用临时签名，代码变化后可能需要重新授权。正式发布需要保持稳定的 Developer ID 签名身份，并完成分发公证。参见[原生构建说明](../../../../packages/experimental/cua-macos/native/README.zh.md#build-and-service)。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: macOS Computer Use grants use bundle identifiers and require renewed consent for old application identities.
+---
+
+# macOS Computer Use application identity
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Application grants use the case-sensitive native bundle identifier. Versions and copies at different paths share permission and revocation, regardless of signing. Applications without a bundle identifier use their canonical executable path and can also receive always-allow grants. Restarting or replacing the executable at that path retains consent; moving it requires renewed consent. A valid running bundle identifier does not require an executable path. Grant records can omit executablePath, and the permission page then shows the name without a path tooltip or icon. Existing records remain readable; older versions that require this field cannot read new pathless records. The profile storage location and conversation scopes are unchanged.
+
+This affects macOS users with saved path/signature grants, including grants imported from the legacy `allowedApps` configuration. Those grants do not match the new identities. They remain visible and removable but do not authorize other installations automatically. Old and new records can show the same name and path; the permission page does not distinguish them. Another program declaring an approved bundle identifier or replacing an executable at an approved fallback path inherits permission; this policy does not authenticate publishers.
+
+## Migration
+
+1. In Computer Use application management, revoke every existing always-allowed entry for each affected application before selecting it again. If you already granted access after upgrading, remove all entries for that application rather than trying to distinguish old and new records.
+2. Under “Applications not allowed,” use “Allow asking again” for that application so a prior refusal or revocation does not prevent the next prompt. Select the application again and approve the intended scope. “Always allow” covers all versions and copies with the same bundle identifier within the profile.
+3. Select another installed copy with that bundle identifier and confirm it does not ask again within the granted scope. Revoke the shared grant to stop access for all copies. Versions with different bundle identifiers still require separate approval.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: macOS Computer Use 授权改用 Bundle ID，旧应用身份需要重新授权。
+---
+
+# macOS Computer Use 应用身份
+
+[English](guide.md) | 中文
+
+## 变更
+
+应用授权使用原生应用提供的、区分大小写的 Bundle ID。不同路径的版本和副本共用许可与撤销决定，不受签名状态影响。缺少 Bundle ID 的应用使用规范化可执行路径，也可以“始终允许”。在该路径重启或替换可执行文件会沿用许可，移动文件则需重新授权。运行中的有效 Bundle ID 不依赖可执行路径。授权记录可以省略 executablePath，权限页此时显示名称，不显示路径提示或图标。已有记录仍可读取，要求该字段的旧版本无法读取缺少路径的新记录。profile 存储位置和对话范围保持不变。
+
+受影响的是保存过路径和签名授权的 macOS 用户，包括通过旧 `allowedApps` 配置导入授权的用户。这些授权不匹配新身份。旧记录仍可查看和撤销，但不会自动授权其他安装副本。新旧条目可能显示相同名称和路径，权限页没有区分它们。其他程序声明已批准的 Bundle ID，或替换路径授权对应的可执行文件时，也会继承许可，这项规则不验证发布者身份。
+
+## 迁移
+
+1. 重新选择应用前，在 Computer Use 应用管理中撤销该应用的所有“始终允许”条目。如果升级后已经批准过，也移除该应用的全部条目，无须判断哪条是旧记录。
+2. 在“不允许访问的应用”中，对该应用点击“允许再次询问”，避免先前的拒绝或撤销阻止下次提示。重新选择应用并批准所需范围。“始终允许”覆盖当前 profile 中相同 Bundle ID 的所有版本和副本。
+3. 选择具有相同 Bundle ID 的另一个已安装副本，确认在许可范围内不再询问。需要停止所有副本的访问时，撤销共用许可。使用不同 Bundle ID 的版本仍需分别批准。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Generated worktree names replace the worktree- prefix and full UUID suffix with dsh- and Session-derived names."
+---
+
+# Update consumers of generated worktree names
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.2.1-rc.3, omitting `name` from `create_worktree` or `ctx.worktrees.create` generates `worktree-<UUID>` by default. The next release generates `dsh-<first eight UUID digits from the Session id>-<four random hexadecimal digits>`, such as `dsh-6b1f02c4-9a3e`. A Session id without a UUID gets `dsh-<eight random hexadecimal digits>`.
+
+Scripts and ignore rules that require the `worktree-` prefix or a full UUID suffix need updating. Explicit names, the configured checkout pool, and existing checkout directories and branches are unchanged. The `namePrefix` setting remains available, but it controls only the prefix, not the suffix format.
+
+## Migration
+
+1. Update scripts and ignore rules that recognize generated names. Prefer the returned `path` and `branch` fields over reconstructing them from the old pattern; the [worktree service reference](../../../../packages/experimental/worktree/README.md#use-this-package) describes these fields.
+2. To retain the old prefix, set `config.namePrefix` to `worktree-` in the existing `@deepseek-ai/dsh-experimental-worktree` configuration row. This does not restore the full UUID suffix. Supply an explicit `name` when an integration requires a particular complete name.
+3. Create a worktree with `name` omitted, inspect its returned `branch` and `path`, and confirm that the updated automation recognizes it. Existing worktrees require no renaming or data migration.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "自动生成的 worktree 名称将 worktree- 前缀和完整 UUID 后缀改为 dsh- 前缀与基于 Session 的名称。"
+---
+
+# 更新依赖自动生成 worktree 名称的使用方
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.1-rc.3 中，调用 `create_worktree` 或 `ctx.worktrees.create` 时省略 `name`，默认生成 `worktree-<UUID>`。下一版本默认生成 `dsh-<Session id 中 UUID 的前八位十六进制数>-<四位随机十六进制数>`，例如 `dsh-6b1f02c4-9a3e`。Session id 不含 UUID 时，生成 `dsh-<八位随机十六进制数>`。
+
+依赖 `worktree-` 前缀或完整 UUID 后缀的脚本和忽略规则需要更新。显式名称、配置的检出父目录以及已有的检出目录和分支保持不变。`namePrefix` 配置项仍然可用，但只控制前缀，不控制后缀格式。
+
+## 迁移
+
+1. 更新识别自动生成名称的脚本和忽略规则。优先使用返回的 `path` 与 `branch` 字段，不要按旧模式重新拼接；[worktree 服务参考](../../../../packages/experimental/worktree/README.zh.md#use-this-package)说明了这些字段。
+2. 如需保留旧前缀，在现有的 `@deepseek-ai/dsh-experimental-worktree` 配置行中将 `config.namePrefix` 设为 `worktree-`。这不会恢复完整 UUID 后缀；集成要求特定完整名称时，请显式传入 `name`。
+3. 创建一个省略 `name` 的 worktree，检查返回的 `branch` 与 `path`，确认更新后的自动化能识别它。已有 worktree 无需改名或迁移数据。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/inbox-only-agent-wait/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Task-board changes no longer end wait_agent calls; send a message to request further work."
+---
+# Agent waits require inbox input
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`wait_agent` waits only for the calling Agent's next-step inbox. Task creation, assignment, completion, and other task updates no longer end an active wait. They do not add inbox messages or start idle Agents. Queued next-turn input and other Agents' status changes also leave the wait pending.
+
+Existing next-step input returns immediately; new messages, completion notifications, and user steering end the wait without consuming that input. Timeout and cancellation behavior remain unchanged.
+
+## Migration
+
+1. After changing a task, use `send_message` when its owner or another member needs to act on the update. Do not rely on a task mutation to release `wait_agent`.
+2. Read current task state before acting; a task update is not a message or an instruction to begin a new turn.
+3. Verify that a task update leaves an empty-inbox wait pending, then send a message and confirm that the wait returns with `timedOut: false`.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/inbox-only-agent-wait/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "任务板变更不再结束 wait_agent 调用；需要继续工作时发送消息。"
+---
+# Agent 等待需要收件箱输入
+
+[English](guide.md) | 中文
+
+## 变更
+
+`wait_agent` 仅等待调用 Agent 的下一步收件箱。任务创建、分配、完成和其他任务更新不再结束正在进行的等待，也不添加收件箱消息或启动空闲 Agent。排队的下一轮输入和其他 Agent 的状态变化同样不会结束等待。
+
+已有下一步输入时立即返回；新消息、完成通知和用户引导会结束等待，但不消费输入。超时和取消行为保持不变。
+
+## 迁移
+
+1. 修改任务后，需要任务所有者或其他成员处理更新时使用 `send_message`。不要依赖任务修改来结束 `wait_agent`。
+2. 行动前读取当前任务状态；任务更新不是消息，也不是开始新轮次的指令。
+3. 验证任务更新不会结束空收件箱上的等待，然后发送消息，确认等待返回 `timedOut: false`。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/independent-session-forks/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "Ordinary Session forks stop recording their source relationship and stop appearing as subagents."
+---
+
+# Ordinary forks are independent Sessions
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Ordinary forks copy the selected history and continue independently. They omit `SessionHeader.parentSession` and the Client's `parentSessionId`; no replacement source field is written. Subagents, including fork-backend subagents, retain their direct creator. Existing logs retain their recorded metadata.
+
+SDK `subagent.started` excludes ordinary forks, including historical ones carrying a parent id. ACP list/resume admits ordinary forks; headless adoption also accepts them when cwd and preset checks pass. Client lists no longer indent them or insert newly discovered forks before their sources; saved manual positions remain intact. Source-based trace queries, parent filters, telemetry, and remote logs cannot recover the source of new ordinary forks. Workspace binding, optional title increments, inherited history, and seed boundaries remain available.
+
+The Session format stays V4. Older V4 readers may reject a parentless fork containing inherited delivery acknowledgements as a corrupt log with `current-generation delivery marker names the wrong Session`. The tested readers refuse before granting a handle or truncating the file. They do not provide an upgrade-specific diagnostic. See the [compatibility decision](../../../../.agents/notes/implemented/architecture/2026-10-23-independent-session-forks.md).
+
+## Migration
+
+1. Upgrade every reader and writer sharing the Session directory before resuming newly created forks. Do not edit old headers or delete delivery records to bypass an older reader's rejection.
+2. Replace consumer checks that treat any `parentSession` as a subagent with `origin === 'subagent'`. Continuation still requires a valid descriptor from the Session's own event range; inherited descriptors do not establish its identity.
+3. Remove any ordinary-fork workflow that requires persistent source tracing. Keep source-dependent actions such as workspace selection within the fork operation.
+4. Confirm that an ordinary fork has no parent field, survives restart with inherited delivery records, and produces no `subagent.started`; confirm that real subagents retain their creator and notification.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/independent-session-forks/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "普通 Session fork 停止记录来源关系，也不再显示为子代理。"
+---
+
+# 普通 fork 是独立 Session
+
+[English](guide.md) | 中文
+
+## 变更
+
+普通 fork 复制选定历史并独立继续运行。它们省略 `SessionHeader.parentSession` 及客户端的 `parentSessionId`，不写入替代来源字段。子代理（包括使用 fork backend 的子代理）保留直接创建者。已有日志保留记录中的元数据。
+
+SDK 的 `subagent.started` 排除普通 fork，包括携带父 ID 的历史会话。ACP 列表和恢复允许普通 fork；通过 cwd 和 preset 检查的普通 fork 也可由 headless 沿用。客户端列表不再将它们缩进，也不再把新发现的 fork 插到来源之前；已保存的手动位置保持不变。基于来源的追踪查询、父关系筛选、遥测和远端日志无法还原新普通 fork 的来源。工作区绑定、可选标题递增、继承历史和 seed 边界仍然可用。
+
+Session 格式保持 V4。旧 V4 reader 可能将包含继承投递确认的无父关系 fork 作为损坏日志拒绝，报错为 `current-generation delivery marker names the wrong Session`。已测试的 reader 在授予句柄或截断文件之前拒绝，不提供专门的升级诊断。参见[兼容性决策](../../../../.agents/notes/implemented/architecture/2026-10-23-independent-session-forks.zh.md)。
+
+## 迁移
+
+1. 在恢复新建 fork 之前，升级共享 Session 目录的全部 reader 和 writer。不要编辑旧 header 或删除投递记录来绕过旧 reader 的拒绝。
+2. 将消费方中把任意 `parentSession` 视为子代理的检查替换为 `origin === 'subagent'`。继续运行仍要求来自 Session 自身事件区间的有效 descriptor；继承的 descriptor 不建立其身份。
+3. 移除依赖持久化来源追踪的普通 fork 工作流。工作区选择等依赖来源的动作保留在 fork 操作期间。
+4. 确认普通 fork 不含父字段、携带继承投递记录也能在重启后恢复，且不产生 `subagent.started`；确认真正子代理保留创建者及通知。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Caller-cancelled run_code results use ABORTED instead of CODE_RUN_FAILED."
+---
+
+# PTC caller cancellation uses the standard tool error code
+
+English | [中文](guide.zh.md)
+
+## Change
+
+When a running `run_code` call is cancelled by its caller and the runtime reports `abort`, its `tool/result` error changes from `CodeRunFailedError` / `CODE_RUN_FAILED` to `AbortError` / `ABORTED`. The result content is `Error: tool call aborted`, replacing the runtime diagnostic, captured output and sandbox summary. SDK clients and Session consumers that classify these results are affected.
+
+The Agent continues to record the specific cancellation cause in `turn/end`, including a hook's `reason`. Runtime failures such as timeout and cleanup failure, and runtime-local cancellation without caller cancellation, retain `CODE_RUN_FAILED`. Cancellation still waits for cleanup; it does not roll back completed tool effects, and retained runtime variables may be cleared.
+
+## Migration
+
+1. In consumers of new `tool/result` events, classify caller cancellation by `data.error.code === 'ABORTED'`. Read the Agent cancellation cause from the corresponding `turn/end` event's `data.reason.reason` when `data.reason.kind === 'aborted'`.
+2. Keep support for `CODE_RUN_FAILED` when reading historical PTC cancellation results. Existing Session logs are not rewritten.
+3. Cancel a running `run_code` call and confirm its result has code `ABORTED`, followed by a `turn/end` event containing the original Agent cancellation cause. Confirm ordinary runtime failures still report `CODE_RUN_FAILED`.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "调用方取消的 run_code 结果使用 ABORTED，取代 CODE_RUN_FAILED。"
+---
+
+# PTC 调用方取消使用标准工具错误码
+
+[English](guide.md) | 中文
+
+## 变更
+
+运行中的 `run_code` 被调用方取消且运行时报告 `abort` 时，其 `tool/result` 错误从 `CodeRunFailedError` / `CODE_RUN_FAILED` 变为 `AbortError` / `ABORTED`。结果内容为 `Error: tool call aborted`，取代运行时诊断、捕获输出和沙箱摘要。按这些结果分类的 SDK 客户端和 Session 消费方受到影响。
+
+Agent 继续在 `turn/end` 中记录具体取消原因，包括 hook 的 `reason`。超时、清理失败等运行时失败，以及没有调用方取消的运行时内部取消，保留 `CODE_RUN_FAILED`。取消仍等待清理完成；它不会回滚已完成的工具操作，保留的运行时变量可能被清空。
+
+## 迁移
+
+1. 在新 `tool/result` 事件的消费方中，通过 `data.error.code === 'ABORTED'` 识别调用方取消。当对应 `turn/end` 事件的 `data.reason.kind === 'aborted'` 时，从 `data.reason.reason` 读取 Agent 取消原因。
+2. 读取历史 PTC 取消结果时，继续支持 `CODE_RUN_FAILED`。已有 Session 日志不会被重写。
+3. 取消运行中的 `run_code`，确认其结果错误码为 `ABORTED`，随后的 `turn/end` 事件包含原始 Agent 取消原因。确认普通运行时失败仍报告 `CODE_RUN_FAILED`。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Session follow callers must explicitly request background Agent activation."
+---
+# Request activation when following a Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`session.follow` no longer automatically resumes a cold ordinary Agent when `activate` is omitted. It reads the opening snapshot and follows subsequent events without activation. This affects integrations that used opening a history stream to make an Agent available. The shipped Web Client sends `activate: true` explicitly and retains its opening behavior.
+
+With `activate: true`, activation starts once the opening snapshot is computed, before it is delivered; that snapshot does not acknowledge Agent readiness. Subagent Sessions still do not use ordinary Agent activation.
+
+## Migration
+
+1. Add `activate: true` to `session.follow` requests that must resume a cold ordinary Agent. Keep the existing `address` and history-window fields.
+2. For passive viewers, omit `activate` or set it to `false`.
+3. Verify that an activation-enabled stream still returns its opening snapshot, then check Agent availability separately. Do not treat receipt of the snapshot as completion of activation.
+
+See the [Session Controller reference](../../../../packages/api/session-controller/README.md) for history and state observation behavior.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Session follow 调用方必须显式请求后台 Agent 激活。"
+---
+# 跟随 Session 时显式请求激活
+
+[English](guide.md) | 中文
+
+## 变更
+
+`session.follow` 在省略 `activate` 时不再自动恢复冷普通 Agent。它只读取开场快照并跟随后续事件，不进行激活。这会影响通过打开历史流使 Agent 可用的集成。随产品提供的 Web Client 显式发送 `activate: true`，保留原有打开行为。
+
+设置 `activate: true` 时，激活在开场快照计算完成后、交付之前开始；该快照不确认 Agent 已就绪。子会话仍不走普通 Agent 激活。
+
+## 迁移
+
+1. 为需要恢复冷普通 Agent 的 `session.follow` 请求添加 `activate: true`，保留原有 `address` 和历史窗口字段。
+2. 被动查看器可以省略 `activate` 或设为 `false`。
+3. 确认启用激活的流仍返回开场快照，再单独检查 Agent 是否可用。不要把收到快照当作激活完成。
+
+历史与状态观察行为见 [Session Controller 参考](../../../../packages/api/session-controller/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/subagent-runtime-ownership/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: Agent factory ownership parameters and registry tree queries are removed; subagent Activations own runtime tree membership.
+---
+
+# Subagent runtime ownership
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-agent` removes the create/resume runtime-owner parameter (`parentAgent` or `ownerAgent`), `AgentRegistry.isOwnedBy()`, `AgentRegistry.roots()`, and the owner argument of `enter()`. Direct factory creation no longer enrolls an Agent in a managed subagent tree. Custom factories no longer implement runtime tree ownership.
+
+The subagent service resolves runtime membership from its existing Activations through `rootOf(agent)`. The Session format and Cordis context ownership of handles are unchanged.
+
+## Migration
+
+1. Create delegated work through `ctx.subagents.startActivation()` with a registered provider. Remove ownership parameters from direct `ctx.agents.create()` and `resume()` calls; these operations create independent runtime instances.
+2. Use `ctx.agents.get(id)` and `list()` for live lookup. To select ordinary live Agents, filter `list()` by `agent.session.header.origin !== 'subagent'`; historical ordinary forks can still have `parentSession`.
+3. Query the live tree root with `ctx.subagents.rootOf(agent)` and compare Agent objects, not only ids. Ordinary live Agents resolve to themselves; unmanaged delegated or stale instances throw `SubagentError` with code `UNAUTHORIZED`. Read `session.header.parentSession` for the direct creator; use durable subagent catalogs when traversing offline creation ancestors.
+4. Update custom factory implementations to call `ctx.agents.enter(agent)` after setup. Retain caller-context disposal, initialization rollback, and exact-instance registration checks. Runtime tree membership is available after managed activation publication; `agent/created` runs before that point. Verify stale instances cannot reuse a disposed instance's ownership.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/subagent-runtime-ownership/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: Agent 工厂归属参数和注册表树查询已删除；subagent Activation 拥有运行时树成员关系。
+---
+
+# Subagent 运行时归属
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-agent` 删除 create/resume 的运行时归属参数（`parentAgent` 或 `ownerAgent`）、`AgentRegistry.isOwnedBy()`、`AgentRegistry.roots()` 以及 `enter()` 的 owner 参数。直接通过工厂创建 Agent 不再将其加入托管 subagent 树。自定义工厂不再实现运行时树归属。
+
+subagent 服务通过 `rootOf(agent)` 从已有 Activation 解析运行时成员关系。Session 格式和 Cordis 上下文对句柄的所有权不变。
+
+## 迁移
+
+1. 通过 `ctx.subagents.startActivation()` 和已注册提供方创建委派工作。删除直接调用 `ctx.agents.create()` 与 `resume()` 时的归属参数；这些操作创建独立的运行时实例。
+2. 通过 `ctx.agents.get(id)` 与 `list()` 查询存活实例。筛选普通存活 Agent 时，用 `agent.session.header.origin !== 'subagent'` 过滤 `list()`；历史普通 fork 仍可能包含 `parentSession`。
+3. 通过 `ctx.subagents.rootOf(agent)` 查询存活树根，并比较 Agent 对象，而非仅比较 id。普通存活 Agent 返回自身；非托管的委派实例或失效实例抛出代码为 `UNAUTHORIZED` 的 `SubagentError`。直接创建者读取 `session.header.parentSession`；遍历离线创建祖先时使用持久化 subagent 目录。
+4. 更新自定义工厂，在 setup 后调用 `ctx.agents.enter(agent)`。保留调用方上下文释放、初始化回滚和确切实例注册检查。运行时树成员关系在托管 activation 发布后可用；`agent/created` 早于该时点。验证失效实例不能复用已释放实例的归属。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/team-mode-menu/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The Team mode slash command is removed; use the root conversation menu."
+---
+
+# Select Team mode from the conversation menu
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`/team on` and `/team off` are no longer registered. The root conversation’s **Use Agent Teams** switch calls `remote.agentTeams.setEnabled` directly. Saved selections, task retention, and root-only authorization are unchanged.
+
+## Migration
+
+1. Enable or disable **Use Agent Teams** in the root conversation’s model and reasoning menu.
+2. Plugins that execute the command should call `ctx.agentTeams.setEnabled(rootAgent, enabled)` instead; browser clients call `remote.agentTeams.setEnabled(rootSessionId, enabled)`.
+3. Confirm the switch reflects the saved selection after reloading the Session.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/team-mode-menu/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Team 模式斜杠命令已移除，请使用根会话菜单。"
+---
+
+# 从会话菜单选择 Team 模式
+
+[English](guide.md) | 中文
+
+## 变更
+
+`/team on` 和 `/team off` 不再注册。根会话的**使用智能体团队**开关直接调用 `remote.agentTeams.setEnabled`。保存的选择、任务保留以及仅允许根会话修改的授权规则不变。
+
+## 迁移
+
+1. 在根会话的模型与推理等级菜单中打开或关闭**使用智能体团队**。
+2. 执行该命令的插件改为调用 `ctx.agentTeams.setEnabled(rootAgent, enabled)`；浏览器客户端调用 `remote.agentTeams.setEnabled(rootSessionId, enabled)`。
+3. 重新加载 Session，确认开关反映已保存的选择。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/team-projection/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Team projection stops restoring historical teammates and mailbox state while retaining tasks and saved mode."
+---
+
+# Team projection retains tasks and mode
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `agentTeam` projection no longer restores `members`, `messages`, or `delivered` from historical `team/member` and `team/message/*` events. It ignores their payloads, so historical roster or mailbox validation failures no longer block task reads or writes. Historical teammates are not restored and queued mail is not delivered.
+
+Task revisions, task owners, deleted-task records, and the saved Team mode remain supported. Ordinary subagent discovery and messaging are unchanged. The Session format and committed log files do not change; projection checkpoint version 7 rebuilds older cached state from the log.
+
+## Migration
+
+1. No data conversion or configuration change is required. Open the Session normally to rebuild incompatible projection checkpoints.
+2. Use `list_agents` and `send_message` for current teammates. Read historical roster or mailbox events from the original Session log if you need an archive; the Team projection no longer supplies these collections.
+3. Confirm that the task board and saved Team mode are restored. Historical roster and mailbox records do not grant task-assignment authority.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/team-projection/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Team 投影停止恢复历史队友与邮箱状态，同时保留任务和保存的模式。"
+---
+
+# Team 投影保留任务与模式
+
+[English](guide.md) | 中文
+
+## 变更
+
+`agentTeam` 投影不再从历史 `team/member` 和 `team/message/*` 事件恢复 `members`、`messages` 或 `delivered`。投影忽略这些载荷，因此历史名册或邮箱校验失败不再阻止任务读写。不恢复历史队友，也不投递排队邮件。
+
+任务修订、任务所有者、已删除任务记录和保存的 Team 模式仍受支持。普通子代理发现与通信保持不变。Session 格式和已提交日志文件不变；投影检查点版本 7 从日志重建旧缓存状态。
+
+## 迁移
+
+1. 无需转换数据或修改配置。正常打开 Session 即可重建不兼容的投影检查点。
+2. 使用 `list_agents` 和 `send_message` 与当前队友协作。需要归档信息时，从原始 Session 日志读取历史名册或邮箱事件；Team 投影不再提供这些集合。
+3. 确认任务板和保存的 Team 模式已恢复。历史名册与邮箱记录不授予任务分配权限。