dsh-primer 0.4.4 → 0.4.6

package/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/cua-native-platform/guide.md
+/:
+  en: 3938944aa9e69309
+  zh: 82f148f46c1e50cf
+/native-cua-application-and-window-api:
+  en: 207c515390c5e529
+  zh: bd4d90881efb011d
+/native-cua-application-and-window-api/change:
+  en: e5d1027faa55adba
+  zh: 4b88ad6a70977fb3
+/native-cua-application-and-window-api/migration:
+  en: 071b67613c512b84
+  zh: 7ee32d8dbcf7a0f2

package/references/official-docs/docs/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
+
+CUA scripts use an explicit window for screenshots and pointer input. App and Window objects share the latest accessibility snapshot for their application handle. Their identifiers are `appHandle` and `windowId` respectively. Application discovery still reports the PID of a running match.
+
+Providers supply startup capabilities alongside their platform guidance. The native helper reports runtime permissions and session lock state. The Host combines both in `getCapabilities()`. Human-facing permission responses carry a `darwin` or `win32` platform tag.
+
+## Migration
+
+1. After `cua.getApp(selector)`, select the target from `app.getWindows()` with `app.getWindow(windowId)`. 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; use `{ emit: false }` to retain the snapshot without displaying it. 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` to hold a key across tool calls. To request one repeat, send another down for a non-modifier key held by that execution. Returning, throwing or pausing releases any remaining keys. If your script handles unknown macOS key names as `NATIVE_ERROR`, handle `INVALID_ARGUMENT` instead. Correct the key name before retrying.
+5. Read `dispatched` from action results, then observe the application to verify 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. Use `listApps()` or running `findApps()` matches when you need a PID.
+6. For a custom provider, replace `CuaBackend.description` with `capabilities` and pass `guidance` and `permissionParameters` to `installCua`. Rebuild any custom `helperPath` against the [operation schema](../../../../packages/experimental/cua/src/protocol.ts) and [tagged permission response](../../../../packages/experimental/cua/src/access-types.ts). Restart the provider, inspect its advertised methods and keyboard scopes, and open the Computer Use permission page to verify its platform controls.

package/references/official-docs/docs/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) | 中文
+
+## 变更
+
+CUA 脚本在指定窗口上截图和操作鼠标。App 和 Window 对象共享同一应用句柄最近读取的辅助功能快照。App 用 `appHandle` 标识，Window 用 `windowId` 标识。查找应用时，运行中的匹配项仍提供 PID。
+
+提供方在安装时声明固定的平台能力并提供操作指引。原生 helper 返回实际的权限和会话锁定状态。Host 合并两者，作为 `getCapabilities()` 的结果。供权限页面使用的响应带有 `darwin` 或 `win32` 平台标记。
+
+## 迁移
+
+1. 调用 `cua.getApp(selector)` 后，从 `app.getWindows()` 返回的列表选定目标，再调用 `app.getWindow(windowId)`。在窗口上调用 `getScreenshot()`、`click()`、`scroll()` 和 `drag()`，将原有的 `hover` 调用改为 `window.mouseMove()`。在 macOS 上，`window.click(id)` 在元素中心发送鼠标事件。需要执行默认辅助功能动作时，改用 `invoke(id)`。需要打开控件菜单且控件声明了 `AXShowMenu` 时，调用 `performAction(id, "AXShowMenu")`。
+2. 将 `getAXState()` 改为 `getAccessibilityTree()`，将 `getAXStateAndScreenshot()` 拆成读取树和截图两次调用。选择应用或窗口不读取 AX。使用元素 ID 前须显式调用 `getAccessibilityTree()`；使用 `{ emit: false }` 可保留快照但不显示树。截图不要求 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` 中可调用此方法跨工具调用保持按键。如果需要一次重复按下，可在这次执行中对已按住的普通键再发一次 `down`。执行返回、异常退出或用户暂停时会释放仍按着的键。如果脚本用 `NATIVE_ERROR` 识别 macOS 上的未知键名，请改为处理 `INVALID_ARGUMENT`，并在重试前修正键名。
+5. 从动作结果读取 `dispatched`，再观察应用确认效果。元素没有默认动作时，`invoke` 返回 `dispatched: false`。移除读取旧字段 `verified` 的代码，以及对已选对象和窗口记录中 `pid` 的读取。需要 PID 时，使用 `listApps()` 或 `findApps()` 返回的运行中应用记录。
+6. 自定义提供方需将 `CuaBackend.description` 改为 `capabilities`，并向 `installCua` 传入 `guidance` 和 `permissionParameters`。如配置了 `helperPath`，请按[操作协议](../../../../packages/experimental/cua/src/protocol.ts)和[带平台标记的权限响应](../../../../packages/experimental/cua/src/access-types.ts)重新构建 helper。重启提供方，检查它声明的方法和键盘输入范围，再打开 Computer Use 权限页确认平台控件。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/dsh-doc-skill/guide.md
+/:
+  en: 9ad5a74808f483b2
+  zh: c89b849f5de717aa
+/dsh-doc-replaces-the-creator-mode-skills:
+  en: c87b3ce7403fa47c
+  zh: 1d0a8ca0fead88a7
+/dsh-doc-replaces-the-creator-mode-skills/change:
+  en: 42be2a4794ccbf7c
+  zh: bb02fb4b4acb9526
+/dsh-doc-replaces-the-creator-mode-skills/migration:
+  en: 1782843e22357167
+  zh: f8eaab2275d1510f

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/forge-change-request-overview/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/forge-change-request-overview/guide.md
+/:
+  en: 5788ee9fab8253cf
+  zh: c8f8da46139d3aec
+/forge-snapshots-carry-the-change-request-overview-and-actions-report-unknown-outcomes:
+  en: a3a5753044d1188b
+  zh: 16562b29b23a3fea
+/forge-snapshots-carry-the-change-request-overview-and-actions-report-unknown-outcomes/change:
+  en: a571055593a2aa44
+  zh: 405b322b9863f841
+/forge-snapshots-carry-the-change-request-overview-and-actions-report-unknown-outcomes/migration:
+  en: 92213118a4373782
+  zh: d41450b2776c59ea

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/forge-pinned-diff/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/forge-pinned-diff/guide.md
+/:
+  en: ad1c3c4e42227656
+  zh: 286eac73122ddbef
+/forge-diffs-read-one-head-commit:
+  en: c017d657e5d9eb08
+  zh: d0eb2aef480e7753
+/forge-diffs-read-one-head-commit/change:
+  en: 6b6465c90a0f893e
+  zh: fb265bd706a77196
+/forge-diffs-read-one-head-commit/migration:
+  en: 147b16ca7c30624c
+  zh: ce246be22d7c378a

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.md
+/:
+  en: 53dbdc67362a5851
+  zh: 9c7b2c4dd31cf666
+/forge-failures-report-unsupported-reads:
+  en: 3e5488f3008886b7
+  zh: 8123e954c41d559c
+/forge-failures-report-unsupported-reads/change:
+  en: 77712ff12908e838
+  zh: 00714f77f3b7ae80
+/forge-failures-report-unsupported-reads/migration:
+  en: 698a34a7e09be2be
+  zh: a32a64dc130f496f

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/plugin-update-method/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/plugin-update-method/guide.md
+/:
+  en: 24d651741581bb5e
+  zh: 670f4299c6fcb8b4
+/bundleinfo-update-replaces-bundleinfo-updatable:
+  en: 3ccbfa4a29f90906
+  zh: 3ff0b0d86a50c92f
+/bundleinfo-update-replaces-bundleinfo-updatable/change:
+  en: 23ec2f7f6b1e6197
+  zh: 33d096a4901d2de7
+/bundleinfo-update-replaces-bundleinfo-updatable/migration:
+  en: 782c9ca1a60d80a1
+  zh: 6528822070e970ee

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

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/plugin-update-method/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "BundleInfo.updatable 由 BundleInfo.update 取代，ManagementError 新增 unexpected-package 错误码。"
+---
+
+# `BundleInfo.update` 取代 `BundleInfo.updatable`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`pluginManager.listBundles()` 不再返回 `BundleInfo.updatable: boolean`，改为返回可选的 `BundleInfo.update`：`listVersions` 能读取其较新版本的组合包为 `'registry'`，从固定到完整提交的 Git spec 安装的组合包为 `'git'`，`updateBundle` 无法替换的组合包不含此字段。此前标记为 `updatable: true` 的组合包现在为 `update: 'registry'`。当 `options.spec` 指向同一仓库目录的较新提交时，`updateBundle` 也接受 `'git'` 组合包。
+
+`ManagementError['code']` 新增 `unexpected-package`：带 `InstallBundleOptions.expected` 运行的安装（`updateBundle` 总会传入该选项）在 spec 安装了其他包或其他版本时以此错误码失败。
+
+受影响的代码包括：通过 Host API、`@deepseek-ai/dsh-plugin-manager/types` 或 `@deepseek-ai/dsh-api-remotes/client` 中的远端客户端读取 `listBundles()` 的代码，以及对 `ManagementError['code']` 做穷尽 switch 的代码。`plugin_manager` 工具从未返回该字段，保持不变。
+
+## 迁移
+
+1. 替换每一处对 `updatable` 的读取。要判断 `listVersions` 能否列出组合包的版本，检查 `bundle.update === 'registry'`；要判断 `updateBundle` 是否能以任何方式替换它，检查 `bundle.update !== undefined`。
+2. 如果代码对 `ManagementError['code']` 做穷尽 switch，需要处理 `unexpected-package`。
+3. 运行类型检查；当不再有对 `updatable` 的读取，也没有未处理的 `ManagementError` 错误码时，类型检查通过。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/runtime-context-reminders/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/runtime-context-reminders/guide.md
+/:
+  en: 9420cefcafb5ca18
+  zh: 68b86eac2f0df9ca
+/runtime-context-reminder-records:
+  en: 24314b42a810c1c9
+  zh: caa0d211650dd3a8
+/runtime-context-reminder-records/change:
+  en: ccbbcf44f91bfdac
+  zh: 0ffa950b9ac802bf
+/runtime-context-reminder-records/migration:
+  en: f1dfb64843da4574
+  zh: b7d12032c4e411d8

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/runtime-context-reminders/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Runtime-context log text gains reminder framing, and clear markers record empty snapshot sections."
+---
+
+# Runtime-context reminder records
+
+English | [中文](guide.zh.md)
+
+## Change
+
+New `user/message` records with `source.kind: 'runtime-context'` wrap their text in `<system-reminder>`. The first snapshot introduces the current session without asserting that it replaces earlier context; later snapshots explicitly replace context retained in conversation summaries. Clear reminders now carry `form: 'snapshot'` and `sections: []`.
+
+A retained legacy snapshot or clear marker without `source.sections` is refreshed once on the next admitted request. This adds a message without rewriting the existing request prefix. A legacy snapshot with unchanged recorded sections is not refreshed solely for its wording. Session format and the public `renderContextSnapshot()` and `joinContextSections()` helpers remain unchanged.
+
+## Migration
+
+1. Update consumers that match runtime-context text literally to recognize the reminder wrapper and the initial/update introductions. Prefer `source.kind` and available `source.sections` when identifying or inspecting these records.
+2. Treat empty sections as cleared context, and retain support for older records without structured sections. Verify both an initial snapshot and a clear reminder in resumed-session output; existing Session files need no rewrite.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/runtime-context-reminders/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "运行时上下文日志文本增加提醒包装，清空标记记录空的快照条目。"
+---
+
+# 运行时上下文提醒记录
+
+[English](guide.md) | 中文
+
+## 变更
+
+新写入且 `source.kind: 'runtime-context'` 的 `user/message` 记录会将文本包在 `<system-reminder>` 内。首份快照介绍当前会话，不宣称覆盖更早的上下文；后续快照明确覆盖对话摘要保留的上下文。清空提醒现在携带 `form: 'snapshot'` 和 `sections: []`。
+
+保留的旧快照或清空标记若没有 `source.sections`，会在下一次获准请求时刷新一次。这会增加一条消息，但不改写现有请求前缀。若旧快照的已记录条目未变，则不会仅因文案而刷新。Session 格式及公开的 `renderContextSnapshot()`、`joinContextSections()` 辅助方法保持不变。
+
+## 迁移
+
+1. 更新按字面匹配运行时上下文文本的消费方，使其识别提醒包装和首次／后续引导语。识别或检查记录时，优先使用 `source.kind` 及可用的 `source.sections`。
+2. 将空条目视为上下文已清空，并继续支持不带结构化条目的旧记录。检查恢复会话输出中的首次快照和清空提醒；现有 Session 文件无需改写。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/session-append-overloads/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/session-append-overloads/guide.md
+/:
+  en: 0c7dd958bce09e16
+  zh: 3b3c85a2152294ec
+/update-replacements-for-session-append:
+  en: 5cc8a72cf2203e52
+  zh: 22976024cf5453eb
+/update-replacements-for-session-append/change:
+  en: 51fbd9ed1cd50cdf
+  zh: 103d3ac9b631414e
+/update-replacements-for-session-append/migration:
+  en: 19c39d4582b09f41
+  zh: 4345d25a52dec57e

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/session-append-overloads/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "Code that replaces Session.append must implement both the single-event and array overloads."
+---
+
+# Update replacements for `Session.append`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.2.2-rc.1, `Session.append` had a single call signature. It now accepts either one typed event call or an array of event tuples. Ordinary single-event calls still compile. Test doubles and wrappers assigned to `Session['append']` must support both overloads.
+
+## Migration
+
+1. For a wrapper around `Session.append`, preserve both overloads by wrapping the original function with a `Proxy` and forwarding from its `apply` trap with `Reflect.apply`. For a test double that only accepts one event, type the single-event helper separately and call it from the relevant test.
+2. Typecheck assignments to `Session['append']`. Call replacements with both `append('turn/start', { turn: 1 })` and `append([['turn/start', { turn: 1 }]])` and verify the first returns one event and the second an array.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/session-append-overloads/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "替换 Session.append 的代码必须实现单事件和数组两种重载。"
+---
+
+# 更新 `Session.append` 的替代实现
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.2-rc.1 中，`Session.append` 只有一个调用签名。现在它可接收一个带类型的事件调用，也可接收事件元组数组。普通单事件调用仍可编译。赋值给 `Session['append']` 的测试替身和包装函数必须支持两种重载。
+
+## 迁移
+
+1. 包装 `Session.append` 时，用 `Proxy` 包装原函数，在 `apply` 拦截器内用 `Reflect.apply` 转发，以保留两种重载。若测试替身只接收单个事件，给该辅助函数单独声明类型并在相应测试中调用。
+2. 检查赋值给 `Session['append']` 的代码能通过类型检查。分别以 `append('turn/start', { turn: 1 })` 和 `append([['turn/start', { turn: 1 }]])` 调用替代实现，验证前者返回一个事件，后者返回数组。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/subagent-interrupt-default/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-rc.1/subagent-interrupt-default/guide.md
+/:
+  en: fda192f58c50cd90
+  zh: 2ebe5d7389eb9689
+/built-in-configurations-disable-agent-interruption:
+  en: c253388db5ba6f5a
+  zh: af138bbc7bfd31b4
+/built-in-configurations-disable-agent-interruption/change:
+  en: 76b23fa746332e06
+  zh: d30315eab3aa53bd
+/built-in-configurations-disable-agent-interruption/migration:
+  en: 0f5bd67305b455dc
+  zh: a98770b64686d612