dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Custom file-action menus must offer save-as only on Desktop and browser downloads on Web."
+---
+
+# File downloads on Web
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Web file-action service no longer offers save-as through a browser file picker. `canSaveAs` is always false on Web, and `save(source, 'saveAs')` rejects before reading the source. Built-in Web file and image menus offer Download and omit Save as. Desktop still offers both actions; successful saves return the absolute destination `path` instead of an opaque file ID.
+
+## Migration
+
+1. Custom Client menus should include Save as only when `ctx.fileActions.canSaveAs` is true.
+2. On Web, call `ctx.fileActions.save(source, 'download')`. The browser handles the original content and suggested filename; a `requested` result means download started, not completed. Do not report a saved local path.
+3. Replace `savedFile(url)` and `reveal(id)` calls with an action on the completed `saved` result, using its `path` with `session.openWorkspacePath`. Keep original-file context-menu reveal independent of saved destinations.
+4. Verify that Web file and image menus expose Download without Save as, including browsers that support `showSaveFilePicker`. Verify that Desktop image menus retain both actions. See the [file-action reference](../../../../packages/client/ui-file-actions/README.md) for save results and feedback ownership.

package/kb/extra/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "自定义文件动作菜单应仅在 Desktop 提供另存为，在 Web 使用浏览器下载。"
+---
+
+# Web 文件下载
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 文件动作服务不再通过浏览器文件选择器提供另存为。Web 的 `canSaveAs` 始终为 false，`save(source, 'saveAs')` 会在读取来源前拒绝。内置 Web 文件和图片菜单提供「下载」，不显示「另存为」。Desktop 仍提供两种操作；保存成功后返回目标绝对路径 `path`，不再返回不透明文件 ID。
+
+## 迁移
+
+1. 自定义 Client 菜单仅在 `ctx.fileActions.canSaveAs` 为 true 时添加「另存为」。
+2. Web 端调用 `ctx.fileActions.save(source, 'download')`。浏览器处理原始内容和建议文件名；`requested` 结果仅表示下载已开始，不代表完成。不要报告本机保存路径。
+3. 将 `savedFile(url)` 和 `reveal(id)` 调用替换为完成后 `saved` 结果上的操作，使用其中的 `path` 调用 `session.openWorkspacePath`。原文件右键定位应独立于保存目标。
+4. 验证 Web 文件和图片菜单只有「下载」而没有「另存为」，包括支持 `showSaveFilePicker` 的浏览器；验证 Desktop 图片菜单保留两种操作。保存结果与提示的归属参见[文件动作参考](../../../../packages/client/ui-file-actions/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.1-rc.3/web-search-defaults/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "One web_search call accepts 10 queries and returns 10 sources by default, and the DeepSeek Search API provider paces its requests."
+---
+
+# Web search defaults
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In `dsh-tool-web`, the `searchMaxQueries` default rises from 4 to 10 and the `searchMaxResults` default rises from 8 to 10. The `web_search` schema now advertises `1–10 search queries`, so a call with 5–10 queries runs instead of failing validation, and each call can return up to 10 sources. A call can therefore start more provider searches and add more source text to the context. With the shipped Messages search provider, each query is one auxiliary model request. `dsh-web-deepseek-api` adds `searchRequestsPerSecond`, default 5: its Search provider sends at most that many requests in any one-second window, so the second five queries of a 10-query call start one second after the first instead of exceeding the account's 5 QPS limit. Values that a deployment already sets are kept.
+
+## Migration
+
+1. To keep the previous limits, set `searchMaxQueries: 4` and `searchMaxResults: 8` in the `tool-web` entry's `config` in `cordis.patch.yml`.
+2. If several processes share one DeepSeek account through the Search API, lower `searchRequestsPerSecond` in the `web-deepseek-api` entry so that their combined rate stays at or below 5.
+3. Confirm the result by running a task that sends 10 queries in one `web_search` call: it returns results instead of `Error: queries must contain at most 4 queries`. See the [tool-web configuration](../../../../packages/web/tool-web/README.md).

package/kb/extra/upgrade-guide/v0.2.1-rc.3/web-search-defaults/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "一次 web_search 调用默认接受 10 个查询并返回 10 个来源，DeepSeek Search API 提供方会为请求限速。"
+---
+
+# Web 搜索默认值
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 `dsh-tool-web` 中，`searchMaxQueries` 默认值从 4 提高到 10，`searchMaxResults` 默认值从 8 提高到 10。`web_search` 的 schema 现在公布 `1–10 search queries`，因此含 5–10 个查询的调用会执行，而不是校验失败；每次调用最多返回 10 个来源。因此一次调用可能发起更多提供方搜索，并向上下文加入更多来源文本。使用内置的 Messages 搜索提供方时，每个查询都是一次辅助模型请求。`dsh-web-deepseek-api` 新增 `searchRequestsPerSecond`，默认 5：其 Search 提供方在任意一秒窗口内最多发送这么多请求，因此 10 个查询的调用中后五个查询比前五个晚一秒开始，而不会超过账号的 5 QPS 限制。部署已设置的值保持不变。
+
+## 迁移
+
+1. 如需保留原上限，在 `cordis.patch.yml` 的 `tool-web` 条目 `config` 中设置 `searchMaxQueries: 4` 和 `searchMaxResults: 8`。
+2. 如果多个进程通过 Search API 共享同一个 DeepSeek 账号，在 `web-deepseek-api` 条目中调低 `searchRequestsPerSecond`，使它们的合计速率不超过 5。
+3. 运行一个在一次 `web_search` 调用中发送 10 个查询的任务来确认：调用返回结果，而不是 `Error: queries must contain at most 4 queries`。参见 [tool-web 配置](../../../../packages/web/tool-web/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "DeepSeek model listings refresh automatically after first use, and custom listing-cache owners must supply live settings and change notifications."
+---
+# Model listings refresh automatically
+
+English | [中文](guide.zh.md)
+
+## Change
+
+DeepSeek account and API-key routes refresh their model listing automatically after first use, including while idle. `modelsMaxAgeMs` keeps its ten-minute default and now schedules background requests instead of waiting for another access. Failed refreshes retain the last successful listing, including badges. Successful refreshes replace badge metadata, including omission or `null`, and notify open Web selectors.
+
+`ModelListingCache` consumers must supply `settings` and `changed` callbacks. Its `dispose()` now returns a promise that settles after active loads and automatic credential lookups finish. `ListedCatalog` also requires a `badges` map, and `ModelSelectInjected` requires a `resolveText` callback.
+
+## Migration
+
+1. Keep existing `modelsMaxAgeMs` values to use the same interval for automatic refresh. Use `0` only when each access should refresh and no automatic timer should run.
+2. Custom `ModelListingCache` owners must provide `settings: () => ListingSettings | undefined` for the latest route configuration and `changed: () => void` to notify catalog consumers. Return `undefined` from `settings` when the route stops following a listing.
+3. Return or await `cache.dispose()` from the owning plugin's cleanup.
+4. Code that constructs `ListedCatalog` must include `badges: new Map()` when it has no badges, or a map from model id to `LlmModelBadge`. Prefer `resolveListedCatalog` to construct this result from decoded listing entries.
+5. Code that constructs `ModelSelectInjected` must provide `resolveText: text => ctx.locale.resolveText(text)` from its owning locale service. Test doubles can use `text => typeof text === 'string' ? text : text.en` when they intentionally render English.
+6. After the next refresh, confirm that an already-open model selector displays the current badge without reloading the page. Remove the badge field or set it to `null` to clear it.

package/kb/extra/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "DeepSeek 模型列表首次使用后自动刷新，自定义列表缓存的持有者必须提供实时配置与变化通知。"
+---
+# 模型列表自动刷新
+
+[English](guide.md) | 中文
+
+## 变更
+
+DeepSeek 账号与 API key 路由首次使用模型列表后会自动刷新，空闲时也会刷新。`modelsMaxAgeMs` 保留十分钟默认值，现在会安排后台请求，无需等待下一次访问。刷新失败时保留上次成功加载的列表及其角标。刷新成功时替换角标元数据，省略或 `null` 也会生效，并通知已打开的 Web 选择器。
+
+`ModelListingCache` 的消费方必须提供 `settings` 与 `changed` 回调。其 `dispose()` 现在返回一个 promise，等待进行中的加载与自动凭据查询结束后才完成。`ListedCatalog` 还要求提供 `badges` 映射，`ModelSelectInjected` 要求提供 `resolveText` 回调。
+
+## 迁移
+
+1. 保留现有 `modelsMaxAgeMs` 值即可按相同间隔自动刷新。只有需要每次访问都刷新、且不运行自动定时器时，才使用 `0`。
+2. 自定义 `ModelListingCache` 持有者必须提供 `settings: () => ListingSettings | undefined` 以读取最新路由配置，并通过 `changed: () => void` 通知目录消费方。路由停止跟随列表时，`settings` 返回 `undefined`。
+3. 在持有该缓存的插件清理函数中返回或等待 `cache.dispose()`。
+4. 构造 `ListedCatalog` 的代码在没有角标时必须提供 `badges: new Map()`，否则提供模型 id 到 `LlmModelBadge` 的映射。优先使用 `resolveListedCatalog` 从已解码的列表条目构造该结果。
+5. 构造 `ModelSelectInjected` 的代码必须通过所属的 locale 服务提供 `resolveText: text => ctx.locale.resolveText(text)`。明确使用英语渲染的测试替身可以使用 `text => typeof text === 'string' ? text : text.en`。
+6. 下一次刷新后，确认已打开的模型选择器无需重新加载页面就显示当前角标。移除角标字段或将其设为 `null` 即可清除角标。

package/kb/extra/upgrade-guide/v0.2.1-rc.4/reasoning-body-props/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Reasoning Body Slot text carries display-ready content, with original output in rawText."
+---
+
+# Reasoning Body Slot text fields
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Contributions to `conversation.chat.reasoning.body` receive the model output in the new `rawText` field. The existing `text` field supplies Chat's prepared display text instead of the original output. `running` is unchanged. This affects custom reasoning renderers and translation wrappers.
+
+The `conversation.chat.reasoning.content` Factory still accepts `text`, `running`, and optional `labels`. It renders the caller-selected Markdown. The [Chat README](../../../../packages/client/ui-chat/README.md#grouped-rendering) documents the Slot.
+
+## Migration
+
+1. Keep reading `text` for ordinary rendering, translation requests, and untranslated views. Update extensions that need the full model output to read `rawText`.
+2. Pass the selected `text`, or its translation, to the Content Factory without repeating Chat's display processing.
+3. Rebuild the extension and verify streamed and settled rendering, translation, and the untranslated view with each supported model format.

package/kb/extra/upgrade-guide/v0.2.1-rc.4/reasoning-body-props/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "推理 Body Slot 的 text 提供显示文本，rawText 保留原始输出。"
+---
+
+# 推理 Body Slot 的文本字段
+
+[English](guide.md) | 中文
+
+## 变更
+
+`conversation.chat.reasoning.body` 扩展通过新增的 `rawText` 字段接收模型输出。现有的 `text` 字段提供 Chat 处理后的显示文本，替代原始输出。`running` 保持不变。这会影响自定义推理渲染器和翻译包装组件。
+
+`conversation.chat.reasoning.content` Factory 仍接收 `text`、`running` 和可选的 `labels`。它渲染调用方选定的 Markdown。[Chat README](../../../../packages/client/ui-chat/README.zh.md#grouped-rendering) 介绍了该 Slot。
+
+## 迁移
+
+1. 在普通渲染、翻译请求和未翻译视图中继续读取 `text`。需要完整模型输出的扩展改为读取 `rawText`。
+2. 向 Content Factory 传入选定的 `text` 或其译文，不要重复执行 Chat 的显示处理。
+3. 重新构建扩展，使用每种支持的模型格式验证流式与完成后的渲染、翻译和未翻译视图。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Client plugins must use the prefixed context menu types and hooks and register keyed icon components."
+---
+
+# Context menu types and icons
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `@deepseek-ai/dsh-client-ui-context-menu/client` export `MenuTarget` is renamed to `ContextMenuTarget`, matching `ContextMenuTargetMap`. The old name has no compatibility alias. Target fields and runtime behavior are unchanged. Workspace and sidebar injections rename `menuTarget` / `useMenuTarget` to `contextMenuTarget` / `useContextMenuTarget`. Action icons accept `{ key, src? }` instead of React nodes and render through the keyed `contextMenu.icon` Slot.
+
+## Migration
+
+1. Replace `MenuTarget` imports and type references with `ContextMenuTarget`.
+2. Rename injected `menuTarget` sources and `useMenuTarget` consumers to `contextMenuTarget` and `useContextMenuTarget`.
+3. Replace action icon elements with `{ key: 'my-plugin.action' }`; carry a captured image URL in `src` when needed. Register the icon component under that key through `ctx.slots.inject('contextMenu.icon', ...)` and `ctx.slots.register()`. See the [menu package](../../../../packages/client/ui-context-menu/README.md#use-this-package).
+4. Rebuild custom Client plugins, confirm that type checks pass, and open their menus to verify icon rendering and plugin-unload cleanup.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Client 插件须使用带前缀的右键菜单类型和 hook，并注册 keyed 图标组件。"
+---
+
+# 右键菜单类型和图标
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-context-menu/client` 导出的 `MenuTarget` 更名为 `ContextMenuTarget`，与 `ContextMenuTargetMap` 保持一致。旧名不保留兼容别名，目标字段和运行时行为不变。工作区与侧栏注入的 `menuTarget` / `useMenuTarget` 改为 `contextMenuTarget` / `useContextMenuTarget`。操作图标改用 `{ key, src? }`，通过 keyed Slot `contextMenu.icon` 渲染，不再接收 React 节点。
+
+## 迁移
+
+1. 将 `MenuTarget` 导入及类型引用替换为 `ContextMenuTarget`。
+2. 将注入源 `menuTarget` 和消费者 `useMenuTarget` 分别改为 `contextMenuTarget`、`useContextMenuTarget`。
+3. 将操作图标元素替换为 `{ key: 'my-plugin.action' }`，需要时通过 `src` 携带已捕获的图片 URL。通过 `ctx.slots.inject('contextMenu.icon', ...)` 和 `ctx.slots.register()` 在该 key 下注册图标组件，参见[菜单包](../../../../packages/client/ui-context-menu/README.zh.md#use-this-package)。
+4. 重新构建自定义 Client 插件，确认类型检查通过，并打开菜单验证图标渲染和插件卸载后的清理。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Loader entry trees report mutations through commit(change), and Include persists them through a journal."
+---
+
+# Loader entry tree reports and Include persistence
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/cordis-plugin-loader` follows Loader 1.0.0-rc.8, and `@deepseek-ai/cordis-plugin-include` follows Include 1.1.1. This affects `cordis.yml` and patch files, code that subclasses `EntryTree`, and code that calls `applyEntryPatches` or relies on Include writes.
+
+- `EntryTree.write()` is removed. Subclasses implement `commit(change: EntryChange)`, which receives each create, update, move, removal and explicit Fiber save synchronously. In-memory trees implement a no-op.
+- `applyEntryPatches(data, patches, warn)` always returns cloned entries, including without patches, and clones inserted rows. Callers can no longer mutate the input through the result.
+- Include persists runtime changes through a journal reconciled with the latest file. File edits win conflicting fields and are logged as conflicts. Changes to patch-owned fields and inserted rows update the parent Include's patches. `flush()` waits for pending writes and rejects while changes remain unsaved; `refresh()` and `stop()` return the same result.
+- Include writes generated ids back into file rows that had none. Runtime changes to rows inserted by patches, including bundle rows, update the parent's patches instead of the included file. The parent of the `dsh` profile's root Include is the in-memory Loader, so such changes, for example a bundle row's self-disposal `disabled: true`, no longer survive a restart; previously the whole patched tree was written into `cordis.yml`.
+
+## Migration
+
+1. In `EntryTree` subclasses, replace `write()` with `commit(change)`. Persist from `change.options` and `change.legacy`: a missing `legacy` is a creation and a missing `options` is a removal.
+2. Treat the `applyEntryPatches` result as the only copy to modify.
+3. Where code needs a runtime change on disk, await `include.flush()`; for patch-owned changes, flush the child Include and then its parent.
+4. Start the application and confirm that runtime edits appear in the configuration file after `flush()`.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Loader 条目树通过 commit(change) 报告变更，Include 通过 journal 持久化这些变更。"
+---
+
+# Loader 条目树变更报告与 Include 持久化
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/cordis-plugin-loader` 跟随 Loader 1.0.0-rc.8，`@deepseek-ai/cordis-plugin-include` 跟随 Include 1.1.1。受影响的是 `cordis.yml` 与 patch 文件、继承 `EntryTree` 的代码，以及调用 `applyEntryPatches` 或依赖 Include 写盘的代码。
+
+- 移除了 `EntryTree.write()`。子类改为实现 `commit(change: EntryChange)`，它会同步收到每一次创建、更新、移动、删除和显式 Fiber 保存。内存树实现为空操作。
+- `applyEntryPatches(data, patches, warn)` 总是返回克隆后的条目，没有 patch 时也一样，插入行同样会被克隆。调用方不能再通过结果修改输入。
+- Include 通过与最新文件协调的 journal 持久化运行时变更。文件编辑在字段冲突时优先，并记录为冲突。对 patch 所拥有字段和插入行的修改会写入父 Include 的 patch。`flush()` 等待待处理的写入，并在仍有未保存变更时拒绝；`refresh()` 和 `stop()` 返回相同的结果。
+- Include 会把生成的 id 写回原本没有 id 的文件行。对 patch 插入行（包括 bundle 行）的运行时修改会写入父级的 patch，而不是被 include 的文件。`dsh` profile 根 Include 的父级是内存中的 Loader，因此这类修改（例如 bundle 行自行释放时写入的 `disabled: true`）重启后不再保留；此前整棵已应用 patch 的树会被写入 `cordis.yml`。
+
+## 迁移
+
+1. 在 `EntryTree` 子类中把 `write()` 换成 `commit(change)`。根据 `change.options` 和 `change.legacy` 持久化：缺少 `legacy` 表示创建，缺少 `options` 表示删除。
+2. 只修改 `applyEntryPatches` 返回的结果。
+3. 需要运行时变更落盘时，await `include.flush()`；对于 patch 所拥有的变更，先 flush 子 Include，再 flush 其父 Include。
+4. 启动应用，确认 `flush()` 之后运行时编辑已出现在配置文件中。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/css-anchored-menus/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Client UI consumers must replace JavaScript panel positioning and Menu rectangle callbacks with CSS anchors."
+---
+
+# CSS-anchored menus
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-primitives` removes the `useAnchoredPosition` value export and `AnchoredPositionOptions` type export. `Menu` replaces `getAnchorRect` with `anchorRef` for an external trigger element or `anchorPoint` for a point-triggered menu. Custom Client UI that imports the removed exports or passes the removed prop must migrate.
+
+Portaled menus follow their anchors through CSS Anchor Positioning. Their size limits use the layout viewport; browser zoom and panning move them with the page, and the panels may extend beyond the visual viewport, including while the keyboard is open. Menu dismissal, keyboard navigation, and internal scrolling remain available. The browser must support the CSS anchor positioning properties used by the component.
+
+## Migration
+
+1. Remove imports of `useAnchoredPosition` and `AnchoredPositionOptions`. For a custom panel, give its trigger a unique `anchor-name` and set the panel's `position-anchor` to the same name. Define placement and size limits in CSS; see the [model selector](../../../../packages/client/ui-model-selection/README.md#understand-the-implementation).
+2. When `Menu.getAnchorRect` returned a trigger's rectangle, pass the trigger's element ref as `anchorRef` instead. An inline `anchor` rendered by `Menu` needs no external ref.
+3. When the callback returned a zero-size rectangle for a pointer gesture, pass `{ x, y }` as `anchorPoint` in the same client-viewport coordinates as `event.clientX`/`clientY` or `getBoundingClientRect()`. `Menu` performs the Safari-to-layout conversion when opening or changing the point; callers must not add the visual-viewport offset themselves.
+4. Rebuild the custom Client UI and check that no removed import or prop remains. Verify opening, scrolling, Escape, focus restoration, and selection before and after browser zoom. Assertions must allow visual-viewport overflow while retaining layout-viewport bounds and content access.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/css-anchored-menus/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Client UI 使用方必须将 JavaScript 面板定位和 Menu 矩形回调替换为 CSS 锚点。"
+---
+
+# CSS 锚定菜单
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-primitives` 移除 `useAnchoredPosition` 值导出和 `AnchoredPositionOptions` 类型导出。`Menu` 将 `getAnchorRect` 替换为指向外部触发元素的 `anchorRef`，或用于按坐标打开菜单的 `anchorPoint`。导入已移除导出或传入已移除 prop 的自定义 Client UI 必须迁移。
+
+使用 portal 的菜单通过 CSS Anchor Positioning 跟随锚点。尺寸限制采用布局视口；浏览器缩放和平移时菜单随页面移动，面板可以超出视觉视口，包括键盘打开时。菜单关闭、键盘导航和内部滚动保持可用。浏览器必须支持组件使用的 CSS 锚点定位属性。
+
+## 迁移
+
+1. 移除 `useAnchoredPosition` 和 `AnchoredPositionOptions` 导入。自定义面板为触发元素设置唯一的 `anchor-name`，将面板的 `position-anchor` 设置为相同名称，并用 CSS 定义位置和尺寸限制；参见[模型选择器](../../../../packages/client/ui-model-selection/README.zh.md#understand-the-implementation)。
+2. 原 `Menu.getAnchorRect` 返回触发元素矩形时，改为通过 `anchorRef` 传入该元素的 ref。由 `Menu` 渲染的内联 `anchor` 无需外部 ref。
+3. 原回调为指针手势返回零尺寸矩形时，改为通过 `anchorPoint` 传入 `{ x, y }`，坐标与 `event.clientX`/`clientY` 或 `getBoundingClientRect()` 使用相同的客户端视口坐标系。`Menu` 在打开或坐标变化时执行 Safari 到布局视口的转换；调用方不要自行叠加视觉视口偏移。
+4. 重新构建自定义 Client UI，确认不再使用已移除的导入或 prop。在浏览器缩放前后验证打开、滚动、Escape、焦点恢复和选择。断言应允许超出视觉视口，同时保留布局视口约束及内容访问能力。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/cua-source-dev-helper/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Source-built Computer Use helpers use a separate development bundle identifier and need one new macOS permission grant."
+---
+
+# Source-built Computer Use helper identity
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Source checkouts previously built `DSH Computer Use.app` with the release bundle identifier `com.deepseek.harness.computer-use` and an ad-hoc signature. They now build `DSH Computer Use Dev.app` with bundle identifier `com.deepseek.harness.computer-use.dev`. Accessibility and Screen Recording grants for the old entry do not apply to it. Desktop and npm installations are unchanged. Source builds still default to ad-hoc signing; developers generate and maintain fixed identities outside DSH home and select them through configuration.
+
+## Migration
+
+1. Keep the default `sourceSigning: ad-hoc` for temporary signatures. To reduce repeated grants after rebuilds and across worktrees, follow the [developer signing skill](../../../../.agents/skills/dsh-cua-macos-signing/SKILL.md) to generate or reuse a certificate, then write `sourceSigning: { identity, keychain }` into the DSH home’s `cordis.patch.yml`; `keychain` must be an absolute path.
+2. Start DSH from the source checkout, call Computer Use, and grant Accessibility and Screen Recording to `DSH Computer Use Dev` in System Settings.
+3. Confirm that `getCapabilities` reports both permissions as `true`. With a fixed signature, check again after changing and rebuilding Swift code and from another worktree. Remove an old `DSH Computer Use` entry only when no installed DSH uses it.
+4. After the keychain locks, rerun setup as described in the skill to unlock and reuse the identity. To stop using it, select `ad-hoc` or remove the configuration, then remove the identity through the skill; deleting DSH home does not delete the developer keychain.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/cua-source-dev-helper/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "源码构建的 Computer Use helper 使用独立的开发版 Bundle ID，需要重新授予一次 macOS 权限。"
+---
+
+# 源码构建的 Computer Use helper 身份
+
+[English](guide.md) | 中文
+
+## 变更
+
+源码检出原先以临时签名构建 `DSH Computer Use.app`，使用正式版 Bundle ID `com.deepseek.harness.computer-use`。现在构建 `DSH Computer Use Dev.app`，使用 `com.deepseek.harness.computer-use.dev`。旧条目的辅助功能和屏幕录制授权不能沿用。Desktop 和 npm 安装版不变。源码构建默认仍为临时签名；固定身份由开发者在 DSH home 之外生成和维护，再通过配置指定。
+
+## 迁移
+
+1. 保持默认 `sourceSigning: ad-hoc` 即可使用临时签名。需要减少重新编译和跨 worktree 的授权次数时，按[开发者签名 skill](../../../../.agents/skills/dsh-cua-macos-signing/SKILL.md)生成或复用证书，并将 `sourceSigning: { identity, keychain }` 写入 DSH home 的 `cordis.patch.yml`；`keychain` 必须为绝对路径。
+2. 从源码检出启动 DSH，调用 Computer Use，在系统设置中给 `DSH Computer Use Dev` 授予辅助功能和屏幕录制权限。
+3. 确认 `getCapabilities` 的两项权限均为 `true`。使用固定签名时，在修改 Swift 源码重建和另一个 worktree 中分别复查。只有确认没有安装版 DSH 使用旧条目时，才移除旧 `DSH Computer Use` 条目。
+4. 钥匙串锁定后，按 skill 重新运行 setup 解锁并复用现有身份。停止使用时改回 `ad-hoc` 或移除该配置，再按 skill 删除身份；删除 DSH home 不会删除开发者钥匙串。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/desktop-stable-channel/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The Desktop stable update channel is named stable instead of latest."
+---
+
+# Desktop stable channel name
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Desktop packages, update feeds, and channel configuration use `stable` instead of `latest`. The `nightly` channel is unchanged. The old channel value is rejected; there is no alias. Fixed website downloads named `dsh-latest-*` are unchanged.
+
+## Migration
+
+1. Select `stable` in packaging workflows or set `DSH_DESKTOP_UPDATE_CHANNEL=stable` when building a stable-channel package. Build a stable version, without a prerelease suffix.
+2. If a local Desktop settings file contains `updates.channel: "latest"`, change the value to `"stable"` and restart Desktop. Omitting the field uses the package default.
+3. Publish with the updated tooling: it writes `stable.yml` on Windows and `stable-mac.yml` on macOS within each architecture's feed directory, with stable-channel binaries under `stable/`. Verify the selected channel and requested feed in the test deployment before production publication. Old packages still requesting `latest` feeds do not migrate automatically.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/desktop-stable-channel/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "桌面正式更新渠道由 latest 更名为 stable。"
+---
+
+# 桌面正式渠道名称
+
+[English](guide.md) | 中文
+
+## 变更
+
+桌面安装包、更新清单及渠道配置使用 `stable`，不再使用 `latest`。`nightly` 渠道不变。旧渠道值会被拒绝，不提供别名。网站名为 `dsh-latest-*` 的固定下载文件保持不变。
+
+## 迁移
+
+1. 在打包工作流中选择 `stable`，或在构建正式渠道包时设置 `DSH_DESKTOP_UPDATE_CHANNEL=stable`。使用不含预发布后缀的稳定版本号。
+2. 如果本地桌面配置文件包含 `updates.channel: "latest"`，将该值改为 `"stable"` 并重启桌面应用。省略该字段时使用安装包默认值。
+3. 使用更新后的工具发布：在各架构的清单目录内，Windows 写入 `stable.yml`，macOS 写入 `stable-mac.yml`；正式渠道二进制位于 `stable/` 下。在正式发布前，通过测试部署核对选定渠道和请求的清单。仍请求 `latest` 清单的旧包不会自动迁移。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Forge Git queries use Session permissions and disable configured diff helpers."
+---
+# Forge Git query permissions and content conversion
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Forge Git queries use the Session's sandbox mode instead of forcing `read-only`. `danger-full-access` works without a sandbox backend; `workspace-write` permits writes within its configured roots. A confined mode still refuses execution when its backend is unavailable.
+
+On Git 2.31 or newer, local diffs and statistics disable enumerated clean/process filters for each command. Git's built-in newline, ident, and encoding conversions still apply. Materialized LFS files and other filtered files can appear changed when ordinary Git considers them clean. The panel does not request LFS downloads. Older Git or concurrently added filters can still execute helpers under Session permissions. Submodule commit changes remain visible, but internal uncommitted changes are omitted.
+
+Filter configuration read failures, including truncated output, report `forgePanel/filter-config-failed` before any comparison and offer a retry. They are separate from `forgePanel/diff-too-large`.
+
+## Migration
+
+1. Keep a Session in `read-only` when its Git queries require operating-system-enforced write protection. Use the existing permission picker to select the intended Session mode; no configuration keys change.
+2. For repositories that require content conversion or submodule working-tree inspection, use an explicit Git command under the intended Session permissions to inspect those changes. The panel's local comparison bypasses clean/process filters on supported Git versions.
+3. On a host without a sandbox backend, select Full access and refresh the Forge panel. Its checkout and ordinary local changes should load; switching to a confined mode must still report the unavailable backend.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Forge Git 查询使用 Session 权限并禁用已配置的 diff 辅助程序。"
+---
+# Forge Git 查询权限与内容转换
+
+[English](guide.md) | 中文
+
+## 变更
+
+Forge Git 查询使用 Session 的沙箱模式，不再强制 `read-only`。`danger-full-access` 无需沙箱后端；`workspace-write` 允许在其配置的根目录内写入。受限模式的后端不可用时仍拒绝执行。
+
+在 Git 2.31 或更新版本中，本地 diff 与统计仅对每次命令禁用已枚举的 clean/process filter。Git 内置的换行、ident 与编码转换仍然生效。已物化的 LFS 文件及其他过滤文件可能显示为变更，即使普通 Git 认为它们未变。面板不请求下载 LFS 对象。旧 Git 或并发新增的过滤器仍可能按 Session 权限执行辅助程序。子模块提交变化仍可见，但内部未提交修改不显示。
+
+过滤器配置读取失败（包括输出被截断）时，在任何比较之前报告 `forgePanel/filter-config-failed` 并提供重试，与 `forgePanel/diff-too-large` 区分。
+
+## 迁移
+
+1. 如果 Git 查询需要操作系统强制禁止写入，请将 Session 保持为 `read-only`。通过现有权限选择器选择所需的 Session 模式；配置键没有变化。
+2. 对于需要内容转换或检查子模块工作区的仓库，请在所需的 Session 权限下显式运行 Git 命令检查这些变化。面板的本地比较在受支持的 Git 版本中绕过 clean/process filter。
+3. 在没有沙箱后端的主机上选择“完全权限”，然后刷新 Forge 面板。检出信息和普通本地变更应可加载；切回受限模式后仍须报告后端不可用。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/forge-worktree-entry/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "The Plugins page replaces the standalone Git worktrees card with Change requests & worktrees."
+---
+
+# One plugin entry for change requests and worktrees
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Web and Desktop use **Change requests & worktrees** to enable the review panel, the new-Session worktree option, and the model's `create_worktree` tool together. The separate **Git worktrees** card is hidden. Profiles that already enabled the Forge bundle also gain the model tool.
+
+Existing profiles are not migrated automatically. A selected `@deepseek-ai/dsh-experimental-tool-worktree` bundle stays active even though its card is hidden, so turning off Forge does not disable that standalone tool. Selecting both it and `@deepseek-ai/dsh-experimental-forge-bundle` inserts duplicate `worktree` and `tool-worktree` ids, making those component controls read-only. Remove the standalone selection before using the unified switch.
+
+## Migration
+
+1. Stop Web or quit Desktop. Back up `$DSH_HOME/profiles/<name>/package.json` and its sibling `cordis.patch.yml`. Use `~/.dsh` when `DSH_HOME` is unset; the standard profile names are `web` and `desktop`. For a custom profile, use its name.
+2. Edit `dsh.profile.bundles` in that `package.json`. Remove every `@deepseek-ai/dsh-experimental-tool-worktree` entry. To keep worktree support through the unified switch, add `@deepseek-ai/dsh-experimental-forge-bundle` once; if it is already selected, keep that entry. To disable both features, remove both bundle names. Preserve all other entries and fields.
+3. Keep existing `cordis.patch.yml` overrides: the `worktree`, `tool-worktree`, and `optional-forge-panel` ids are unchanged. To use the Forge panel without exposing the model tool, add or update this entry in the existing patch list:
+
+   ```yaml
+   - id: tool-worktree
+     disabled: true
+   ```
+
+4. Restart the application. In Plugins, confirm that **Change requests & worktrees** reflects your selection. With no disabling row override, enabling it provides the panel and `create_worktree`; turning it off removes both. Confirm that the profile lists no standalone worktree bundle. Existing worktrees, branches, and Session records are retained.
+
+Headless profiles and custom compositions that need only the standalone tool can keep it; do not also select the Forge bundle. In Web or Desktop, that standalone selection remains hidden and must be managed through the profile file.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/forge-worktree-entry/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "插件页将独立的 Git 工作树卡片合入变更请求与工作树。"
+---
+
+# 变更请求与工作树使用同一个插件入口
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 和 Desktop 通过**变更请求与工作树**同时启用评审面板、新会话的工作树选项和模型的 `create_worktree` 工具。独立的 **Git 工作树**卡片被隐藏。已经启用 Forge 组合包的 profile 也会新增模型工具。
+
+已有 profile 不会自动迁移。选中的 `@deepseek-ai/dsh-experimental-tool-worktree` 组合包仍会运行，即使其卡片已隐藏，因此关闭 Forge 不会停用这个独立工具。同时选择它和 `@deepseek-ai/dsh-experimental-forge-bundle` 会插入重复的 `worktree` 与 `tool-worktree` id，使对应组件控件变为只读。使用统一开关前，请移除独立组合包的选择。
+
+## 迁移
+
+1. 停止 Web 或退出 Desktop。备份 `$DSH_HOME/profiles/<name>/package.json` 及同目录下的 `cordis.patch.yml`。未设置 `DSH_HOME` 时使用 `~/.dsh`；标准 profile 名称为 `web` 和 `desktop`。自定义 profile 使用其自身名称。
+2. 编辑该 `package.json` 的 `dsh.profile.bundles`。移除所有 `@deepseek-ai/dsh-experimental-tool-worktree` 条目。若要通过统一开关保留工作树功能，添加一次 `@deepseek-ai/dsh-experimental-forge-bundle`；若已选中它，则保留该条目。若要关闭两项功能，则移除这两个组合包名称。保留其他所有条目和字段。
+3. 保留现有的 `cordis.patch.yml` 覆盖配置：`worktree`、`tool-worktree` 和 `optional-forge-panel` 的 id 均未改变。若只使用 Forge 面板，不向模型提供工作树工具，在现有 patch 列表中添加或更新以下条目：
+
+   ```yaml
+   - id: tool-worktree
+     disabled: true
+   ```
+
+4. 重启应用。在插件页确认**变更请求与工作树**的状态符合你的选择。没有禁用插件行的覆盖配置时，启用它会提供面板与 `create_worktree`，关闭后两者均移除。确认 profile 不再列出独立的工作树组合包。已有工作树、分支和 Session 记录均保留。
+
+仅需要独立工具的 Headless profile 和自定义组合可以继续保留它，但不要同时选择 Forge 组合包。在 Web 或 Desktop 中，该独立选择仍然隐藏，需要通过 profile 文件管理。

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

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

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

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

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

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