dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/upgrade-guide/v0.2.1-rc.2/conditional-tools/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "工具声明只来自步骤准入的注册：`system-prompt/assemble` 不再携带工具，条件工具需要已解析的步骤集合，`exit_plan_mode` 只在会话首次进入计划模式后声明。"
+---
+
+# 通过步骤准入声明条件工具
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ctx.tools.register(definition, { when })` 可以附加同步或异步条件。AgentLoop 在提示词组装与 `agent/pre-step` 之前，以 `{ agent, modelSelection, signal }` 为每个拟议步骤计算一次条件，并在该步骤及其重试中用得到的 `ResolvedToolSet` 决定工具声明、原生分发、PTC 绑定和嵌套调用。条件返回 false 时，工具从以上所有位置移除；条件抛错时，轮次以 `TOOL_ACTIVATION_FAILED` 结束。
+
+`system-prompt/assemble` waterfall 现在接收不含工具数组的段落、上下文与变量（`PromptPresentation`），返回的 `tools` 字段会被忽略。在这个 waterfall 中删除或添加工具声明的插件会受到影响：它们做的删除不再进入请求；读取 `assembly.tools` 的监听器会拿到 `undefined`，并在运行时出错。
+
+模型的工具调用只通过所属步骤的准入集合执行。没有已解析集合的条件工具调用、集合释放之后的调用，以及注册在步骤内被替换或移除时尚未开始的调用，都会返回 `UNKNOWN_TOOL`，不会执行。替换规则适用于所有工具，因此在步骤中途重新注册工具的热重载、MCP 重连或 skill 重载会让该步骤里这个工具尚未开始的调用失败。不传集合的调用方（例如实验性 `claude-code-mods` 的 `$.tool.call`）无法调用条件工具。
+
+`exit_plan_mode` 从已选计划状态首次为激活的步骤起声明，并在会话剩余部分保持声明，因此从未进入计划模式的会话，其请求不再列出它。现有 Session 无需格式迁移。
+
+## 迁移
+
+1. 把 `system-prompt/assemble` 监听器中的工具过滤和对 `assembly.tools` 的读取改为注册时的 `when` 条件；从条件的 `modelSelection` 读取该步骤的提供方、模型与推理强度。waterfall 中只保留段落、上下文与变量的修改。
+2. 让工具指引跟随同一准入：段落回调把 `context.toolSet` 传给 `ctx.tools.get()` 或 `ctx.tools.schemas()`。
+3. 程序化调用条件工具时，调用 `ctx.tools.resolve({ agent, modelSelection, signal })`，把返回的 `toolSet` 传给 `assemble()` 与 `ctx.tools.execute()` 批次，并在批次结束后释放。不使用共享 pipeline 的自定义执行器用 `ctx.tools.executable(name, agent, toolSet)` 查找每次调用。
+4. 更新在会话进入计划模式之前仍列出 `exit_plan_mode` 的期望。验证被禁用的工具不出现在请求中，用其名称调用会返回 `UNKNOWN_TOOL` 且不进入实现，条件失败时轮次以 `TOOL_ACTIVATION_FAILED` 结束。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "Custom Client compositions must provide the context-menu and file-action services required by GUI plugins."
+---
+
+# Context menu services in custom Client compositions
+
+English | [中文](guide.zh.md)
+
+## Change
+
+GUI plugins now inject `contextMenus` to open shared object menus. The open-in-app plugin also injects `fileActions`, `sidebarRight`, `sidebarRightTabs`, and `remote.workspaceFiles`. Custom compositions that mount these GUI plugins without the new services cannot activate them. The shipped Web application bundle includes the providers; existing Session and tab menu Slot names remain available.
+
+## Migration
+
+1. In the package manifest that owns a custom composition, add dependencies on `@deepseek-ai/dsh-client-ui-context-menu` and `@deepseek-ai/dsh-client-ui-file-actions` at the same Harness version.
+2. Add both package names as plugin rows in the custom Client composition alongside the existing locale, slots, shortcuts, sidebar, and workspace-file providers. The default `@deepseek-ai/dsh-web-app` bundle already contains these rows.
+3. Rename `ctx.menus` to `ctx.contextMenus` and `MenuTargetMap` to `ContextMenuTargetMap`; neither old name has an alias. Mount the menu plugin so its `ctx.slots.provideRoot` contribution supplies `useContextMenu` to every Slot. Components call the hook once and spread `getTriggerProps(target, handlers?)` onto each element, including elements created in loops. See the [menu reference](../../../../packages/client/ui-context-menu/README.md) for handler composition and external action registration.
+4. Rebuild and launch the custom profile. Confirm that GUI plugins activate, right-clicking a background Session preserves selection, and existing Session/tab Slot contributions still appear.
+5. Custom Slot hosts must remove their declarations of `sidebar.workspaces.session.menu.item` and `sidebar.right.tab.menu.item`; the workspace and right-sidebar adapters now own these under `contextMenu.content`. Session rows retain the `[open, setOpen]` hook context, and tab rows receive `{ tab, dismiss }` within the clicked Session’s provider. A custom host replacing these adapters must declare the same children and supply those owners itself. Dockkit embedders using `getTabTriggerProps` own the popup and dismissal; `renderTabMenuItems` is used only by the kit popup. Supply reactive `tabMenuOpen` to suppress close-button tooltips while a custom menu prepares or remains open.
+
+6. Built-in Session menu items are data contributions. The legacy React Slot retains external entries together before Archive; Slot priority no longer shadows built-in actions. Use `ctx.contextMenus.register` for new actions and optional `commandId` to display an existing command’s current binding. Keep captured-target execution in `run`; no command dispatch is added.
+7. Menu contributions use `icon?: ReactNode`; replace `symbol` with a glyph element and wrap icon URLs in `<img>`. Obtain `useContextMenu` at each actual Slot entry. Plain children receive `getTriggerProps` or bound `contextMenuProps`; ToolRow uses `fileContextMenuProps` and `urlContextMenuProps`. Remove menu fields from Chat flow/node owners. The assistant entry supplies an ordinary file adapter to `forClosing()`, while Markdown adapts its target type at `MarkdownDelegateProvider.getTriggerProps`. Keep Session identity and gesture-time path resolution in the business registration. Remove imports of `contextMenuTrigger` and `menuPoint`; their independent utility package is removed. Do not add gesture exports to ui-primitives.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "自定义 Client 组合必须提供 GUI 插件所需的右键菜单与文件动作服务。"
+---
+
+# 自定义 Client 组合中的右键菜单服务
+
+[English](guide.md) | 中文
+
+## 变更
+
+GUI 插件现在注入 `contextMenus` 以打开共享对象菜单。open-in-app 插件还注入 `fileActions`、`sidebarRight`、`sidebarRightTabs` 和 `remote.workspaceFiles`。自定义组合若挂载这些 GUI 插件却没有新服务，将无法激活它们。随附 Web 应用 bundle（插件包）已包含提供方；现有 Session 和标签页菜单 Slot 名称仍可使用。
+
+## 迁移
+
+1. 在自定义组合所属的包清单中，添加与 Harness 版本一致的 `@deepseek-ai/dsh-client-ui-context-menu` 和 `@deepseek-ai/dsh-client-ui-file-actions` 依赖。
+2. 在自定义 Client 组合中将两个包名添加为插件行，与已有 locale、slots、shortcuts、侧栏和工作区文件提供方并列。默认 `@deepseek-ai/dsh-web-app` bundle 已包含这些行。
+3. 将 `ctx.menus` 改为 `ctx.contextMenus`，将 `MenuTargetMap` 改为 `ContextMenuTargetMap`，旧名均无兼容别名。挂载菜单插件，由其 `ctx.slots.provideRoot` 贡献向每个 Slot 提供 `useContextMenu`。组件调用一次 hook，将 `getTriggerProps(target, handlers?)` 展开到每个元素，包括循环生成的元素。处理器组合和外部动作注册见[菜单参考](../../../../packages/client/ui-context-menu/README.zh.md)。
+4. 重新构建并启动自定义 profile（配置档）。确认 GUI 插件正常激活、右键后台 Session 不改变选择，且现有 Session/标签页 Slot 贡献仍然显示。
+5. 自定义 Slot 宿主应移除对 `sidebar.workspaces.session.menu.item` 和 `sidebar.right.tab.menu.item` 的声明；现在由工作区和右侧栏适配器在 `contextMenu.content` 下拥有它们。会话行继续接收 `[open, setOpen]` hook context，标签行在所点击会话的 provider 内接收 `{ tab, dismiss }`。替换这些适配器的自定义宿主须自行声明相同的子 Slot 并提供这些 owner。使用 `getTabTriggerProps` 的 Dockkit 嵌入方负责弹窗和关闭，`renderTabMenuItems` 仅供组件自身的弹窗使用。通过响应式 `tabMenuOpen` 在自定义菜单准备或显示时禁用关闭按钮的 Tooltip。
+
+6. 内置 Session 菜单项改为数据贡献。旧 React Slot 将外部条目集中显示在归档之前，Slot priority 不再覆盖内置动作。新增动作用 `ctx.contextMenus.register`，可通过 `commandId` 展示已有命令的当前绑定。针对捕获目标的执行仍放在 `run`，不增加命令调度。
+7. 菜单贡献使用 `icon?: ReactNode`：将 `symbol` 改为图标元素，并用 `<img>` 包装图标 URL。在每个实际 Slot 入口获取 `useContextMenu`。普通子组件接收 `getTriggerProps` 或绑定后的 `contextMenuProps`；ToolRow 使用 `fileContextMenuProps` 和 `urlContextMenuProps`。删除 Chat 消息流和节点 owner 的菜单字段。助手入口向 `forClosing()` 传入普通文件适配函数，Markdown 则在 `MarkdownDelegateProvider.getTriggerProps` 处适配目标类型。业务注册保留 Session 归属和触发时路径解析。删除 `contextMenuTrigger` 和 `menuPoint` 导入，其独立工具包已删除。不要向 ui-primitives 增加手势导出。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Computer Use application consent moves from profile configuration to durable profile-scoped storage."
+---
+
+# Computer Use consent storage
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Computer Use stores application consent through `storageDomain`. With the default JSON backend, each canonical profile directory has its own `$DSH_HOME/storages/cua_permissions_<sha256>.json`. “Allow for this session” now follows the conversation ID across DSH restart and Computer Use disablement. It does not authorize another conversation. Unverifiable applications still require a matching native process identity; restarting that application may require new consent.
+
+`allowedApps` is a legacy import source. The first store access imports it once. Subsequent configuration edits do not grant or revoke access, and a revoked grant is not restored by reloading the old configuration. The permission page remains the authoring interface for grants and refusals. macOS privileges are unchanged.
+
+## Migration
+
+1. Keep the profile's existing storage services mounted. Shipped profiles already include `storageDomain` and the JSON backend; custom profiles need the same services. A profile without domain storage refuses authorization operations.
+2. Enable Computer Use and open its details to initialize storage. Confirm that the always-allowed applications appear.
+3. Remove `allowedApps` from the CUA entry in the profile configuration and other overlays after confirmation. Keep the remaining CUA configuration.
+4. Use the permission page to revoke applications or allow asking again. Existing conversation-only grants held by an older running process cannot be recovered; grant those once after upgrading. Newly granted conversation access then survives restart.
+5. Keep the storage file with that profile's state. Moving the profile to a different real directory selects a different store. File locks coordinate processes on one machine, not different machines sharing a network filesystem.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Computer Use 应用授权从 profile 配置迁移到按 profile 隔离的持久存储。"
+---
+
+# Computer Use 授权存储
+
+[English](guide.md) | 中文
+
+## 变更
+
+Computer Use 通过 `storageDomain` 保存应用授权。使用默认 JSON 后端时，每个 profile 的真实目录对应独立的 `$DSH_HOME/storages/cua_permissions_<sha256>.json`。“本会话允许”现在按对话 ID 跨 DSH 重启和 Computer Use 启停保留，不授权其他对话。无法验证签名的应用仍需匹配本机进程身份，应用重启后可能需要重新授权。
+
+`allowedApps` 作为旧数据来源，只在首次访问存储时导入一次。此后修改配置不会授予或撤销访问权限，重新加载旧配置也不会恢复已撤销的许可。权限页继续提供授权管理和清除拒绝的操作。macOS 系统权限保持原样。
+
+## 迁移
+
+1. 保留 profile 的现有存储服务。随附 profile 已包含 `storageDomain` 和 JSON 后端，自定义 profile 需要挂载相同服务。有 profile 但没有域存储时，授权操作会被拒绝。
+2. 启用 Computer Use 并打开详情页，初始化存储。确认始终允许的应用显示正确。
+3. 确认后，从 profile 配置及其他覆盖层的 CUA 条目中删除 `allowedApps`，保留其他 CUA 配置。
+4. 在权限页撤销应用授权或允许再次询问。旧进程内已有的会话许可无法恢复，升级后需要重新授予一次；新授予的会话许可随后可跨重启保留。
+5. 将存储文件作为该 profile 的状态保留。把 profile 移到另一个真实目录后会使用不同存储。文件锁协调同一电脑上的进程，不支持多台电脑共用网络文件系统。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/cua-preset-scope/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Standalone native CUA compositions must explicitly select global tool registration."
+---
+
+# CUA defaults to PTC session scopes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The native CUA provider defaults `agentPreset` to `ptc`. It registers tools for existing and new PTC Agents, including when a saved application-grants configuration omits the new field. Custom compositions without an Agent preset registry no longer receive global CUA tools by default.
+
+## Migration
+
+1. For the standard Computer Use switch, keep the default; existing application grants remain usable.
+2. For a standalone composition that needs global tools, add `agentPreset: false` under the native CUA entry’s `config` in its profile patch or overlay. Preserve its other fields, including `allowedApps` and `helperPath`.
+3. Restart or let HMR apply the edit, then confirm that the intended Agent exposes `cua` in native mode or through the PTC SDK.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/cua-preset-scope/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "独立原生 CUA 组合需要显式选择全局工具注册。"
+---
+
+# CUA 默认使用 PTC 会话作用域
+
+[English](guide.md) | 中文
+
+## 变更
+
+原生 CUA 提供方的 `agentPreset` 默认为 `ptc`。工具注册到已有和新建 PTC Agent，即使保存的应用授权配置没有这个新字段也会生效。不包含 Agent preset 注册表的自定义组合不再默认获得全局 CUA 工具。
+
+## 迁移
+
+1. 使用标准 Computer Use 开关时保持默认值，已有应用授权仍可使用。
+2. 独立组合若需要全局工具，在 profile patch 或 overlay 的原生 CUA 条目 `config` 下添加 `agentPreset: false`，保留 `allowedApps`、`helperPath` 等其他字段。
+3. 重启或等待 HMR 应用后，确认目标 Agent 能在原生模式或 PTC SDK 中使用 `cua`。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/cua-relative-coordinates/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "CUA relative coordinates accept integers from 0 to 999 and reject the former endpoint 1000."
+---
+
+# CUA relative coordinates use 0–999
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `cua` tool and application/window object methods now accept integers from 0 to 999 when `relative: true`. The previous range was 0 to 1000. Coordinates still use thousandths: divide by 1000, scale to window dimensions, and clamp inside the window. Values from 0 to 999 keep their existing positions. This affects `click`, `hover`, `scroll`, and both `drag` endpoints. Absolute screenshot pixels and AX element indices are unchanged.
+
+## Migration
+
+1. Update scripts and prompts that generate relative coordinates. Keep existing values from 0 to 999 unchanged. Replace the old endpoint 1000 with 999, for example with `Math.min(oldValue, 999)` for valid old coordinates. On larger windows, 999 can land farther inside than the former endpoint 1000.
+2. Read fresh window state, then invoke the affected action with integer coordinates in 0–999. Verify the result with a fresh observation. Relative values of 1000, negative values, and fractions are rejected before native input.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/cua-relative-coordinates/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "CUA 相对坐标接受 0～999 的整数，并拒绝原端点 1000。"
+---
+
+# CUA 相对坐标使用 0～999
+
+[English](guide.md) | 中文
+
+## 变更
+
+`cua` 工具和应用或窗口对象方法在 `relative: true` 时接受 0～999 的整数，原范围为 0～1000。坐标仍使用千分比：除以 1000 后按窗口尺寸缩放，并限制在窗口内。0～999 的坐标保持原有落点。这影响 `click`、`hover`、`scroll` 和 `drag` 的起终点。绝对截图像素和 AX 元素编号保持原有行为。
+
+## 迁移
+
+1. 更新生成相对坐标的脚本和提示。0～999 的现有数值保持不变。将旧端点 1000 改为 999，例如对原本合法的旧坐标使用 `Math.min(oldValue, 999)`。在较大的窗口中，999 可能比原端点 1000 更靠内。
+2. 读取新的窗口状态后，使用 0～999 的整数坐标调用相应动作，再读取新状态验证结果。相对坐标为 1000、负数或小数时，会在原生输入前被拒绝。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/file-drag-callbacks/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Custom image factories and Markdown image delegates must supply file preparation callbacks."
+---
+
+# Supply file preparation callbacks to image views
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The published `conversation.images.content` Factory now requires a `fileDrag` inject member, and `MarkdownDelegate.fileImages` requires the same callbacks. `ChatViewInjected` also gains `fileDrag`. Custom registrations that construct these values must update before compilation succeeds. The shipped Web and Desktop compositions provide `@deepseek-ai/dsh-client-ui-file-drag`; custom compositions must provide the service and its feedback slot. Existing image label fields are unchanged.
+
+## Migration
+
+1. Include `@deepseek-ai/dsh-client-ui-file-drag` in the custom client composition, together with locale, the slot renderer, and a shell declaring `shell.overlay`. Declare `fileDrag` in each consumer plugin’s `inject` list.
+2. Pass `ctx.fileDrag.actions` as `fileDrag` when registering `conversation.images.content`, assembling `ChatViewInjected`, or constructing `MarkdownDelegate.fileImages`. The callbacks prepare Blob or URL content and report localized failures; components receive them explicitly. Optional `resourceAddress(path)` supplies a Session resource reference for authorized Desktop source reuse.
+3. Custom composer implementations can receive `ctx.fileDrag.read` through their own inject interface to accept application-local tokens. The `conversation.input.attachments` slot’s public props remain unchanged; only the shipped attachment implementation requires this callback. Accept internal drops in the composer region and retain ordinary `dataTransfer.files` handling for external files.
+4. Rebuild custom packages and verify an image drag into the composer. Confirm the original filename and bytes and that dropping back on the source does not add an attachment. See the [file-drag plugin](../../../../packages/client/ui-file-drag/README.md) for ownership and browser limitations.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/file-drag-callbacks/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "自定义图片 Factory 和 Markdown 图片委托必须提供文件准备回调。"
+---
+
+# 为图片视图提供文件准备回调
+
+[English](guide.md) | 中文
+
+## 变更
+
+已发布的 `conversation.images.content` Factory 现在要求 `fileDrag` 注入成员，`MarkdownDelegate.fileImages` 也要求相同回调。`ChatViewInjected` 同样新增 `fileDrag`。构造这些值的自定义注册必须更新才能通过编译。内置 Web 和 Desktop 组合提供 `@deepseek-ai/dsh-client-ui-file-drag`；自定义组合必须提供该服务及其反馈插槽。已有图片文案字段不变。
+
+## 迁移
+
+1. 在自定义客户端组合中加载 `@deepseek-ai/dsh-client-ui-file-drag`，同时提供 locale、插槽渲染器和声明 `shell.overlay` 的外壳。在每个消费插件的 `inject` 列表中声明 `fileDrag`。
+2. 注册 `conversation.images.content`、组装 `ChatViewInjected` 或构造 `MarkdownDelegate.fileImages` 时，将 `ctx.fileDrag.actions` 作为 `fileDrag` 传入。回调负责准备 Blob 或 URL 内容及报告本地化失败；组件显式接收它们。可选的 `resourceAddress(path)` 提供 Session 资源引用，以便 Desktop 经授权后复用源文件。
+3. 自定义输入框实现可通过自己的注入接口接收 `ctx.fileDrag.read`，以接受应用内令牌。`conversation.input.attachments` 插槽的公开 props 不变；只有内置附件实现要求该回调。内部投放仅在输入框范围接受，外部文件保留普通 `dataTransfer.files` 处理。
+4. 重新构建自定义包，验证图片拖入输入框后的原始文件名和字节，并确认拖回源图不会增加附件。所有权和浏览器限制见[文件拖放插件](../../../../packages/client/ui-file-drag/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/headless-policy-composition/guide.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "Headless compositions that disable the command-line provider must supply their sandbox policy configuration directly."
+---
+
+# Configure policy when replacing headless startup
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The headless bundle reads `--add-dir` through `headlessStartup` before activating its sandbox policy. An overlay that disables `headless-startup` must also remove that dependency from `sandbox-policy`. Otherwise the policy and its dependent tools remain pending. Ordinary `dsh headless` invocations need no configuration change.
+
+## Migration
+
+1. In the overlay that disables `headless-startup`, supply the policy directly. Retain any existing policy settings in this replacement config:
+
+   ```yaml
+   - id: sandbox-policy
+     inject: []
+     config:
+       mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
+       workspaceRoot: !!js process.cwd()
+   ```
+
+2. If the overlay keeps command-line startup but replaces `headless-runner` or `sandbox-policy`, retain their `headlessStartup` bindings from the [headless bundle](../../../../packages/bundle/headless/cordis.patch.yml).
+3. Launch a small task through the custom profile and verify that its tools activate. If startup remains enabled, pass `--add-dir` and check that a write to the selected directory succeeds.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/headless-policy-composition/guide.zh.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "禁用命令行提供方的 Headless 组合必须直接提供沙箱策略配置。"
+---
+
+# 替换 headless startup 时配置策略
+
+[English](guide.md) | 中文
+
+## 变更
+
+headless 组合包在激活沙箱策略前，通过 `headlessStartup` 读取 `--add-dir`。禁用 `headless-startup` 的 overlay 也必须从 `sandbox-policy` 移除该依赖，否则策略及其依赖工具会保持 pending 状态。普通 `dsh headless` 调用无需修改配置。
+
+## 迁移
+
+1. 在禁用 `headless-startup` 的 overlay 中直接提供策略。在此替换配置中保留已有策略设置：
+
+   ```yaml
+   - id: sandbox-policy
+     inject: []
+     config:
+       mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
+       workspaceRoot: !!js process.cwd()
+   ```
+
+2. 如果 overlay 保留命令行 startup，但替换了 `headless-runner` 或 `sandbox-policy`，请保留 [headless 组合包](../../../../packages/bundle/headless/cordis.patch.yml)中的 `headlessStartup` 绑定。
+3. 通过自定义配置档运行一个小任务并确认工具已激活。如果保留 startup，请传入 `--add-dir`，并检查对所选目录的写入是否成功。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The fixed 1017 model badge package is removed; model badges come from the DeepSeek model listing."
+---
+# The `ui-deepseek-model-label-1017` package is removed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` and its `ui-deepseek-model-label-1017` row in the Web bundle are removed, and the package receives no further releases. The composer model selector shows the badge that the DeepSeek `GET /models` listing declares for a model; without a declared badge, `DeepSeek-V4.1-Flash` shows no `1017`. A profile patch that disables or edits the removed row matches no entry, so boot warns that the entry is not found and skips the patch.
+
+## Migration
+
+1. Delete the patch whose `id` is `ui-deepseek-model-label-1017`, with its `disabled` or other fields, from `$DSH_HOME/profiles/<profile>/cordis.patch.yml` and from any overlay passed with `--patch`.
+2. Remove `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` from the dependencies of any package that lists it.
+3. To change how model names or badges render, contribute to the `conversation.input.model.label` slot; its owner props carry the catalog `model.badge` ([label extensions](../../../../packages/client/ui-model-selection/README.md#use-this-package)).
+4. Restart DSH and confirm that boot reports no missing `ui-deepseek-model-label-1017` entry.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/model-badge-package-removal/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "固定的 1017 模型角标包已移除，模型角标改由 DeepSeek 模型列表下发。"
+---
+# `ui-deepseek-model-label-1017` 包已移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-deepseek-model-label-1017` 及其在 Web bundle 中的 `ui-deepseek-model-label-1017` 条目已移除，该包不再发布新版本。composer 模型选择器显示 DeepSeek `GET /models` 列表为模型声明的角标；列表没有声明角标时，`DeepSeek-V4.1-Flash` 不再显示 `1017`。停用或修改该条目的 profile patch 不再匹配任何条目，启动时会警告找不到该条目并跳过这条 patch。
+
+## 迁移
+
+1. 从 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 以及通过 `--patch` 传入的 overlay 中，删除 `id` 为 `ui-deepseek-model-label-1017` 的 patch，连同其中的 `disabled` 或其他字段。
+2. 若有包在依赖中列出 `@deepseek-ai/dsh-client-ui-deepseek-model-label-1017`，将其删除。
+3. 如需改变模型名称或角标的显示方式，向 `conversation.input.model.label` slot 注册组件；其 owner props 携带目录中的 `model.badge`（[名称扩展](../../../../packages/client/ui-model-selection/README.zh.md#use-this-package)）。
+4. 重启 DSH，确认启动输出中没有找不到 `ui-deepseek-model-label-1017` 条目的警告。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/new-session-blank-reuse/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "New Session reuses a blank Session in the Workspace again instead of creating a fresh Agent on every call."
+---
+
+# New Session returns to its blank Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In 0.2.1-rc.2, New Session in Web and Desktop, and `uiWorkspace.startSession(workspaceId)` without options, created a fresh Session and Agent on every call ([earlier guide](../../v0.2.1-alpha.1/new-session-generations/guide.md)). The blank Session it left behind is hidden from the Session tree, so its unsent draft could no longer be reached.
+
+New Session now reuses the first unstarted, unarchived blank Session in the Workspace, which the Host switches to its default preset, and creates a Session only when none exists. `startSession` with options, `openWorkspace`, and `connectWorkspace` follow the same rule; a request that names an Agent preset skips blanks whose listed preset is a different one, so preset flows such as the Creator entries do not take over another preset's draft.
+
+A reused blank whose Agent is still loaded keeps the preset composition it was created with. New Session no longer guarantees the current preset definition.
+
+## Migration
+
+1. After changing a preset definition, start the conversation in a Session whose Agent was composed after the change, for example by restarting the Host before using New Session; a blank resumed after a restart composes the current definition.
+2. Client integrations that must not take over a blank listing another preset pass `{ agentPreset }` to `startSession`, `openWorkspace`, or `connectWorkspace`.
+3. To confirm, type a draft after New Session, open another Session, and use New Session again: the same blank opens with the draft.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/new-session-blank-reuse/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "新会话重新复用工作区内的空白 Session，不再每次都创建新的 Agent。"
+---
+
+# 新会话回到其空白 Session
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 0.2.1-rc.2 中，Web 和 Desktop 的新会话，以及不带选项的 `uiWorkspace.startSession(workspaceId)`，每次调用都创建新的 Session 和 Agent（[此前的指南](../../v0.2.1-alpha.1/new-session-generations/guide.zh.md)）。被留下的空白 Session 不在 Session 树中显示，因此其中未发送的草稿无法再回到。
+
+现在新会话复用工作区内第一个未开始、未归档的空白 Session，由 Host 切换到其默认 preset，没有空白 Session 时才创建。带选项的 `startSession`、`openWorkspace` 和 `connectWorkspace` 采用相同规则；指明 Agent preset 的请求会跳过列出其他 preset 的空白会话，因此创造模式入口等 preset 流程不会接管其他 preset 的草稿。
+
+被复用的空白会话若其 Agent 仍在加载状态，会保留创建时的 preset 装配。新会话不再保证使用当前的 preset 定义。
+
+## 迁移
+
+1. 更改 preset 定义后，在 Agent 于更改之后装配的 Session 中开始对话，例如先重启 Host 再使用新会话；重启后恢复的空白会话会按当前定义装配。
+2. 不能接管列出其他 preset 的空白会话的客户端集成，向 `startSession`、`openWorkspace` 或 `connectWorkspace` 传入 `{ agentPreset }`。
+3. 确认方式：新会话中输入草稿，打开另一个 Session，再使用新会话，应打开同一个空白会话并显示该草稿。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/node-24/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DSH requires Node.js 24.9 or newer and no longer supports Node.js 22."
+---
+# Node.js 24 is required
+
+English | [中文](guide.zh.md)
+
+## Change
+
+DSH requires Node.js 24.9 or newer. The previous release also supported Node.js 22.19 and newer releases in the 22.x line. This change affects npm installations, source checkouts, and the Python SDK's explicit `DSH_RUNTIME_MODE=node` development carrier. Packaged desktop applications and the Python SDK's bundled executable provide their own runtime.
+
+## Migration
+
+1. Upgrade the Node.js installation used to start DSH to version 24.9 or newer. Update Node version pins in development environments, containers, and CI jobs.
+2. Run `node --version` in the same environment and confirm that it reports version 24.9 or newer.
+3. For a source checkout, run `pnpm install`. Start DSH with the profile you normally use and confirm that it starts successfully.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/node-24/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DSH 要求 Node.js 24.9 或更高版本，不再支持 Node.js 22。"
+---
+# 必须使用 Node.js 24
+
+[English](guide.md) | 中文
+
+## 变更
+
+DSH 要求 Node.js 24.9 或更高版本。上一版本还支持 Node.js 22.19 及 22.x 系列中的后续版本。此变更影响 npm 安装、源码检出，以及 Python SDK 显式指定 `DSH_RUNTIME_MODE=node` 的开发载体。打包的桌面应用和 Python SDK 的内置可执行文件自带运行时。
+
+## 迁移
+
+1. 将用于启动 DSH 的 Node.js 安装升级至 24.9 或更高版本。更新开发环境、容器和 CI 任务中固定的 Node 版本。
+2. 在同一环境中运行 `node --version`，确认版本为 24.9 或更高版本。
+3. 对于源码检出，运行 `pnpm install`。使用平常的 profile 启动 DSH，确认它能成功启动。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/official-bundle-lists/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The bundle lists and profile templates move from @deepseek-ai/dsh-app-boot to @deepseek-ai/dsh-official-bundles."
+---
+
+# Import bundle lists from `@deepseek-ai/dsh-official-bundles`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-app-boot` no longer exports `PROFILE_TEMPLATES`, `ProfileTemplate`, `DEFAULT_PROFILE_BUNDLES`, `OPTIONAL_BUNDLES`, `ON_DEMAND_BUNDLES`, `OFFICIAL_ON_DEMAND_CATALOG`, or `OfficialBundleCatalogEntry`. The new published package `@deepseek-ai/dsh-official-bundles` exports them with unchanged values and types. Code that imports any of these names from `@deepseek-ai/dsh-app-boot` fails to compile or load. The `dsh` launcher, profiles, and bundle selection behave as before.
+
+## Migration
+
+1. Add `@deepseek-ai/dsh-official-bundles` to the `dependencies` of each package that imports one of these names.
+2. Change those imports from `@deepseek-ai/dsh-app-boot` to `@deepseek-ai/dsh-official-bundles`, for example `import { PROFILE_TEMPLATES } from '@deepseek-ai/dsh-official-bundles'`. Keep importing every other name, such as `initProfile` or `loadProfile`, from `@deepseek-ai/dsh-app-boot`.
+3. Run your type check or build; it succeeds when no import of a moved name from `@deepseek-ai/dsh-app-boot` remains. See the [package README](../../../../packages/util/official-bundles/README.md) for each list.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/official-bundle-lists/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "组合包列表和 profile 模板从 @deepseek-ai/dsh-app-boot 移至 @deepseek-ai/dsh-official-bundles。"
+---
+
+# 从 `@deepseek-ai/dsh-official-bundles` 导入组合包列表
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-app-boot` 不再导出 `PROFILE_TEMPLATES`、`ProfileTemplate`、`DEFAULT_PROFILE_BUNDLES`、`OPTIONAL_BUNDLES`、`ON_DEMAND_BUNDLES`、`OFFICIAL_ON_DEMAND_CATALOG` 和 `OfficialBundleCatalogEntry`。新发布的包 `@deepseek-ai/dsh-official-bundles` 导出它们，值和类型不变。从 `@deepseek-ai/dsh-app-boot` 导入这些名称的代码将无法编译或加载。`dsh` 启动器、profile 和组合包选择的行为不变。
+
+## 迁移
+
+1. 在每个导入这些名称的包的 `dependencies` 中加入 `@deepseek-ai/dsh-official-bundles`。
+2. 把这些导入从 `@deepseek-ai/dsh-app-boot` 改为 `@deepseek-ai/dsh-official-bundles`，例如 `import { PROFILE_TEMPLATES } from '@deepseek-ai/dsh-official-bundles'`。其他名称（如 `initProfile` 或 `loadProfile`）仍从 `@deepseek-ai/dsh-app-boot` 导入。
+3. 运行类型检查或构建；不再有从 `@deepseek-ai/dsh-app-boot` 导入已移动名称的代码时即通过。各列表的说明见[包 README](../../../../packages/util/official-bundles/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/persistent-terminal-controls/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Persistent-terminal bundle controls leave the Plugins page; profile configuration still enables and disables the bundle."
+---
+
+# Manage persistent terminals through profile configuration
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Web and Desktop no longer show the persistent-terminal bundle in Plugins lists or detail pages, including for profiles that already enabled it. The package and existing activation remain intact. The minimal preset's own persistent shell is independent of this bundle.
+
+## Migration
+
+1. To keep an existing selection, no action is required. To change it, open `$DSH_HOME/profiles/<name>/package.json`, where the default home is `~/.dsh` and `<name>` is the running profile, such as `web` or `desktop`.
+2. Remove `@deepseek-ai/dsh-experimental-terminal-bundle` from `dsh.profile.bundles` to disable it, or add it to enable it. Keep the other entries and dependencies intact.
+3. Restart the same profile to apply the selection. For a CLI-managed profile, run `dsh --profile <name> --dump-config`: the `optional-persistent-terminals` group is present only when the bundle is selected. See the [profile reference](../../../../apps/cli/reference/README.md#profile-boot).

package/kb/extra/upgrade-guide/v0.2.1-rc.2/persistent-terminal-controls/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "持久终端组合包开关移出插件页，仍可通过 profile 配置启用或关闭组合包。"
+---
+
+# 通过 profile 配置管理持久终端
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 和 Desktop 的插件列表和详情页不再显示持久终端组合包，包括此前已启用它的 profile。包及已有启用状态保持不变。minimal 预设自带的持久 shell 独立于此组合包。
+
+## 迁移
+
+1. 保留已有选择无需操作。如需更改，打开 `$DSH_HOME/profiles/<name>/package.json`，home 默认为 `~/.dsh`，`<name>` 是运行中的 profile，例如 `web` 或 `desktop`。
+2. 从 `dsh.profile.bundles` 中移除 `@deepseek-ai/dsh-experimental-terminal-bundle` 即可关闭，加入即可启用。保留其他条目和依赖。
+3. 重启同一个 profile 后生效。对于 CLI 管理的 profile，运行 `dsh --profile <name> --dump-config`：只有选中此组合包时，配置才包含 `optional-persistent-terminals` 分组。详见 [profile 参考](../../../../apps/cli/reference/README.zh.md#profile-boot)。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/pi-ai-default-capacities/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Undescribed pi-ai models inherit larger context and output capacities unless the provider configures explicit defaults."
+---
+
+# pi-ai default model capacities
+
+English | [中文](guide.zh.md)
+
+## Change
+
+For models whose capacity is absent from both configuration and the installed catalog, `llm-pi-ai` raises `defaultContextWindow` from 262,144 to 1,000,000 tokens and `defaultMaxTokens` from 32,768 to 128,000 tokens. A larger assumed context window can delay automatic compaction. Explicit model capacities, catalog values, and provider defaults retain their precedence. The output-capacity fallback does not become a Harness request-level `maxTokens` default.
+
+## Migration
+
+1. Check the actual limits of custom endpoints. In the `llm-pi-ai` configuration in `cordis.patch.yml`, set `providers.<provider>.defaultContextWindow` and `providers.<provider>.defaultMaxTokens` when those limits differ. To retain the previous defaults, use `262144` and `32768` respectively.
+2. For models with different limits on the same provider, set `contextWindow` and `maxTokens` on their `providers.<provider>.models` entries. An explicitly configured model `maxTokens` also supplies the Harness request default.
+3. Reopen the profile configuration and confirm the saved numeric values. See the [provider configuration reference](../../../../packages/llm/llm-pi-ai/README.md).

package/kb/extra/upgrade-guide/v0.2.1-rc.2/pi-ai-default-capacities/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "配置和目录均未描述容量的 pi-ai 模型会继承更大的上下文与输出容量，除非提供方显式配置默认值。"
+---
+
+# pi-ai 默认模型容量
+
+[English](guide.md) | 中文
+
+## 变更
+
+对于配置和已安装目录均未提供容量的模型，`llm-pi-ai` 将 `defaultContextWindow` 从 262,144 提高到 1,000,000 tokens，将 `defaultMaxTokens` 从 32,768 提高到 128,000 tokens。更大的假定上下文窗口可能推迟自动压缩。显式模型容量、目录值和提供方默认值仍保留原有优先级。输出容量回退值不会成为 Harness 请求级 `maxTokens` 默认值。
+
+## 迁移
+
+1. 核对自定义端点的实际限制。如果限制不同，在 `cordis.patch.yml` 的 `llm-pi-ai` 配置中设置 `providers.<provider>.defaultContextWindow` 和 `providers.<provider>.defaultMaxTokens`。如需保留原默认值，分别填写 `262144` 和 `32768`。
+2. 同一提供方的模型限制不同时，在相应 `providers.<provider>.models` 条目上设置 `contextWindow` 和 `maxTokens`。显式配置的模型 `maxTokens` 同时提供 Harness 请求默认值。
+3. 重新打开 profile 配置，确认保存的数值。参见[提供方配置参考](../../../../packages/llm/llm-pi-ai/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/pi-ai-model-catalog/guide.md

@@ -0,0 +1,53 @@
+---
+kind: upgrade-guide
+description: "The pi-ai 1.3.0 catalog removes model IDs and lowers some model capacities."
+---
+
+# pi-ai 1.3.0 model catalog changes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The pi-ai dependency changes from 1.1.0 to 1.3.0. These chat model IDs leave the catalog. Stored `modelOverrides` report missing-catalog diagnostics; new overrides are rejected. Explicit `models` entries lose their catalog defaults.
+
+| Provider | Removed model IDs |
+|---|---|
+| `google-vertex` | `gemini-flash-latest`, `gemini-flash-lite-latest` |
+| `nvidia` | `moonshotai/kimi-k3`, `nvidia/nemotron-3-super-120b-a12b` |
+| `opencode` | `exo-free`, `fledge-alpha-free`, `ling-3.0-flash-fin-free`, `ling-3.1-flash-free` |
+| `opencode-go` | `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp`, `grok-4.6`, `minimax-m2.7` |
+| `openrouter` | `anthropic/claude-sonnet-4`, `apodex/apodex-1.1-mini:free`, `inclusionai/ling-3.0-flash-fin`, `inclusionai/ling-3.0-flash-sante:free`, `qwen/qwen-plus-2025-07-28`, `qwen/qwen3-235b-a22b`, `qwen/qwen3-30b-a3b-thinking-2507`, `qwen/qwen3-8b`, `qwen/qwen3-coder-plus`, `qwen/qwen3-max`, `qwen/qwen3-max-thinking`, `qwen/qwen3-vl-235b-a22b-thinking`, `qwen/qwen3-vl-32b-instruct`, `qwen/qwen3-vl-8b-thinking`, `qwen/qwen3.6-max-preview`, `sao10k/l3.1-euryale-70b`, `unbiased/pareto`, `unbiased/pareto-26.10-preview` |
+| `vercel-ai-gateway` | `alibaba/qwen-3.6-max-preview`, `alibaba/qwen3-235b-a22b-thinking`, `alibaba/qwen3-coder-plus`, `alibaba/qwen3-max`, `alibaba/qwen3-max-preview`, `alibaba/qwen3-vl-235b-a22b-instruct`, `alibaba/qwen3-vl-thinking`, `anthropic/claude-3-haiku`, `anthropic/claude-opus-4`, `inclusionai/ling-3.1-flash-free` |
+
+These catalog limits decrease. Values are tokens; `—` means that limit did not decrease. Explicit overrides still take precedence. `maxTokens` describes model capacity, not an implicit request limit.
+
+| Provider/model | New contextWindow / maxTokens |
+|---|---|
+| `anthropic/claude-sonnet-4-5` | 200000 / — |
+| `anthropic/claude-sonnet-4-5-20250929` | 200000 / — |
+| `openrouter/deepseek/deepseek-v4-flash` | 1048575 / 943717 |
+| `openrouter/inclusionai/ling-3.0-flash-vl` | 131072 / — |
+| `openrouter/meta-llama/llama-4-scout` | 131072 / — |
+| `openrouter/minimax/minimax-m2` | — / 131072 |
+| `openrouter/minimax/minimax-m2.5` | 198000 / 32768 |
+| `openrouter/minimax/minimax-m2.7` | — / 131072 |
+| `openrouter/moonshotai/kimi-k2-thinking` | — / 98304 |
+| `openrouter/nvidia/nemotron-3-ultra-550b-a55b` | 202800 / — |
+| `openrouter/openai/gpt-oss-120b` | — / 65536 |
+| `openrouter/qwen/qwen3-235b-a22b-thinking-2507` | 128000 / 16384 |
+| `openrouter/qwen/qwen3.5-35b-a3b` | 256000 / 16384 |
+| `openrouter/qwen/qwen3.8-2.4t-a95b` | 1000000 / — |
+| `openrouter/qwen/qwen3.8-27b` | 262144 / — |
+| `openrouter/~z-ai/glm-latest` | — / 131072 |
+| `radius/claude-sonnet-4-5` | 200000 / — |
+| `vercel-ai-gateway/alibaba/qwen3-coder` | — / 32768 |
+| `vercel-ai-gateway/deepseek/deepseek-v4.1-flash-fast` | — / 32768 |
+
+The `vercel-ai-gateway` model `alibaba/qwen-3-235b` is now non-reasoning. Protocol and effort changes have a [separate guide](../pi-ai-protocol-replay/guide.md).
+
+## Migration
+
+1. In Settings → Models, replace removed IDs with supported models. Check endpoints, capabilities, and prices; IDs have no automatic replacement.
+2. Update selections in `cordis.patch.yml`, preset patches, and affected Sessions. Remove obsolete `providers.<provider>.modelOverrides.<id>` entries and replace removed IDs in `providers.<provider>.models` lists. See the [configuration reference](../../../../packages/llm/llm-pi-ai/README.md).
+3. Review capacity and reasoning overrides against the endpoint's supported values. Start the profile, confirm the model has no configuration diagnostic, and send a short prompt.