dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/office-skill-resources/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-alpha.3/office-skill-resources/guide.md
+/:
+  en: be76cf53968415f9
+  zh: e641c2ede9b53fcd
+/office-skills-load-from-the-packaged-assets:
+  en: 9dadceb35e48b91c
+  zh: 5c7103427581a6bd
+/office-skills-load-from-the-packaged-assets/change:
+  en: da134862e17a7bd2
+  zh: dc31dc816c669add
+/office-skills-load-from-the-packaged-assets/migration:
+  en: e9c9fc8e2ec5a9b0
+  zh: e736d57c47fb111c

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/subagent-names/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-alpha.3/subagent-names/guide.md
+/:
+  en: 9d10fcdf4af74152
+  zh: 1e932a7fe192df48
+/subagent-tools-address-agents-by-name:
+  en: 7aad2f3764a30b45
+  zh: 4e24d2370e54bc37
+/subagent-tools-address-agents-by-name/change:
+  en: 6b457593371cf01e
+  zh: 730d30aad31ebd91
+/subagent-tools-address-agents-by-name/migration:
+  en: d416c6b1cef47655
+  zh: edcae0ecc55dcfe5

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/subagent-names/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "Subagent control and Team task tools address agents by name, list_agents rows change, and subagent catalogs write payload version 3."
+---
+
+# Subagent tools address agents by name
+
+English | [中文](guide.zh.md)
+
+## Change
+
+New subagents have sibling-unique names in their creator's `subagent/catalog`. The root is `lead`; descendant names are paths such as `reviewer/checker`. The [subagent runtime](../../../../packages/subagent/subagent/README.md#agent-names) defines naming rules. Historical children keep their Session ids. Scripts, PTC, SDK callers, and transcripts must adopt these changes:
+
+- `send_message({ agent_id, message })` becomes `send_message({ agent, message })`, and `interrupt_agent({ agent_id })` becomes `interrupt_agent({ agent })`. `agent` accepts a name or a Session id. A call that still passes `agent_id` fails argument validation.
+- `subagent`, `subagent_fork`, and `subagent_oar` accept an optional `name`. They return `started subagent <name>` with result `{ kind: 'activation', name }`.
+- `list_agents` returns `{ name, status, description? }` rows instead of rows with `kind`, `id`, `label`, `parent`, `depth`, and `reason`. Unreadable branches report `corrupt`, `unsupported`, or `unavailable` as `status`. Text rows read `<name> [<status>] — <description>`.
+- Team task results replace `ownerId` with `owner`, the owner's name. `team_task_list` and `team_task_update` accept a name as `owner`. To list tasks without an owner, use `unowned: true` instead of `owner: "unowned"`.
+- Local and parent-delivered external creation write `subagent/catalog` payload version 3. Releases before this one reject catalogs that contain it, so they cannot open Sessions that create subagents after upgrading. See the [persistence acknowledgement](../../../persistence-changes/2026-11-02-subagent-catalog-names.md).
+- `SubagentActivation` has a required `name` field, and `SubagentActivationSpec` accepts an optional `name`.
+
+## Migration
+
+1. In scripts, PTC programs, and SDK calls, rename the `agent_id` argument of `send_message` and `interrupt_agent` to `agent`. Pass the name that `list_agents` or the start receipt reports; a saved Session id still works.
+2. Update parsers of `list_agents` output to read `name`, `status`, and `description`. Only complete named paths encode creators: the prefix before the last `/`, or `lead` without `/`. Unnamed children or ancestors cause Session-id fallback; these rows expose neither creator nor depth.
+3. Update Team task consumers to read `owner` instead of `ownerId`. Host code that calls `ctx.agentTeams` still reads `ownerId`; display `ownerName ?? ownerId`. New assignments persist optional `ownerName`; historical records remain unchanged. Older projections reject named tasks; see the [acknowledgement](../../../persistence-changes/2026-11-02-team-task-owner-names.md).
+4. Read `name` instead of `subagentId` from delegation tool results. Update recorded transcripts or fixtures that contain `agent_id` arguments, `started subagent <Session id>` receipts, identity runtime context text, `Agent <Session id> sent a message` signatures, `Background subagent <Session id>` notices, or the earlier `list_agents` rows. Signatures and notices now use names.
+5. Add `name` when constructing `SubagentActivation` values. Code that reads catalog rows can read the optional `name` field.
+6. Upgrade every process that opens the same Session store before creating subagents. Older releases cannot open Sessions that contain catalog payload version 3.
+7. To confirm the change, start a subagent with `name: "reviewer"` and check that the receipt reads `started subagent reviewer`, that `list_agents` lists `reviewer`, and that `send_message({ agent: "reviewer", message })` succeeds.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.3/subagent-names/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "Subagent 控制工具和 Team 任务工具按名称寻址 agent，list_agents 行格式改变，subagent 目录写入第 3 版载荷。"
+---
+
+# Subagent 工具按名称寻址 agent
+
+[English](guide.md) | 中文
+
+## 变更
+
+新 subagent（子智能体）在创建者的 `subagent/catalog` 中拥有同级唯一的名称。根为 `lead`；后代名称是 `reviewer/checker` 这样的路径。[subagent 运行时](../../../../packages/subagent/subagent/README.zh.md#agent-names)定义名称规则。升级前创建的子级继续以 Session id 作为名称。脚本、PTC、SDK 调用方和 transcript（文本记录）需要适配以下变更：
+
+- `send_message({ agent_id, message })` 改为 `send_message({ agent, message })`，`interrupt_agent({ agent_id })` 改为 `interrupt_agent({ agent })`。`agent` 接受名称或 Session id。仍传入 `agent_id` 的调用无法通过参数校验。
+- `subagent`、`subagent_fork` 和 `subagent_oar` 接受可选的 `name`。它们返回 `started subagent <name>`，结果为 `{ kind: 'activation', name }`。
+- `list_agents` 返回 `{ name, status, description? }` 行，取代含 `kind`、`id`、`label`、`parent`、`depth` 和 `reason` 的行。不可读分支以 `status` 报告 `corrupt`、`unsupported` 或 `unavailable`。文本行格式为 `<name> [<status>] — <description>`。
+- Team 任务结果以 `owner`（所有者名称）取代 `ownerId`。`team_task_list` 和 `team_task_update` 的 `owner` 接受名称。查询无所有者任务时，用 `unowned: true` 替代 `owner: "unowned"`。
+- 本地创建和父级投递的外部创建写入第 3 版 `subagent/catalog` 载荷。本版本之前的发布会拒绝包含该载荷的目录，因此无法打开升级后创建过 subagent 的 Session。参见[持久化确认记录](../../../persistence-changes/2026-11-02-subagent-catalog-names.zh.md)。
+- `SubagentActivation` 新增必需字段 `name`，`SubagentActivationSpec` 接受可选的 `name`。
+
+## 迁移
+
+1. 在脚本、PTC 程序和 SDK 调用中，将 `send_message` 和 `interrupt_agent` 的 `agent_id` 参数改名为 `agent`。传入 `list_agents` 或启动回执报告的名称；已保存的 Session id 仍可使用。
+2. 更新 `list_agents` 输出的解析器，读取 `name`、`status` 和 `description`。只有完整命名路径编码创建者：最后一个 `/` 之前的前缀，不含 `/` 时为 `lead`。未命名的子级或祖先导致回退到 Session id；这些行既不提供创建者，也不提供深度。
+3. 更新 Team 任务消费方，读取 `owner` 而非 `ownerId`。调用 `ctx.agentTeams` 的 host 代码仍读取 `ownerId`；展示时读取 `ownerName ?? ownerId`。新分配会持久化可选的 `ownerName`，历史记录保持不变。旧投影会拒绝带名称的任务；参见[确认记录](../../../persistence-changes/2026-11-02-team-task-owner-names.zh.md)。
+4. 从委派工具结果读取 `name` 而非 `subagentId`。更新包含 `agent_id` 参数、`started subagent <Session id>` 回执、身份运行时上下文文本、`Agent <Session id> sent a message` 署名、`Background subagent <Session id>` 通知或旧 `list_agents` 行的录制 transcript 或 fixture。署名和通知现在使用名称。
+5. 构造 `SubagentActivation` 值时添加 `name`。读取目录行的代码可读取可选的 `name` 字段。
+6. 在创建 subagent 之前，升级所有打开同一 Session 存储的进程。旧版本无法打开包含第 3 版目录载荷的 Session。
+7. 验证迁移：以 `name: "reviewer"` 启动一个 subagent，确认回执为 `started subagent reviewer`，`list_agents` 列出 `reviewer`，且 `send_message({ agent: "reviewer", message })` 成功。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/account-notification-fields/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/account-notification-fields/guide.md
+/:
+  en: 8436a6f26fab028f
+  zh: 38236167b791e6cc
+/update-account-notification-consumers:
+  en: bd380bec124f847c
+  zh: fcdb87325050b311
+/update-account-notification-consumers/change:
+  en: 035a33041e86f008
+  zh: fa1e62eba84f58ec
+/update-account-notification-consumers/migration:
+  en: 914732f69a48d226
+  zh: 251e69c9618f7445

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/account-remote-provider/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/account-remote-provider/guide.md
+/:
+  en: 561965d845c4ae75
+  zh: 169f6d5fe2d6d3e4
+/account-service-and-remote-imports:
+  en: ac80b8c714afec7b
+  zh: 62e1e73b51c3ea1d
+/account-service-and-remote-imports/change:
+  en: 7839978713aa24da
+  zh: 0225e3baa4425c46
+/account-service-and-remote-imports/migration:
+  en: fcaddf93cb778db9
+  zh: 4921e5ef8d75ea9e

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/archive-worktrees/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/archive-worktrees/guide.md
+/:
+  en: bd4ec57ff904967c
+  zh: 4be24cb594ad31ba
+/worktree-cleanup-on-archive:
+  en: bc309764ab7b8b98
+  zh: 20fdfbce76706025
+/worktree-cleanup-on-archive/change:
+  en: 990690039f918e72
+  zh: 8e23fbabf88a777f
+/worktree-cleanup-on-archive/migration:
+  en: 05f29b760cb99ae9
+  zh: 33f181ac2a582bdf

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/attachment-error-codes/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/attachment-error-codes/guide.md
+/:
+  en: 8a0a1ff4ca3ad446
+  zh: 4bd6cd51cbd791c2
+/attachment-failures-keep-their-codes:
+  en: 4f2b2f0db0646d3b
+  zh: 9467f41336a65c48
+/attachment-failures-keep-their-codes/change:
+  en: 0f8c05c401f15a7d
+  zh: adf5976a05802bf1
+/attachment-failures-keep-their-codes/migration:
+  en: 8599ead7a17bc7eb
+  zh: 1120fd02065567f5

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/cua-ax-read-limits/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-ax-read-limits/guide.md
+/:
+  en: a8ca814cf60ea12e
+  zh: f068d1ee13e80594
+/macos-ax-tree-read-limits:
+  en: a7eed0c191ff2b32
+  zh: 15291798ba91329b
+/macos-ax-tree-read-limits/change:
+  en: e4281d86095b950f
+  zh: 684ddf2957443ace
+/macos-ax-tree-read-limits/migration:
+  en: 97a3885f5d1cb907
+  zh: 19313c56eff68835

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/cua-hover-ax-only/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-hover-ax-only/guide.md
+/:
+  en: 5ebb4c8a6b20b644
+  zh: 22a8983d06fa5789
+/macos-hover-keeps-the-system-pointer-in-place-by-default:
+  en: 6833a7851486f10d
+  zh: 22983f326fb725ce
+/macos-hover-keeps-the-system-pointer-in-place-by-default/change:
+  en: e6d2e56ccb50e46a
+  zh: a788fc19e0771a46
+/macos-hover-keeps-the-system-pointer-in-place-by-default/migration:
+  en: 5db40025fe40c374
+  zh: a5556c0e0b000d1c

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