dsh-plugin-dev-kb 1.6.0 → 1.8.0

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`，保留校验原因；调用者自行选择的通用响应模型保留原有校验行为。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/session-header-menu/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Custom Web compositions must provide context menus for Session actions, and export dialogs now remain visible across Session switches."
+---
+
+# Session Header menus and export dialogs
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The browser half of `@deepseek-ai/dsh-session-log-export` requires `contextMenus` to contribute copy, download, and feedback actions. Custom Web compositions without a context-menu provider must add one or these client actions cannot activate. The default Web composition already includes it. The Header More button belongs to `ui-conversation`, so removing the export plugin does not remove other registered Header actions such as Open in. The button hides when no Header-menu providers are registered.
+
+Download dialogs are mounted in the root `shell.overlay`, rather than a Session Header. They identify the exported Session and remain visible when the user switches Sessions. Downloads may run concurrently, but dialogs appear one at a time in request order; closing one shows the next and does not cancel its download. Host export routes and the `/export` command are unchanged.
+
+## Migration
+
+1. Add `@deepseek-ai/dsh-client-ui-context-menu` to custom Web compositions that lack it, with the menu package's required services. See [context-menu composition](../../../../packages/client/ui-context-menu/README.md#use-this-package). Keep `ui-conversation` for the Session Header and the shell's root overlay for download feedback. Default Web profiles need no configuration change.
+2. Custom client code using `SessionLogDownloadDialogProps` must use root-overlay runtime props instead of Session-header props and remove the `request` injection. `SessionLogDownloadEntry` includes an `order` value; the dialog reads Session identities and ordering from `bySession`.
+3. Restart the profile. Confirm that Header More contains the registered actions, Open in remains after disabling the export plugin, and starting downloads for two Sessions presents their dialogs in request order even after switching Sessions.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/session-header-menu/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "自定义 Web 组合必须为会话操作提供右键菜单服务，导出弹窗在切换 Session 后仍保持显示。"
+---
+
+# 会话头部菜单与导出弹窗
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-log-export` 的浏览器半包需要 `contextMenus` 提供复制、下载和反馈操作。没有右键菜单提供者的自定义 Web 组合必须补充，否则这些客户端操作无法激活。默认 Web 组合已包含提供者。头部更多按钮由 `ui-conversation` 持有，因此移除导出插件不会移除其他已注册的头部操作，例如在应用中打开。没有注册任何头部菜单提供者时，按钮隐藏。
+
+下载弹窗挂载于根级 `shell.overlay`，不再位于 Session Header。弹窗标明正在导出的 Session，切换 Session 后仍然显示。多个下载可以并行进行，但弹窗按发起顺序一次展示一个；关闭当前弹窗会展示下一个，不取消其下载。Host 导出路由及 `/export` 命令不变。
+
+## 迁移
+
+1. 自定义 Web 组合缺少提供者时，添加 `@deepseek-ai/dsh-client-ui-context-menu` 并提供菜单包要求的服务。参见[右键菜单组合](../../../../packages/client/ui-context-menu/README.zh.md#use-this-package)。保留 `ui-conversation` 以提供会话头部，以及 shell 的根级 overlay 以展示下载反馈。默认 Web profile 无需修改配置。
+2. 使用 `SessionLogDownloadDialogProps` 的自定义客户端代码需改用根级 overlay runtime props，不再使用 Session Header props，并移除 `request` 注入。`SessionLogDownloadEntry` 包含 `order` 值；弹窗从 `bySession` 读取 Session 身份与顺序。
+3. 重启 profile，确认头部更多菜单包含已注册的操作，禁用导出插件后仍可在应用中打开，并确认两个 Session 的下载弹窗按发起顺序显示，切换 Session 后仍然保留。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/subagent-explicit-reasoning/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Subagent reasoning overrides require an explicit provider and model, and explicit routes use model-default reasoning when effort is omitted."
+---
+
+# Subagent reasoning overrides require an explicit route
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Delegation tools with model selection enabled reject `reasoning_effort` unless the same call supplies both `provider` and `model`. Previously, an effort-only call could use a configured or inherited route. The rejection occurs before child creation.
+
+An explicit provider/model pair without `reasoning_effort` uses the selected model's default effort, including when the pair matches the parent or configured child route. Previously, the unchanged route could retain a configured or parent effort. Omitting all three tool fields preserves the configured child defaults and existing fallback behavior.
+
+## Migration
+
+1. Update prompts, skills, and tool-call producers that send only `reasoning_effort`: include the authorized `provider` and `model`, or omit all three fields to use the default child selection. Query `list_subagent_models` for authorized routes and supported effort ids.
+2. To preserve a specific effort while selecting a route, pass it explicitly as `reasoning_effort`.
+3. Confirm an effort-only call returns a missing-route error without starting a child. For a complete route, check the child's logged `request/header` configuration: an omitted effort follows that model's default rather than the parent's selected effort.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/subagent-explicit-reasoning/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "subagent 推理强度覆盖要求显式指定提供方和模型，显式路由省略强度时使用模型默认值。"
+---
+
+# subagent 推理强度覆盖要求显式路由
+
+[English](guide.md) | 中文
+
+## 变更
+
+启用模型选择的委派工具要求同一次调用同时提供 `provider` 和 `model`，否则拒绝 `reasoning_effort`。此前，仅指定强度的调用可以使用配置或继承的路由。拒绝发生在创建子级之前。
+
+显式提供提供方／模型组合但省略 `reasoning_effort` 时，使用所选模型的默认强度，即使该组合与父级或配置的子级路由相同。此前，路由不变时可能保留配置或父级强度。省略全部三个工具字段时，仍保留配置的子级默认值与现有回退行为。
+
+## 迁移
+
+1. 更新仅发送 `reasoning_effort` 的提示、skill 和工具调用生成方：补齐已授权的 `provider` 和 `model`，或省略全部三个字段以使用默认子级选择。通过 `list_subagent_models` 查询已授权路由与支持的强度 ID。
+2. 选择路由时若要保留某个强度，显式传入 `reasoning_effort`。
+3. 确认仅指定强度的调用返回缺少路由的错误，且没有启动子级。对于完整路由，检查子级日志中的 `request/header` 配置：省略强度时应采用该模型的默认值，而不是父级选择的强度。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-credential-modes/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DeepSeek web search and fetch take their endpoint from the DeepSeek model route; the shared baseURL, apiKeyEnv, and apiKey fields are removed in favor of per-capability fields."
+---
+
+# DeepSeek web search and fetch follow the DeepSeek model route
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Previously, the DeepSeek Search API and Fetch API (`web-deepseek-api`) sent their credential to one shared `baseURL` (default `https://api.deepseek.com/v1/tools`): the account token when the Session's latest model request used the `deepseek-account` route and the user was signed in, otherwise the key under `apiKeyEnv` (default `DEEPSEEK_API_KEY`) or a literal `apiKey`. Now each capability follows the same route rule but takes the endpoint from the route: on `deepseek-account` the account token goes to the account route's origin with `/v1/tools`; otherwise, including a signed-out account conversation, the key under the `apiKeyEnv` of the `deepseek-official` route goes to that route's origin with `/v1/tools`, so `DEEPSEEK_BASE_URL` now moves Search and Fetch too. Without a `deepseek-official` route, `DEEPSEEK_API_KEY` goes to `https://api.deepseek.com/v1/tools`; a mounted route whose settings do not resolve fails the operation instead. The `baseURL`, `apiKeyEnv`, and `apiKey` fields are removed; stored values load without error and are ignored. Setting either `searchBaseURL` or `searchApiKeyEnv` (`fetchBaseURL` or `fetchApiKeyEnv` for Fetch) pins that capability to its own endpoint (default `https://api.deepseek.com/v1/tools`) and key (default `DEEPSEEK_API_KEY`) and never sends the account token. These fields are YAML-only. Users without those YAML fields, without `DEEPSEEK_BASE_URL`, and without a custom model base URL see no change.
+
+## Migration
+
+1. Users who set `baseURL`, `apiKeyEnv`, or a literal `apiKey` on the `web-deepseek-api` row: for each of Search and Fetch, compare the old endpoint and key with what the route now sends, the origin of the DeepSeek model provider's base URL with `/v1/tools` and that provider's `apiKeyEnv`. When both match, remove the old fields. Otherwise set the pair, `searchBaseURL` with `searchApiKeyEnv` (`fetchBaseURL` with `fetchApiKeyEnv`), to the old endpoint and key reference, setting both fields even when one old value equals the route's: an unset field of the pair falls back to `https://api.deepseek.com/v1/tools` or `DEEPSEEK_API_KEY`, never to the route's value. For a literal `apiKey`, store it in the credential store or the launching environment under a reference and use that reference. A pinned capability never sends the account token. Confirm: `dsh` starts, and a search and a fetch reach the intended endpoint without a credential error.
+2. Users with `DEEPSEEK_BASE_URL` or a custom base URL on the DeepSeek model provider whose host does not serve `/v1/tools`: set the same pair to `https://api.deepseek.com/v1/tools` and the reference of a key that endpoint accepts. Confirm: a search returns results.