dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/fs-observation-policy-default-off/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "The fs-observation-policy row ships disabled, so write, edit, and apply_patch no longer require a prior read, and dsh-base plus the Web standard preset gain apply_patch."
+---
+
+# Filesystem mutations no longer require a prior read by default
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In 0.2.2-alpha.2, `dsh-base` mounted `@deepseek-ai/dsh-fs-observation-policy`, so in every base-backed profile `write` refused to overwrite a file the model had not read, `edit` refused an unread or externally changed file, and the model's guidance named the policy. The `fs-observation-policy` row now ships `disabled: true`: `write` overwrites, `edit` replaces literal text, and the new `apply_patch` applies hunks on context match alone, each unconditionally. The `write` and `edit` guidance still asks for a prior read but no longer cites the policy. Review capture, sandbox confinement, and `fs/observed` events are unchanged.
+
+The `dsh-base` `tool-fs` row (headless, SDK, and ACP) and the Web `standard` preset now list `apply_patch` (`applyPatch: true`); the Web `ptc` and `cordis` presets keep `applyPatch: false`.
+
+Affected: the base-backed profiles (`headless`, `web`, `sdk`, `acp`; `sdk-minimal` stacks no `dsh-base`, never mounted the policy, and keeps its text tools off), profile patches that override the `fs-observation-policy` or `tool-fs` rows by id, and recorded expectations that include an `FS_NOT_OBSERVED` or `FS_STALE_VERSION` refusal.
+
+## Migration
+
+1. To keep read-before-write behavior, add to the profile's `cordis.patch.yml` (`$DSH_HOME/profiles/<profile>/cordis.patch.yml`):
+
+   ```yaml
+   - id: fs-observation-policy
+     disabled: false
+   ```
+
+   A profile patch that already carries this row with `disabled: false` needs no change; one that set `disabled: true` to opt out can drop that override.
+2. To run without `apply_patch`, add `- {id: tool-fs, config: {applyPatch: false}}` to the profile's `cordis.patch.yml` for `headless`, `sdk`, and `acp` (the shipped [PTC overlay](../../../../apps/cli/config/examples/ptc.yml) already does so, matching the Web `ptc` preset); for the Web `standard` preset, edit it from the Agent presets settings page or set `applyPatch: false` on its `tool-fs` row in `packages/bundle/web-app/presets/standard.patch.yml`.
+3. Confirm with `dsh --profile <profile> --dump-config`: the `fs-observation-policy` row shows the intended `disabled` value, and the `tool-fs` rows show the intended `applyPatch` value. In a session, an `edit` of a file that was not read succeeds with the row disabled and fails with `FS_NOT_OBSERVED` with it enabled.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/fs-observation-policy-default-off/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "fs-observation-policy 行随发行版禁用，write、edit 与 apply_patch 不再要求先读，dsh-base 与 Web standard preset 新增 apply_patch。"
+---
+
+# 文件系统修改默认不再要求先读
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 0.2.2-alpha.2 中，`dsh-base` 挂载了 `@deepseek-ai/dsh-fs-observation-policy`，因此所有叠加 base 的 profile 中，`write` 拒绝覆盖模型未读过的文件，`edit` 拒绝未读或被外部修改的文件，模型提示语也点名该策略。现在 `fs-observation-policy` 行以 `disabled: true` 交付：`write` 直接覆盖，`edit` 直接替换字面文本，新增的 `apply_patch` 只凭上下文匹配应用 hunk，三者均无条件执行。`write` 与 `edit` 的提示语仍要求先读，但不再引用该策略。Review 采集、沙箱围栏与 `fs/observed` 事件不变。
+
+`dsh-base` 的 `tool-fs` 行（headless、SDK、ACP）与 Web 的 `standard` preset 现在列出 `apply_patch`（`applyPatch: true`）；Web 的 `ptc`、`cordis` preset 保持 `applyPatch: false`。
+
+受影响范围：叠加 base 的 profile（`headless`、`web`、`sdk`、`acp`；`sdk-minimal` 不叠加 `dsh-base`，从未挂载该策略，文本工具保持关闭），按 id 覆盖 `fs-observation-policy` 或 `tool-fs` 行的 profile patch，以及包含 `FS_NOT_OBSERVED` 或 `FS_STALE_VERSION` 拒绝的录制期望。
+
+## 迁移
+
+1. 要保留先读后写行为，在 profile 的 `cordis.patch.yml`（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）中加入：
+
+   ```yaml
+   - id: fs-observation-policy
+     disabled: false
+   ```
+
+   已带有该行且 `disabled: false` 的 profile patch 无需改动；为退出策略而写 `disabled: true` 的可以删掉该覆盖。
+2. 要在没有 `apply_patch` 的情况下运行，为 `headless`、`sdk`、`acp` 在 profile 的 `cordis.patch.yml` 中加入 `- {id: tool-fs, config: {applyPatch: false}}`（随发行版交付的 [PTC overlay](../../../../apps/cli/config/examples/ptc.yml) 已这样做，与 Web `ptc` preset 一致）；对 Web `standard` preset，在 Agent presets 设置页编辑它，或在 `packages/bundle/web-app/presets/standard.patch.yml` 的 `tool-fs` 行上设置 `applyPatch: false`。
+3. 用 `dsh --profile <profile> --dump-config` 确认：`fs-observation-policy` 行显示预期的 `disabled` 值，`tool-fs` 行显示预期的 `applyPatch` 值。在会话中，行禁用时对未读文件执行 `edit` 成功，启用时以 `FS_NOT_OBSERVED` 失败。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/llm-error-builtin-codes/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "`new LlmError` accepts only built-in failure codes; other codes go through `LlmError.fromFailure`."
+---
+
+# `new LlmError` accepts only built-in failure codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In `@deepseek-ai/dsh-llm`, the `code` parameter of the `LlmError` constructor was `string` and is now `BuiltinLlmFailureCode`: a key of `LLM_FAILURE_CODES` or `HTTP_<status>`. Runtime behavior and `LlmFailure.code` are unchanged. TypeScript code that constructs `LlmError` with any other code, such as an out-of-tree provider adapter or a test double, no longer compiles.
+
+## Migration
+
+1. Replace each `new LlmError(message, code, options)` whose `code` is not built-in with `LlmError.fromFailure({ message, code, ...facts }, { cause })`, where `facts` holds any `status`, `providerRetryAfterMs`, `requestId`, or `offloadImages`.
+2. Re-raise a failure received from a stream with `LlmError.fromFailure(finish.failure)` instead of passing `finish.failure.code` to the constructor.
+3. Confirm with `tsc` that no `LlmError` construction reports a code that is not assignable to `BuiltinLlmFailureCode`.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/llm-error-builtin-codes/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "`new LlmError` 只接受内置失败 code；其他 code 改用 `LlmError.fromFailure`。"
+---
+
+# `new LlmError` 只接受内置失败 code
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 `@deepseek-ai/dsh-llm` 中，`LlmError` 构造函数的 `code` 参数原为 `string`，现为 `BuiltinLlmFailureCode`：`LLM_FAILURE_CODES` 的键或 `HTTP_<status>`。运行时行为和 `LlmFailure.code` 不变。用其他 code 构造 `LlmError` 的 TypeScript 代码（例如仓库外的提供方适配器或测试替身）将无法通过编译。
+
+## 迁移
+
+1. 把每个 `code` 不是内置值的 `new LlmError(message, code, options)` 改为 `LlmError.fromFailure({ message, code, ...facts }, { cause })`，其中 `facts` 包含需要的 `status`、`providerRetryAfterMs`、`requestId` 或 `offloadImages`。
+2. 重新抛出从流中收到的失败时，使用 `LlmError.fromFailure(finish.failure)`，而不是把 `finish.failure.code` 传给构造函数。
+3. 用 `tsc` 确认没有任何 `LlmError` 构造报告 code 不能赋值给 `BuiltinLlmFailureCode`。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "Auxiliary LLM request purposes require producer-owned type declarations instead of a shared fixed union."
+---
+
+# Declare auxiliary LLM request purposes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`GenerateOptions.purpose` derives from the declaration-mergeable `LlmRequestPurposeMap` exported by `@deepseek-ai/dsh-llm/types`. The shared package no longer declares `compaction` or `session-title`. Plugins that construct auxiliary requests must load the producer's declarations or declare their own purpose. Existing runtime purpose strings keep their meaning.
+
+## Migration
+
+1. Import `@deepseek-ai/dsh-compaction-basic` for direct compaction requests, or `@deepseek-ai/dsh-session-title-llm` for title requests, using a type-only import when only the declaration is needed.
+2. For a plugin-owned purpose, augment `LlmRequestPurposeMap` from the plugin's public type entry. Map the purpose key to `true`:
+
+   ```ts
+   import type {} from '@deepseek-ai/dsh-llm/types'
+
+   declare module '@deepseek-ai/dsh-llm/types' {
+     interface LlmRequestPurposeMap {
+       'my-plugin-purpose': true
+     }
+   }
+   ```
+
+3. Compile the plugin against the new package declarations. Confirm that its request accepts the declared purpose and rejects an undeclared key.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "辅助 LLM 请求用途改为生产方拥有的类型声明，不再使用共享固定联合。"
+---
+
+# 声明辅助 LLM 请求用途
+
+[English](guide.md) | 中文
+
+## 变更
+
+`GenerateOptions.purpose` 由 `@deepseek-ai/dsh-llm/types` 导出的可声明合并的 `LlmRequestPurposeMap` 派生。共享包不再声明 `compaction` 或 `session-title`。构造辅助请求的插件必须加载生产方的声明，或声明自己的用途。现有运行时用途字符串保持原有含义。
+
+## 迁移
+
+1. 直接构造压缩请求时导入 `@deepseek-ai/dsh-compaction-basic`，构造标题请求时导入 `@deepseek-ai/dsh-session-title-llm`；只需要声明时使用仅类型导入。
+2. 对插件拥有的用途，在插件公开类型入口中扩展 `LlmRequestPurposeMap`，将用途键映射到 `true`：
+
+   ```ts
+   import type {} from '@deepseek-ai/dsh-llm/types'
+
+   declare module '@deepseek-ai/dsh-llm/types' {
+     interface LlmRequestPurposeMap {
+       'my-plugin-purpose': true
+     }
+   }
+   ```
+
+3. 使用新包的声明编译插件，确认请求接受已声明用途，并拒绝未声明的键。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/pi-ai-request-image-count/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "pi-ai routes now offload the oldest history images once a request carries more than 50 retained images."
+---
+
+# pi-ai request image count
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`llm-pi-ai` previously bounded request images only by `maxRequestImageBytes`, so every retained image was resent until that byte bound was reached. Each provider route now also has `maxRequestImages` (default 50) and `imageOffloadCountQuantum` (default 10). When a request carries more retained images than `maxRequestImages`, `dsh-compaction-image-offload` replaces the oldest `imageOffloadCountQuantum` images with placeholder text and retries. The omission is recorded in the Session and does not revert. This affects Sessions with more than 50 images on any pi-ai route, including providers that accept more images per request.
+
+## Migration
+
+1. Check the per-request image limit of each pi-ai provider. In the `llm-pi-ai` configuration in `cordis.patch.yml`, set `providers.<provider>.maxRequestImages` to that limit when it is higher than 50.
+2. To change how many images one overflow offloads, set `providers.<provider>.imageOffloadCountQuantum`; it must not exceed `maxRequestImages`.
+3. Reopen the profile configuration and confirm the saved values. See the [provider configuration reference](../../../../packages/llm/llm-pi-ai/README.md).

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/pi-ai-request-image-count/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "当请求保留的图片超过 50 张时，pi-ai 路由现在会省略历史中最老的图片。"
+---
+
+# pi-ai 请求图片数量
+
+[English](guide.md) | 中文
+
+## 变更
+
+`llm-pi-ai` 原先只用 `maxRequestImageBytes` 限制请求图片，因此在达到该字节上限前会重发每张保留图片。现在每条提供方路由还有 `maxRequestImages`（默认 50）和 `imageOffloadCountQuantum`（默认 10）。请求保留的图片多于 `maxRequestImages` 时，`dsh-compaction-image-offload` 把最老的 `imageOffloadCountQuantum` 张图片替换为占位文本并重试。该省略记录在 Session 中，不会回退。这会影响任何 pi-ai 路由上超过 50 张图片的 Session，包括单次请求接受更多图片的提供方。
+
+## 迁移
+
+1. 核对每个 pi-ai 提供方的单次请求图片上限。上限高于 50 时，在 `cordis.patch.yml` 的 `llm-pi-ai` 配置中把 `providers.<provider>.maxRequestImages` 设为该上限。
+2. 如需改变每次超限省略的图片数，设置 `providers.<provider>.imageOffloadCountQuantum`；它不得超过 `maxRequestImages`。
+3. 重新打开 profile 配置，确认保存的数值。参见[提供方配置参考](../../../../packages/llm/llm-pi-ai/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/projection-event-frames/guide.md

@@ -0,0 +1,32 @@
+---
+kind: upgrade-guide
+description: "Live Session projection frames list every key one committed event changed instead of carrying one key each."
+---
+
+# Projection frames list every key one event changed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Live `projection` frames on the `session/control` stream and change frames on the `session/observeProjections` stream carried one projection key each: `{ type: 'projection', sessionId, key, value, seq }`. An event that changed several keys produced several frames with the same `seq`. Each frame now carries every key one committed event changed: `{ type: 'projection', sessionId, seq, changes }` on `session/control`, and the same fields without `sessionId` on `session/observeProjections`. `changes` holds one `{ key, val }` entry per changed key, without duplicate keys, where `val` is the key's new value. A key absent from `changes` is unchanged. The exported types `SessionProjectionUpdate`, `SessionProjectionChange`, `SessionControlFrame`, and `SessionProjectionFrame` of `@deepseek-ai/dsh-api-session-controller` follow the new fields.
+
+Baseline frames, `session/projections` reads, and the Host listener `ctx.sessionProjections.onChanged` keep their behavior. The Host adds `ctx.sessionProjections.onEventChanged` for one call per committed event.
+
+This affects Remote clients that read either stream directly, such as test harnesses, proxies, and external dashboards. The bundled Web client and `@deepseek-ai/dsh-api-session-controller/client` read the new frames.
+
+## Migration
+
+1. Replace a call such as `apply(frame.key, frame.value, frame.seq)` with a loop over `frame.changes`:
+
+   ```ts
+   import type { SessionControlFrame } from '@deepseek-ai/dsh-api-session-controller'
+
+   declare const frame: Extract<SessionControlFrame, { type: 'projection' }>
+   declare function apply(key: string, value: unknown, seq: number): void
+
+   for (const change of frame.changes) apply(change.key, change.val, frame.seq)
+   ```
+
+2. Replace key tests such as `frame.key === 'inbox'` with `frame.changes.find(change => change.key === 'inbox')`, and read the value from that entry's `val`.
+3. Confirm that one committed event yields at most one `projection` frame per Session, and that the values your client holds match a fresh `session/projections` read.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/projection-event-frames/guide.zh.md

@@ -0,0 +1,32 @@
+---
+kind: upgrade-guide
+description: "实时 Session projection 帧改为列出一个已提交事件改变的全部 key，不再每帧只带一个 key。"
+---
+
+# Projection 帧列出一个事件改变的全部 key
+
+[English](guide.md) | 中文
+
+## 变更
+
+`session/control` 流上的实时 `projection` 帧与 `session/observeProjections` 流上的变更帧，原先每帧只带一个 projection key：`{ type: 'projection', sessionId, key, value, seq }`。一个事件改变多个 key 时，会产生多帧 `seq` 相同的帧。现在每帧携带一个已提交事件改变的全部 key：`session/control` 上是 `{ type: 'projection', sessionId, seq, changes }`，`session/observeProjections` 上是去掉 `sessionId` 的同样字段。`changes` 中每个变化的 key 一项 `{ key, val }`，key 不重复，`val` 是该 key 的新值。未出现在 `changes` 中的 key 没有变化。`@deepseek-ai/dsh-api-session-controller` 导出的 `SessionProjectionUpdate`、`SessionProjectionChange`、`SessionControlFrame` 与 `SessionProjectionFrame` 类型随新字段更新。
+
+baseline 帧、`session/projections` 读取以及 Host 监听器 `ctx.sessionProjections.onChanged` 的行为不变。Host 新增 `ctx.sessionProjections.onEventChanged`，按每个已提交事件调用一次。
+
+受影响的是直接读取这两条流的 Remote 客户端，例如测试 harness、代理和外部看板。内置 Web 客户端与 `@deepseek-ai/dsh-api-session-controller/client` 已读取新帧。
+
+## 迁移
+
+1. 把 `apply(frame.key, frame.value, frame.seq)` 这类调用改为遍历 `frame.changes`：
+
+   ```ts
+   import type { SessionControlFrame } from '@deepseek-ai/dsh-api-session-controller'
+
+   declare const frame: Extract<SessionControlFrame, { type: 'projection' }>
+   declare function apply(key: string, value: unknown, seq: number): void
+
+   for (const change of frame.changes) apply(change.key, change.val, frame.seq)
+   ```
+
+2. 把 `frame.key === 'inbox'` 这类 key 判断改为 `frame.changes.find(change => change.key === 'inbox')`，并从该项的 `val` 读取值。
+3. 确认一个已提交事件对每个 Session 至多产生一个 `projection` 帧，且客户端持有的值与重新调用 `session/projections` 读到的一致。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/projection-released-checkpoint/guide.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "`ctx.sessionProjections.checkpoint(session)` keeps a released unit's last row instead of omitting it."
+---
+
+# Released projection units stay in checkpoints
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Previously, when the last registrant of a projection key released it, through `handle.dispose()` or by unloading the owning fiber, the registry deleted the unit and `ctx.sessionProjections.checkpoint(session)` stopped returning its row.
+
+Now the released unit stays in the registry as a predecessor. It leaves event drives, `snapshot()`, `summaryKeys()`, `restoreFloor()`, `restore()`, `viewCheckpoint()`, and `hydrate()`, and Sessions created afterward get no cell for it. `checkpoint(session)` still returns the last row the unit folded for each existing Session, and the registry no longer advances that row. Registering the same key again replaces the predecessor and refolds the log; see the [registration lifecycle](../../../../packages/session/session-projection/README.md).
+
+This affects plugin code and tests that read `checkpoint()` after a projection's owner unloads, such as HMR tests that assert a released key is absent. `@deepseek-ai/dsh-session-projection-cache` stores these rows, so a graceful shutdown no longer drops the values that Web-layer plugins folded before their Sessions detach.
+
+## Migration
+
+1. Find reads of `sessionProjections.checkpoint(...)` that run after a projection's owner unloads, including calls through an alias of `ctx.sessionProjections`.
+2. Replace an assertion that the released key is absent from an existing Session with one that its row keeps the pre-unload value:
+
+   ```ts ignore-check
+   const row = ctx.sessionProjections.checkpoint(session).myKey
+   await owner.dispose()
+   expect(ctx.sessionProjections.checkpoint(session)).toHaveProperty('myKey', row)
+   ```
+
+3. To show that the unit left live participation, assert that a Session created after the unload has no row, `expect(ctx.sessionProjections.checkpoint(ctx.sessions.create())).not.toHaveProperty('myKey')`, or that an event appended after the unload leaves the row unchanged. A client-visible key is also absent from `snapshot(session).values`.
+4. Run the affected tests; they pass when no assertion expects a released key to disappear from an existing Session's checkpoint.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/projection-released-checkpoint/guide.zh.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "`ctx.sessionProjections.checkpoint(session)` 保留已释放单元的最后一行，而不再省略它。"
+---
+
+# 已释放的投影单元保留在检查点中
+
+[English](guide.md) | 中文
+
+## 变更
+
+此前，投影 key 的最后一个注册方通过 `handle.dispose()` 或卸载所属 fiber 释放它时，注册表会删除该单元，`ctx.sessionProjections.checkpoint(session)` 也不再返回它的行。
+
+现在，已释放的单元作为前任留在注册表中。它退出事件推进、`snapshot()`、`summaryKeys()`、`restoreFloor()`、`restore()`、`viewCheckpoint()` 和 `hydrate()`，此后新建的 Session 也不会为它建立 cell。`checkpoint(session)` 仍为每个已有 Session 返回该单元最后折叠出的行，注册表不再推进这一行。同一 key 再次注册时会替换前任并重新折叠日志；参见[注册生命周期](../../../../packages/session/session-projection/README.zh.md)。
+
+这会影响在投影所属方卸载后读取 `checkpoint()` 的插件代码和测试，例如断言已释放 key 不存在的 HMR 测试。`@deepseek-ai/dsh-session-projection-cache` 会存储这些行，因此正常关停不再丢掉 Web 层插件在其 Session detach 之前已折叠出的值。
+
+## 迁移
+
+1. 找出在投影所属方卸载后执行的 `sessionProjections.checkpoint(...)` 读取，包括通过 `ctx.sessionProjections` 别名的调用。
+2. 把「已有 Session 中不存在已释放 key」的断言，改为断言它的行保持卸载前的值：
+
+   ```ts ignore-check
+   const row = ctx.sessionProjections.checkpoint(session).myKey
+   await owner.dispose()
+   expect(ctx.sessionProjections.checkpoint(session)).toHaveProperty('myKey', row)
+   ```
+
+3. 如需证明该单元已退出实时参与，可断言卸载后新建的 Session 没有这一行，即 `expect(ctx.sessionProjections.checkpoint(ctx.sessions.create())).not.toHaveProperty('myKey')`，或断言卸载后追加的事件不会改变这一行。客户端可见的 key 也不会出现在 `snapshot(session).values` 中。
+4. 运行受影响的测试；当没有断言要求已释放 key 从已有 Session 的检查点中消失时，测试即通过。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/projection-snapshot-scope/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Projection snapshot reads compute only the returned units, the registry cached snapshot read is deprecated, and Session list summaries omit context pressure and breakdown."
+---
+
+# Projection snapshot scope
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ctx.sessionProjections.snapshot(session, keys)` from `@deepseek-ai/dsh-session-projection` computes only the units it returns: with `keys` it computes only the selected units, and without `keys` it computes every unit that defines `wire` and no Host-only unit. A plugin can no longer rely on other units being computed after it calls `snapshot`. The registry's `cachedSnapshot(session, keys)` is deprecated; it returns only values another read already computed and may omit keys. The persisted cache read `ctx.sessionProjectionCache.cachedSnapshot(header, keys)` is unchanged. `session.list` summary `projections` no longer carry `contextBreakdown` or `contextPressure`; the `@deepseek-ai/dsh-token-meter` entries are now `SessionProjectionSummaryExcluded`. Plugins and SDK or wire clients that read these values are affected.
+
+## Migration
+
+1. Read Host state of your own unit through the handle that `await ctx.sessionProjections.register(definition)` returns, with `handle.stateOf(session)`, instead of calling `snapshot` first and reading cells afterwards.
+2. Replace calls to the registry's `cachedSnapshot(session, keys)` with `snapshot(session, keys)`.
+3. Read `contextBreakdown` and `contextPressure` from an opened Session, for example the Session projection snapshot or follow baseline, instead of from `session.list` rows.
+4. Rebuild your plugins and clients, confirm that type checks pass without `no-deprecated` findings for `cachedSnapshot`, and confirm that an opened Session still shows its context meter.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/projection-snapshot-scope/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "投影 snapshot 读取只计算返回的单元，注册表的 cached snapshot 读取已废弃，Session 列表摘要不再包含 context pressure 和 breakdown。"
+---
+
+# 投影 snapshot 的计算范围
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-projection` 的 `ctx.sessionProjections.snapshot(session, keys)` 只计算它返回的单元：传 `keys` 时只计算选中的单元，不传时计算每个定义了 `wire` 的单元、不计算 Host 专用单元。插件不能再依赖调用 `snapshot` 之后其他单元已经算好。注册表的 `cachedSnapshot(session, keys)` 已废弃，它只返回其他读取已经算好的值，可能缺少 key。持久化缓存的读取 `ctx.sessionProjectionCache.cachedSnapshot(header, keys)` 不变。`session.list` 摘要的 `projections` 不再携带 `contextBreakdown` 和 `contextPressure`，`@deepseek-ai/dsh-token-meter` 的这两项改为 `SessionProjectionSummaryExcluded`。读取这些值的插件以及 SDK 或 wire 客户端受影响。
+
+## 迁移
+
+1. 通过 `await ctx.sessionProjections.register(definition)` 返回的句柄，用 `handle.stateOf(session)` 读取自己单元的 Host 状态，不要先调用 `snapshot` 再读取 cell。
+2. 把对注册表 `cachedSnapshot(session, keys)` 的调用替换为 `snapshot(session, keys)`。
+3. 从打开的 Session 读取 `contextBreakdown` 和 `contextPressure`，例如 Session 投影 snapshot 或 follow 基线，不要从 `session.list` 行读取。
+4. 重新构建插件和客户端，确认类型检查通过、`cachedSnapshot` 没有 `no-deprecated` 告警，并确认打开的 Session 仍显示上下文用量。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/retained-ptc-timeout/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Retained Node PTC uses cooperative stop on timeout or cancellation, with process termination when acknowledgment fails."
+---
+
+# Retained PTC timeout recovery
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Timeouts and cancellation in `persistent-in-memory` mode and `vm-script` with `scriptPersistence: true` request cooperative stop. Previously, they always cleared the environment. Canceled tool calls throw, allowing `catch` and `finally` to run. Stop acknowledgment waits for the evaluation to settle and preserves variables and earlier mutations. The host waits up to `stopGraceMs` (default `3000`) for acknowledgment, then terminates the managed process range if acknowledgment is missing or fails. A blocked loop therefore still loses state. Temporary execution continues to terminate its process.
+
+The runtime returns after acknowledgment or fallback cleanup, with the original `timeout` or `abort` kind and a diagnostic stating whether variables survived. Confirmed termination allows the next call to create an empty environment. Failed cleanup returns `worker-exit` and blocks reuse until host release succeeds. Timers, arbitrary user Promises, I/O callbacks, Workers and subprocesses have no per-evaluation cancellation guarantee; acknowledgment does not mean all Node activity has stopped.
+
+## Migration
+
+1. Check the reported state outcome instead of assuming that timeout or cancellation clears variables. Reuse retained bindings; recreate them after fallback termination. Earlier effects are not rolled back.
+2. Use the host's `PtcExecutor.reset(agent)` or runtime `release(owner)` if cleanup failed or retained resources cannot be trusted. No reset tool is exposed to the model. Await reset before running more code.
+3. Set `stopGraceMs` in the `@deepseek-ai/dsh-ptc-runtime-node` configuration if needed. It bounds acknowledgment separately from the existing process-cleanup `graceMs`. Verify that an asynchronous wait preserves an earlier variable and a blocked loop clears it. See the [runtime reference](../../../../packages/ptc-runtime/ptc-runtime-node/README.md).
+4. When `launch.bootstrapPath` points to a separately installed Node bootstrap, upgrade it with the host. Readiness checks the protocol revision before dispatch; an older bootstrap reports `bootstrap protocol mismatch` instead of running code.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/retained-ptc-timeout/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "保留状态的 Node PTC 在超时或取消时协作式停止，确认失败时终止进程兜底。"
+---
+
+# 保留状态的 PTC 超时恢复
+
+[English](guide.md) | 中文
+
+## 变更
+
+`persistent-in-memory` 模式及启用 `scriptPersistence: true` 的 `vm-script` 在超时或取消时请求协作式停止。此前这两种情况总会清空环境；现在取消的工具调用正常抛错，允许 `catch` 和 `finally` 运行。停止确认等待本次执行结束，并保留变量及此前修改。宿主最多等待 `stopGraceMs`（默认 `3000`）取得确认，未收到确认或确认失败时终止受管进程范围。因此阻塞的死循环仍会丢失状态。临时执行仍终止进程。
+
+运行时在收到确认或兜底清理完成后返回，保留原来的 `timeout` 或 `abort` 类型，并在诊断中说明变量是否保留。确认终止后，下一次调用可创建空环境。清理失败返回 `worker-exit`，并阻止复用，直到宿主释放成功。定时器、任意用户 Promise、I/O 回调、Worker 和子进程不承诺按执行取消；收到确认不表示所有 Node 活动均已停止。
+
+## 迁移
+
+1. 检查报告的状态结果，不再假定超时或取消会清空变量。复用保留的绑定；兜底终止后重新创建。此前的效果不会回滚。
+2. 清理失败或保留资源不可信时，使用宿主的 `PtcExecutor.reset(agent)` 或运行时 `release(owner)`。模型不会获得重置工具。等待重置完成后再执行代码。
+3. 按需在 `@deepseek-ai/dsh-ptc-runtime-node` 配置中设置 `stopGraceMs`。它限制确认等待时间，与现有进程清理的 `graceMs` 独立。验证异步等待会保留此前变量，阻塞的死循环会清空变量。参阅[运行时参考](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md)。
+4. 如果 `launch.bootstrapPath` 指向单独安装的 Node bootstrap，随宿主一起升级它。派发前的就绪握手会检查协议版本；旧 bootstrap 报告 `bootstrap protocol mismatch`，不会执行代码。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/schedule-agent-tools/guide.md

@@ -0,0 +1,37 @@
+---
+kind: upgrade-guide
+description: "The Schedule model tools become `schedule_create`, `schedule_list`, `schedule_view`, and `schedule_edit` over every Host task, and `schedule_update` and `schedule_delete` are removed."
+---
+
+# Schedule tools manage every Host task by RRULE and target
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Earlier, `@deepseek-ai/dsh-tool-schedule` registered `schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete`. They managed only the reminders of the calling Session, and `schedule_create` took one timing selector: `after_seconds`, `at`, `every_seconds`, `daily`, `weekly`, or `cron`.
+
+The package now registers `schedule_create`, `schedule_list`, `schedule_view`, and `schedule_edit`:
+
+- `schedule_create` takes `title`, `prompt`, `rrule` (one `DTSTART` line and one `RRULE` line), and `target` (`this_session`, `new_once`, or `new`). It accepts no timing selector.
+- `schedule_list` returns one page `{ items, shown, total, limit, offset }` of active, paused, and ended tasks instead of an array of active reminders.
+- `schedule_view` reads one task by id.
+- `schedule_edit` with `action: "update"` replaces `schedule_update` and can also change `rrule` and `target` or pause and resume a task; `action: "delete"` replaces `schedule_delete`.
+- Each tool reads, changes, and deletes any Host task by id, not only the tasks of the calling Session.
+- A call from a delegated subagent returns `subagent_session` with the message `A delegated subagent cannot use scheduled tasks.`
+
+Existing reminders keep their timing and delivery. Recorded Sessions keep their earlier calls and results, and the Web transcript still renders them.
+
+This affects:
+
+- prompts, skills, and scripts that tell a model to call `schedule_update`, `schedule_delete`, or a timing selector;
+- deployments that rely on each Session seeing only its own reminders;
+- TypeScript code that imports `scheduleView` from the root entry, or `ScheduleView`, `ScheduleState`, `ScheduleDeliveryMode`, `ScheduleCreateValue`, `ScheduleListValue`, `ScheduleDeleteRequest`, `ScheduleDeleteValue`, `ScheduleTimingChange`, `ScheduleUpdateContent`, `ScheduleUpdateMiss`, `ScheduleUpdateRequest`, `ScheduleUpdateResult`, or `ScheduleUpdateValue` from the root or `/client` entry of `@deepseek-ai/dsh-schedule`.
+
+## Migration
+
+1. In prompts, skills, and scripts, replace `schedule_update` and `schedule_delete` with `schedule_edit`, replace each timing selector with an RRULE, and supply the required `target` on creation. For example, `daily: { time: "09:00:00", time_zone: "Asia/Shanghai" }` becomes `rrule: "DTSTART;TZID=Asia/Shanghai:20261013T090000\nRRULE:FREQ=DAILY"`; use `target: "this_session"` to keep delivery in the calling Session.
+2. If the agents of a preset must not manage the tasks of other Sessions, remove the `@deepseek-ai/dsh-tool-schedule` row from that preset.
+3. In TypeScript code, use `ScheduleCreateRequest`, `ScheduleTiming`, `SchedulePatch`, and `ScheduleEditRequest` for writes, and `ScheduleViewResult`, `ScheduleListResult`, and `ScheduleEditResult` for reads and edits. Call `ScheduleService.view`, paged `list`, and `edit` instead of `scheduleView`, `update`, and `delete`. `ScheduleDeleteResult`, `ScheduleDeleteChange`, and `ScheduleDeleteInactiveResult` remain exported from the root and `/client`; the old request/value types above do not. The [Schedule service README](../../../../packages/schedule/schedule/README.md) describes these APIs.
+4. Custom compositions must provide both `tools` and `systemPrompt` before mounting this consumer; registration also waits for `schedule`. The `tool:schedule` section supplies the shared authorization instruction. A `complete: true` prompt override must include that instruction itself.
+5. Open a Session under each changed preset and confirm that its tool list shows the four tool names. Delegate a task and confirm that a Schedule tool call from the child returns `subagent_session`; the child's tool list includes the four names, as [Configure subagent composition through presets](../../v0.2.1-alpha.1/subagent-preset-composition/guide.md) describes.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/schedule-agent-tools/guide.zh.md

@@ -0,0 +1,37 @@
+---
+kind: upgrade-guide
+description: "Schedule 的模型工具改为面向宿主全部任务的 `schedule_create`、`schedule_list`、`schedule_view` 与 `schedule_edit`，并移除 `schedule_update` 与 `schedule_delete`。"
+---
+
+# Schedule 工具按 RRULE 与目标管理宿主的全部任务
+
+[English](guide.md) | 中文
+
+## 变更
+
+较早时，`@deepseek-ai/dsh-tool-schedule` 注册 `schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete`。它们只管理调用方 Session 的提醒，`schedule_create` 接受一个时间选择参数：`after_seconds`、`at`、`every_seconds`、`daily`、`weekly` 或 `cron`。
+
+现在本包注册 `schedule_create`、`schedule_list`、`schedule_view` 与 `schedule_edit`：
+
+- `schedule_create` 接受 `title`、`prompt`、`rrule`（一行 `DTSTART` 与一行 `RRULE`）和 `target`（`this_session`、`new_once` 或 `new`）。它不接受任何时间选择参数。
+- `schedule_list` 返回一页 `{ items, shown, total, limit, offset }`，包含活动、暂停与已结束的任务，而不是活动提醒的数组。
+- `schedule_view` 按 id 读取一个任务。
+- 带 `action: "update"` 的 `schedule_edit` 取代 `schedule_update`，并且还能改变 `rrule` 与 `target`，或暂停与恢复任务；`action: "delete"` 取代 `schedule_delete`。
+- 每个工具都按 id 读取、改变和删除宿主的任意任务，而不只是调用方 Session 的任务。
+- 被委派的子 agent 发起的调用返回 `subagent_session`，消息为 `A delegated subagent cannot use scheduled tasks.`
+
+已有提醒保留其时间规则与投递方式。已录制的 Session 保留较早的调用与结果，Web transcript 仍会渲染它们。
+
+受影响的对象：
+
+- 让模型调用 `schedule_update`、`schedule_delete` 或某个时间选择参数的提示词、skill 与脚本；
+- 依赖“每个 Session 只看到自己的提醒”的部署；
+- 从 `@deepseek-ai/dsh-schedule` 根入口导入 `scheduleView`，或从根入口或 `/client` 入口导入 `ScheduleView`、`ScheduleState`、`ScheduleDeliveryMode`、`ScheduleCreateValue`、`ScheduleListValue`、`ScheduleDeleteRequest`、`ScheduleDeleteValue`、`ScheduleTimingChange`、`ScheduleUpdateContent`、`ScheduleUpdateMiss`、`ScheduleUpdateRequest`、`ScheduleUpdateResult` 或 `ScheduleUpdateValue` 的 TypeScript 代码。
+
+## 迁移
+
+1. 在提示词、skill 与脚本中，把 `schedule_update` 与 `schedule_delete` 替换为 `schedule_edit`，把每个时间选择参数替换为 RRULE，并在创建时提供必填的 `target`。例如，`daily: { time: "09:00:00", time_zone: "Asia/Shanghai" }` 变为 `rrule: "DTSTART;TZID=Asia/Shanghai:20261013T090000\nRRULE:FREQ=DAILY"`；使用 `target: "this_session"` 将投递保留在调用方 Session。
+2. 如果某个 preset 的 agent 不应管理其他 Session 的任务，从该 preset 中移除 `@deepseek-ai/dsh-tool-schedule` 这一行。
+3. 在 TypeScript 代码中，写入使用 `ScheduleCreateRequest`、`ScheduleTiming`、`SchedulePatch` 和 `ScheduleEditRequest`，读取与编辑结果使用 `ScheduleViewResult`、`ScheduleListResult` 和 `ScheduleEditResult`。调用 `ScheduleService.view`、分页的 `list` 和 `edit`，替换 `scheduleView`、`update` 和 `delete`。根入口与 `/client` 仍导出 `ScheduleDeleteResult`、`ScheduleDeleteChange` 和 `ScheduleDeleteInactiveResult`，但不再导出上述旧请求／结果值类型。[Schedule 服务 README](../../../../packages/schedule/schedule/README.zh.md) 描述了这些 API。
+4. 自定义组合须先提供 `tools` 和 `systemPrompt`，再挂载此消费者；注册还会等待 `schedule`。`tool:schedule` 区段提供共用授权指令。使用 `complete: true` 的提示词覆盖时，须自行保留该指令。
+5. 在每个改动过的 preset 下打开一个 Session，确认其工具列表显示这四个工具名。委派一个任务，确认子 agent 调用 Schedule 工具时返回 `subagent_session`；子 agent 的工具列表包含这四个工具名，详见[通过 preset 配置子 Agent 组装](../../v0.2.1-alpha.1/subagent-preset-composition/guide.zh.md)。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/schedule-remote-host-tasks/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Schedule clients use one Host-wide management API and typed timing records; stored Host tasks keep the existing domain and layout."
+---
+
+# Schedule uses one Host-wide management API
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Schedule management addresses every Host task by id. The native and Remote APIs share one service; the previous Session-bound `delete` and `update` methods are removed. Native creation takes a typed `timing`, and catalog results discriminate After, At, Every, Daily, Weekly, Cron, and RRULE with `kind`.
+
+The existing `schedule` domain writes version 2 and reads version 1 without startup writes, retaining its route, envelope, and layout. SQLite's physical schema stays at version 1. Back up the store before upgrading: the first successful v2 write stamps the unit v2, which a v1 binary refuses to open. Downgrade requires restoring that backup. Edits and delivery save current rows without a separate migration command. The plugin README owns the [stored schema, upgrade timing, and costs](../../../../packages/schedule/schedule/README.md#storage-format).
+
+## Migration
+
+1. Native callers use `create({ title, prompt, timing, target? }, actorSessionId?, signal?)` and `edit(request, actorSessionId?, signal?)`. Remote callers use `schedule/create` and `schedule/edit` with a `request` argument. Wrap a Cron selector as `{ kind: "cron", cron: { expression, time_zone } }`, or RRULE as `{ kind: "rrule", rrule }`. Model tool arguments continue to expose RRULE.
+2. Replace Session-bound deletion with `edit({ id, action: "delete" })`; replace updates with `edit({ id, action: "update", patch, expectedUpdatedAt? })`. Timing edits use `patch.timing`. Supply the read revision, or `null` to compare an absent revision; handle `schedule_conflict` by rereading.
+3. `list({ active?, limit?, offset? })` returns `{ items, shown, total, limit, offset }` across the Host. `catalog()` returns all tasks; `view({ id })`, `history({ id, limit, before? })`, and `run({ id })` need no owner Session. Read a reusable destination from `target`, and each receipt destination from `targetSessionId`.
+4. Use the unprefixed types exported by the package root or `/client`, including `ScheduleRecord`, `ScheduleTiming`, and `ScheduleCatalogEntry`. Narrow by `kind` before reading timing fields. Handle `paused` and `ended` instead of `inactive`, and allow absent creation/change timestamps. The root helpers `scheduleView`, `decodeScheduleChange`, `foldScheduleEvents`, and `SCHEDULE_CHANGE_VERSION` are removed; historical event types remain frozen data declarations. The [tool upgrade guide](../schedule-agent-tools/guide.md) lists the removed types and their replacements.
+5. Verify that Automation tasks shows existing Cron and calendar tasks and that a metadata edit preserves their timing and history. Historical Session-log reminders still require explicit recreation; they are outside this Host-task change.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/schedule-remote-host-tasks/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Schedule 客户端改用统一的宿主管理 API 和带类型时间记录；已有宿主任务保留现有领域和布局。"
+---
+
+# Schedule 使用统一的宿主管理 API
+
+[English](guide.md) | 中文
+
+## 变更
+
+Schedule 管理按 id 寻址宿主全部任务。原生与 Remote API 共用一个服务；移除先前按 Session 绑定的 `delete` 和 `update` 方法。原生创建接收带类型的 `timing`，目录结果通过 `kind` 区分 After、At、Every、Daily、Weekly、Cron 和 RRULE。
+
+现有 `schedule` 领域写入版本 2，读取版本 1 时不进行启动写入，保留路由、封套和布局。SQLite 物理 schema 保持版本 1。升级前备份存储：首次成功的 v2 写入将单元标记为 v2，v1 程序会拒绝打开。降级需要恢复该备份。编辑和投递保存当前行，无需独立迁移命令。插件 README 拥有[存储 schema、升级时机与成本](../../../../packages/schedule/schedule/README.zh.md#storage-format)。
+
+## 迁移
+
+1. 原生调用方使用 `create({ title, prompt, timing, target? }, actorSessionId?, signal?)` 和 `edit(request, actorSessionId?, signal?)`。Remote 调用方使用带 `request` 参数的 `schedule/create` 和 `schedule/edit`。Cron 选择器包装为 `{ kind: "cron", cron: { expression, time_zone } }`，RRULE 包装为 `{ kind: "rrule", rrule }`。模型工具参数继续暴露 RRULE。
+2. 将按 Session 绑定的删除替换为 `edit({ id, action: "delete" })`；更新替换为 `edit({ id, action: "update", patch, expectedUpdatedAt? })`。时间编辑使用 `patch.timing`。提供读取的版本，或以 `null` 比较缺失版本；遇到 `schedule_conflict` 时重新读取。
+3. `list({ active?, limit?, offset? })` 返回宿主范围的 `{ items, shown, total, limit, offset }`。`catalog()` 返回全部任务；`view({ id })`、`history({ id, limit, before? })` 和 `run({ id })` 无需所有者 Session。从 `target` 读取可复用目的地，从 `targetSessionId` 读取每条回执目的地。
+4. 使用包根入口或 `/client` 导出的无前缀类型，包括 `ScheduleRecord`、`ScheduleTiming` 和 `ScheduleCatalogEntry`。读取时间字段前先按 `kind` 收窄。用 `paused` 和 `ended` 替代 `inactive`，并允许创建/变更时间戳缺失。根入口助手 `scheduleView`、`decodeScheduleChange`、`foldScheduleEvents` 和 `SCHEDULE_CHANGE_VERSION` 已移除；历史事件类型仍是冻结的数据声明。[工具升级指南](../schedule-agent-tools/guide.zh.md)列出已移除类型及其替代方式。
+5. 确认自动化任务显示已有 Cron 和日历任务，且元数据编辑保留其时间规则与历史。历史 Session 日志提醒仍需显式重建；它们不属于本次宿主任务变更。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "SDK run recognizes native commands and returns RunResult after its input completes."
+---
+
+# SDK run accepts native commands
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Python and TypeScript `run()` accept strings and content-block arrays through the existing entry and always return `RunResult`. Supported native commands are recognized by their definition identities and effective registered names. English and Chinese aliases follow renamed definitions; unrelated exact-name replacements remain ordinary input. See the [supported command rules](../../../../packages/sdk/server/README.md#command-input).
+
+`final_response` / `finalResponse` contains the final assistant text, or an empty string when the activity emits none. State-only commands return the native handler's result text. `finish_reason` / `finishReason` reports the terminal outcome. Every result retains its Session id, root events and Session-tree notifications. State-only commands finish without waiting for a model turn; `/plan <task>` waits for its admitted activity, including native review and any approved continuation. Goal creation and resume wait across automatic rounds until the goal stops and its closing activity ends. Low-level strict command calls still return `CommandExecution` after the native handler settles.
+
+Content-block arrays no longer bypass native routing. A recognized command requires one text block and optional encoded raster images; native handlers enforce image admission. `/plan off` with an image fails without changing plan state. Empty arrays and blank-only input reject before Session creation; image-only input remains accepted. Identity rejection by the strict endpoint retains its initialized Session without executing a handler or submitting a prompt.
+
+## Migration
+
+1. Keep the existing `result.final_response` / `result.finalResponse` access for prompts and commands. Inspect `finish_reason` / `finishReason` for failure; command ids and native outcomes remain in `command/run` and `command/done` events. Save the result's Session id to continue or restore it.
+2. Keep the user-question callback alive for plan review. State-changing command failures appear in `RunResult`; routing, malformed protocol data and transport failures still raise or reject. A timeout or observer failure does not roll back runtime work.
+3. For literal queued input, use Python `client.session_prompt(session_id, blocks)` or TypeScript `client.prompt(sessionId, blocks)`, and manage its subsequent activity. Runtime skill recognition still applies.
+4. Custom `session/query` clients send `{ sessionId, contentBlocks }`. Command responses acknowledge the native handler; the matching `session.query.completed` notification carries the final input outcome. Preserve notification order and subscribe before sending.
+5. Filter empty input before calling `run()`. Use an image-capable model and the existing `run([text_block, image_block])` form for images. Python malformed native command responses raise `SdkProtocolError`, preserving their validation cause; generic caller-selected response models retain their validation behavior.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "SDK run 识别原生命令，并在本次输入完成后返回 RunResult。"
+---
+
+# SDK run 接受原生命令
+
+[English](guide.md) | 中文
+
+## 变更
+
+Python 和 TypeScript 的 `run()` 通过原有入口接受字符串和内容块数组，始终返回 `RunResult`。受支持原生命令按定义身份和实际注册名识别。中英文别名跟随重命名的定义；无关的同名替代命令仍作为普通输入。见[支持的命令规则](../../../../packages/sdk/server/README.zh.md#command-input)。
+
+`final_response` / `finalResponse` 包含最终助手文本；活动未输出助手文本时为空字符串。仅改变状态的命令返回原生 handler 的结果文本。`finish_reason` / `finishReason` 表示结束结果。每份结果都保留 Session id、根会话事件和会话树通知。仅改变状态的命令无需等待模型 turn；`/plan <task>` 等待其提交的活动，包括原生审阅及获批后的后续执行。目标创建和恢复跨越自动轮次等待，直到目标停止及最后的活动结束。底层严格命令调用仍在原生 handler 完成后返回 `CommandExecution`。
+
+内容块数组不再绕过原生命令路由。已识别命令要求一个文本块及可选的编码位图；原生 handler 执行图片准入。`/plan off` 带图片会失败且不改变计划状态。空数组和纯空白输入在创建 Session 前拒绝；纯图片输入仍然接受。严格端点拒绝命令身份时保留已经初始化的 Session，不执行 handler 或提交提示词。
+
+## 迁移
+
+1. 普通提示词和命令均继续使用 `result.final_response` / `result.finalResponse`。通过 `finish_reason` / `finishReason` 检查失败；命令 id 和原生结果保留在 `command/run` 与 `command/done` 事件中。保存结果的 Session id，以便继续或恢复会话。
+2. 计划审阅期间保持用户问题回调可用。状态变更命令的失败体现在 `RunResult` 中；路由、协议数据格式和传输失败仍抛出或拒绝。超时或观察回调失败不会回滚运行时工作。
+3. 需要按原文排队输入时，使用 Python `client.session_prompt(session_id, blocks)` 或 TypeScript `client.prompt(sessionId, blocks)`，并管理后续活动。运行时技能识别仍然适用。
+4. 自定义 `session/query` 客户端发送 `{ sessionId, contentBlocks }`。命令响应确认原生 handler 完成；对应的 `session.query.completed` 通知携带本次输入的最终结果。保持通知顺序，并在发送前订阅。
+5. 调用 `run()` 前过滤空输入。图片使用支持图片的模型及原有 `run([text_block, image_block])` 形式。Python 对格式错误的原生命令响应抛出 `SdkProtocolError`，保留校验原因；调用者自行选择的通用响应模型保留原有校验行为。