dsh-primer 0.4.3 → 0.4.5

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: 43ace3409e7976b8
+  zh: da185b705dfe600a
+/native-cua-application-and-window-api/migration:
+  en: 33bdef11cad75c53
+  zh: 0d576c6160278b7b

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
+
+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/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) | 中文
+
+## 变更
+
+截图和指针输入要求显式选择窗口。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/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/package-export-cleanup/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/package-export-cleanup/guide.md
+/:
+  en: 5048dc7fc046e7ab
+  zh: 7845cb3ba5a543d4
+/replace-internal-plugin-root-imports:
+  en: 65af277d1f4ed1a0
+  zh: 9d2b980fb6fabe89
+/replace-internal-plugin-root-imports/change:
+  en: fcb1af4db4d0edd5
+  zh: 6cc6ed79d0100eac
+/replace-internal-plugin-root-imports/migration:
+  en: 01c24ef3fa9273f6
+  zh: cd5ae3b6f0218aba

package/references/official-docs/docs/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/references/official-docs/docs/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/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/ptc-bootstrap-protocol/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/ptc-bootstrap-protocol/guide.md
+/:
+  en: cee454924a9ab1f8
+  zh: 2d7cbdcc398fa914
+/node-ptc-bootstrap-protocol-version-3-and-the-scoped-repl-format:
+  en: 541c4f16c0107c90
+  zh: edda22e2ebf01992
+/node-ptc-bootstrap-protocol-version-3-and-the-scoped-repl-format/change:
+  en: f9b071385a270a1e
+  zh: e664c70b769579e9
+/node-ptc-bootstrap-protocol-version-3-and-the-scoped-repl-format/migration:
+  en: 350de9ad88b43420
+  zh: 8b8bfe380cbf6fe8

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-bootstrap-protocol/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Update custom Node PTC bootstraps to protocol version 3 before running them with the upgraded Host, and handle the new scoped-repl program format."
+---
+
+# Node PTC bootstrap protocol version 3 and the scoped-repl format
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Node PTC Host requires bootstrap protocol version 3 instead of version 2. It rejects an older bootstrap before dispatching a program, with `bootstrap protocol mismatch; upgrade launch.bootstrapPath with the host`. This affects custom `launch.bootstrapPath` deployments in every execution mode, including `@deepseek-ai/dsh-ssh` hosts with a `node-script` launch that set `launch.bootstrapPath` and `launch.bootstrapHash`. The bootstrap bundled with DSH updates with the Host and needs no configuration change.
+
+Version 3 carries optional `ProgramBootData.initialization` source for each new environment. The bootstrap evaluates it separately after installing current bindings, then awaits the Host's `initialized()` RPC acceptance and rechecks cancellation before running the model program. Initialization failure discards the environment and prevents model execution. The Node provider supports initializer registration only in `persistent-in-memory` mode.
+
+Version 3 also carries `ProgramBootData.discardCompletion` to discard completion values before JSON validation and serialization. The bootstrap provides `inspect` and sends selected images through `HostMethods.image(id)` in output order. Custom bootstraps must support these fields and methods alongside environment initialization.
+
+Version 3 also adds the `scoped-repl` program format. `PtcProgramFormat` in `@deepseek-ai/dsh-ptc-runtime` now includes `'scoped-repl'`, which `@deepseek-ai/dsh-ptc-runtime-node` reports as `PtcRuntime.programFormat` when `replScoped: true` is set with `executionMode: persistent-in-memory`. Code that matches the union exhaustively stops compiling until it handles the new value.
+
+## Migration
+
+1. If your Node PTC configuration sets `launch.bootstrapPath`, deploy the matching version of `@deepseek-ai/dsh-ptc-runtime-node` in its execution environment. Use the package's built `lib/process.js` or REPL-default `lib/persistent-process.js` with its dependencies. Keep the Host and bootstrap versions aligned; changing only the advertised version is insufficient.
+2. Update `launch.bootstrapPath` to the matching entry and restart the provider. For `@deepseek-ai/dsh-ssh` with a `node-script` launch, copy the new bootstrap to the remote `launch.bootstrapPath` and set `launch.bootstrapHash` to its lowercase SHA-256, for example from `sha256sum`. For local deployments that need no custom bootstrap, remove that override to use the installed default. The [Node runtime documentation](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#persistent-repl) describes retained execution and remote launch.
+3. Handle `'scoped-repl'` wherever code switches over `PtcProgramFormat` or keys a record by it. A `scoped-repl` program is REPL statements whose final expression is the result; top-level `return` is not supported, and a final Promise is not awaited.
+4. Run a program in each configured execution mode and confirm that it completes without the protocol error. Consumers using `registerEnvironmentInitializer(program)` must also verify that initialization runs once per new environment and that an initialization error prevents the model program's effects. Typecheck the code that uses `PtcProgramFormat`.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-bootstrap-protocol/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "自定义 Node PTC bootstrap 必须升级到协议版本 3，才能与新版 Host 一起运行；还要处理新增的 scoped-repl 程序格式。"
+---
+
+# Node PTC bootstrap 协议版本 3 与 scoped-repl 格式
+
+[English](guide.md) | 中文
+
+## 变更
+
+Node PTC Host 要求 bootstrap 协议版本从 2 升至 3。它会在派发程序前拒绝旧 bootstrap，并报告 `bootstrap protocol mismatch; upgrade launch.bootstrapPath with the host`。这影响所有执行模式下自定义 `launch.bootstrapPath` 的部署，包括使用 `node-script` 启动、设置了 `launch.bootstrapPath` 和 `launch.bootstrapHash` 的 `@deepseek-ai/dsh-ssh` 宿主。DSH 内置 bootstrap 随 Host 更新，无需修改配置。
+
+版本 3 为每个新环境携带可选的 `ProgramBootData.initialization` 源码。bootstrap 安装本次绑定后独立执行初始化，随后等待 Host 对 `initialized()` RPC 的确认，再次检查取消状态后才执行模型程序。初始化失败会丢弃环境并阻止模型代码执行。Node 提供方仅在 `persistent-in-memory` 模式下支持注册初始化程序。
+
+版本 3 还携带 `ProgramBootData.discardCompletion`，用于在 JSON 校验和序列化前丢弃完成值。bootstrap 提供 `inspect`，并通过 `HostMethods.image(id)` 按输出顺序发送选中的图片。自定义 bootstrap 必须同时支持这些字段、方法和环境初始化。
+
+版本 3 还新增了 `scoped-repl` 程序格式。`@deepseek-ai/dsh-ptc-runtime` 的 `PtcProgramFormat` 新增 `'scoped-repl'`；`@deepseek-ai/dsh-ptc-runtime-node` 在 `executionMode: persistent-in-memory` 下设置 `replScoped: true` 时，`PtcRuntime.programFormat` 报告这个值。对这个联合类型做穷尽匹配的代码，处理新值之前无法通过编译。
+
+## 迁移
+
+1. 如果 Node PTC 配置设置了 `launch.bootstrapPath`，请在其执行环境中部署匹配版本的 `@deepseek-ai/dsh-ptc-runtime-node`。使用包内构建产物 `lib/process.js`，或默认采用 REPL 的 `lib/persistent-process.js`，并保留其依赖。Host 与 bootstrap 版本必须匹配；只修改声明的版本号并不够。
+2. 将 `launch.bootstrapPath` 指向匹配的入口并重启提供方。使用 `node-script` 启动的 `@deepseek-ai/dsh-ssh`：把新的 bootstrap 复制到远端的 `launch.bootstrapPath`，并把 `launch.bootstrapHash` 设为它的小写 SHA-256，例如用 `sha256sum` 计算。本地部署若不需要自定义 bootstrap，可以移除此覆盖项以使用安装默认值。[Node 运行时文档](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#persistent-repl)说明状态保留和远程启动方式。
+3. 在按 `PtcProgramFormat` 分支或以它为键的地方处理 `'scoped-repl'`。`scoped-repl` 程序是 REPL 语句，最后一条表达式就是结果；不支持顶层 `return`，末尾的 Promise 不会被等待。
+4. 在每种已配置的执行模式中运行一个程序，确认正常完成且没有协议错误。使用 `registerEnvironmentInitializer(program)` 的消费方还须验证：初始化在每个新环境中只执行一次，且初始化出错时模型程序不会产生效果。再对使用 `PtcProgramFormat` 的代码做类型检查。