dsh-primer 0.4.4 → 0.4.6

package/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/llm-error-builtin-codes/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.2-alpha.2/llm-error-builtin-codes/guide.md
+/:
+  en: a3bc51b72528488c
+  zh: 1feb265c92492487
+/new-llmerror-accepts-only-built-in-failure-codes:
+  en: 390a9a983fc10296
+  zh: 2ce8cbc8c8661acf
+/new-llmerror-accepts-only-built-in-failure-codes/change:
+  en: db9bc6fe227f0d41
+  zh: 9ef71a6e7a2214be
+/new-llmerror-accepts-only-built-in-failure-codes/migration:
+  en: 605b8836fd1872e9
+  zh: 7cd1e58bb9cdb49e

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/llm-request-purpose-declarations/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.2-alpha.2/llm-request-purpose-declarations/guide.md
+/:
+  en: 0a5cfa851101f3e9
+  zh: 1c8e0e437718d4e2
+/declare-auxiliary-llm-request-purposes:
+  en: 5d5e1b6cb5b9c95e
+  zh: 11cf31babb07da28
+/declare-auxiliary-llm-request-purposes/change:
+  en: 0682a43eb52792fd
+  zh: 954b186cc66fdb08
+/declare-auxiliary-llm-request-purposes/migration:
+  en: eae671d1e185ecbf
+  zh: c042a276a1a7ad17

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/pi-ai-request-image-count/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.2-alpha.2/pi-ai-request-image-count/guide.md
+/:
+  en: 18359b607f378e44
+  zh: c94f503a30b8ebe0
+/pi-ai-request-image-count:
+  en: 8ed160da9859a7d0
+  zh: 5252360ebf0a2c4d
+/pi-ai-request-image-count/change:
+  en: c000351899001605
+  zh: fd5048dba5987295
+/pi-ai-request-image-count/migration:
+  en: 1bdf29eb86d198ca
+  zh: a60f1719dccd6717

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/projection-event-frames/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.2-alpha.2/projection-event-frames/guide.md
+/:
+  en: e48b8561bd5e8c36
+  zh: 250e816f38495c97
+/projection-frames-list-every-key-one-event-changed:
+  en: 3f22f3e46a3903db
+  zh: 7694cef52b9aa7f0
+/projection-frames-list-every-key-one-event-changed/change:
+  en: f0d17c8787e7da13
+  zh: 3b193ae03232b6be
+/projection-frames-list-every-key-one-event-changed/migration:
+  en: fa9b8d4e4c426754
+  zh: 70f21eb8ec280fdd

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/projection-released-checkpoint/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.2-alpha.2/projection-released-checkpoint/guide.md
+/:
+  en: 738f2376c5a8ebe5
+  zh: 078f2a08d8b6ad4b
+/released-projection-units-stay-in-checkpoints:
+  en: 9355d9de711acc7d
+  zh: eb89da6b886a7556
+/released-projection-units-stay-in-checkpoints/change:
+  en: 5944b6c7b72e15e4
+  zh: 051d68e2eb5151d7
+/released-projection-units-stay-in-checkpoints/migration:
+  en: 9f24ecf12748eb41
+  zh: c07649e79a0174f9

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/projection-snapshot-scope/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.2-alpha.2/projection-snapshot-scope/guide.md
+/:
+  en: 82a6e0261297097c
+  zh: c86e496c258e72b2
+/projection-snapshot-scope:
+  en: c8b08322a943d6b2
+  zh: 31862a259b7738bb
+/projection-snapshot-scope/change:
+  en: d95cd644b01419a1
+  zh: 89038a6de9b74e8a
+/projection-snapshot-scope/migration:
+  en: 408d88a4ea6fe3a9
+  zh: 397de0dc2d8318df

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/retained-ptc-timeout/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.2-alpha.2/retained-ptc-timeout/guide.md
+/:
+  en: 81282ebd9fb3522f
+  zh: a10b0dd429c1e527
+/retained-ptc-timeout-recovery:
+  en: 077a655f2f967e61
+  zh: 2c3458dc17023b75
+/retained-ptc-timeout-recovery/change:
+  en: f3ebfde587b16d65
+  zh: b48f8fdc91d84ccb
+/retained-ptc-timeout-recovery/migration:
+  en: 969be7aa004c1c83
+  zh: a8dfde8f75efaa9a

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/schedule-agent-tools/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.2-alpha.2/schedule-agent-tools/guide.md
+/:
+  en: 534c875c6423421f
+  zh: 041b62aed9b5689f
+/schedule-tools-manage-every-host-task-by-rrule-and-target:
+  en: 390ea3dd55433b66
+  zh: eb1b5e4cf2ae6551
+/schedule-tools-manage-every-host-task-by-rrule-and-target/change:
+  en: 3609120a0dee5cee
+  zh: 0b5d3c77c998e46d
+/schedule-tools-manage-every-host-task-by-rrule-and-target/migration:
+  en: ca46aafc12815cc4
+  zh: c99e9160e2bb871e

package/references/official-docs/docs/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/references/official-docs/docs/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)。