dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-operation-tools/guide.zh.md

@@ -0,0 +1,49 @@
+---
+kind: upgrade-guide
+description: "删除 `office-render`、`office-recalculate` 和 `office-export-pdf` 技能、skill-office 的 `node` 和 `cli` 配置键，以及两个 Office CLI 环境变量；Office 操作改用由技能激活的工具。"
+---
+
+# Office 操作技能由 Office 工具取代
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-skill-office` 不再注册 `office-render`、`office-recalculate` 和 `office-export-pdf` 技能，只注册 `office` 路由技能，以及 `office-docx`、`office-pptx` 和 `office-xlsx` 编写技能。加载 Office 技能后，模型从下一步起调用 [`office_render`、`office_convert` 和 `office_recalculate`](../../../../packages/document/tool-office/README.zh.md)。
+
+配置变化：
+
+| 已删除 | 替代 |
+|---|---|
+| `skill-office` 配置键 `node` 和 `cli` | 无；Office 工具在 Host 中转换 |
+| `DSH_BUNDLED_OFFICE_CLI` 和 `DSH_BUNDLED_OFFICE_NODE` | 无；不再有组件读取它们 |
+| `DSH_BUNDLED_PRIMARY_RUNTIME` | `DSH_PRIMARY_RUNTIME` |
+
+`skill-office` 新增 `pythonEnvironment`。默认值 `'workspace-dependencies'` 让 Python 技能调用 `load_workspace_dependencies`；没有挂载 `@deepseek-ai/dsh-tool-workspace-dependencies` 的组合必须设为 `'user'`。`DSH_BUNDLED_OFFICE_SKILLS` 的删除见 [Office 技能资源](../office-skill-resources/guide.zh.md)。
+
+Office 工具在 Host 进程内用原生 LibreOffice Kit 引擎解析不可信的文档，不受 shell 沙箱和 PTC 权限约束，并具有 Host 用户的权限；输入仍由文件系统后端授权。`office-kit` 条目新增 `outputDirectory`（默认 `$DSH_HOME/office-kit/outputs`）、`outputRetentionMs` 和 `maxOutputStoreBytes`。
+
+Web profile，以及没有 primary runtime 的 SDK profile，会在首次请求上下文和 `/` 菜单中列出 Office 技能。
+
+受影响的有：使用已删除技能的用户和提示词，设置了已删除配置键或环境变量的组合和启动器，`assetRoot` 技能副本，已保存的 `standard` 或 `ptc` 预设，依赖 shell 沙箱解析文档的部署，以及固定了首次请求上下文或 `/` 菜单的测试。
+
+## 迁移
+
+1. 把每个已删除的技能替换为加载 `office` 并调用对应工具：
+   - `office-render`：`office_render`；
+   - `office-recalculate`：`office_recalculate`，`format` 为 `"xlsx"` 或 `"ods"`；
+   - `office-export-pdf`：`office_convert`，`format` 为 `"pdf"`。
+2. 从 `cordis.yml`、patch 和 overlay 的所有 `skill-office` 行中删除 `node` 和 `cli`。除非组合挂载了 `@deepseek-ai/dsh-tool-workspace-dependencies`，否则设置 `pythonEnvironment: user`。
+3. 不使用随发行版 bundle、自行挂载 `@deepseek-ai/dsh-skill-office` 的组合，同时挂载 `@deepseek-ai/dsh-office-kit` 和 `@deepseek-ai/dsh-tool-office`。
+4. 在启动器中不再设置 `DSH_BUNDLED_OFFICE_CLI` 和 `DSH_BUNDLED_OFFICE_NODE`，并把 `DSH_BUNDLED_PRIMARY_RUNTIME` 改名为 `DSH_PRIMARY_RUNTIME`。Python SDK 优先使用环境中设置或继承的 `DSH_PRIMARY_RUNTIME`（空值也一样），其次才是下载缓存；要使用缓存，请取消设置该变量。
+5. 在 `assetRoot` 引用的副本中，用已安装包 `assets/` 下的对应目录替换其余四个目录，并删除三个已删除技能的目录。
+6. 在 Agent 预设编辑器中保存过的 `standard` 或 `ptc` 预设会替换随发行版提供的插件列表，因此其 Session 没有 Office 工具。把下面这一行加入已保存的列表，或加入 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 中 `preset-standard` 或 `preset-ptc` 行的 `config.plugins`（`<profile>`：`web` 或 `desktop`）：
+
+   ```yaml
+   - id: tool-office
+     name: '@deepseek-ai/dsh-tool-office'
+   ```
+
+7. 需要在沙箱中解析文档的部署不挂载 `@deepseek-ai/dsh-tool-office`。
+8. 更新首次请求上下文和 `/` 菜单的预期结果，使其包含 Office 技能。
+9. 确认：在 `standard` 或 `ptc` 的新 Session 中发送 `/office`，再另发一条导出 PDF 的请求；该请求会产生一次 `office_convert` 调用，返回临时 PDF 路径或 `unavailable` 消息。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-skill-resources/guide.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: "`DSH_BUNDLED_OFFICE_SKILLS` and the `office-skills/` resource directories are removed; Office skills load from the `skill-office` package's assets."
+---
+
+# Office skills load from the packaged assets
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Web and SDK profiles no longer set `assetRoot` on the `skill-office` row, so [`@deepseek-ai/dsh-skill-office`](../../../../packages/skill/skill-office/README.md) reads the Office skills from its packaged `assets/` in every deployment:
+
+| Removed | Replacement |
+|---|---|
+| `DSH_BUNDLED_OFFICE_SKILLS` | `assetRoot` in a profile patch, or same-name filesystem skills |
+| Desktop `resources/runtime/office-skills/` | The skill package inside `resources/app.asar` |
+| Python runtime wheel `<platform>-<arch>/office-skills/` | The skill package inside the runtime executable |
+| `office-skills/` beside `primary-runtime/` in `pnpm run prepare:primary-runtime` output and the downloaded authoring payload | None |
+
+`pythonEnvironment` and its values are unchanged. This affects launchers that set `DSH_BUNDLED_OFFICE_SKILLS`, tools that read or edit skill files in those directories, and container images that copy `office-skills/` beside `primary-runtime/`.
+
+## Migration
+
+1. Stop setting `DSH_BUNDLED_OFFICE_SKILLS`. To keep a custom skill directory, set `assetRoot` in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`. A patch replaces the row's whole `config`, so also set `pythonEnvironment: user` unless the profile mounts `workspace-dependencies`, which requires a nonempty `DSH_PRIMARY_RUNTIME` in Desktop and the SDK:
+
+   ```yaml
+   - id: skill-office
+     config:
+       assetRoot: /absolute/path/to/office-skills
+       pythonEnvironment: user
+   ```
+
+2. Alternatively, place a skill named `office`, `office-docx`, `office-pptx`, or `office-xlsx` in a [project or user skill directory](../../../../packages/skill/skill-filesystem/README.md); filesystem skills take precedence over the bundled skills with the same name.
+3. Remove steps that copy or read `office-skills/` in Desktop resources, Python wheels, or prepared primary-runtime payloads. Containers copy only `primary-runtime/` and keep `DSH_PRIMARY_RUNTIME` pointing at it.
+4. Confirm: in a new Session, load `office-docx`; its result names a base directory under the skill package's `assets/`, under the configured `assetRoot`, or in the overriding skill directory.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/office-skill-resources/guide.zh.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: "`DSH_BUNDLED_OFFICE_SKILLS` 和 `office-skills/` 资源目录被删除；Office 技能从 `skill-office` 包的 assets 加载。"
+---
+
+# Office 技能从包内 assets 加载
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 和 SDK profile 不再为 `skill-office` 行设置 `assetRoot`，因此 [`@deepseek-ai/dsh-skill-office`](../../../../packages/skill/skill-office/README.zh.md) 在所有部署中都从包内 `assets/` 读取 Office 技能：
+
+| 已删除 | 替代 |
+|---|---|
+| `DSH_BUNDLED_OFFICE_SKILLS` | profile patch 中的 `assetRoot`，或同名文件系统技能 |
+| Desktop `resources/runtime/office-skills/` | `resources/app.asar` 内的技能包 |
+| Python 运行时 wheel 的 `<platform>-<arch>/office-skills/` | 运行时可执行程序内的技能包 |
+| `pnpm run prepare:primary-runtime` 输出和下载的创作载荷中与 `primary-runtime/` 同级的 `office-skills/` | 无 |
+
+`pythonEnvironment` 及其取值不变。受影响的有：设置 `DSH_BUNDLED_OFFICE_SKILLS` 的启动器，读取或编辑上述目录中技能文件的工具，以及把 `office-skills/` 复制到 `primary-runtime/` 旁边的容器镜像。
+
+## 迁移
+
+1. 不再设置 `DSH_BUNDLED_OFFICE_SKILLS`。要继续使用自定义技能目录，在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 中设置 `assetRoot`。patch 会替换该行的整个 `config`，因此除非 profile 挂载了 `workspace-dependencies`（Desktop 和 SDK 都要求 `DSH_PRIMARY_RUNTIME` 非空），还要设置 `pythonEnvironment: user`：
+
+   ```yaml
+   - id: skill-office
+     config:
+       assetRoot: /absolute/path/to/office-skills
+       pythonEnvironment: user
+   ```
+
+2. 也可以在[项目或用户技能目录](../../../../packages/skill/skill-filesystem/README.zh.md)中放置名为 `office`、`office-docx`、`office-pptx` 或 `office-xlsx` 的技能；文件系统技能优先于同名内置技能。
+3. 删除从 Desktop 资源、Python wheel 或准备好的主运行时载荷中复制或读取 `office-skills/` 的步骤。容器只复制 `primary-runtime/`，并让 `DSH_PRIMARY_RUNTIME` 继续指向它。
+4. 确认：在新 Session 中加载 `office-docx`，其结果给出的基础目录位于技能包的 `assets/` 下、所配置的 `assetRoot` 下，或覆盖它的技能目录中。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/account-notification-fields/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "Generic account notification APIs replace bonus-specific methods and notification requests use the Harness domain."
+---
+
+# Update account notification consumers
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`DeepSeekAccount.getNotifications()` and `account/getNotifications` replace `getUnnotifiedBonuses()`. They return `AccountNotificationBatch.notifications` with opaque string `id`, `createdAt`, nullable `displayUntil`, localized `title` and `body`, ordered `actions`, and optional JSON `data`. The batch also requires `nextPollAfterSeconds`, projected from the wire field `next_poll_after`. Bonus metadata belongs in `data`; the bonus-specific types and fields are removed. `reportNotificationEvent()` replaces `ackBonusNotified()` and takes `(id, event, client)` to report `displayed`, `cta_clicked`, or `dismissed` using the notification ID. `getNotificationContent()` reads localized content by notification ID, including consumed notifications, without changing consumption.
+
+`DeepSeekAccount.watch()` and `account/watch` emit `AccountUpdate` items containing `type` and the complete `state`. Initial subscription and login progress use `snapshot`; credential writes and removal use `credentials-changed`.
+
+The account provider adds `harnessOrigin`, defaulting to `https://harness.deepseek.com`, for notification list, content, and events. `platformOrigin` retains its `https://platform.deepseek.com` default for login, profile, balance, logout, external navigation, and native embedded pages. Grant issuer checks still use `platformOrigin`.
+
+`ui-account-notifications` owns notifications; `ui-settings-account` supplies its account state, refresh events, and presentation slot.
+
+## Migration
+
+1. Read account state from `update.state`. A `credentials-changed` event or new Remote-stream generation clears notification state and restarts polling when signed in; progress snapshots retain it. Update providers, Remote consumers, and fixtures to use the new fields, opaque string IDs, and required delay in seconds. List decoding skips malformed or unsupported notifications individually; malformed envelopes still fail the request.
+2. Remove notification account-ID arguments and the batch accountId field. `getNotificationContent(id, client)` and `reportNotificationEvent(id, event, client)` use the current token directly, without a profile preflight. Credential changes end old requests, cards, and polls; late replies are discarded. Report each event once; valid `acked: true` and `acked: false` responses both finish the attempt. Failed reports keep local card state and are not retried. Report `displayed` after presentation, `cta_clicked` for every non-dismiss action with no action ID, and only `dismissed` after explicit close. Action clicks retain the card and execute without waiting for the report; closing before presentation does not generate a display event; expiry and account cleanup do not count as dismissal. Refresh current cards through `getNotificationContent()` when the language changes; retain their position and avoid another display event.
+3. Remove `bonusAckRetryDelayMs` and `bonusAckRetryMaxDelayMs` from `ui-settings-account` configuration; event reporting has no retry settings. A failed report does not undo the current interaction or retry that report. If a later list offers a closed notification again, the client displays it again.
+4. Keep existing `platformOrigin` configuration. Private deployments and loopback fixtures set `harnessOrigin` to their notification service origin. Confirm only list, content, and events use that origin; login, profile, balance, logout, and pages retain `platformOrigin`.
+5. Load `@deepseek-ai/dsh-client-ui-account-notifications` beside account settings. Set its new `notificationPollIntervalMs` option when the ten-minute initial interval is unsuitable. Move notification-state and reporting consumers to the new plugin. Verify both plugins share one account stream, including after notification-plugin reload.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/account-notification-fields/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "通用账号通知 API 替换赠金专用方法，通知请求改用 Harness 域名。"
+---
+
+# 更新账号通知使用方
+
+[English](guide.md) | 中文
+
+## 变更
+
+`DeepSeekAccount.getNotifications()` 和 `account/getNotifications` 替换 `getUnnotifiedBonuses()`，返回的 `AccountNotificationBatch.notifications` 包含不透明字符串 `id`、`createdAt`、可为 null 的 `displayUntil`、本地化的 `title` 与 `body`、有序的 `actions`，以及可选 JSON `data`。批次还要求提供 `nextPollAfterSeconds`，由接口字段 `next_poll_after` 投影。赠金元数据放入 `data`；赠金专用类型和字段移除。`reportNotificationEvent()` 替换 `ackBonusNotified()`，接收 `(id, event, client)`，以通知 ID 上报 `displayed`、`cta_clicked` 或 `dismissed` 事件。`getNotificationContent()` 按通知 ID 读取本地化内容，支持已消费通知，不改变消费状态。
+
+`DeepSeekAccount.watch()` 和 `account/watch` 发出包含 `type` 和完整 `state` 的 `AccountUpdate`。首次订阅和登录进度使用 `snapshot`；凭据写入和删除使用 `credentials-changed`。
+
+账号提供者新增 `harnessOrigin`，默认值为 `https://harness.deepseek.com`，用于通知 list、content 和 events。`platformOrigin` 保留 `https://platform.deepseek.com` 默认值，用于登录、资料、余额、退出登录、外部导航和原生内嵌页面。授权来源仍按 `platformOrigin` 校验。
+
+`ui-account-notifications` 负责通知；`ui-settings-account` 提供已有账号状态、刷新事件和展示插槽。
+
+## 迁移
+
+1. 从 `update.state` 读取账号状态。收到 `credentials-changed` 事件或 Remote 流进入新一代连接时，清空通知状态，已登录时重启轮询；进度快照保留当前轮询。更新提供者、Remote 使用方和测试夹具，使用新字段、不透明字符串 ID 和必填的秒数间隔。列表解码逐条跳过格式错误或不支持的通知；列表外层格式错误仍使请求失败。
+2. 移除通知方法的账号 ID 参数和批次的 accountId 字段。`getNotificationContent(id, client)` 和 `reportNotificationEvent(id, event, client)` 直接使用当前 token，不前置查询资料。凭据变化后终止旧请求、卡片与轮询，并丢弃迟到的响应。每次事件只上报一次；有效的 `acked: true` 和 `acked: false` 均结束本次尝试。上报失败保留本地卡片状态，不重试。展示后上报 `displayed`，所有非 dismiss 操作点击都上报 `cta_clicked`，不携带 action ID，主动关闭仅上报 `dismissed`。点击业务按钮保留卡片并立即执行操作，不等待上报；尚未展示就关闭时不补报展示事件；过期和账号清理不计为主动关闭。切换语言时，通过 `getNotificationContent()` 刷新当前卡片，保留位置，不重复上报展示事件。
+3. 从 `ui-settings-account` 配置中移除 `bonusAckRetryDelayMs` 和 `bonusAckRetryMaxDelayMs`；事件上报没有重试配置。上报失败不撤销当前交互，也不重试该次上报。后续列表再次返回已关闭通知时，客户端会再次展示。
+4. 保留已有的 `platformOrigin` 配置。私有部署和本机测试夹具将 `harnessOrigin` 设为各自的通知服务来源。确认仅 list、content 和 events 使用该来源；登录、资料、余额、退出登录和页面保留 `platformOrigin`。
+5. 在账号设置旁加载 `@deepseek-ai/dsh-client-ui-account-notifications`。初始十分钟间隔不适用时，设置其新增的 `notificationPollIntervalMs` 选项。将通知状态及上报使用方迁移到新插件。确认两个插件共用一条账号流，包括重载通知插件之后。

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` 代码时即通过。