dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/schedule-remote-host-tasks/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-remote-host-tasks/guide.md
+/:
+  en: 69c0cf0c8201d784
+  zh: a7831ef117a6f20c
+/schedule-uses-one-host-wide-management-api:
+  en: 380dae2dc6802943
+  zh: dfdca40926880a67
+/schedule-uses-one-host-wide-management-api/change:
+  en: 8fab9b2c62b64745
+  zh: b7cff45264a852f8
+/schedule-uses-one-host-wide-management-api/migration:
+  en: 2f20ccf5e82d299e
+  zh: b01fa9cd6d297f5e

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/sdk-run-commands/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/sdk-run-commands/guide.md
+/:
+  en: 695ee5740865d684
+  zh: 83cb4df5ecf20a99
+/sdk-run-accepts-native-commands:
+  en: 54f8a31426f4758c
+  zh: 283820d3f187092e
+/sdk-run-accepts-native-commands/change:
+  en: 478742169aa04c50
+  zh: 3324d99f4206d1fc
+/sdk-run-accepts-native-commands/migration:
+  en: 0298fc31efa6466c
+  zh: ab99db4beaa86a14

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/session-header-menu/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/session-header-menu/guide.md
+/:
+  en: 54b02da822ff0fbb
+  zh: 1d43d9775ebb92a8
+/session-header-menus-and-export-dialogs:
+  en: d7c751cc3dbc57b7
+  zh: 3d08043e08ccf406
+/session-header-menus-and-export-dialogs/change:
+  en: cf5c9760f279f709
+  zh: cb640560cc139fa9
+/session-header-menus-and-export-dialogs/migration:
+  en: 4a12455c8862476f
+  zh: 49f775d6fcc10751

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/subagent-explicit-reasoning/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/subagent-explicit-reasoning/guide.md
+/:
+  en: 74a51bb421eb125c
+  zh: 2fccbfa5bcafb2af
+/subagent-reasoning-overrides-require-an-explicit-route:
+  en: f6bc10b254fe4420
+  zh: 9ac48f0264d1bd69
+/subagent-reasoning-overrides-require-an-explicit-route/change:
+  en: e31a906fc29dd5a6
+  zh: 2fa39b8bcbdfdb38
+/subagent-reasoning-overrides-require-an-explicit-route/migration:
+  en: 9ebfdab054389c89
+  zh: 7c50e28db91781e4

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/web-search-credential-modes/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/web-search-credential-modes/guide.md
+/:
+  en: 5b07a9a586fe0ef8
+  zh: 957123dc3a23c9a9
+/deepseek-web-search-and-fetch-follow-the-deepseek-model-route:
+  en: bf3ccc3a2347cdbf
+  zh: ff4557b79d972e56
+/deepseek-web-search-and-fetch-follow-the-deepseek-model-route/change:
+  en: ff12048c0d6a6e11
+  zh: 159e178776739bbe
+/deepseek-web-search-and-fetch-follow-the-deepseek-model-route/migration:
+  en: 97da49ad7b5342fa
+  zh: ce0f49d638045891

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

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/web-search-credential-modes/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DeepSeek 网页搜索与获取从 DeepSeek 模型路由取得端点；共享的 baseURL、apiKeyEnv 与 apiKey 字段已移除，改用按能力区分的字段。"
+---
+
+# DeepSeek 网页搜索与获取跟随 DeepSeek 模型路由
+
+[English](guide.md) | 中文
+
+## 变更
+
+过去，DeepSeek Search API 与 Fetch API（`web-deepseek-api`）把凭据发往同一个共享的 `baseURL`（默认 `https://api.deepseek.com/v1/tools`）：会话最近一次模型请求使用 `deepseek-account` 路由且用户已登录时发送账号令牌，否则发送 `apiKeyEnv`（默认 `DEEPSEEK_API_KEY`）下的密钥或字面 `apiKey`。现在每个能力沿用相同的路由规则，但端点取自路由：在 `deepseek-account` 上把账号令牌发往账号路由的 origin 加 `/v1/tools`；其他情况（包括未登录的账号会话）把 `deepseek-official` 路由 `apiKeyEnv` 下的密钥发往该路由的 origin 加 `/v1/tools`，因此 `DEEPSEEK_BASE_URL` 现在也会改变 Search 与 Fetch 的端点。没有 `deepseek-official` 路由时，把 `DEEPSEEK_API_KEY` 发往 `https://api.deepseek.com/v1/tools`；已挂载的路由设置无法解析时，操作直接失败。`baseURL`、`apiKeyEnv` 与 `apiKey` 字段已移除；已保存的值可以正常加载，但会被忽略。只要设置 `searchBaseURL` 或 `searchApiKeyEnv` 中的任一项（Fetch 为 `fetchBaseURL` 或 `fetchApiKeyEnv`），就会把该能力固定到其自己的端点（默认 `https://api.deepseek.com/v1/tools`）和密钥（默认 `DEEPSEEK_API_KEY`），且从不发送账号令牌。这些字段只能在 YAML 中设置。没有设置这些 YAML 字段、没有设置 `DEEPSEEK_BASE_URL`、也没有自定义模型基础地址的用户不受影响。
+
+## 迁移
+
+1. 在 `web-deepseek-api` 条目上设置过 `baseURL`、`apiKeyEnv` 或字面 `apiKey` 的用户：对 Search 与 Fetch 分别比较原端点和密钥与路由现在发送的值，即 DeepSeek 模型提供方基础地址的 origin 加 `/v1/tools`，以及该提供方的 `apiKeyEnv`。两者都一致时，删除旧字段。否则把成对字段 `searchBaseURL` 与 `searchApiKeyEnv`（Fetch 为 `fetchBaseURL` 与 `fetchApiKeyEnv`）设为原端点和原密钥引用；即使其中一个原值与路由的值相同，也要两个字段都设置：成对字段中未设置的一项回退到 `https://api.deepseek.com/v1/tools` 或 `DEEPSEEK_API_KEY`，不会继承路由的值。设置过字面 `apiKey` 时，把该值以某个引用存入凭据存储或启动环境，并使用该引用。单独配置的能力从不发送账号令牌。确认：`dsh` 正常启动，且搜索和抓取都到达预期端点，没有凭据错误。
+2. 设置了 `DEEPSEEK_BASE_URL` 或为 DeepSeek 模型提供方设置了自定义基础地址、且该主机不提供 `/v1/tools` 的用户：把同一对字段设为 `https://api.deepseek.com/v1/tools` 和该端点接受的密钥引用。确认：搜索返回结果。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/web-search-default-provider/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/web-search-default-provider/guide.md
+/:
+  en: 2a8012259f83b47f
+  zh: 913cf3290acedfd0
+/search-defaults-to-the-deepseek-search-api-exa-and-perplexity-are-removed:
+  en: d74d9ae56bde707f
+  zh: 45eafef25e659780
+/search-defaults-to-the-deepseek-search-api-exa-and-perplexity-are-removed/change:
+  en: acb404257af50295
+  zh: c22c29e18fc1dbab
+/search-defaults-to-the-deepseek-search-api-exa-and-perplexity-are-removed/migration:
+  en: 5f69931cdd39ea2f
+  zh: 7e569007c068151c

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/web-search-default-provider/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The shipped Search default moves from legacy Messages search to the DeepSeek Search API, and the optional Exa and Perplexity search packages are removed."
+---
+
+# Search defaults to the DeepSeek Search API; Exa and Perplexity are removed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Previously, the shared base composition set `web.searchProvider` to `deepseek-official`: each search was an auxiliary Messages request to `web-search-deepseek`'s endpoint, sending `Perform a web search for the query: <query>` to `deepseek-v4-flash` with a server-side `web_search` tool, billed as model tokens. Now it sets `deepseek-search-api`: each search is one direct request to the DeepSeek Search API, without a model request, and may incur Search API charges instead of model tokens. That request sends `query`, `count`, `need_content: false`, and, unless `web-deepseek-api.sendOriginalQuestion` is `false`, the user's latest prompt cut to 128 characters as `ori_question`. Its credential and endpoint follow the [DeepSeek model route](../web-search-credential-modes/guide.md). Compositions that set `web.searchProvider` themselves see no change, and Fetch still defaults to `http`.
+
+The optional packages `@deepseek-ai/dsh-web-search-exa` (provider `exa`) and `@deepseek-ai/dsh-web-search-perplexity` (provider `perplexity`) are removed. A row naming either package no longer loads, and `searchProvider: exa` or `searchProvider: perplexity` names no provider.
+
+## Migration
+
+1. To keep legacy Messages search, set `searchProvider: deepseek-official` in the `config` of the `@deepseek-ai/dsh-web` row, or select DeepSeek (legacy) in the Web search provider menu on the Web search and fetch settings page. Confirm: that menu shows DeepSeek (legacy), and a search appends a `web/deepseek-search-llm-request` event to the Session log.
+2. Deployments that mounted Exa or Perplexity: delete the `@deepseek-ai/dsh-web-search-exa` or `@deepseek-ai/dsh-web-search-perplexity` row from `cordis.yml` or the profile patch, remove `EXA_API_KEY` or `PERPLEXITY_API_KEY` if nothing else uses it, and set `searchProvider` to `deepseek-search-api` or `deepseek-official`, or delete it to take the default. Confirm: `dsh` starts without a load error for either package, the Web search provider menu shows the chosen provider, and a search returns results.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/web-search-default-provider/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "交付的 Search 默认值从旧版 Messages 搜索改为 DeepSeek Search API，可选的 Exa 与 Perplexity 搜索包已移除。"
+---
+
+# Search 默认使用 DeepSeek Search API；Exa 与 Perplexity 已移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+过去，共享的基础组合把 `web.searchProvider` 设为 `deepseek-official`：每次搜索都是发往 `web-search-deepseek` 端点的一次辅助 Messages 请求，以 `Perform a web search for the query: <query>` 调用带服务端 `web_search` 工具的 `deepseek-v4-flash`，按模型 token 计费。现在它设为 `deepseek-search-api`：每次搜索是一次直接发往 DeepSeek Search API 的请求，不调用模型，可能产生 Search API 费用而非模型 token 费用。该请求发送 `query`、`count`、`need_content: false`，并且除非 `web-deepseek-api.sendOriginalQuestion` 为 `false`，还会把用户最近一条提示截取前 128 个字符作为 `ori_question` 发送。其凭据和端点跟随 [DeepSeek 模型路由](../web-search-credential-modes/guide.zh.md)。自行设置了 `web.searchProvider` 的组合不受影响，Fetch 仍默认为 `http`。
+
+可选包 `@deepseek-ai/dsh-web-search-exa`（提供方 `exa`）与 `@deepseek-ai/dsh-web-search-perplexity`（提供方 `perplexity`）已移除。指名任一包的条目不再能加载，`searchProvider: exa` 或 `searchProvider: perplexity` 也不再对应任何提供方。
+
+## 迁移
+
+1. 要继续使用旧版 Messages 搜索，在 `@deepseek-ai/dsh-web` 条目的 `config` 中设置 `searchProvider: deepseek-official`，或在「网页搜索与获取」设置页的「网页搜索提供方」菜单中选择 DeepSeek（旧版）。确认：该菜单显示 DeepSeek（旧版），且每次搜索都会向会话日志追加一个 `web/deepseek-search-llm-request` 事件。
+2. 挂载过 Exa 或 Perplexity 的部署：从 `cordis.yml` 或 profile 补丁中删除 `@deepseek-ai/dsh-web-search-exa` 或 `@deepseek-ai/dsh-web-search-perplexity` 条目；若 `EXA_API_KEY` 或 `PERPLEXITY_API_KEY` 不再被其他地方使用，一并移除；再把 `searchProvider` 设为 `deepseek-search-api` 或 `deepseek-official`，或删除该字段以采用默认值。确认：`dsh` 启动时没有这两个包的加载错误，「网页搜索提供方」菜单显示所选提供方，且搜索返回结果。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/chat-process-activity-context/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.3/chat-process-activity-context/guide.md
+/:
+  en: cee1fd1a4a871edb
+  zh: d02fdd6e917aacc1
+/chat-processactivity-adds-context:
+  en: eb074a142ff239d1
+  zh: a73ee547890e9ec9
+/chat-processactivity-adds-context/change:
+  en: 27273494c758b014
+  zh: aa34a345a74a39c8
+/chat-processactivity-adds-context/migration:
+  en: 220c40bf5382ac52
+  zh: aae0d1731127571a

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/chat-process-activity-context/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Chat ProcessActivity gains a context category, and the running activity uses RunningProcessActivity."
+---
+
+# Chat `ProcessActivity` adds `context`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ProcessActivity`, exported from `@deepseek-ai/dsh-client-ui-chat/client`, gains the member `context`. A closed process group whose members are all Context injections reports it as its only category. `ProcessActivitySummary.running` is now typed as the new exported `RunningProcessActivity`, which excludes `context`. This affects extensions that switch exhaustively over `ProcessActivity` or map every member to a label or icon.
+
+## Migration
+
+1. Add a `context` branch wherever code handles every `ProcessActivity` member, for example in a `Record<ProcessActivity, …>` or a `switch` ending in `assertNever`.
+2. Type values read from `summary.running` as `RunningProcessActivity` when they need not cover `context`.
+3. Run the extension's typecheck and confirm it compiles without a missing-member error.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/chat-process-activity-context/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Chat 的 ProcessActivity 新增 context 类别，运行中活动改用 RunningProcessActivity。"
+---
+
+# Chat `ProcessActivity` 新增 `context`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-chat/client` 导出的 `ProcessActivity` 新增成员 `context`。成员全部为上下文注入的已结束过程组以它作为唯一类别。`ProcessActivitySummary.running` 的类型改为新导出的 `RunningProcessActivity`，该类型不含 `context`。对 `ProcessActivity` 做穷尽 switch 或为每个成员映射文案、图标的扩展受影响。
+
+## 迁移
+
+1. 在处理全部 `ProcessActivity` 成员的位置补上 `context` 分支，例如 `Record<ProcessActivity, …>` 或以 `assertNever` 结尾的 `switch`。
+2. 读取 `summary.running` 且无需覆盖 `context` 的值，类型改为 `RunningProcessActivity`。
+3. 运行扩展的类型检查，确认没有缺少成员的编译错误。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/office-kit-package/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.3/office-kit-package/guide.md
+/:
+  en: 0e3fae218b0fe86f
+  zh: 31fa1f4ac5cfffe6
+/deepseek-ai-dsh-office-kit-replaces-deepseek-ai-dsh-office-to-pdf:
+  en: e9c8bf48217b3e1c
+  zh: 710a0cd0489a65b7
+/deepseek-ai-dsh-office-kit-replaces-deepseek-ai-dsh-office-to-pdf/change:
+  en: 885088211bc994ac
+  zh: ee8192f950f2597b
+/deepseek-ai-dsh-office-kit-replaces-deepseek-ai-dsh-office-to-pdf/migration:
+  en: 9871a035772e8bbd
+  zh: 53f05c66de3ceb0e

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/office-kit-package/guide.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "`@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf`, renaming its service, Remote methods, exported types, and configuration row."
+---
+
+# `@deepseek-ai/dsh-office-kit` replaces `@deepseek-ai/dsh-office-to-pdf`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Office conversion provider moved from `@deepseek-ai/dsh-office-to-pdf` to `@deepseek-ai/dsh-office-kit`. Compositions, plugins, and Clients that name the old package, service, Remote methods, or exported symbols are affected:
+
+| Old | New |
+|---|---|
+| `cordis.yml` row `id: office-to-pdf`, `name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`, `name: '@deepseek-ai/dsh-office-kit'`; configuration keys are unchanged |
+| `ctx.officeToPdf` | `ctx.officeKit` |
+| Remote `officeToPdf/render`, `officeToPdf/generation` | `officeKit/render`, `officeKit/generation` |
+| `OfficeToPdf` | `OfficeKit` |
+| `OfficeToPdfError`, `OfficeToPdfErrorCode` | `OfficeKitError`, `OfficeKitErrorCode` |
+| `OfficeToPdfGeneration` | `OfficeKitGeneration` |
+| `OfficeToPdfRequest`, `OfficeToPdfResult`, `OfficeToPdfPriority`, `OfficeToPdfKey` | `OfficeKitRequest`, `OfficeKitResult`, `OfficeKitPriority`, `OfficeKitKey` |
+
+The `document-render/failed` Remote error, `RenderedDocumentBytes`, `OfficeSourceKey`, and `OfficeExtension` keep their names. The `/types` and `/remote` entries remain.
+
+The provider previously failed to load when LibreOffice Kit was absent. It now registers without Kit; each conversion that needs a converter rejects with `OfficeKitError` code `unavailable` and locates Kit again, so installing Kit later takes effect without reloading the provider.
+
+## Migration
+
+1. In `cordis.yml`, patches, and overlays, change the row `id: office-to-pdf` to `id: office-kit` and its `name` to `'@deepseek-ai/dsh-office-kit'`. Keep its `config` block unchanged.
+2. Replace the dependency `@deepseek-ai/dsh-office-to-pdf` with `@deepseek-ai/dsh-office-kit` in `package.json`, and update import specifiers, including `/types` and `/remote`.
+3. Rename `ctx.officeToPdf`, Remote method names, and the exported symbols listed above.
+4. Code that treated a load failure of the conversion row as "Kit absent" now checks for `OfficeKitError` with code `unavailable` from conversion instead.
+5. Confirm the migration by searching the project for `office-to-pdf`, `officeToPdf`, and `OfficeToPdf`, then opening a DOCX file in the Web document preview.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/office-kit-package/guide.zh.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "`@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf`，其服务、Remote 方法、导出类型和配置行随之改名。"
+---
+
+# `@deepseek-ai/dsh-office-kit` 取代 `@deepseek-ai/dsh-office-to-pdf`
+
+[English](guide.md) | 中文
+
+## 变更
+
+Office 转换提供方从 `@deepseek-ai/dsh-office-to-pdf` 移到 `@deepseek-ai/dsh-office-kit`。引用旧包、服务、Remote 方法或导出符号的组合、插件和 Client 受到影响：
+
+| 旧名 | 新名 |
+|---|---|
+| `cordis.yml` 行 `id: office-to-pdf`、`name: '@deepseek-ai/dsh-office-to-pdf'` | `id: office-kit`、`name: '@deepseek-ai/dsh-office-kit'`；配置项不变 |
+| `ctx.officeToPdf` | `ctx.officeKit` |
+| Remote `officeToPdf/render`、`officeToPdf/generation` | `officeKit/render`、`officeKit/generation` |
+| `OfficeToPdf` | `OfficeKit` |
+| `OfficeToPdfError`、`OfficeToPdfErrorCode` | `OfficeKitError`、`OfficeKitErrorCode` |
+| `OfficeToPdfGeneration` | `OfficeKitGeneration` |
+| `OfficeToPdfRequest`、`OfficeToPdfResult`、`OfficeToPdfPriority`、`OfficeToPdfKey` | `OfficeKitRequest`、`OfficeKitResult`、`OfficeKitPriority`、`OfficeKitKey` |
+
+Remote 错误 `document-render/failed`、`RenderedDocumentBytes`、`OfficeSourceKey` 和 `OfficeExtension` 保持原名。`/types` 和 `/remote` 入口仍然保留。
+
+原先 LibreOffice Kit 缺失时提供方加载失败。现在没有 Kit 时提供方照常注册；每次需要转换器的转换都以代码为 `unavailable` 的 `OfficeKitError` 拒绝，并重新定位 Kit，因此之后安装的 Kit 无需重新加载提供方即可生效。
+
+## 迁移
+
+1. 在 `cordis.yml`、patch 和 overlay 中，把 `id: office-to-pdf` 行改为 `id: office-kit`，并把其 `name` 改为 `'@deepseek-ai/dsh-office-kit'`。`config` 块保持不变。
+2. 在 `package.json` 中用 `@deepseek-ai/dsh-office-kit` 替换依赖 `@deepseek-ai/dsh-office-to-pdf`，并更新导入路径，包括 `/types` 和 `/remote`。
+3. 按上表重命名 `ctx.officeToPdf`、Remote 方法名和导出符号。
+4. 原先把转换行加载失败视为“Kit 缺失”的代码，改为检查转换返回的、代码为 `unavailable` 的 `OfficeKitError`。
+5. 在项目中搜索 `office-to-pdf`、`officeToPdf` 和 `OfficeToPdf` 确认已无残留，然后在 Web 文档预览中打开一个 DOCX 文件，确认迁移完成。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/office-operation-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.3/office-operation-tools/guide.md
+/:
+  en: f25812af9f761878
+  zh: 3a8dbcde68ed75c9
+/office-operation-skills-are-replaced-by-office-tools:
+  en: 6c5aaef399e15878
+  zh: 92c4ae1a8d812790
+/office-operation-skills-are-replaced-by-office-tools/change:
+  en: 1d12b14e002bcf3b
+  zh: ac844c2aeb9f9053
+/office-operation-skills-are-replaced-by-office-tools/migration:
+  en: 9646620e0c4636c3
+  zh: be896458a90937ba

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/office-operation-tools/guide.md

@@ -0,0 +1,49 @@
+---
+kind: upgrade-guide
+description: "The `office-render`, `office-recalculate`, and `office-export-pdf` skills, the skill-office `node` and `cli` keys, and two Office CLI environment variables are removed; Office operations use skill-activated tools."
+---
+
+# Office operation skills are replaced by Office tools
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-skill-office` no longer registers the `office-render`, `office-recalculate`, and `office-export-pdf` skills; it registers the `office` router and the `office-docx`, `office-pptx`, and `office-xlsx` authoring skills. After an Office skill loads, the model calls [`office_render`, `office_convert`, and `office_recalculate`](../../../../packages/document/tool-office/README.md) from the following step.
+
+Configuration changes:
+
+| Removed | Replacement |
+|---|---|
+| `skill-office` keys `node` and `cli` | None; Office tools convert in the Host |
+| `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE` | None; no component reads them |
+| `DSH_BUNDLED_PRIMARY_RUNTIME` | `DSH_PRIMARY_RUNTIME` |
+
+`skill-office` gains `pythonEnvironment`. Its default, `'workspace-dependencies'`, directs the Python skills to `load_workspace_dependencies`; a composition without `@deepseek-ai/dsh-tool-workspace-dependencies` must set `'user'`. [Office skill resources](../office-skill-resources/guide.md) covers the removal of `DSH_BUNDLED_OFFICE_SKILLS`.
+
+The Office tools parse untrusted documents with the native LibreOffice Kit engine in the Host process, outside the shell sandbox and PTC permissions, with the Host user's permissions; the filesystem backend still authorizes inputs. The `office-kit` row gains `outputDirectory` (default `$DSH_HOME/office-kit/outputs`), `outputRetentionMs`, and `maxOutputStoreBytes`.
+
+The Web profile, and the SDK profile without a primary runtime, list the Office skills in the first request context and `/` menu.
+
+This affects users and prompts of the removed skills, compositions and launchers setting the removed keys or variables, `assetRoot` skill copies, saved `standard` or `ptc` presets, deployments relying on the shell sandbox for document parsing, and tests pinning the first request context or `/` menu.
+
+## Migration
+
+1. Replace each removed skill with loading `office` and calling the matching tool:
+   - `office-render`: `office_render`;
+   - `office-recalculate`: `office_recalculate` with `format: "xlsx"` or `"ods"`;
+   - `office-export-pdf`: `office_convert` with `format: "pdf"`.
+2. Remove `node` and `cli` from every `skill-office` row in `cordis.yml`, patches, and overlays. Set `pythonEnvironment: user` unless the composition mounts `@deepseek-ai/dsh-tool-workspace-dependencies`.
+3. Compositions that mount `@deepseek-ai/dsh-skill-office` without the shipped bundles also mount `@deepseek-ai/dsh-office-kit` and `@deepseek-ai/dsh-tool-office`.
+4. In launchers, stop setting `DSH_BUNDLED_OFFICE_CLI` and `DSH_BUNDLED_OFFICE_NODE`, and rename `DSH_BUNDLED_PRIMARY_RUNTIME` to `DSH_PRIMARY_RUNTIME`. The Python SDK prefers a set or inherited `DSH_PRIMARY_RUNTIME`, even empty, over its download cache; unset it to use the cache.
+5. In a copy referenced by `assetRoot`, replace the four remaining folders with the installed package's `assets/` and delete the three removed skill folders.
+6. A `standard` or `ptc` preset saved from the Agent Preset editor replaces the shipped plugin list, so its Sessions lack the Office tools. Add this row to the saved list, or to `config.plugins` of the `preset-standard` or `preset-ptc` row in `$DSH_HOME/profiles/<profile>/cordis.patch.yml` (`<profile>`: `web` or `desktop`):
+
+   ```yaml
+   - id: tool-office
+     name: '@deepseek-ai/dsh-tool-office'
+   ```
+
+7. Deployments that require sandboxed document parsing omit `@deepseek-ai/dsh-tool-office`.
+8. Update expected first request contexts and `/` menus with the Office skills.
+9. Confirm: in a new `standard` or `ptc` Session, send `/office`, then a separate PDF export request; it produces an `office_convert` call that returns a temporary PDF path or the `unavailable` message.