dsh-primer 0.4.3 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-service-methods/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The subagent service removes drainChildren, listChildren, and list."
+---
+
+# Subagent service method removal
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ctx.subagents` removes `drainChildren(parent, childIds)`, `listChildren(parentSessionId, signal?)`, and `list()`. This affects plugins that release resident children by id, read direct-child catalogs through the service, or enumerate registered provider names.
+
+## Migration
+
+1. Retain the activation returned by `startActivation()` and await its `dispose()` to release that exact execution. An old activation cannot release a later execution of the same Session. There is no replacement for releasing the current resident child by id; use `drainDescendants([root])` only when closing the entire tree. `interrupt()` stops current work but preserves a local Activation.
+2. For direct-child entries, use `ctx.sessionQuery.observeSession(parentSessionId, { signal })`, read `observation.projections?.values.subagentCatalog`, and dispose the observation with `using`. Load Session Query and the subagent service, and treat a missing catalog projection as unavailable. Keep `listDescendants()` for recursive discovery; its rows differ from direct catalog entries.
+3. Use `getProvider(name)` to check known provider names. The service no longer enumerates all registered names.
+4. Rebuild plugins against the updated service declarations. Verify registration and unload checks, exact-activation disposal, and catalog observation cleanup.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-service-methods/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "子代理服务移除 drainChildren、listChildren 和 list。"
+---
+
+# 子代理服务方法移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ctx.subagents` 移除 `drainChildren(parent, childIds)`、`listChildren(parentSessionId, signal?)` 和 `list()`。这会影响按 id 释放驻留子代理、通过服务读取直接子级目录或枚举已注册 provider 名称的插件。
+
+## 迁移
+
+1. 保留 `startActivation()` 返回的 activation，并等待其 `dispose()` 完成以释放那一次执行。旧 activation 不能释放同一 Session 后来恢复的执行。按 id 释放当前驻留子代理没有替代方法；仅在关闭整棵树时使用 `drainDescendants([root])`。`interrupt()` 停止当前工作，但保留本地 Activation。
+2. 读取直接子级条目时，使用 `ctx.sessionQuery.observeSession(parentSessionId, { signal })`，读取 `observation.projections?.values.subagentCatalog`，并通过 `using` 释放观察对象。加载 Session Query 和子代理服务，并将缺失的目录投影视为不可用。递归发现继续使用 `listDescendants()`；它返回的行与直接目录条目不同。
+3. 使用 `getProvider(name)` 检查已知 provider 名称。服务不再枚举全部已注册名称。
+4. 根据更新后的服务声明重新构建插件，验证注册和卸载检查、指定 activation 的释放以及目录观察对象的清理。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.md
+/:
+  en: 9d77440fbd1ac5ee
+  zh: e51db37880a28684
+/subagent-user-controls-address-the-target-session:
+  en: 8f5fcee305e3a5d7
+  zh: c6bb2c762cd2b86d
+/subagent-user-controls-address-the-target-session/change:
+  en: 0a309d3a2a123b46
+  zh: 416f075bfdb8664a
+/subagent-user-controls-address-the-target-session/migration:
+  en: f3a61ba7c3a5110e
+  zh: 95c88d6f9d685fd4

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "Subagent user controls address only the target Session, rename the interrupt endpoint, and require target Session permissions instead of global permissions."
+---
+
+# Subagent user controls address the target Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Browser and custom Remote callers send subagent prompts without `parentSessionId` or `mode`. `subagents/interruptByParent(childSessionId, parentSessionId, mode)` is replaced by `subagents/interruptByUser(childSessionId)`. Creation ancestry, history addresses, completion recipients, and persisted Session data are unchanged.
+
+Both operations name the child as a `session` access resource. Non-owner policies must grant the corresponding action on that Session; a `global` binding or a binding on its parent does not grant access. Owner behavior is unchanged. Model messages remain limited to one subagent tree, and model interruption remains ancestor-only.
+
+The same-process `SubagentInterruptAuthority` user variant is `{ kind: 'user' }`. The published `@deepseek-ai/dsh-subagent/internal` entry point is removed, including its host prompt adapters and tool identity markers. Remote authorization is performed by the Gateway.
+
+Old prompt payloads with extra fields inside `request` can decode on the new Host, subject to its new access rules. Old interrupt calls fail because the endpoint is removed. New callers require the new Host. Upgrade custom clients and hosts together; the bundled Web client is delivered with its Host.
+
+## Migration
+
+1. Remove `parentSessionId` and `mode` from subagent prompt requests. Keep `childSessionId`, `requestId`, `delivery`, `content`, and optional `clientTimeZone`.
+2. Replace calls to `interruptByParent(childId, parentId, 'continuable')` with `interruptByUser(childId)`.
+3. Update non-owner policies to grant `subagents/prompt` and/or `subagents/interruptByUser` on `{ kind: 'session', id: childId }`. Parent-to-child grants remain an explicit policy decision.
+4. Remove `parentSessionId` from `{ kind: 'user' }` interrupt authorities. Replace imports from `@deepseek-ai/dsh-subagent/internal`: authenticated user prompts use `subagents/prompt`; model-authored messages use `ctx.subagents.sendMessage()`. There is no public arbitrary-source host prompt adapter. Custom tools own their instructions through tool descriptions and `systemPrompt.context()`, without identity markers. Keep parent ids in history addresses and creation records.
+5. Verify that a target-authorized user can send and interrupt, while a user authorized only for the parent or global resource is refused before any input or cancellation is admitted.

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

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "子代理用户控制仅按目标 Session 寻址，重命名中断端点，并以目标 Session 权限替代 global 权限。"
+---
+
+# 子代理用户控制按目标 Session 寻址
+
+[English](guide.md) | 中文
+
+## 变更
+
+浏览器和自定义 Remote 调用方发送子代理提示词时，不再提供 `parentSessionId` 或 `mode`。`subagents/interruptByParent(childSessionId, parentSessionId, mode)` 替换为 `subagents/interruptByUser(childSessionId)`。创建祖先、历史地址、完成通知接收者和持久化 Session 数据保持不变。
+
+两个操作都将子会话声明为 `session` 访问资源。非 owner 策略必须授予该 Session 上对应操作的权限；`global` 绑定或父会话上的绑定不授予访问权。owner 行为保持不变。模型消息仍限于同一棵子代理树，模型中断仍仅允许祖先发起。
+
+同进程 `SubagentInterruptAuthority` 的用户分支为 `{ kind: 'user' }`。已发布的 `@deepseek-ai/dsh-subagent/internal` 入口已删除，包括宿主 prompt 适配器和工具身份标记。远程授权由 Gateway 执行。
+
+旧提示词载荷在 `request` 内多带字段时，可以在新 Host 上解码，但须满足新的访问规则。旧中断调用因端点已移除而失败。新调用方要求新 Host。自定义客户端和宿主应一起升级；内置 Web 客户端随 Host 一起交付。
+
+## 迁移
+
+1. 从子代理提示词请求中移除 `parentSessionId` 和 `mode`。保留 `childSessionId`、`requestId`、`delivery`、`content` 和可选的 `clientTimeZone`。
+2. 将 `interruptByParent(childId, parentId, 'continuable')` 调用替换为 `interruptByUser(childId)`。
+3. 更新非 owner 策略，在 `{ kind: 'session', id: childId }` 上授予 `subagents/prompt` 和／或 `subagents/interruptByUser` 权限。父会话到子会话的授权仍由策略显式决定。
+4. 从 `{ kind: 'user' }` 中断授权中移除 `parentSessionId`。替换 `@deepseek-ai/dsh-subagent/internal` 的导入：经过认证的用户 prompt 使用 `subagents/prompt`；模型编写的消息使用 `ctx.subagents.sendMessage()`。不再提供允许任意来源的公开宿主 prompt 适配器。自定义工具通过工具描述和 `systemPrompt.context()` 提供说明，无需身份标记。历史地址和创建记录仍保留父级 id。
+5. 验证获准操作目标的用户能够发送和中断，而仅获准操作父会话或 global 资源的用户在输入或取消被接纳前遭到拒绝。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/tool-executor-plugins/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/tool-executor-plugins/guide.md
+/:
+  en: 3b1ca9e0f78709e0
+  zh: 13f23adcc722f319
+/mount-a-tool-executor:
+  en: 73002a2963b9ea27
+  zh: a67ea382d7c70c61
+/mount-a-tool-executor/change:
+  en: fac0b27c9452c4f2
+  zh: 2f53fd013ff460ba
+/mount-a-tool-executor/migration:
+  en: 4d91c0177d06f4bd
+  zh: e93047b58a5aef4c

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/tool-executor-plugins/guide.md

@@ -0,0 +1,35 @@
+---
+kind: upgrade-guide
+description: "Tool execution modes move from dsh-tools configuration into explicit executor plugins."
+---
+
+# Mount a tool executor
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-tools` keeps tool registration and executor selection, but rejects the removed `mode` and `maxParallelSubCalls` configuration fields at load time. Native and PTC execution require `@deepseek-ai/dsh-tool-executor-native` or `@deepseek-ai/dsh-tool-executor-ptc`. Shipped profiles mount an executor; custom compositions must add one. The existing `dsh-agent-tool-presentation` selector remains supported but is deprecated. Enabled `tool-executor-native` and `tool-executor-ptc` rows are required at startup; invalid executor configuration now stops startup. Web, headless, and SDK no longer read `DSH_TOOLS_MODE`; all inherit native execution from base.
+
+## Migration
+
+1. Keep the `dsh-tools` row and remove its execution configuration. Mount one native or PTC executor in the intended deployment or preset scope. For shipped profile patches, target the executor row instead of the `tools` row.
+2. Move `maxParallelSubCalls` to the PTC executor configuration and mount a compatible `ctx.ptcRuntime` provider. The executor declares this service as a required injection; a missing runtime stops startup, and unloading the runtime withdraws the executor. `agent-loop.maxParallelToolCalls` and saved overrides stay in place with default `10`. The loop forwards the current limit to each batch; live edits apply to the next batch instead of the next tool group.
+3. Custom executors implement `describe` and `execute`. Programmatic callers pass raw `calls` and `signal`, optional `agent`, and optional `log: { turn, step }`; read single-call outcomes from `results`. Omit `log` outside a committed model step.
+4. Import PTC SDK renderers and `CodeRunFailedError` from `@deepseek-ai/dsh-tool-executor-ptc`. Run a task with the selected interaction mode and confirm its tool results appear in the Session.
+5. Import `ToolExecutionPipeline` and `executeToolBatch` from `@deepseek-ai/dsh-tools/pipeline`. Complete calls, including single calls, use batches; custom schedulers call `prepare`, `dispatch`, and `complete` directly. Add `@deepseek-ai/dsh-tool-testkit` as a development dependency for tool fixtures and import them from that package. Neither is exported by the tool registry entry.
+6. Import shared dispatch events and the `ptc-mode` message-source declaration from `@deepseek-ai/dsh-tool-executor-ptc/types`; Client code uses its `/client` re-export. Host policy extensions use `import type` from `@deepseek-ai/dsh-tool-executor-ptc` for `PtcDispatchLog` and `tools/ptc-dispatch-log`.
+
+7. Remove `DSH_TOOLS_MODE` from launch environments. For PTC, save the following as `ptc.yml` and pass it with `--patch`; native execution needs no overlay. The same patch works with `--profile web` and `--profile sdk`; TypeScript and Python SDK clients pass its path through `patches`. Confirm that the model receives only `run_code` in PTC mode.
+
+```yaml
+- id: tool-executor-native
+  disabled: true
+
+- id: tool-executor-ptc
+  disabled: false
+```
+
+```bash
+dsh --profile headless --patch ./ptc.yml "task"
+```

package/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/web-fetch-private-destinations/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/web-fetch-private-destinations/guide.md
+/:
+  en: 8d967f90aee1902e
+  zh: 30735df66cafe05d
+/web-fetch-reaches-private-destinations:
+  en: 8c157d5137d0a507
+  zh: 27cef187efdb1323
+/web-fetch-reaches-private-destinations/change:
+  en: bcbce3e213b81afc
+  zh: dda264a679117c36
+/web-fetch-reaches-private-destinations/migration:
+  en: e076bdd8bd132ee8
+  zh: 26d5da33ccc8e37c

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/webserver-index-peer/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/webserver-index-peer/guide.md
+/:
+  en: 4182112137303167
+  zh: 8451ce873cfca164
+/webserver-index-rendering-takes-a-peer:
+  en: 7986c2aaf1511f53
+  zh: a6f78fc166e1ea19
+/webserver-index-rendering-takes-a-peer/change:
+  en: 07a11388305a0124
+  zh: 662003b29c238d30
+/webserver-index-rendering-takes-a-peer/migration:
+  en: 7ef144b29ffb2f39
+  zh: defb62ecc4ba6c2e

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.3/attachment-read-access/guide.md
+/:
+  en: 1e002ad3fd9b1e79
+  zh: aeba3ee1e74fa2ae
+/image-read-requests-carry-the-complete-attachment-reference:
+  en: df690494e7cec0b8
+  zh: e21d937f2f305d8e
+/image-read-requests-carry-the-complete-attachment-reference/change:
+  en: cca17091c60b9757
+  zh: 8f300ab9d0b870d8
+/image-read-requests-carry-the-complete-attachment-reference/migration:
+  en: b593e623619ea508
+  zh: 41714f50a249f941

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.3/computer-use-helper-permissions/guide.md
+/:
+  en: 23336f139ca68e47
+  zh: 20ef9419a53642d5
+/authorize-the-computer-use-helper:
+  en: f8335f2dca7a15cf
+  zh: 469a0a753fea2a93
+/authorize-the-computer-use-helper/change:
+  en: 1552866718133b10
+  zh: 1c760c5c2d5cfc0b
+/authorize-the-computer-use-helper/migration:
+  en: 2a28385e24468734
+  zh: 725c1856a604bc0c

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.3/cua-bundle-id-consent/guide.md
+/:
+  en: af8e19ff73adbfbd
+  zh: 9daf099256b07409
+/macos-computer-use-application-identity:
+  en: d24696e5f85e9144
+  zh: 184f7ebd8b8880df
+/macos-computer-use-application-identity/change:
+  en: 7edc0de236633686
+  zh: 08afc35393c95484
+/macos-computer-use-application-identity/migration:
+  en: 9c13aeec5e544d36
+  zh: da697d3ee5a4637f

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.3/generated-worktree-names/guide.md
+/:
+  en: c799b94bab92d848
+  zh: 1e1f9cd572fc8665
+/update-consumers-of-generated-worktree-names:
+  en: 210bc140e21cc68e
+  zh: dccc592eec81f483
+/update-consumers-of-generated-worktree-names/change:
+  en: 7a7d682dde36dd7e
+  zh: b15e84c570d11ee2
+/update-consumers-of-generated-worktree-names/migration:
+  en: f87101bee9c48150
+  zh: 3a79159711475af3

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/inbox-only-agent-wait/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.3/inbox-only-agent-wait/guide.md
+/:
+  en: f09a5fde2cedb48c
+  zh: beec903a10ed62ee
+/agent-waits-require-inbox-input:
+  en: 96c9f5fc6514557a
+  zh: aac52f37d543ed9b
+/agent-waits-require-inbox-input/change:
+  en: 568583cb15f85337
+  zh: 6c7e3028f23d1f3e
+/agent-waits-require-inbox-input/migration:
+  en: 156a027d11ad3769
+  zh: 301029cecd3ae640