dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/reasoning-body-props/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Reasoning Body Slot text carries display-ready content, with original output in rawText."
+---
+
+# Reasoning Body Slot text fields
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Contributions to `conversation.chat.reasoning.body` receive the model output in the new `rawText` field. The existing `text` field supplies Chat's prepared display text instead of the original output. `running` is unchanged. This affects custom reasoning renderers and translation wrappers.
+
+The `conversation.chat.reasoning.content` Factory still accepts `text`, `running`, and optional `labels`. It renders the caller-selected Markdown. The [Chat README](../../../../packages/client/ui-chat/README.md#grouped-rendering) documents the Slot.
+
+## Migration
+
+1. Keep reading `text` for ordinary rendering, translation requests, and untranslated views. Update extensions that need the full model output to read `rawText`.
+2. Pass the selected `text`, or its translation, to the Content Factory without repeating Chat's display processing.
+3. Rebuild the extension and verify streamed and settled rendering, translation, and the untranslated view with each supported model format.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/reasoning-body-props/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "推理 Body Slot 的 text 提供显示文本，rawText 保留原始输出。"
+---
+
+# 推理 Body Slot 的文本字段
+
+[English](guide.md) | 中文
+
+## 变更
+
+`conversation.chat.reasoning.body` 扩展通过新增的 `rawText` 字段接收模型输出。现有的 `text` 字段提供 Chat 处理后的显示文本，替代原始输出。`running` 保持不变。这会影响自定义推理渲染器和翻译包装组件。
+
+`conversation.chat.reasoning.content` Factory 仍接收 `text`、`running` 和可选的 `labels`。它渲染调用方选定的 Markdown。[Chat README](../../../../packages/client/ui-chat/README.zh.md#grouped-rendering) 介绍了该 Slot。
+
+## 迁移
+
+1. 在普通渲染、翻译请求和未翻译视图中继续读取 `text`。需要完整模型输出的扩展改为读取 `rawText`。
+2. 向 Content Factory 传入选定的 `text` 或其译文，不要重复执行 Chat 的显示处理。
+3. 重新构建扩展，使用每种支持的模型格式验证流式与完成后的渲染、翻译和未翻译视图。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/sandbox-unsupported-policy-error/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.1-rc.4/sandbox-unsupported-policy-error/guide.md
+/:
+  en: d7c1fc703991b92a
+  zh: f5cddebaa6b311a0
+/remove-sandboxunsupportedpolicyerror-imports:
+  en: fc8fa3704fa036ce
+  zh: e96b09c9882f760b
+/remove-sandboxunsupportedpolicyerror-imports/change:
+  en: 3ca1bb8d19b7781e
+  zh: 9f3800c847791344
+/remove-sandboxunsupportedpolicyerror-imports/migration:
+  en: 29b8d3231a83e606
+  zh: 24416c92a4dc9b71

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/sandbox-unsupported-policy-error/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The sandbox package removes SandboxUnsupportedPolicyError; Windows processes ignore additional writable roots."
+---
+
+# Remove SandboxUnsupportedPolicyError imports
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-sandbox` no longer exports `SandboxUnsupportedPolicyError`. Windows subprocess confinement ignores additional writable directories instead of rejecting execution with `SANDBOX_UNSUPPORTED_POLICY`. The harness `write` and `edit` tools still honor those directories; Windows processes retain workspace and private-temp access under `workspace-write`.
+
+## Migration
+
+1. Remove imports and error handlers specific to `SandboxUnsupportedPolicyError` or `SANDBOX_UNSUPPORTED_POLICY`.
+2. Use the harness file tools for writes to additional directories on Windows. Do not assume a successful process launch grants those directories.
+3. Rebuild the consumer and verify that workspace commands run while extra directories remain accessible only through the file tools.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/sandbox-unsupported-policy-error/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "sandbox 包移除 SandboxUnsupportedPolicyError；Windows 进程忽略额外可写根目录。"
+---
+
+# 移除 SandboxUnsupportedPolicyError 导入
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-sandbox` 不再导出 `SandboxUnsupportedPolicyError`。Windows 子进程隔离忽略额外可写目录，不再以 `SANDBOX_UNSUPPORTED_POLICY` 拒绝执行。Harness 的 `write` 与 `edit` 工具仍执行这些目录的授权；Windows 进程在 `workspace-write` 下保留工作区与私有临时目录访问权限。
+
+## 迁移
+
+1. 移除针对 `SandboxUnsupportedPolicyError` 或 `SANDBOX_UNSUPPORTED_POLICY` 的导入与错误处理。
+2. 在 Windows 上使用 Harness 文件工具写入额外目录。不要假定进程启动成功就意味着这些目录已获授权。
+3. 重新构建消费方，验证工作区命令可以运行，额外目录仍仅能通过文件工具访问。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/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.2/context-menu-target/guide.md
+/:
+  en: 6c606440532dfae0
+  zh: 9308d72d451e12c7
+/context-menu-types-and-icons:
+  en: d1237d3842936881
+  zh: b32fcacf82bed5f1
+/context-menu-types-and-icons/change:
+  en: 35faa7bd1cff539f
+  zh: 0dc2515e0025e3d8
+/context-menu-types-and-icons/migration:
+  en: e15e76d8d6a95f35
+  zh: 4bf2dec8d764e5ae

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Client plugins must use the prefixed context menu types and hooks and register keyed icon components."
+---
+
+# Context menu types and icons
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `@deepseek-ai/dsh-client-ui-context-menu/client` export `MenuTarget` is renamed to `ContextMenuTarget`, matching `ContextMenuTargetMap`. The old name has no compatibility alias. Target fields and runtime behavior are unchanged. Workspace and sidebar injections rename `menuTarget` / `useMenuTarget` to `contextMenuTarget` / `useContextMenuTarget`. Action icons accept `{ key, src? }` instead of React nodes and render through the keyed `contextMenu.icon` Slot.
+
+## Migration
+
+1. Replace `MenuTarget` imports and type references with `ContextMenuTarget`.
+2. Rename injected `menuTarget` sources and `useMenuTarget` consumers to `contextMenuTarget` and `useContextMenuTarget`.
+3. Replace action icon elements with `{ key: 'my-plugin.action' }`; carry a captured image URL in `src` when needed. Register the icon component under that key through `ctx.slots.inject('contextMenu.icon', ...)` and `ctx.slots.register()`. See the [menu package](../../../../packages/client/ui-context-menu/README.md#use-this-package).
+4. Rebuild custom Client plugins, confirm that type checks pass, and open their menus to verify icon rendering and plugin-unload cleanup.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/context-menu-target/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Client 插件须使用带前缀的右键菜单类型和 hook，并注册 keyed 图标组件。"
+---
+
+# 右键菜单类型和图标
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-context-menu/client` 导出的 `MenuTarget` 更名为 `ContextMenuTarget`，与 `ContextMenuTargetMap` 保持一致。旧名不保留兼容别名，目标字段和运行时行为不变。工作区与侧栏注入的 `menuTarget` / `useMenuTarget` 改为 `contextMenuTarget` / `useContextMenuTarget`。操作图标改用 `{ key, src? }`，通过 keyed Slot `contextMenu.icon` 渲染，不再接收 React 节点。
+
+## 迁移
+
+1. 将 `MenuTarget` 导入及类型引用替换为 `ContextMenuTarget`。
+2. 将注入源 `menuTarget` 和消费者 `useMenuTarget` 分别改为 `contextMenuTarget`、`useContextMenuTarget`。
+3. 将操作图标元素替换为 `{ key: 'my-plugin.action' }`，需要时通过 `src` 携带已捕获的图片 URL。通过 `ctx.slots.inject('contextMenu.icon', ...)` 和 `ctx.slots.register()` 在该 key 下注册图标组件，参见[菜单包](../../../../packages/client/ui-context-menu/README.zh.md#use-this-package)。
+4. 重新构建自定义 Client 插件，确认类型检查通过，并打开菜单验证图标渲染和插件卸载后的清理。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/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.2/cordis-loader-entry-trees/guide.md
+/:
+  en: 02dfa517303f3206
+  zh: abf9a22603299cc7
+/loader-entry-tree-reports-and-include-persistence:
+  en: dc27815908c90cd9
+  zh: e9cc077d4d3fdbec
+/loader-entry-tree-reports-and-include-persistence/change:
+  en: 6bbe6a3a14e182d1
+  zh: 4256bd997293f8f2
+/loader-entry-tree-reports-and-include-persistence/migration:
+  en: 574f30ad53da1e66
+  zh: 1b9914c4ead412f7

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Loader entry trees report mutations through commit(change), and Include persists them through a journal."
+---
+
+# Loader entry tree reports and Include persistence
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/cordis-plugin-loader` follows Loader 1.0.0-rc.8, and `@deepseek-ai/cordis-plugin-include` follows Include 1.1.1. This affects `cordis.yml` and patch files, code that subclasses `EntryTree`, and code that calls `applyEntryPatches` or relies on Include writes.
+
+- `EntryTree.write()` is removed. Subclasses implement `commit(change: EntryChange)`, which receives each create, update, move, removal and explicit Fiber save synchronously. In-memory trees implement a no-op.
+- `applyEntryPatches(data, patches, warn)` always returns cloned entries, including without patches, and clones inserted rows. Callers can no longer mutate the input through the result.
+- Include persists runtime changes through a journal reconciled with the latest file. File edits win conflicting fields and are logged as conflicts. Changes to patch-owned fields and inserted rows update the parent Include's patches. `flush()` waits for pending writes and rejects while changes remain unsaved; `refresh()` and `stop()` return the same result.
+- Include writes generated ids back into file rows that had none. Runtime changes to rows inserted by patches, including bundle rows, update the parent's patches instead of the included file. The parent of the `dsh` profile's root Include is the in-memory Loader, so such changes, for example a bundle row's self-disposal `disabled: true`, no longer survive a restart; previously the whole patched tree was written into `cordis.yml`.
+
+## Migration
+
+1. In `EntryTree` subclasses, replace `write()` with `commit(change)`. Persist from `change.options` and `change.legacy`: a missing `legacy` is a creation and a missing `options` is a removal.
+2. Treat the `applyEntryPatches` result as the only copy to modify.
+3. Where code needs a runtime change on disk, await `include.flush()`; for patch-owned changes, flush the child Include and then its parent.
+4. Start the application and confirm that runtime edits appear in the configuration file after `flush()`.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Loader 条目树通过 commit(change) 报告变更，Include 通过 journal 持久化这些变更。"
+---
+
+# Loader 条目树变更报告与 Include 持久化
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/cordis-plugin-loader` 跟随 Loader 1.0.0-rc.8，`@deepseek-ai/cordis-plugin-include` 跟随 Include 1.1.1。受影响的是 `cordis.yml` 与 patch 文件、继承 `EntryTree` 的代码，以及调用 `applyEntryPatches` 或依赖 Include 写盘的代码。
+
+- 移除了 `EntryTree.write()`。子类改为实现 `commit(change: EntryChange)`，它会同步收到每一次创建、更新、移动、删除和显式 Fiber 保存。内存树实现为空操作。
+- `applyEntryPatches(data, patches, warn)` 总是返回克隆后的条目，没有 patch 时也一样，插入行同样会被克隆。调用方不能再通过结果修改输入。
+- Include 通过与最新文件协调的 journal 持久化运行时变更。文件编辑在字段冲突时优先，并记录为冲突。对 patch 所拥有字段和插入行的修改会写入父 Include 的 patch。`flush()` 等待待处理的写入，并在仍有未保存变更时拒绝；`refresh()` 和 `stop()` 返回相同的结果。
+- Include 会把生成的 id 写回原本没有 id 的文件行。对 patch 插入行（包括 bundle 行）的运行时修改会写入父级的 patch，而不是被 include 的文件。`dsh` profile 根 Include 的父级是内存中的 Loader，因此这类修改（例如 bundle 行自行释放时写入的 `disabled: true`）重启后不再保留；此前整棵已应用 patch 的树会被写入 `cordis.yml`。
+
+## 迁移
+
+1. 在 `EntryTree` 子类中把 `write()` 换成 `commit(change)`。根据 `change.options` 和 `change.legacy` 持久化：缺少 `legacy` 表示创建，缺少 `options` 表示删除。
+2. 只修改 `applyEntryPatches` 返回的结果。
+3. 需要运行时变更落盘时，await `include.flush()`；对于 patch 所拥有的变更，先 flush 子 Include，再 flush 其父 Include。
+4. 启动应用，确认 `flush()` 之后运行时编辑已出现在配置文件中。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/css-anchored-menus/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.2/css-anchored-menus/guide.md
+/:
+  en: bdb7c51789ea8d61
+  zh: 5bd9ab5abbf48670
+/css-anchored-menus:
+  en: 2d9b87ac50fc94bb
+  zh: 97f8c85f921b3793
+/css-anchored-menus/change:
+  en: 6361b58498cf3297
+  zh: 4e1d21372bec95a9
+/css-anchored-menus/migration:
+  en: 7dba5d8b6e6bdc4a
+  zh: d97a7c13086e9a00

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/css-anchored-menus/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Client UI consumers must replace JavaScript panel positioning and Menu rectangle callbacks with CSS anchors."
+---
+
+# CSS-anchored menus
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-primitives` removes the `useAnchoredPosition` value export and `AnchoredPositionOptions` type export. `Menu` replaces `getAnchorRect` with `anchorRef` for an external trigger element or `anchorPoint` for a point-triggered menu. Custom Client UI that imports the removed exports or passes the removed prop must migrate.
+
+Portaled menus follow their anchors through CSS Anchor Positioning. Their size limits use the layout viewport; browser zoom and panning move them with the page, and the panels may extend beyond the visual viewport, including while the keyboard is open. Menu dismissal, keyboard navigation, and internal scrolling remain available. The browser must support the CSS anchor positioning properties used by the component.
+
+## Migration
+
+1. Remove imports of `useAnchoredPosition` and `AnchoredPositionOptions`. For a custom panel, give its trigger a unique `anchor-name` and set the panel's `position-anchor` to the same name. Define placement and size limits in CSS; see the [model selector](../../../../packages/client/ui-model-selection/README.md#understand-the-implementation).
+2. When `Menu.getAnchorRect` returned a trigger's rectangle, pass the trigger's element ref as `anchorRef` instead. An inline `anchor` rendered by `Menu` needs no external ref.
+3. When the callback returned a zero-size rectangle for a pointer gesture, pass `{ x, y }` as `anchorPoint` in the same client-viewport coordinates as `event.clientX`/`clientY` or `getBoundingClientRect()`. `Menu` performs the Safari-to-layout conversion when opening or changing the point; callers must not add the visual-viewport offset themselves.
+4. Rebuild the custom Client UI and check that no removed import or prop remains. Verify opening, scrolling, Escape, focus restoration, and selection before and after browser zoom. Assertions must allow visual-viewport overflow while retaining layout-viewport bounds and content access.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/css-anchored-menus/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Client UI 使用方必须将 JavaScript 面板定位和 Menu 矩形回调替换为 CSS 锚点。"
+---
+
+# CSS 锚定菜单
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-primitives` 移除 `useAnchoredPosition` 值导出和 `AnchoredPositionOptions` 类型导出。`Menu` 将 `getAnchorRect` 替换为指向外部触发元素的 `anchorRef`，或用于按坐标打开菜单的 `anchorPoint`。导入已移除导出或传入已移除 prop 的自定义 Client UI 必须迁移。
+
+使用 portal 的菜单通过 CSS Anchor Positioning 跟随锚点。尺寸限制采用布局视口；浏览器缩放和平移时菜单随页面移动，面板可以超出视觉视口，包括键盘打开时。菜单关闭、键盘导航和内部滚动保持可用。浏览器必须支持组件使用的 CSS 锚点定位属性。
+
+## 迁移
+
+1. 移除 `useAnchoredPosition` 和 `AnchoredPositionOptions` 导入。自定义面板为触发元素设置唯一的 `anchor-name`，将面板的 `position-anchor` 设置为相同名称，并用 CSS 定义位置和尺寸限制；参见[模型选择器](../../../../packages/client/ui-model-selection/README.zh.md#understand-the-implementation)。
+2. 原 `Menu.getAnchorRect` 返回触发元素矩形时，改为通过 `anchorRef` 传入该元素的 ref。由 `Menu` 渲染的内联 `anchor` 无需外部 ref。
+3. 原回调为指针手势返回零尺寸矩形时，改为通过 `anchorPoint` 传入 `{ x, y }`，坐标与 `event.clientX`/`clientY` 或 `getBoundingClientRect()` 使用相同的客户端视口坐标系。`Menu` 在打开或坐标变化时执行 Safari 到布局视口的转换；调用方不要自行叠加视觉视口偏移。
+4. 重新构建自定义 Client UI，确认不再使用已移除的导入或 prop。在浏览器缩放前后验证打开、滚动、Escape、焦点恢复和选择。断言应允许超出视觉视口，同时保留布局视口约束及内容访问能力。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/cua-source-dev-helper/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.2/cua-source-dev-helper/guide.md
+/:
+  en: 2f745e146345238c
+  zh: 9b41a7625ae45170
+/source-built-computer-use-helper-identity:
+  en: 72a8ea364f7427fa
+  zh: 9e7ed2e00425bddb
+/source-built-computer-use-helper-identity/change:
+  en: c1aa84364896b994
+  zh: a4559c563d995b2b
+/source-built-computer-use-helper-identity/migration:
+  en: a86e330ab60ef800
+  zh: ce32e1959ca707fc

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/cua-source-dev-helper/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Source-built Computer Use helpers use a separate development bundle identifier and need one new macOS permission grant."
+---
+
+# Source-built Computer Use helper identity
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Source checkouts previously built `DSH Computer Use.app` with the release bundle identifier `com.deepseek.harness.computer-use` and an ad-hoc signature. They now build `DSH Computer Use Dev.app` with bundle identifier `com.deepseek.harness.computer-use.dev`. Accessibility and Screen Recording grants for the old entry do not apply to it. Desktop and npm installations are unchanged. Source builds still default to ad-hoc signing; developers generate and maintain fixed identities outside DSH home and select them through configuration.
+
+## Migration
+
+1. Keep the default `sourceSigning: ad-hoc` for temporary signatures. To reduce repeated grants after rebuilds and across worktrees, follow the [developer signing skill](../../../../.agents/skills/dsh-cua-macos-signing/SKILL.md) to generate or reuse a certificate, then write `sourceSigning: { identity, keychain }` into the DSH home’s `cordis.patch.yml`; `keychain` must be an absolute path.
+2. Start DSH from the source checkout, call Computer Use, and grant Accessibility and Screen Recording to `DSH Computer Use Dev` in System Settings.
+3. Confirm that `getCapabilities` reports both permissions as `true`. With a fixed signature, check again after changing and rebuilding Swift code and from another worktree. Remove an old `DSH Computer Use` entry only when no installed DSH uses it.
+4. After the keychain locks, rerun setup as described in the skill to unlock and reuse the identity. To stop using it, select `ad-hoc` or remove the configuration, then remove the identity through the skill; deleting DSH home does not delete the developer keychain.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/cua-source-dev-helper/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "源码构建的 Computer Use helper 使用独立的开发版 Bundle ID，需要重新授予一次 macOS 权限。"
+---
+
+# 源码构建的 Computer Use helper 身份
+
+[English](guide.md) | 中文
+
+## 变更
+
+源码检出原先以临时签名构建 `DSH Computer Use.app`，使用正式版 Bundle ID `com.deepseek.harness.computer-use`。现在构建 `DSH Computer Use Dev.app`，使用 `com.deepseek.harness.computer-use.dev`。旧条目的辅助功能和屏幕录制授权不能沿用。Desktop 和 npm 安装版不变。源码构建默认仍为临时签名；固定身份由开发者在 DSH home 之外生成和维护，再通过配置指定。
+
+## 迁移
+
+1. 保持默认 `sourceSigning: ad-hoc` 即可使用临时签名。需要减少重新编译和跨 worktree 的授权次数时，按[开发者签名 skill](../../../../.agents/skills/dsh-cua-macos-signing/SKILL.md)生成或复用证书，并将 `sourceSigning: { identity, keychain }` 写入 DSH home 的 `cordis.patch.yml`；`keychain` 必须为绝对路径。
+2. 从源码检出启动 DSH，调用 Computer Use，在系统设置中给 `DSH Computer Use Dev` 授予辅助功能和屏幕录制权限。
+3. 确认 `getCapabilities` 的两项权限均为 `true`。使用固定签名时，在修改 Swift 源码重建和另一个 worktree 中分别复查。只有确认没有安装版 DSH 使用旧条目时，才移除旧 `DSH Computer Use` 条目。
+4. 钥匙串锁定后，按 skill 重新运行 setup 解锁并复用现有身份。停止使用时改回 `ad-hoc` 或移除该配置，再按 skill 删除身份；删除 DSH home 不会删除开发者钥匙串。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/desktop-stable-channel/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.2/desktop-stable-channel/guide.md
+/:
+  en: 754ae2b680f57c78
+  zh: b3586f3db403f9e3
+/desktop-stable-channel-name:
+  en: 085fffc14a9bb6be
+  zh: 51c269f7b97b6e31
+/desktop-stable-channel-name/change:
+  en: bca4377ec9032e3b
+  zh: 6da9f3be04f1cd39
+/desktop-stable-channel-name/migration:
+  en: 8442b24f420f6be2
+  zh: b2517178eccbf8d5

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/desktop-stable-channel/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The Desktop stable update channel is named stable instead of latest."
+---
+
+# Desktop stable channel name
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Desktop packages, update feeds, and channel configuration use `stable` instead of `latest`. The `nightly` channel is unchanged. The old channel value is rejected; there is no alias. Fixed website downloads named `dsh-latest-*` are unchanged.
+
+## Migration
+
+1. Select `stable` in packaging workflows or set `DSH_DESKTOP_UPDATE_CHANNEL=stable` when building a stable-channel package. Build a stable version, without a prerelease suffix.
+2. If a local Desktop settings file contains `updates.channel: "latest"`, change the value to `"stable"` and restart Desktop. Omitting the field uses the package default.
+3. Publish with the updated tooling: it writes `stable.yml` on Windows and `stable-mac.yml` on macOS within each architecture's feed directory, with stable-channel binaries under `stable/`. Verify the selected channel and requested feed in the test deployment before production publication. Old packages still requesting `latest` feeds do not migrate automatically.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/desktop-stable-channel/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "桌面正式更新渠道由 latest 更名为 stable。"
+---
+
+# 桌面正式渠道名称
+
+[English](guide.md) | 中文
+
+## 变更
+
+桌面安装包、更新清单及渠道配置使用 `stable`，不再使用 `latest`。`nightly` 渠道不变。旧渠道值会被拒绝，不提供别名。网站名为 `dsh-latest-*` 的固定下载文件保持不变。
+
+## 迁移
+
+1. 在打包工作流中选择 `stable`，或在构建正式渠道包时设置 `DSH_DESKTOP_UPDATE_CHANNEL=stable`。使用不含预发布后缀的稳定版本号。
+2. 如果本地桌面配置文件包含 `updates.channel: "latest"`，将该值改为 `"stable"` 并重启桌面应用。省略该字段时使用安装包默认值。
+3. 使用更新后的工具发布：在各架构的清单目录内，Windows 写入 `stable.yml`，macOS 写入 `stable-mac.yml`；正式渠道二进制位于 `stable/` 下。在正式发布前，通过测试部署核对选定渠道和请求的清单。仍请求 `latest` 清单的旧包不会自动迁移。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/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.2/forge-git-permissions/guide.md
+/:
+  en: 670467a1e1ef4871
+  zh: a5c49c32981a3d50
+/forge-git-query-permissions-and-content-conversion:
+  en: 622fa28fae275249
+  zh: 75888856615bcfd3
+/forge-git-query-permissions-and-content-conversion/change:
+  en: d8f544395f65b663
+  zh: f785a6d6f9a696b6
+/forge-git-query-permissions-and-content-conversion/migration:
+  en: db9ae3d66f6bb1e7
+  zh: 315bfde302564a7c

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Forge Git queries use Session permissions and disable configured diff helpers."
+---
+# Forge Git query permissions and content conversion
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Forge Git queries use the Session's sandbox mode instead of forcing `read-only`. `danger-full-access` works without a sandbox backend; `workspace-write` permits writes within its configured roots. A confined mode still refuses execution when its backend is unavailable.
+
+On Git 2.31 or newer, local diffs and statistics disable enumerated clean/process filters for each command. Git's built-in newline, ident, and encoding conversions still apply. Materialized LFS files and other filtered files can appear changed when ordinary Git considers them clean. The panel does not request LFS downloads. Older Git or concurrently added filters can still execute helpers under Session permissions. Submodule commit changes remain visible, but internal uncommitted changes are omitted.
+
+Filter configuration read failures, including truncated output, report `forgePanel/filter-config-failed` before any comparison and offer a retry. They are separate from `forgePanel/diff-too-large`.
+
+## Migration
+
+1. Keep a Session in `read-only` when its Git queries require operating-system-enforced write protection. Use the existing permission picker to select the intended Session mode; no configuration keys change.
+2. For repositories that require content conversion or submodule working-tree inspection, use an explicit Git command under the intended Session permissions to inspect those changes. The panel's local comparison bypasses clean/process filters on supported Git versions.
+3. On a host without a sandbox backend, select Full access and refresh the Forge panel. Its checkout and ordinary local changes should load; switching to a confined mode must still report the unavailable backend.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/forge-git-permissions/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Forge Git 查询使用 Session 权限并禁用已配置的 diff 辅助程序。"
+---
+# Forge Git 查询权限与内容转换
+
+[English](guide.md) | 中文
+
+## 变更
+
+Forge Git 查询使用 Session 的沙箱模式，不再强制 `read-only`。`danger-full-access` 无需沙箱后端；`workspace-write` 允许在其配置的根目录内写入。受限模式的后端不可用时仍拒绝执行。
+
+在 Git 2.31 或更新版本中，本地 diff 与统计仅对每次命令禁用已枚举的 clean/process filter。Git 内置的换行、ident 与编码转换仍然生效。已物化的 LFS 文件及其他过滤文件可能显示为变更，即使普通 Git 认为它们未变。面板不请求下载 LFS 对象。旧 Git 或并发新增的过滤器仍可能按 Session 权限执行辅助程序。子模块提交变化仍可见，但内部未提交修改不显示。
+
+过滤器配置读取失败（包括输出被截断）时，在任何比较之前报告 `forgePanel/filter-config-failed` 并提供重试，与 `forgePanel/diff-too-large` 区分。
+
+## 迁移
+
+1. 如果 Git 查询需要操作系统强制禁止写入，请将 Session 保持为 `read-only`。通过现有权限选择器选择所需的 Session 模式；配置键没有变化。
+2. 对于需要内容转换或检查子模块工作区的仓库，请在所需的 Session 权限下显式运行 Git 命令检查这些变化。面板的本地比较在受支持的 Git 版本中绕过 clean/process filter。
+3. 在没有沙箱后端的主机上选择“完全权限”，然后刷新 Forge 面板。检出信息和普通本地变更应可加载；切回受限模式后仍须报告后端不可用。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/forge-worktree-entry/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.2/forge-worktree-entry/guide.md
+/:
+  en: e25e3adac59e3584
+  zh: 1a16ac4c16ab3a0d
+/one-plugin-entry-for-change-requests-and-worktrees:
+  en: 2eb2f0805d09f0c4
+  zh: a7b02646515b39df
+/one-plugin-entry-for-change-requests-and-worktrees/change:
+  en: b814d167dea20941
+  zh: a8e3c416acd4fb65
+/one-plugin-entry-for-change-requests-and-worktrees/migration:
+  en: 08b0e3bae9e9697e
+  zh: 62f66d48328f1037

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/forge-worktree-entry/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "The Plugins page replaces the standalone Git worktrees card with Change requests & worktrees."
+---
+
+# One plugin entry for change requests and worktrees
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Web and Desktop use **Change requests & worktrees** to enable the review panel, the new-Session worktree option, and the model's `create_worktree` tool together. The separate **Git worktrees** card is hidden. Profiles that already enabled the Forge bundle also gain the model tool.
+
+Existing profiles are not migrated automatically. A selected `@deepseek-ai/dsh-experimental-tool-worktree` bundle stays active even though its card is hidden, so turning off Forge does not disable that standalone tool. Selecting both it and `@deepseek-ai/dsh-experimental-forge-bundle` inserts duplicate `worktree` and `tool-worktree` ids, making those component controls read-only. Remove the standalone selection before using the unified switch.
+
+## Migration
+
+1. Stop Web or quit Desktop. Back up `$DSH_HOME/profiles/<name>/package.json` and its sibling `cordis.patch.yml`. Use `~/.dsh` when `DSH_HOME` is unset; the standard profile names are `web` and `desktop`. For a custom profile, use its name.
+2. Edit `dsh.profile.bundles` in that `package.json`. Remove every `@deepseek-ai/dsh-experimental-tool-worktree` entry. To keep worktree support through the unified switch, add `@deepseek-ai/dsh-experimental-forge-bundle` once; if it is already selected, keep that entry. To disable both features, remove both bundle names. Preserve all other entries and fields.
+3. Keep existing `cordis.patch.yml` overrides: the `worktree`, `tool-worktree`, and `optional-forge-panel` ids are unchanged. To use the Forge panel without exposing the model tool, add or update this entry in the existing patch list:
+
+   ```yaml
+   - id: tool-worktree
+     disabled: true
+   ```
+
+4. Restart the application. In Plugins, confirm that **Change requests & worktrees** reflects your selection. With no disabling row override, enabling it provides the panel and `create_worktree`; turning it off removes both. Confirm that the profile lists no standalone worktree bundle. Existing worktrees, branches, and Session records are retained.
+
+Headless profiles and custom compositions that need only the standalone tool can keep it; do not also select the Forge bundle. In Web or Desktop, that standalone selection remains hidden and must be managed through the profile file.

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/forge-worktree-entry/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "插件页将独立的 Git 工作树卡片合入变更请求与工作树。"
+---
+
+# 变更请求与工作树使用同一个插件入口
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 和 Desktop 通过**变更请求与工作树**同时启用评审面板、新会话的工作树选项和模型的 `create_worktree` 工具。独立的 **Git 工作树**卡片被隐藏。已经启用 Forge 组合包的 profile 也会新增模型工具。
+
+已有 profile 不会自动迁移。选中的 `@deepseek-ai/dsh-experimental-tool-worktree` 组合包仍会运行，即使其卡片已隐藏，因此关闭 Forge 不会停用这个独立工具。同时选择它和 `@deepseek-ai/dsh-experimental-forge-bundle` 会插入重复的 `worktree` 与 `tool-worktree` id，使对应组件控件变为只读。使用统一开关前，请移除独立组合包的选择。
+
+## 迁移
+
+1. 停止 Web 或退出 Desktop。备份 `$DSH_HOME/profiles/<name>/package.json` 及同目录下的 `cordis.patch.yml`。未设置 `DSH_HOME` 时使用 `~/.dsh`；标准 profile 名称为 `web` 和 `desktop`。自定义 profile 使用其自身名称。
+2. 编辑该 `package.json` 的 `dsh.profile.bundles`。移除所有 `@deepseek-ai/dsh-experimental-tool-worktree` 条目。若要通过统一开关保留工作树功能，添加一次 `@deepseek-ai/dsh-experimental-forge-bundle`；若已选中它，则保留该条目。若要关闭两项功能，则移除这两个组合包名称。保留其他所有条目和字段。
+3. 保留现有的 `cordis.patch.yml` 覆盖配置：`worktree`、`tool-worktree` 和 `optional-forge-panel` 的 id 均未改变。若只使用 Forge 面板，不向模型提供工作树工具，在现有 patch 列表中添加或更新以下条目：
+
+   ```yaml
+   - id: tool-worktree
+     disabled: true
+   ```
+
+4. 重启应用。在插件页确认**变更请求与工作树**的状态符合你的选择。没有禁用插件行的覆盖配置时，启用它会提供面板与 `create_worktree`，关闭后两者均移除。确认 profile 不再列出独立的工作树组合包。已有工作树、分支和 Session 记录均保留。
+
+仅需要独立工具的 Headless profile 和自定义组合可以继续保留它，但不要同时选择 Forge 组合包。在 Web 或 Desktop 中，该独立选择仍然隐藏，需要通过 profile 文件管理。

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/fs-observation-policy-default-off/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.2/fs-observation-policy-default-off/guide.md
+/:
+  en: 94b863d7f57ffb37
+  zh: 158af8a6f172ee5f
+/filesystem-mutations-no-longer-require-a-prior-read-by-default:
+  en: e6dd0c06f99737e4
+  zh: a706b0bbdea94aac
+/filesystem-mutations-no-longer-require-a-prior-read-by-default/change:
+  en: d7a64f82068f7869
+  zh: 8a42e9c0a56cd3e5
+/filesystem-mutations-no-longer-require-a-prior-read-by-default/migration:
+  en: c156c11ab737f75a
+  zh: faadea98c8558d07

package/references/official-docs/docs/upgrade-guide/v0.2.2-alpha.2/fs-observation-policy-default-off/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "The fs-observation-policy row ships disabled, so write, edit, and apply_patch no longer require a prior read, and dsh-base plus the Web standard preset gain apply_patch."
+---
+
+# Filesystem mutations no longer require a prior read by default
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In 0.2.2-alpha.2, `dsh-base` mounted `@deepseek-ai/dsh-fs-observation-policy`, so in every base-backed profile `write` refused to overwrite a file the model had not read, `edit` refused an unread or externally changed file, and the model's guidance named the policy. The `fs-observation-policy` row now ships `disabled: true`: `write` overwrites, `edit` replaces literal text, and the new `apply_patch` applies hunks on context match alone, each unconditionally. The `write` and `edit` guidance still asks for a prior read but no longer cites the policy. Review capture, sandbox confinement, and `fs/observed` events are unchanged.
+
+The `dsh-base` `tool-fs` row (headless, SDK, and ACP) and the Web `standard` preset now list `apply_patch` (`applyPatch: true`); the Web `ptc` and `cordis` presets keep `applyPatch: false`.
+
+Affected: the base-backed profiles (`headless`, `web`, `sdk`, `acp`; `sdk-minimal` stacks no `dsh-base`, never mounted the policy, and keeps its text tools off), profile patches that override the `fs-observation-policy` or `tool-fs` rows by id, and recorded expectations that include an `FS_NOT_OBSERVED` or `FS_STALE_VERSION` refusal.
+
+## Migration
+
+1. To keep read-before-write behavior, add to the profile's `cordis.patch.yml` (`$DSH_HOME/profiles/<profile>/cordis.patch.yml`):
+
+   ```yaml
+   - id: fs-observation-policy
+     disabled: false
+   ```
+
+   A profile patch that already carries this row with `disabled: false` needs no change; one that set `disabled: true` to opt out can drop that override.
+2. To run without `apply_patch`, add `- {id: tool-fs, config: {applyPatch: false}}` to the profile's `cordis.patch.yml` for `headless`, `sdk`, and `acp` (the shipped [PTC overlay](../../../../apps/cli/config/examples/ptc.yml) already does so, matching the Web `ptc` preset); for the Web `standard` preset, edit it from the Agent presets settings page or set `applyPatch: false` on its `tool-fs` row in `packages/bundle/web-app/presets/standard.patch.yml`.
+3. Confirm with `dsh --profile <profile> --dump-config`: the `fs-observation-policy` row shows the intended `disabled` value, and the `tool-fs` rows show the intended `applyPatch` value. In a session, an `edit` of a file that was not read succeeds with the row disabled and fails with `FS_NOT_OBSERVED` with it enabled.