dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-rc.1/account-remote-provider/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Move account plugin composition and Remote imports to the concrete deepseek-account service."
+---
+
+# Account service and Remote imports
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-deepseek-account` is a concrete `DeepSeekAccount` service owning browser login, stored credentials, and the `account` Remote namespace. The abstract account class, `@deepseek-ai/dsh-deepseek-account-platform`, and `@deepseek-ai/dsh-api-account-controller` are removed. Existing `ctx.deepseekAccount` and `ctx.remote.account` operations retain their names and arguments. Host-only credential methods are not Remote operations. The `/types` entry remains available without loading the service implementation.
+
+Stored credentials keep the `deepseek-account-platform/default` and `deepseek-account-platform/device` keys; this package change does not require signing in again.
+
+## Migration
+
+1. Replace `@deepseek-ai/dsh-deepseek-account-platform` with `@deepseek-ai/dsh-deepseek-account` in custom plugin rows and dependencies. Keep the existing `deepseek-account` row id and configuration. Remove any `account-controller` row and its package dependency.
+2. Import `DeepSeekAccount` instead of `PlatformAccount`. The class is concrete; custom subclasses of the former abstract account definition must be updated. Existing imports of shared types from `@deepseek-ai/dsh-deepseek-account/types` remain valid.
+3. Replace old provider or controller `/remote` and `/typert` imports with `@deepseek-ai/dsh-deepseek-account/remote` and `@deepseek-ai/dsh-deepseek-account/typert`.
+4. Import Platform header and cookie helpers from `@deepseek-ai/dsh-deepseek-account/client-metadata`. Read the configuration schema from `DeepSeekAccount.Config`. Stop calling `installAccountTaskCancellation` directly: mounting the service installs it. `isRunningAccountTask` is internal.
+5. Rebuild custom compositions and verify login, notification queries, sign-out, and cancellation of account state subscriptions. Confirm that Remote exports omit `resolveToken`, `rejectToken`, `getPlatformSession`, and `getDeviceIdentity`.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/account-remote-provider/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "将账号插件组合与 Remote 导入迁移到具体的 deepseek-account 服务。"
+---
+
+# 账号服务与 Remote 导入
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-deepseek-account` 是具体的 `DeepSeekAccount` 服务，拥有浏览器登录、已存储凭证和 `account` Remote 命名空间。抽象账号类、`@deepseek-ai/dsh-deepseek-account-platform` 和 `@deepseek-ai/dsh-api-account-controller` 被移除。已有 `ctx.deepseekAccount` 和 `ctx.remote.account` 操作保留名称和参数。凭据相关的 Host 专用方法不会成为 Remote 操作。`/types` 出口仍可用，且不会加载服务实现。
+
+已存储凭证保留 `deepseek-account-platform/default` 和 `deepseek-account-platform/device` key；这次包变更不要求重新登录。
+
+## 迁移
+
+1. 将自定义插件行和依赖中的 `@deepseek-ai/dsh-deepseek-account-platform` 替换为 `@deepseek-ai/dsh-deepseek-account`。保留现有 `deepseek-account` 行 id 和配置。移除所有 `account-controller` 行及其包依赖。
+2. 将 `PlatformAccount` 导入改为 `DeepSeekAccount`。该类为具体实现；继承原抽象账号定义的自定义子类需要调整。从 `@deepseek-ai/dsh-deepseek-account/types` 导入共享类型的现有代码保持有效。
+3. 将旧服务或 controller 的 `/remote`、`/typert` 导入替换为 `@deepseek-ai/dsh-deepseek-account/remote` 和 `@deepseek-ai/dsh-deepseek-account/typert`。
+4. 从 `@deepseek-ai/dsh-deepseek-account/client-metadata` 导入 Platform 请求头和 Cookie 辅助函数。从 `DeepSeekAccount.Config` 读取配置 schema。不再直接调用 `installAccountTaskCancellation`：挂载服务时会安装该逻辑。`isRunningAccountTask` 为内部函数。
+5. 重新构建自定义组合，验证登录、通知查询、退出和账号状态订阅取消。确认 Remote 导出不包含 `resolveToken`、`rejectToken`、`getPlatformSession` 和 `getDeviceIdentity`。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/archive-worktrees/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Archiving a Session can remove its clean worktree while retaining the branch, and the Forge bundle mounts one worktree service."
+---
+
+# Worktree cleanup on archive
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Archiving a Session previously retained its checkout. The worktree service now records each checkout it creates as a `plugin:worktree/created` record and, when the Session that created one is archived, removes it with a non-force `git worktree remove` when no unarchived Session refers to it, its creator's policy is not read-only, and Git finds no tracked changes, untracked files, initialized submodules, locks, or detached HEAD. Ignored files such as `node_modules` and edits to skip-worktree or assume-unchanged files, which `git status` hides, do not retain it; Git discards them. Git refuses to remove a checkout holding a committed embedded repository, so that checkout stays and the archive notice reports a failed cleanup. Branches and commits remain. The service's `retainOnArchive` setting, off by default, keeps every checkout instead. Checkouts created before this release have no such event and are never swept, nor are Sessions archived earlier. See the [worktree service](../../../../packages/experimental/worktree/README.md).
+
+The Forge bundle mounts one `worktree` service for both the panel and the `create_worktree` tool. The `forge-worktree` row and the `optional-forge-panel` group that isolated a second service are gone; the panel is the top-level `forge-panel` row.
+
+## Migration
+
+1. If a checkout must remain available outside DSH, keep its Session unarchived, lock it with `git worktree lock <path>` before archiving, or turn on **Keep worktrees when archiving** on the Forge bundle's worktree row of the Plugins page (`retainOnArchive`), which keeps every checkout. Ignored files are not kept, nor are edits to skip-worktree or assume-unchanged files: commit those edits, or clear the flags with `git update-index --no-skip-worktree` or `--no-assume-unchanged`, before archiving.
+2. To resume an archived Session whose checkout was removed, unarchive it and use **Restore worktree**. The retained branch is checked out at the recorded path.
+3. In a profile's `cordis.patch.yml`, move any `forge-worktree` override to the `worktree` row and any `optional-forge-panel` override to the `forge-panel` row; a `disabled: true` on `forge-panel` turns off the panel alone.
+4. Confirm the branch and commits are present with `git branch --list` and that **Restore worktree** makes the recorded checkout available. Session logs require no migration.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/archive-worktrees/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "归档 Session 可以删除其干净的工作树并保留分支，Forge bundle 只挂载一个工作树服务。"
+---
+
+# 归档时清理工作树
+
+[English](guide.md) | 中文
+
+## 变更
+
+归档 Session 以前会保留检出目录。工作树服务现在把它创建的每个检出目录记录为 `plugin:worktree/created` Session 事件；当创建它的 Session 被归档时，若没有未归档的 Session 引用该目录、创建者的策略不是只读，且 Git 未发现跟踪文件改动、未跟踪文件、已初始化的子模块、锁或分离 HEAD，就用不带 force 的 `git worktree remove` 删除它。`node_modules` 之类被忽略的文件，以及 `git status` 不报告的 skip-worktree 或 assume-unchanged 文件改动，都不会保留目录，Git 会丢弃它们。含已提交内嵌仓库的检出目录会被 Git 拒绝删除，因此保留，归档提示显示清理失败。分支和提交仍会保留。服务的 `retainOnArchive` 设置默认关闭，开启后改为保留所有检出目录。本版本之前创建的检出目录没有该事件，不会被扫描；更早归档的 Session 也不会。参见[工作树服务](../../../../packages/experimental/worktree/README.zh.md)。
+
+Forge bundle 为面板和 `create_worktree` 工具挂载同一个 `worktree` 服务。隔离第二个服务的 `forge-worktree` 行与 `optional-forge-panel` 组已移除；面板是顶层的 `forge-panel` 行。
+
+## 迁移
+
+1. 如果检出目录必须供 DSH 之外继续使用，请保持其 Session 未归档，在归档前用 `git worktree lock <path>` 锁定它，或在插件页 Forge 套件的 worktree 行上开启**归档时不删除工作树**（`retainOnArchive`），它会保留所有检出目录。被忽略的文件不会保留，skip-worktree 或 assume-unchanged 文件的改动也不会：归档前请提交这些改动，或用 `git update-index --no-skip-worktree` 或 `--no-assume-unchanged` 清除标记。
+2. 要继续使用已归档且检出目录已删除的 Session，请取消归档并使用**恢复工作树**。保留的分支会在记录的路径重新检出。
+3. 在 profile 的 `cordis.patch.yml` 中，把针对 `forge-worktree` 的覆盖迁到 `worktree` 行，把针对 `optional-forge-panel` 的覆盖迁到 `forge-panel` 行；对 `forge-panel` 设置 `disabled: true` 可以只关闭面板。
+4. 用 `git branch --list` 确认分支与提交仍然存在，并确认**恢复工作树**使记录的检出目录重新可用。Session 日志无需迁移。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/attachment-error-codes/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "AttachmentError now extends HarnessError, so tool and model-request failures record attachment codes instead of losing them or reporting UNKNOWN."
+---
+
+# Attachment failures keep their codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`AttachmentError` from `@deepseek-ai/dsh-attachment` now extends `HarnessError` from `@deepseek-ai/dsh-error`. Its `name` (`AttachmentError`) and every `ATTACHMENT_*` and image admission code are unchanged. Two persisted results change:
+
+- When a model request fails because an adapter could not read an image attachment, the failed turn's `turn/end` error previously recorded `code: 'UNKNOWN'`. It now records the `AttachmentError` code, such as `ATTACHMENT_NOT_FOUND`, `ATTACHMENT_CORRUPT`, `ATTACHMENT_READ_FAILED`, or an image admission code such as `INVALID_IMAGE` or `IMAGE_TOO_LARGE`.
+- A tool whose body lets an `AttachmentError` escape now records `error: { name: 'AttachmentError', code }` on its `tool/result`; previously the result had no `error`. `read_image` also records the `AttachmentError` code and names the file and the next step in the message.
+
+`instanceof HarnessError` now matches `AttachmentError`. `isAttachmentError` is unchanged.
+
+## Migration
+
+1. If analytics or retry rules treat `UNKNOWN` model failures as a catch-all, add the codes of the exported `AttachmentErrorCode` type; in code, identify these failures with `isAttachmentError`. The codes do not share one prefix.
+2. If code catches `HarnessError` before `AttachmentError`, move the `AttachmentError` check first wherever the two need different handling.
+3. Earlier Session logs keep `UNKNOWN`; readers that compare old and new logs should treat both as the same failure class for attachment reads.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/attachment-error-codes/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "AttachmentError 现在继承 HarnessError，工具失败与模型请求失败会记录附件错误码，不再丢失或报告为 UNKNOWN。"
+---
+
+# 附件失败保留其错误码
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-attachment` 的 `AttachmentError` 现在继承 `@deepseek-ai/dsh-error` 中的 `HarnessError`。其 `name`（`AttachmentError`）以及所有 `ATTACHMENT_*` 与图像准入错误码均保持不变。两类持久化结果会变化：
+
+- 适配器无法读取图像附件而导致模型请求失败时，失败 turn 的 `turn/end` 错误过去记录 `code: 'UNKNOWN'`。现在记录 `AttachmentError` 的错误码，例如 `ATTACHMENT_NOT_FOUND`、`ATTACHMENT_CORRUPT`、`ATTACHMENT_READ_FAILED`，或 `INVALID_IMAGE`、`IMAGE_TOO_LARGE` 等图像准入错误码。
+- 工具主体让 `AttachmentError` 逸出时，其 `tool/result` 现在记录 `error: { name: 'AttachmentError', code }`；过去结果中没有 `error`。`read_image` 同样记录 `AttachmentError` 的错误码，并在消息中写明文件与下一步。
+
+`instanceof HarnessError` 现在会匹配 `AttachmentError`。`isAttachmentError` 不变。
+
+## 迁移
+
+1. 如果分析或重试规则把 `UNKNOWN` 模型失败当作兜底类别，请加入导出类型 `AttachmentErrorCode` 中的错误码；代码中用 `isAttachmentError` 识别这些失败。这些错误码没有统一前缀。
+2. 如果代码先捕获 `HarnessError` 再捕获 `AttachmentError`，在两者需要不同处理的地方把 `AttachmentError` 检查移到前面。
+3. 较早的 Session 日志仍保留 `UNKNOWN`；对比新旧日志的读取方应把附件读取的这两种记录视为同一类失败。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "macOS reads more AX nodes by default and accepts per-read overrides of configured traversal budgets."
+---
+
+# macOS AX tree read limits
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The default macOS node count rises from 2000 to 5000 and the default depth from 25 to 50. Reading a large window can take longer and emit more text to the model.
+
+Configured `maxElements` and `maxDepth` now supply defaults independently for omitted arguments. Callers can request larger or smaller values for one read. Paste menu discovery continues to use the configured limits.
+
+## Migration
+
+1. To keep the previous budgets for ordinary reads, find the `@deepseek-ai/dsh-experimental-cua-macos` entry in your `cordis.yml` or profile patch. Set `maxElements: 2000` and `maxDepth: 25` in its existing `config`.
+2. Restart the profile and confirm both defaults in the Computer Use model instructions.
+3. If a script depends on specific traversal budgets, pass them explicitly to `getAccessibilityTree()`. An override applies only to that call.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "macOS 默认读取更多 AX 节点，调用方可为单次读取覆盖配置值。"
+---
+
+# macOS AX 树读取范围
+
+[English](guide.md) | 中文
+
+## 变更
+
+macOS 的默认节点数从 2000 增至 5000，默认深度从 25 增至 50。窗口中有更多节点可访问时，读取可能耗时更长，输出到模型的文本也可能增加。
+
+`maxElements` 和 `maxDepth` 分别决定省略对应参数时的读取范围。调用方可以为一次读取指定高于或低于配置的值。查找粘贴菜单始终使用配置值。
+
+## 迁移
+
+1. 如需沿用原先的常规读取范围，在 `cordis.yml` 或配置补丁中找到 `@deepseek-ai/dsh-experimental-cua-macos`，在现有的 `config` 下设置 `maxElements: 2000` 和 `maxDepth: 25`。
+2. 重启配置，确认 Computer Use 模型说明中的两个默认值与配置一致。
+3. 如果脚本依赖特定的遍历范围，在 `getAccessibilityTree()` 的调用处显式传入这两个参数。一次调用的覆盖值不会影响后续读取。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/cua-hover-ax-only/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "macOS mouseMove requires AX alternate UI by default and returns HOVER_UNAVAILABLE instead of moving the user's cursor."
+---
+
+# macOS hover keeps the system pointer in place by default
+
+English | [中文](guide.zh.md)
+
+## Change
+
+On macOS, `win.mouseMove(target)` uses an enabled element or ancestor that advertises both `AXShowAlternateUI` and `AXShowDefaultUI`. Without that route, previous versions moved the visible system cursor. The default now returns `HOVER_UNAVAILABLE` before sending input. By default, explicitly requesting the system pointer asks the user for this session.
+
+## Migration
+
+1. For an available control, use its advertised action or click it directly. Use browser tools for web content that requires page hover.
+2. If your profile sets `helperPath`, rebuild the custom helper to support the per-request `useSystemPointer` field and restart the profile.
+3. When the task requires physical movement, call `win.mouseMove(target, { useSystemPointer: true })` on an unobscured foreground target. After approval this move reports `systemPointerMoved: true`. Pass `useSystemPointer: true` again for each subsequent physical move. Closing the session or restarting DSH clears approval.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/cua-hover-ax-only/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "macOS 的 mouseMove 默认要求控件支持 AX 备用界面，否则返回 HOVER_UNAVAILABLE，保留用户的光标位置。"
+---
+
+# macOS 悬停默认保留系统光标位置
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 macOS 上，`win.mouseMove(target)` 会查找已启用且同时声明 `AXShowAlternateUI` 和 `AXShowDefaultUI` 的控件或祖先。找不到时，旧版会移动系统光标，新版默认在发送输入前返回 `HOVER_UNAVAILABLE`。默认配置下，显式请求移动系统光标时会询问用户是否授权当前会话。
+
+## 迁移
+
+1. 对已经可用的控件，可执行它声明的动作或直接点击。需要网页悬停时可用浏览器工具。
+2. 如果 profile 设置了 `helperPath`，请重新构建该 helper，使其支持按请求读取 `useSystemPointer` 字段，然后重启 profile。
+3. 任务确实需要移动鼠标时，在前台未受遮挡的目标上调用 `win.mouseMove(target, { useSystemPointer: true })`。用户同意后，本次移动返回 `systemPointerMoved: true`。之后每次移动系统鼠标仍需显式传 `useSystemPointer: true`。关闭会话或重启 DSH 后需要重新授权。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "Migrate CUA scripts and custom native providers to scoped window input, string element IDs, and platform capabilities."
+---
+
+# Native CUA application and window API
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Screenshots and pointer input require explicit windows. App (`appHandle`) and Window (`windowId`) objects share their application handle's latest accessibility snapshot. Window IDs are opaque strings. macOS retains running application PIDs and permission `helper.pid` and `parent.pid`. Windows permission metadata omits PIDs.
+
+Providers supply startup capabilities and implement `getGuidance(kind)` instead of supplying a `guidance` string. `raw` selects instructions for the raw `cua` tool; `standalone` selects instructions for `cua_run_code`. The native helper reports runtime permissions and session lock state; the Host combines these with startup capabilities in `getCapabilities()`. Human-facing permission responses carry a `darwin` or `windows` platform tag.
+
+## Migration
+
+1. Pass a current `app.getWindows()` ID unchanged to `app.getWindow(windowId)`. Rediscover saved numeric IDs. Use `window.getScreenshot()`, `window.click()`, `window.scroll()`, and `window.drag()`. Replace `hover` with `window.mouseMove()`. On macOS, `window.click(id)` sends mouse events at the element center. Switch to `invoke(id)` for the default accessibility action, or `performAction(id, "AXShowMenu")` to request an advertised menu action.
+2. Replace `getAXState()` with `getAccessibilityTree()`. Replace `getAXStateAndScreenshot()` with separate tree and screenshot reads. Application and window selection does not read AX. Before using element IDs, call `getAccessibilityTree()` explicitly. To display the tree in TypeScript PTC, pass its return value to `inspect`. A screenshot does not require a successful AX read. Before coordinate input, including relative coordinates, obtain a successful AX observation covering the window or a screenshot; absolute coordinates require a screenshot. See [macOS AX read limits](../cua-ax-read-limits/guide.md) for changes to traversal defaults and configuration.
+3. Pass the opaque string ID from the latest tree wherever you passed a numeric element index. In raw requests use `elementId` with `snapshotId`. Replace `performSecondaryAction` with `listActions(id)` and `performAction(id, exactName, argument?)`, or use `invoke(id)` for the default action. `setValue` accepts the provider’s supported JSON values. On macOS, `performAction(id, 'AXRaise')` performs the advertised raise action. Call `app.activate()` first when the application must become active.
+4. Replace a packed chord such as `pressKey('shift+Tab')` with `pressKey('Tab', ['shift'])`. Check `(await cua.getCapabilities()).methods` before using `sendKeyEvent`. On macOS, call it inside one `run_code` or `cua_run_code` to hold a key across tool calls. Repeat a held non-modifier with another down. Returning, throwing or pausing releases any remaining keys. Replace `NATIVE_ERROR` with `INVALID_ARGUMENT` for unknown macOS keys and correct the key before retrying.
+5. Read `dispatched`, then observe the outcome. `invoke` returns `dispatched: false` when the element has no default action. Remove reads of the old `verified` field and of `pid` on selected objects or window records. Pass a Windows application ID unchanged. For a specific macOS instance, use `getApp(String(row.pid))`. Update permission readers that test for `win32` to use `windows`.
+6. Custom providers replace `CuaBackend.description` with `capabilities` and `guidance` with `getGuidance(kind)`. Supply `permissionParameters`. Set `acceptsPidSelector: true` if `getApp` accepts process IDs. Rebuild custom `helperPath` against the [operation schema](../../../../packages/experimental/cua/src/protocol.ts) and [tagged permission response](../../../../packages/experimental/cua/src/access-types.ts). Restart. Verify both tool forms’ guidance, advertised methods, keyboard scopes and permission controls.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "迁移 CUA 脚本和自定义原生提供方，使用显式窗口、字符串元素 ID 和平台能力声明。"
+---
+
+# 原生 CUA 应用和窗口 API
+
+[English](guide.md) | 中文
+
+## 变更
+
+截图和指针输入要求显式选择窗口。App（`appHandle`）和 Window（`windowId`）对象共享所属应用句柄的最新辅助功能快照。窗口 ID 是不透明字符串，macOS 应用发现保留运行进程的 PID，权限诊断保留 `helper.pid` 和 `parent.pid`。Windows 权限诊断不提供 PID。
+
+提供方声明启动能力，并实现 `getGuidance(kind)`，不再传入 `guidance` 字符串。`raw` 选择原始 `cua` 工具的指引，`standalone` 选择 `cua_run_code` 的指引。原生 helper 返回运行时权限和会话锁定状态，Host 将其与启动能力合并到 `getCapabilities()` 中。供权限页面使用的响应带有 `darwin` 或 `windows` 平台标记。
+
+## 迁移
+
+1. 从 `app.getWindows()` 返回的列表选定目标，把原始字符串传给 `app.getWindow(windowId)`。曾以数字保存的窗口 ID 需要重新获取。在窗口上调用 `getScreenshot()`、`click()`、`scroll()` 和 `drag()`，将原有的 `hover` 调用改为 `window.mouseMove()`。在 macOS 上，`window.click(id)` 在元素中心发送鼠标事件。需要执行默认辅助功能动作时，改用 `invoke(id)`。需要打开控件菜单且控件声明了 `AXShowMenu` 时，调用 `performAction(id, "AXShowMenu")`。
+2. 将 `getAXState()` 改为 `getAccessibilityTree()`，将 `getAXStateAndScreenshot()` 拆成读取树和截图两次调用。选择应用或窗口不读取 AX。使用元素 ID 前须显式调用 `getAccessibilityTree()`。在 TypeScript PTC 中，将返回值传给 `inspect` 即可展示这棵树。截图不要求 AX 读取成功。所有坐标输入（包括相对坐标）之前都须成功读取覆盖该窗口的 AX 或取得截图；绝对坐标要求截图。[读取上限的迁移说明](../cua-ax-read-limits/guide.zh.md)列出了 macOS 默认值和配置含义的变化。
+3. 将数字元素索引改为从最新树中取得的字符串 ID。直接发送请求时使用 `elementId` 和 `snapshotId`。原先调用 `performSecondaryAction` 的地方，先用 `listActions(id)` 取得完整动作名，再调用 `performAction(id, exactName, argument?)`。要执行默认动作，可调用 `invoke(id)`。`setValue` 接受提供方支持的 JSON 值。 在 macOS 上，`performAction(id, 'AXRaise')` 只执行元素声明的抬起窗口动作。需要把应用切到前台时先调用 `app.activate()`。
+4. 将 `pressKey('shift+Tab')` 之类的组合键写法改为 `pressKey('Tab', ['shift'])`。调用 `sendKeyEvent` 前检查 `(await cua.getCapabilities()).methods`。在 macOS 上，同一次 `run_code` 或 `cua_run_code` 中可调用此方法跨工具调用保持按键。如果需要一次重复按下，可在这次执行中对已按住的普通键再发一次 `down`。执行返回、异常退出或用户暂停时会释放仍按着的键。如果脚本用 `NATIVE_ERROR` 识别 macOS 上的未知键名，请改为处理 `INVALID_ARGUMENT`，并在重试前修正键名。
+5. 从动作结果读取 `dispatched`，再观察应用确认效果。元素没有默认动作时，`invoke` 返回 `dispatched: false`。移除读取旧字段 `verified` 的代码，以及对已选对象和窗口记录中 `pid` 的读取。Windows 应用 ID 原样传递。需要选择某个 macOS 进程时，使用 `getApp(String(row.pid))`。读取权限状态时，将原先判断 `win32` 的代码改为判断 `windows`。
+6. 自定义提供方将 `CuaBackend.description` 改为 `capabilities`，将 `guidance` 改为 `getGuidance(kind)`，并向 `installCua` 传入 `permissionParameters`。若 `getApp` 接受进程 ID，设置 `acceptsPidSelector: true`。按[操作协议](../../../../packages/experimental/cua/src/protocol.ts)和[带平台标记的权限响应](../../../../packages/experimental/cua/src/access-types.ts)重新构建自定义 `helperPath` 对应的 helper。重启后验证两种工具形态的指引、声明的方法、键盘输入范围及 Computer Use 权限页的平台控件。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.md

@@ -0,0 +1,35 @@
+---
+kind: upgrade-guide
+description: "Creator mode replaces its four skills with one `dsh-doc` skill, and the repository documentation skill becomes `dsh-doc-writing`."
+---
+
+# `dsh-doc` replaces the Creator mode skills
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Creator mode offered four skills from `@deepseek-ai/dsh-agent-preset`: `cordis-plugin-development`, `editing-cordis-compositions`, `cordis-composition-reference`, and `agent-experience`. It now offers one skill, `dsh-doc`. Its former content is in files that `dsh-doc` reads on demand, under `skills/dsh-doc/references/` and `skills/dsh-doc/templates/` of that package. The old skill names no longer appear in the skill catalog, and loading one by name fails.
+
+In a DSH source checkout, the documentation-writing skill `.agents/skills/dsh-doc` is now `.agents/skills/dsh-doc-writing`, named `dsh-doc-writing`.
+
+This affects Creator mode users whose prompts, saved instructions, or own skills name an old skill, and compositions or scripts that read files at the old paths.
+
+## Migration
+
+1. Replace each old skill name in prompts, instructions, and skills with `dsh-doc`; for the source checkout documentation skill, use `dsh-doc-writing`.
+2. Replace file paths under `@deepseek-ai/dsh-agent-preset/skills/` as follows:
+
+   | Old path | New path |
+   |---|---|
+   | `cordis-plugin-development/SKILL.md` | `dsh-doc/references/plugin-development.md` |
+   | `cordis-plugin-development/references/<file>` | `dsh-doc/references/<file>` |
+   | `cordis-plugin-development/templates/<name>/` | `dsh-doc/templates/<name>/` |
+   | `editing-cordis-compositions/SKILL.md` | `dsh-doc/references/compositions.md` |
+   | `cordis-composition-reference/SKILL.md` | `dsh-doc/references/composition-reference.md` |
+   | `cordis-composition-reference/references/packages.md` | `dsh-doc/references/packages.md` |
+   | `agent-experience/SKILL.md` | `dsh-doc/references/tool-design.md` |
+
+3. A composition that sets `customSkillDirs` to the package's `skills` directory needs no change.
+4. Rename or remove a skill named `dsh-doc` in a project's `.dsh/skills/` or `.agents/skills/`: project skills take precedence and would hide the packaged one. In a DSH source checkout, update the checkout to a revision that contains this change, which renames the repository skill.
+5. Start a new Creator mode session with an installation or revision that contains this change, and confirm that the skill catalog lists `dsh-doc` and none of the four skills this package shipped before.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.zh.md

@@ -0,0 +1,35 @@
+---
+kind: upgrade-guide
+description: "创造模式用一个 `dsh-doc` skill 取代原有的四个 skill，仓库文档 skill 更名为 `dsh-doc-writing`。"
+---
+
+# `dsh-doc` 取代创造模式的 skill
+
+[English](guide.md) | 中文
+
+## 变更
+
+创造模式原先从 `@deepseek-ai/dsh-agent-preset` 提供四个 skill（技能）：`cordis-plugin-development`、`editing-cordis-compositions`、`cordis-composition-reference` 和 `agent-experience`。现在只提供一个 skill：`dsh-doc`。原有内容位于该包 `skills/dsh-doc/references/` 和 `skills/dsh-doc/templates/` 下的文件中，由 `dsh-doc` 按需读取。旧 skill 名称不再出现在 skill 目录中，按名称加载旧 skill 会失败。
+
+在 DSH 源码 checkout 中，文档编写 skill `.agents/skills/dsh-doc` 现为 `.agents/skills/dsh-doc-writing`，名称为 `dsh-doc-writing`。
+
+受影响的对象包括：提示词、已保存指令或自有 skill 中引用旧 skill 名称的创造模式用户，以及读取旧路径文件的组合或脚本。
+
+## 迁移
+
+1. 将提示词、指令和 skill 中的每个旧 skill 名称替换为 `dsh-doc`；源码 checkout 中的文档 skill 改用 `dsh-doc-writing`。
+2. 按下表替换 `@deepseek-ai/dsh-agent-preset/skills/` 下的文件路径：
+
+   | 旧路径 | 新路径 |
+   |---|---|
+   | `cordis-plugin-development/SKILL.md` | `dsh-doc/references/plugin-development.md` |
+   | `cordis-plugin-development/references/<file>` | `dsh-doc/references/<file>` |
+   | `cordis-plugin-development/templates/<name>/` | `dsh-doc/templates/<name>/` |
+   | `editing-cordis-compositions/SKILL.md` | `dsh-doc/references/compositions.md` |
+   | `cordis-composition-reference/SKILL.md` | `dsh-doc/references/composition-reference.md` |
+   | `cordis-composition-reference/references/packages.md` | `dsh-doc/references/packages.md` |
+   | `agent-experience/SKILL.md` | `dsh-doc/references/tool-design.md` |
+
+3. 将 `customSkillDirs` 设为该包 `skills` 目录的组合无需修改。
+4. 重命名或删除项目 `.dsh/skills/` 或 `.agents/skills/` 中名为 `dsh-doc` 的 skill：项目 skill 优先级更高，会遮蔽随包提供的同名 skill。在 DSH 源码 checkout 中，将该 checkout 更新到包含本变更的修订版本；本变更会重命名仓库 skill。
+5. 使用包含本变更的安装或修订版本新建一个创造模式会话，确认 skill 目录列出 `dsh-doc`，且不包含本包此前提供的四个 skill 中的任何一个。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-change-request-overview/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "ChangeRequestSnapshot gains required overview fields, ChangeRequestCheck gains the required rerun field, and ForgeActionFailure gains the unknown code."
+---
+
+# Forge snapshots carry the change request overview, and actions report unknown outcomes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ChangeRequestSnapshot` gains seven required fields: `reviewers` and `reviewersTruncated`, `closingIssues` and `closingIssuesTruncated`, `branchUpdates`, `canRequestReviews`, and `canRerunChecks`. `ChangeRequestCheck` gains the required `rerun: ForgeCheckId | null`, which names how the provider reruns the check. The change request card reads these fields to list reviewers, linked issues, and the branch update, and to offer rerunning failed checks, requesting reviews, and updating the branch.
+
+`ForgeActionFailure['code']` gains `unknown`: the host's answer did not confirm the outcome, so the change may have been applied. The GitHub provider returns it for viewed marks, review requests, and branch updates GitHub did not confirm; `ctx.forge.markReady` and `ctx.forge.merge` return it only from a provider that does.
+
+`ForgeProvider` also gains optional `viewedFiles` with `setViewed`, `rerunChecks`, `requestReviews` with `reviewerCandidates`, and `updateBranch`; a provider without them keeps working, and the card then offers none of those actions.
+
+This affects third-party `ForgeProvider` implementations registered with `ctx.forge.register` and other code that builds `ChangeRequestSnapshot` or `ChangeRequestCheck` values. All types come from `@deepseek-ai/dsh-experimental-forge`.
+
+## Migration
+
+1. In every `ChangeRequestCheck` a provider builds, set `rerun: null` unless the provider implements `rerunChecks`; a provider that does names each rerunnable check with a branded `ForgeCheckId` it can resolve again, as [`actionsRun`](../../../../packages/experimental/forge-github/src/graphql.ts) does for GitHub Actions runs.
+2. In every `ChangeRequestSnapshot`, set the overview fields the host reports. Without host data, use `reviewers: []`, `reviewersTruncated: false`, `closingIssues: []`, `closingIssuesTruncated: false`, `branchUpdates: []`, `canRequestReviews: false`, and `canRerunChecks: false`; the card then shows the review decision alone and offers no overview action.
+3. Optionally implement the new provider methods; [`GitHubProvider`](../../../../packages/experimental/forge-github/src/provider.ts) shows each one, and the [forge subsystem page](../../../subsystems/forge.md#overview-and-viewed-marks) states their contract.
+4. Handle `unknown` wherever code switches exhaustively over `ForgeActionFailure['code']`: show that the outcome must be checked on the host, and do not try the change again before it is.
+5. Run your type check; it succeeds when every snapshot and check a provider builds sets the new fields and no `ForgeActionFailure` code is unhandled.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-change-request-overview/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "ChangeRequestSnapshot 新增必填的概览字段，ChangeRequestCheck 新增必填的 rerun 字段，ForgeActionFailure 新增 unknown 代码。"
+---
+
+# Forge 快照携带变更请求概览，操作报告结果不明
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ChangeRequestSnapshot` 新增七个必填字段：`reviewers` 与 `reviewersTruncated`、`closingIssues` 与 `closingIssuesTruncated`、`branchUpdates`、`canRequestReviews`，以及 `canRerunChecks`。`ChangeRequestCheck` 新增必填的 `rerun: ForgeCheckId | null`，指出提供方如何重跑该检查。变更请求卡片读取这些字段，列出评审者、关联 issue 与分支更新，并提供重跑失败检查、请求评审与更新分支。
+
+`ForgeActionFailure['code']` 新增 `unknown`：主机的答复无法确认结果，改动可能已经生效。GitHub 提供方在 GitHub 未确认已审阅标记、评审请求与分支更新的结果时返回它；`ctx.forge.markReady` 与 `ctx.forge.merge` 只在提供方返回它时才会返回。
+
+`ForgeProvider` 还新增可选的 `viewedFiles` 与 `setViewed`、`rerunChecks`、`requestReviews` 与 `reviewerCandidates`，以及 `updateBranch`；未实现它们的提供方照常工作，卡片不提供对应操作。
+
+受影响的是通过 `ctx.forge.register` 注册的第三方 `ForgeProvider` 实现，以及其他构造 `ChangeRequestSnapshot` 或 `ChangeRequestCheck` 值的代码。所有类型都来自 `@deepseek-ai/dsh-experimental-forge`。
+
+## 迁移
+
+1. 在提供方构造的每个 `ChangeRequestCheck` 中设置 `rerun: null`，除非提供方实现了 `rerunChecks`；实现了的提供方为每个可重跑的检查给出能再次解析的品牌化 `ForgeCheckId`，GitHub Actions 运行的做法见 [`actionsRun`](../../../../packages/experimental/forge-github/src/graphql.ts)。
+2. 在每个 `ChangeRequestSnapshot` 中设置托管平台报告的概览字段。没有平台数据时，使用 `reviewers: []`、`reviewersTruncated: false`、`closingIssues: []`、`closingIssuesTruncated: false`、`branchUpdates: []`、`canRequestReviews: false` 与 `canRerunChecks: false`；卡片随后只显示评审结论，不提供概览操作。
+3. 可选地实现新的提供方方法；[`GitHubProvider`](../../../../packages/experimental/forge-github/src/provider.ts) 展示了每个方法，契约见 [forge 子系统页面](../../../subsystems/forge.zh.md#overview-and-viewed-marks)。
+4. 在所有对 `ForgeActionFailure['code']` 做穷举的地方处理 `unknown`：提示需要到主机上核对结果，核对之前不要再次尝试该改动。
+5. 运行类型检查；提供方构造的每个快照与检查都设置了新字段、且没有未处理的 `ForgeActionFailure` 代码时即通过。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-pinned-diff/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "ForgeProvider.diff and ctx.forge.diff take the head commit to read, ForgeFailure gains the stale code, and ChangeRequestSnapshot gains threadsTruncated."
+---
+
+# Forge diffs read one head commit
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ForgeProvider.diff(ref, signal)` becomes `diff(ref, headSha, signal)`, and `ctx.forge.diff(ref, signal)` becomes `ctx.forge.diff(ref, headSha, signal)`. A provider returns a patch only when it describes `headSha`; when the change request's head is another commit, it resolves to a `ForgeFailure` whose code is the new `stale`. `ctx.forge.diff` then polls the change request again at once when it is watched. The GitHub provider reads the head and base commits in one GraphQL query, returns `stale` when the head is another commit, and otherwise reads the patch through the compare API between those two commits instead of `gh pr diff`. A GitHub pull request over 300 files, which `gh pr diff` refused as too large, now shows its complete diff; only output over `maxOutputBytes` or GitHub's own refusal remains `too-large`.
+
+`ForgeFailure['code']` gains `stale`. `ChangeRequestSnapshot` gains the required `threadsTruncated: boolean`, which marks `unresolvedThreads` as a lower bound when the provider counted only some review threads.
+
+The `forgePanel.changeRequestDiff` Remote rejects with `forgePanel/stale-head` instead of returning a patch read at another head.
+
+This affects third-party `ForgeProvider` implementations registered with `ctx.forge.register`, code that calls `ctx.forge.diff` or `forgePanel.changeRequestDiff`, code that builds `ChangeRequestSnapshot` values, and code that switches exhaustively over `ForgeFailure['code']`. All types come from `@deepseek-ai/dsh-experimental-forge`.
+
+## Migration
+
+1. In a `ForgeProvider`, add the `headSha: string` parameter to `diff` before `signal`. Return the patch only when the host computed it at `headSha`; otherwise return `{ code: 'stale', message }`. [`GitHubProvider.diff`](../../../../packages/experimental/forge-github/src/provider.ts) reads the current head first and then a diff addressed by commit.
+2. Pass the head commit to every `ctx.forge.diff` call, usually `ctx.forge.latest(ref)`'s `snapshot.headSha`. On `stale`, wait for a later status and read again at its head; do not cache the result under the old head.
+3. Set `threadsTruncated` in every `ChangeRequestSnapshot` a provider builds: `false` when `unresolvedThreads` counts every review thread.
+4. Handle `stale` wherever code switches exhaustively over `ForgeFailure['code']`, and `forgePanel/stale-head` wherever a caller of `forgePanel.changeRequestDiff` distinguishes Remote error codes.
+5. Run your type check; it succeeds when every `diff` implementation and call passes a head commit, every snapshot sets `threadsTruncated`, and no `ForgeFailure` code is unhandled.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-pinned-diff/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "ForgeProvider.diff 与 ctx.forge.diff 需要传入要读取的 head 提交，ForgeFailure 新增 stale 代码，ChangeRequestSnapshot 新增 threadsTruncated。"
+---
+
+# Forge diff 读取指定的 head 提交
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ForgeProvider.diff(ref, signal)` 改为 `diff(ref, headSha, signal)`，`ctx.forge.diff(ref, signal)` 改为 `ctx.forge.diff(ref, headSha, signal)`。提供方只在补丁描述 `headSha` 时返回补丁；变更请求的 head 已是其他提交时，resolve 为代码为新增 `stale` 的 `ForgeFailure`。此时若该变更请求正被 watch，`ctx.forge.diff` 会立即重新轮询它。GitHub 提供方在一次 GraphQL 查询中读取 head 与基准提交，head 是其他提交时返回 `stale`，否则不再使用 `gh pr diff`，改经 compare API 读取这两个提交之间的补丁。超过 300 个文件、此前被 `gh pr diff` 判为过大的 GitHub pull request 现在显示完整 diff；只有输出超过 `maxOutputBytes` 或 GitHub 自身拒绝时才仍为 `too-large`。
+
+`ForgeFailure['code']` 新增 `stale`。`ChangeRequestSnapshot` 新增必填字段 `threadsTruncated: boolean`；提供方只统计了部分评审讨论时，它表示 `unresolvedThreads` 只是下限。
+
+`forgePanel.changeRequestDiff` Remote 以 `forgePanel/stale-head` 拒绝，不再返回在其他 head 读到的补丁。
+
+受影响的是用 `ctx.forge.register` 注册的第三方 `ForgeProvider` 实现、调用 `ctx.forge.diff` 或 `forgePanel.changeRequestDiff` 的代码、构造 `ChangeRequestSnapshot` 的代码，以及对 `ForgeFailure['code']` 做穷尽分支的代码。这些类型都来自 `@deepseek-ai/dsh-experimental-forge`。
+
+## 迁移
+
+1. 在 `ForgeProvider` 的 `diff` 中，于 `signal` 之前加入 `headSha: string` 参数。只有托管平台在 `headSha` 处计算出补丁时才返回补丁，否则返回 `{ code: 'stale', message }`。[`GitHubProvider.diff`](../../../../packages/experimental/forge-github/src/provider.ts) 先读取当前 head，再读取按提交寻址的 diff。
+2. 每次调用 `ctx.forge.diff` 都传入 head 提交，通常是 `ctx.forge.latest(ref)` 的 `snapshot.headSha`。收到 `stale` 时，等待更新的状态并按其 head 重新读取；不要把结果缓存在旧 head 下。
+3. 提供方构造的每个 `ChangeRequestSnapshot` 都要设置 `threadsTruncated`：`unresolvedThreads` 统计了全部评审讨论时为 `false`。
+4. 凡对 `ForgeFailure['code']` 做穷尽分支的地方都处理 `stale`；凡区分 `forgePanel.changeRequestDiff` Remote 错误代码的调用方都处理 `forgePanel/stale-head`。
+5. 运行类型检查；所有 `diff` 实现与调用都传入 head 提交、所有快照都设置 `threadsTruncated`、没有未处理的 `ForgeFailure` 代码时，检查通过。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "ForgeFailure gains the unsupported code, which ctx.forge.readReview returns for a provider without review reads."
+---
+
+# Forge failures report unsupported reads
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ForgeFailure['code']` gains `unsupported`. `ctx.forge.readReview(ref, headSha, signal)`, new beside the optional `ForgeProvider.readReview`, returns it when the provider of the change request does not read review threads. Other reads keep their codes: a provider without `fetchChecks` still makes `ctx.forge.fetchChecks` return `unavailable`.
+
+This affects code that switches exhaustively over `ForgeFailure['code']`, such as a `Record<ForgeFailure['code'], …>` lookup or a `switch` that ends in `assertNever`. All types come from `@deepseek-ai/dsh-experimental-forge`. Providers need no change: `readReview` is optional.
+
+## Migration
+
+1. Handle `unsupported` wherever code switches exhaustively over `ForgeFailure['code']`; treat it as a capability the provider lacks, not as a failed read to retry.
+2. Run your type check; it succeeds when no `ForgeFailure` code is unhandled.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "ForgeFailure 新增 unsupported 代码；提供方不支持读取评审讨论时，ctx.forge.readReview 返回它。"
+---
+
+# Forge 失败代码报告不支持的读取
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ForgeFailure['code']` 新增 `unsupported`。新增的 `ctx.forge.readReview(ref, headSha, signal)` 对应可选的 `ForgeProvider.readReview`；变更请求的提供方不支持读取评审讨论时，它返回 `unsupported`。其他读取的代码不变：提供方未实现 `fetchChecks` 时，`ctx.forge.fetchChecks` 仍返回 `unavailable`。
+
+受影响的是对 `ForgeFailure['code']` 做穷举的代码，例如 `Record<ForgeFailure['code'], …>` 查表，或以 `assertNever` 结尾的 `switch`。所有类型都来自 `@deepseek-ai/dsh-experimental-forge`。提供方无需修改：`readReview` 是可选方法。
+
+## 迁移
+
+1. 在所有对 `ForgeFailure['code']` 做穷举的地方处理 `unsupported`，把它当作提供方缺少的能力，而不是需要重试的读取失败。
+2. 运行类型检查；没有未处理的 `ForgeFailure` 代码时即通过。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/package-export-cleanup/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: Internal helper values are removed from three published plugin-root entries.
+---
+
+# Replace internal plugin-root imports
+
+English | [中文](guide.zh.md)
+
+## Change
+
+After upgrading from v0.2.2-rc.1, the following plugin-root values are no longer exported. Their implementations remain inside the packages. Consumers importing these values from a package root must change their imports or use the owning service.
+
+| Package suffix (`@deepseek-ai/dsh-`) | Removed root helpers |
+|---|---|
+| `file-reference-local` | `DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES`, `DEFAULT_FILE_SEARCH_MAX_ENTRIES`, `DEFAULT_FILE_SEARCH_MAX_RESULTS`, `WorkspaceFileSearch`, `FILE_REFERENCE_PROMPT`, `activeAtToken`, `formatFileMention` |
+| `llm-pi-ai` | `recordKeyFor` |
+| `lsp-stdio` | `LspConnection`, `LspInstance`, `MessageDecoder`, `canonicalizeWorkspace`, `encodeMessage`, `negotiatePositionEncoding`, `normalizeHover`, `normalizeLocations`, `readHostSource`, `requestMethod`, `supportsOperation`, `supportsTransientOpen` |
+
+Brand constructors, package subpaths, persisted values and Session formats are unchanged.
+
+## Migration
+
+1. Stop importing the listed helper values from plugin roots. Package-owned tests can use relative imports from the corresponding internal modules.
+2. Application code should use the injected `fileReferences` or `lsp` service instead of provider implementation classes or protocol helpers. File-reference grammar remains at `@deepseek-ai/dsh-file-reference/grammar`; `FILE_REFERENCE_PROMPT` remains at `@deepseek-ai/dsh-file-reference`. `recordKeyFor` has no replacement public entry.
+3. Compile the application and run its tests. Load any plain-JavaScript consumers under Node as well: TypeScript checking alone does not cover missing ESM named exports in `.mjs` files.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/package-export-cleanup/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: 三个已发布插件的根入口移除内部辅助实体的值导出。
+---
+
+# 替换内部插件根导入
+
+[English](guide.md) | 中文
+
+## 变更
+
+从 v0.2.2-rc.1 升级后，以下插件根入口不再导出这些值。对应实现在包内保留。从包根入口导入这些值的消费方需要更改导入或改用所属服务。
+
+| 包名后缀（`@deepseek-ai/dsh-`） | 移除的根辅助实体 |
+|---|---|
+| `file-reference-local` | `DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES`、`DEFAULT_FILE_SEARCH_MAX_ENTRIES`、`DEFAULT_FILE_SEARCH_MAX_RESULTS`、`WorkspaceFileSearch`、`FILE_REFERENCE_PROMPT`、`activeAtToken`、`formatFileMention` |
+| `llm-pi-ai` | `recordKeyFor` |
+| `lsp-stdio` | `LspConnection`、`LspInstance`、`MessageDecoder`、`canonicalizeWorkspace`、`encodeMessage`、`negotiatePositionEncoding`、`normalizeHover`、`normalizeLocations`、`readHostSource`、`requestMethod`、`supportsOperation`、`supportsTransientOpen` |
+
+品牌构造器、包子路径、持久化值和 Session 格式不变。
+
+## 迁移
+
+1. 停止从插件根入口导入上表的辅助实体值。包内测试可以相对导入对应内部模块。
+2. 应用代码应使用注入的 `fileReferences` 或 `lsp` 服务，而不是提供方的实现类或协议辅助函数。文件引用语法仍在 `@deepseek-ai/dsh-file-reference/grammar`；`FILE_REFERENCE_PROMPT` 仍在 `@deepseek-ai/dsh-file-reference`。`recordKeyFor` 没有替代的公开入口。
+3. 编译应用并运行其测试，同时用 Node 加载纯 JavaScript 消费方：仅检查 TypeScript 无法覆盖 `.mjs` 文件中缺少 ESM 命名导出的错误。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/plugin-update-method/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "BundleInfo.updatable is replaced by BundleInfo.update, and ManagementError gains the unexpected-package code."
+---
+
+# `BundleInfo.update` replaces `BundleInfo.updatable`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`pluginManager.listBundles()` no longer returns `BundleInfo.updatable: boolean`. It returns the optional `BundleInfo.update`, which is `'registry'` for a bundle whose newer versions `listVersions` reads, `'git'` for a bundle installed from a Git spec pinned to a full commit, and absent for a bundle `updateBundle` cannot replace. A bundle that `updatable: true` marked before is now `update: 'registry'`. `updateBundle` also accepts a `'git'` bundle when `options.spec` names a newer commit of the same repository directory.
+
+`ManagementError['code']` gains `unexpected-package`: an installation run with `InstallBundleOptions.expected`, which `updateBundle` always passes, fails with it when the spec installs another package or version.
+
+This affects code that reads `listBundles()` through the Host API, `@deepseek-ai/dsh-plugin-manager/types`, or the remote client in `@deepseek-ai/dsh-api-remotes/client`, and code that switches exhaustively over `ManagementError['code']`. The `plugin_manager` tool never returned the field and is unchanged.
+
+## Migration
+
+1. Replace each read of `updatable`. To decide whether `listVersions` can list a bundle's versions, test `bundle.update === 'registry'`; to decide whether `updateBundle` can replace it at all, test `bundle.update !== undefined`.
+2. If code switches exhaustively over `ManagementError['code']`, handle `unexpected-package`.
+3. Run your type check; it succeeds when no `updatable` read and no unhandled `ManagementError` code remains.