dsh-plugin-guide 0.3.33 → 0.3.36

package/references/official-docs/docs/ui-radius.md

@@ -38,9 +38,9 @@ H means designed outer height in CSS pixels, including borders. R means CSS `bor
 
 Prefer an existing shared size variant when a proposed control falls between these bands. A taller card remains a card: do not promote it to R28 merely because it exceeds a button's height. A multiline cell intentionally designed for multiple lines uses R16; an ordinary button whose label wraps retains its button variant.
 
-Concrete defaults: `Button` uses H28/R8 for `sm` and H36/R12 for `md`, including outline variants. Standard H32 inputs and H36 selectors use R12. The Workspace files and New terminal guide entries both use R20, including title-only and described variants. Reserve R28 for their enclosing panel or dialog, not those entries.
+Concrete defaults: `Button` uses H28/R8 for `sm` and H36/R12 for `md`, including outline variants. Standard H32 inputs and H36 selectors use R12. The Workspace files and New terminal guide entries both use R20, including title-only and described variants. Reserve R28 for their enclosing panel or dialog, not those entries. Composer statistics and the context-occupancy trigger use compact-control R8 with the theme curve, including hover, expanded, and focus states.
 
-Code blocks, diffs, and file previews share R16: changed-file entry cards, delivered-file cards, generic file attachment cards, and hover preview panels. The 40px file-icon tiles inside changed-file and delivery cards use R10 on all four corners as a component-specific exception. Their hover fills keep the same contour.
+Code blocks, diffs, and preview cards share R16: changed-file entry cards, delivered-file cards, submitted-plan cards, created-task cards, generic file attachment cards before and after sending, and hover preview panels. The 40px icon tiles inside changed-file, delivery, submitted-plan, and created-task cards use R10 on all four corners as a component-specific exception and share the same neutral tile fill and border in both themes. Their hover fills keep the same contour.
 
 <a id="shapes"></a>
 ## Reuse tokens and preserve deliberate shapes
@@ -64,11 +64,13 @@ Distinguish these three arrangements before changing a child radius:
 
 | Arrangement | Rule | Example |
 |---|---|---|
-| Concentric inset | Inner R = max(0, outer R − inset); use the same curve | Outer R16, inset 4, inner R12 |
+| Circular concentric inset | Inner R = max(0, outer R − inset); both arcs share a center and use `round` | Outer R16, inset 4, inner R12 |
 | Fill flush against an enclosing edge | The enclosure owns the visible corner; clip the fill or inherit the matching corner | A split-button card with two independent hover regions |
 | Separate card or form group inside another surface | Choose the child's semantic tier; do not subtract all parent padding mechanically | R16 editor within an R20 settings card |
 
-Standard menus use outer R16, 4px padding, and R12 items. Compact menus use outer R12, 4px padding, and R8 items. Shared `SegmentedControl` uses outer R12, 4px inset, and R8 segments/indicator; `SegmentedTabs` uses outer R16, 4px inset, and R12 segments/indicator. Keep indicator offsets, width calculations, submenu alignment, and pointer bridges consistent when changing padding.
+Standard menus use outer R16, 4px padding, and R12 items, including command selection, task menus, and the exposed highlights in subagent and background-job menus. Tree disclosure gutters retain their indentation; controls inside a filled job row keep their own compact geometry. Compact menus use outer R12, 4px padding, and R8 items. Shared `SegmentedControl` uses outer R12, 4px inset, and R8 segments/indicator; `SegmentedTabs` uses outer R16, 4px inset, and R12 segments/indicator. Keep indicator offsets, width calculations, submenu alignment, and pointer bridges consistent when changing padding.
+
+The radius subtraction is also the nominal sizing rule for nested superellipses. Equal exponents do not make them exact offset curves, so their diagonal gap may differ from the side inset. Keep the shared superellipse menu and segmented-control treatments; use circular arcs when strict equal radial spacing is required.
 
 A single clickable surface paints hover on itself. A flush pseudo-element or overlay uses the same radius and curve as the visible enclosure. Avoid a separately rounded fill that leaves a crescent between the background and the border.
 

package/references/official-docs/docs/ui-radius.zh.md

@@ -38,9 +38,9 @@ H 表示以 CSS 像素计、包含边框的设计外部高度。R 表示浏览
 
 拟定控件尺寸落在档位之间时，优先复用已有的公共尺寸变体。高卡片仍是卡片，不因高度超过按钮就升到 R28。专门设计为多行的 cell 使用 R16；普通按钮的文字发生换行时，仍保留其按钮变体。
 
-具体默认值：`Button` 的 `sm` 使用 H28/R8，`md` 使用 H36/R12，包含描边变体。标准 H32 输入框和 H36 选择器使用 R12。“工作区文件”和“新建终端”引导入口统一使用 R20，包含仅标题与带描述的变体。R28 留给包围它们的面板或对话框，不用于这些入口。
+具体默认值：`Button` 的 `sm` 使用 H28/R8，`md` 使用 H36/R12，包含描边变体。标准 H32 输入框和 H36 选择器使用 R12。“工作区文件”和“新建终端”引导入口统一使用 R20，包含仅标题与带描述的变体。R28 留给包围它们的面板或对话框，不用于这些入口。输入框统计控件与上下文占用率入口使用紧凑控件的 R8 和主题曲线，包含 hover、展开与焦点状态。
 
-代码块、diff 与文件预览共用 R16：包括改动文件入口卡片、交付文件卡片、通用附件文件卡片和悬停预览浮层。改动文件与交付文件卡片内部的 40px 文件图标底框作为组件特例，四角统一使用 R10。各自的 hover 保持同一轮廓。
+代码块、diff 与预览卡片共用 R16：包括改动文件入口卡片、交付文件卡片、已提交计划卡片、已创建任务卡片、发送前后的通用附件文件卡片和悬停预览浮层。改动文件、交付文件、已提交计划与已创建任务卡片内部的 40px 图标底框作为组件特例，四角统一使用 R10，并在明暗两种主题下分别共用相同的中性底色与边框。各自的 hover 保持同一轮廓。
 
 <a id="shapes"></a>
 ## 复用 token，保留有意设计的形状
@@ -64,11 +64,13 @@ H 表示以 CSS 像素计、包含边框的设计外部高度。R 表示浏览
 
 | 关系 | 规则 | 示例 |
 |---|---|---|
-| 同心内缩 | 内层 R = max(0, 外层 R − 内缩距离)；使用相同曲线 | 外层 R16，内缩 4，内层 R12 |
+| 圆弧同心内缩 | 内层 R = max(0, 外层 R − 内缩距离)；两段圆弧同心且使用 `round` | 外层 R16，内缩 4，内层 R12 |
 | 底色紧贴容器边缘 | 由外框决定可见圆角；裁切底色或继承相应圆角 | 两个独立 hover 区域组成的分体按钮卡片 |
 | 容器内独立的卡片或表单组 | 按子元素用途选择档位；不机械减去全部父级内边距 | R20 设置卡片内的 R16 编辑器 |
 
-标准菜单使用外层 R16、4px 内边距、R12 菜单项。紧凑菜单使用外层 R12、4px 内边距、R8 菜单项。公共 `SegmentedControl` 使用外层 R12、4px 内缩、R8 分段和指示器；`SegmentedTabs` 使用外层 R16、4px 内缩、R12 分段和指示器。修改内边距时，同步保持指示器偏移、宽度计算、子菜单对齐与指针桥接区域一致。
+标准菜单使用外层 R16、4px 内边距、R12 菜单项，包含命令选择、任务菜单，以及子会话和后台任务菜单的外露高亮区域。树形展开操作保留缩进；带底色任务行内的控件保留各自的紧凑几何。紧凑菜单使用外层 R12、4px 内边距、R8 菜单项。公共 `SegmentedControl` 使用外层 R12、4px 内缩、R8 分段和指示器；`SegmentedTabs` 使用外层 R16、4px 内缩、R12 分段和指示器。修改内边距时，同步保持指示器偏移、宽度计算、子菜单对齐与指针桥接区域一致。
+
+半径相减也用于嵌套超级椭圆的名义尺寸关系。相同指数不意味着两条曲线严格等距，因此对角线间隙可能不同于侧边内缩。菜单与分段控件保留公共的超级椭圆样式；要求径向严格等距时使用圆弧。
 
 单个可点击表面在自身绘制 hover。贴边的伪元素或覆盖层使用与可见外框相同的圆角和曲线。避免单独给底色设置圆角，导致背景与边框之间出现月牙状空隙。
 

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/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.0-rc.2/primary-runtime-python-aliases/guide.md
+/:
+  en: a4f973e3aed3cbb1
+  zh: e33e5eb33838f82e
+/custom-python-runtime-aliases-must-target-a-sibling-interpreter:
+  en: c38fad48cd870c4c
+  zh: 49fff1636ca8c8fd
+/custom-python-runtime-aliases-must-target-a-sibling-interpreter/change:
+  en: 55f21ac0b9190e37
+  zh: 2d1c7aaa89ddfe19
+/custom-python-runtime-aliases-must-target-a-sibling-interpreter/migration:
+  en: 2839866a08be236d
+  zh: 11a01d35a7f396ce

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Custom primary-runtime payloads require relocatable Python interpreter aliases."
+---
+
+# Custom Python runtime aliases must target a sibling interpreter
+
+English | [中文](guide.zh.md)
+
+## Change
+
+On macOS and Linux, `DSH_PRIMARY_RUNTIME` previously accepted interpreter links that resolved outside their payload or through other links. Payload validation now requires each linked `dependencies/python/bin/python` or `python3` to point directly to the regular sibling interpreter named for `runtime.json`'s Python major and minor version, such as `python3.12`. Regular command files remain supported, including those distributed in Python wheels. Windows is unchanged.
+
+## Migration
+
+1. For a custom payload, keep the versioned interpreter in `dependencies/python/bin/` and make `python` and `python3` relative links to its filename. The [runtime preparation instructions](../../../../packages/skill/tool-workspace-dependencies/README.md) list the required target and output arguments.
+2. Preserve relative links when copying prepared resources. With Node `fs.cp`, use `verbatimSymlinks: true`; wheel builders must materialize the command files because pip does not restore links. The native build smoke requires the prepared resource tree to retain both aliases.
+3. Confirm that `readlink` reports only the sibling filename for both aliases, then move the payload away from its build directory, point `DSH_PRIMARY_RUNTIME` at its new directory, and verify that `load_workspace_dependencies` and the returned Python command succeed.

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/primary-runtime-python-aliases/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "自定义 primary-runtime payload 的 Python 解释器别名必须支持目录迁移。"
+---
+
+# 自定义 Python 运行时别名必须指向同目录解释器
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 macOS 和 Linux 上，`DSH_PRIMARY_RUNTIME` 之前接受指向 payload 外部或经过其他链接的解释器链接。现在，payload 校验要求 `dependencies/python/bin/python` 或 `python3` 的链接直接指向同目录的普通解释器文件，文件名由 `runtime.json` 中 Python 的主版本号和次版本号决定，例如 `python3.12`。普通命令文件仍受支持，包括 Python wheel 中分发的文件。Windows 不变。
+
+## 迁移
+
+1. 对于自定义 payload，将版本化解释器保留在 `dependencies/python/bin/` 中，并让 `python` 和 `python3` 以该文件名为目标建立相对链接。[运行时准备说明](../../../../packages/skill/tool-workspace-dependencies/README.zh.md)列出了必需的目标与输出参数。
+2. 复制准备好的资源时保留相对链接。使用 Node `fs.cp` 时设置 `verbatimSymlinks: true`；wheel 构建器必须将命令展开为普通文件，因为 pip 不会还原链接。本机构建冒烟检查要求准备好的资源目录保留两个别名。
+3. 确认 `readlink` 对两个别名都只返回同目录解释器的文件名，再将 payload 移离构建目录，将 `DSH_PRIMARY_RUNTIME` 指向新目录，验证 `load_workspace_dependencies` 和返回的 Python 命令均可成功执行。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/job-id-identity/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-alpha.1/job-id-identity/guide.md
+/:
+  en: d6fdce6b58c67691
+  zh: a103e5028f5442d0
+/background-job-ids-identify-one-execution:
+  en: 9b06780be69e93f6
+  zh: c33945fd584c6a23
+/background-job-ids-identify-one-execution/change:
+  en: 047ec9d0337bfc0b
+  zh: 1218472855e81189
+/background-job-ids-identify-one-execution/migration:
+  en: 08921c9c25218c83
+  zh: 7ff1d3ac63ae40ef

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JobId now identifies one background execution across registry lifetimes."
+---
+
+# Background job ids identify one execution
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The job registry returns `<kind>-<short-uuid>` instead of `<kind>-N`; the suffix is 16 lowercase UUID hex characters. The same `JobId` appears in live controls, `job/registered`, and `job/settled`; lifecycle records no longer carry `executionId`. The identifier remains owner-authorized. Existing Session histories remain unchanged and do not resume their jobs.
+
+## Migration
+
+1. Pass the exact id returned by a start result or `jobs.list()` to `job_output` and `job_kill`; use `job_output` with `wait: true` to wait. Remove code that constructs an id from the kind and an ordinal.
+2. Pair SDK lifecycle events by `data.jobId`. Remove imports of `JobExecutionId` and code that maps it to a process-local `jobId`.
+3. Verify a new job's registration and settlement contain the same `jobId`, and a later registry instance issues a different one.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/job-id-identity/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JobId 现在跨注册表生命周期标识一次后台执行。"
+---
+
+# 后台 job id 标识一次执行
+
+[English](guide.md) | 中文
+
+## 变更
+
+job 注册表返回 `<kind>-<short-uuid>`，不再返回 `<kind>-N`；后缀是 UUID 的 16 位小写十六进制字符。运行期控制、`job/registered` 和 `job/settled` 使用同一个 `JobId`；生命周期记录不再携带 `executionId`。访问仍按所有者授权。已有 Session 历史保持原样，不会恢复其中的 job。
+
+## 迁移
+
+1. 把启动结果或 `jobs.list()` 返回的原始 id 传给 `job_output` 和 `job_kill`；等待时为 `job_output` 设置 `wait: true`。移除按 kind 和序号构造 id 的代码。
+2. 使用 `data.jobId` 配对 SDK 生命周期事件。移除 `JobExecutionId` 导入，以及将它映射为进程内 `jobId` 的代码。
+3. 核对新 job 的注册与结算含有相同 `jobId`，后续注册表实例发放不同 id。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/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-alpha.1/jsonl-persistence-plugin/guide.md
+/:
+  en: eff30513d0de970b
+  zh: c16a32f374bd07e1
+/mount-jsonl-persistence-through-its-plugin:
+  en: ae3ff407a497cf5c
+  zh: 1b71e651967b8255
+/mount-jsonl-persistence-through-its-plugin/change:
+  en: ea5defddc1a9b989
+  zh: 97902f22a4196b12
+/mount-jsonl-persistence-through-its-plugin/migration:
+  en: 93d9f202c59303e9
+  zh: c5ced26ed819d7c5

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JSONL persistence uses a namespace plugin import; direct service-class construction and class type annotations must use the persistence service instead."
+---
+
+# Mount JSONL persistence through its plugin
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-session-persistence-jsonl` exports a function plugin through named `name`, `Config`, and `apply` exports, with no default export. Default imports, direct construction, subclassing, `instanceof`, and class type annotations are affected. The plugin retains listeners and handles through the consumer unloads triggered by removing this provider; concurrent root disposal remains unordered. The `sessionPersistence` service API, YAML configuration, and stored files remain unchanged.
+
+## Migration
+
+1. Replace the default import with `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`. Existing `ctx.plugin(JsonlSessionPersistence, config)` calls remain valid; replace direct construction with this mounting call. For dynamic imports, use the module namespace returned by `await import(...)` instead of its `.default`. Consumers declare `inject: ['sessionPersistence']` and access `ctx.sessionPersistence`.
+2. Use the `SessionPersistence` type from `@deepseek-ai/dsh-session-persistence` for service annotations. Replace concrete-class `instanceof` checks and subclasses with consumers of that service; the concrete JSONL class is private.
+3. Await plugin startup and confirm a session can be created, flushed, and reopened. Register asynchronous consumer cleanup in the scope that injects `sessionPersistence` so backend unloading waits for it.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/jsonl-persistence-plugin/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "JSONL 持久化使用插件命名空间导入；直接构造服务类和类类型标注需要改用持久化服务。"
+---
+
+# 通过插件挂载 JSONL 持久化
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-persistence-jsonl` 通过命名导出的 `name`、`Config` 和 `apply` 提供函数插件，没有默认导出。默认导入、直接构造、继承、`instanceof` 和类类型标注会受到影响。插件会保留监听器和句柄，直到移除该提供者所触发的消费者卸载完成；根作用域的并发卸载仍不保证顺序。`sessionPersistence` 服务 API、YAML 配置和存储文件保持不变。
+
+## 迁移
+
+1. 将默认导入替换为 `import * as JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'`。现有的 `ctx.plugin(JsonlSessionPersistence, config)` 调用仍然有效；将直接构造改为该挂载调用。动态导入直接使用 `await import(...)` 返回的模块命名空间，不再取其 `.default`。消费者声明 `inject: ['sessionPersistence']` 并访问 `ctx.sessionPersistence`。
+2. 服务类型标注使用 `@deepseek-ai/dsh-session-persistence` 的 `SessionPersistence` 类型。将针对具体类的 `instanceof` 检查和子类改为消费该服务；具体 JSONL 类是私有的。
+3. 等待插件启动完成，确认能够创建、flush 并重新打开会话。将消费者的异步清理注册到注入 `sessionPersistence` 的作用域中，以便后端卸载时等待它完成。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/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-alpha.1/subagent-preset-composition/guide.md
+/:
+  en: 0351f79f0f7acc90
+  zh: c6815e557ffa1a2f
+/configure-subagent-composition-through-presets:
+  en: aab975172f278acf
+  zh: 4e6dad4ef487cc52
+/configure-subagent-composition-through-presets/change:
+  en: e758e1d0c34846db
+  zh: 93675aa1b3f7be4e
+/configure-subagent-composition-through-presets/migration:
+  en: 0ae5b3e77d8c4b83
+  zh: 746b44875e23dea6

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Subagent persona and toolFilter configuration is replaced by Agent Preset composition."
+---
+
+# Configure subagent composition through presets
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`dsh-tool-subagent` rejects `persona` and `toolFilter` configuration. New `SubagentStartRequest` values and provider capabilities no longer expose either field. In-process spawn selects a preset through `agentPreset`; its persona and tools come from that preset's plugins. Fork inherits the parent's preset and cannot independently change persona or restrict tools. Model and reasoning-effort options are unchanged.
+
+The shipped `standard`, `ptc`, and `cordis` delegation tools no longer hide `schedule_*` tools. Delegated callers still receive the existing execution refusal. Historical child Session descriptors retain their persona and tool restrictions when resumed.
+
+## Migration
+
+1. Remove `persona` and `toolFilter` from `dsh-tool-subagent` rows in your profile patches and custom presets. Update programmatic callers and provider capability declarations to remove the same fields.
+2. For spawn, define an Agent Preset containing `dsh-persona` and the required tool plugins, then set the delegation tool's `agentPreset` to its id. Use `allowedAgentPresets` to offer several declared presets to the parent model. Presets select plugin compositions; there is no replacement per-child tool-name filter.
+3. For fork, remove the overrides and accept the inherited composition. If the task needs a different composition, use spawn with a preset; it does not inherit the parent's conversation.
+4. Start a new Session and delegate a task. Confirm that the child uses the selected preset's persona and tools. Existing persisted child Sessions need no manual edits.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.1/subagent-preset-composition/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Subagent 的 persona 与 toolFilter 配置由 Agent Preset 组装替代。"
+---
+
+# 通过 preset 配置子 Agent 组装
+
+[English](guide.md) | 中文
+
+## 变更
+
+`dsh-tool-subagent` 拒绝 `persona` 与 `toolFilter` 配置。新的 `SubagentStartRequest` 和提供方能力声明也不再暴露这两个字段。进程内 spawn 通过 `agentPreset` 选择 preset，其 persona 与工具来自该 preset 的插件。fork 继承父方 preset，不能独立改变 persona 或限制工具。模型与推理强度选项保持不变。
+
+出货的 `standard`、`ptc` 和 `cordis` 委派工具不再隐藏 `schedule_*` 工具。委派调用方仍会收到已有的执行拒绝。历史子 Session 的 descriptor 在恢复时仍应用其 persona 与工具限制。
+
+## 迁移
+
+1. 从 profile patch 和自定义 preset 的 `dsh-tool-subagent` 行中移除 `persona` 与 `toolFilter`。同步从程序化调用方和提供方能力声明中移除这两个字段。
+2. 对于 spawn，定义包含 `dsh-persona` 和所需工具插件的 Agent Preset，再将委派工具的 `agentPreset` 设为其 id。使用 `allowedAgentPresets` 向父模型开放多个已声明 preset。preset 选择插件组合，不提供替代的逐子级工具名过滤器。
+3. 对于 fork，移除覆盖并接受继承的组合。如果任务需要不同组合，使用带 preset 的 spawn；它不继承父方对话。
+4. 启动新 Session 并委派任务，确认子级使用所选 preset 的 persona 与工具。已有持久化子 Session 无须手动修改。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/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-alpha.2/deepseek-account-identity-watch/guide.md
+/:
+  en: 7f67e85211e09294
+  zh: 989bd997224ba1d9
+/explicitly-subscribe-to-account-identity-changes:
+  en: c3ea4288a28acf1d
+  zh: 91483de64b303db0
+/explicitly-subscribe-to-account-identity-changes/change:
+  en: 1573d98d30b5eb0a
+  zh: 74b8281ab614773b
+/explicitly-subscribe-to-account-identity-changes/migration:
+  en: c0d458e4b471239e
+  zh: fa7fa792efeec570

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "DeepSeekAccount.watch no longer includes Platform identity changes unless explicitly requested."
+---
+
+# Explicitly subscribe to account identity changes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The public `DeepSeekAccount.watch(signal)` method previously emitted a snapshot when a profile read first supplied or changed the cached Platform user ID. It now emits account-state changes only by default. Plugins that use this stream to refresh `getPlatformSession()` must opt into identity changes. Credential replacement and sign-in state changes still notify every subscriber.
+
+## Migration
+
+1. Find calls to `deepseekAccount.watch(signal)` in plugins that refresh the Platform session or synchronize its user ID.
+2. Change those calls to `deepseekAccount.watch(signal, true)`. Leave account UI subscriptions that only need sign-in and credential state unchanged.
+3. Confirm that a ready `getProfile()` result whose user ID first appears or changes wakes the subscription and causes it to re-read `getPlatformSession()`. Repeated reads with the same ID do not emit another identity notification.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-identity-watch/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "DeepSeekAccount.watch 默认不再通知 Platform 身份变化，订阅者必须显式启用。"
+---
+
+# 显式订阅账号身份变化
+
+[English](guide.md) | 中文
+
+## 变更
+
+公开方法 `DeepSeekAccount.watch(signal)` 原先会在资料查询首次补齐或改变缓存的 Platform 用户 ID 时发出快照。现在默认仅通知账号状态变化。通过该流刷新 `getPlatformSession()` 的插件必须显式订阅身份变化。凭证替换和登录状态变化仍会通知所有订阅者。
+
+## 迁移
+
+1. 在刷新 Platform 会话或同步其用户 ID 的插件中查找 `deepseekAccount.watch(signal)` 调用。
+2. 将这些调用改为 `deepseekAccount.watch(signal, true)`。只需要登录和凭证状态的账号界面订阅保持不变。
+3. 确认 `getProfile()` 返回 ready 结果且用户 ID 首次出现或变化时，订阅被唤醒并重新读取 `getPlatformSession()`。重复读取同一 ID 不会再次发出身份通知。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/deepseek-account-model-catalog/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-alpha.2/deepseek-account-model-catalog/guide.md
+/:
+  en: 60a8441ae7ea6841
+  zh: 3715b44e11c5131b
+/deepseek-account-models-come-from-the-account-listing:
+  en: 2208c82c24d75a53
+  zh: fa6c53c925aae6f2
+/deepseek-account-models-come-from-the-account-listing/change:
+  en: bf4c84372b8b1316
+  zh: af1623701d19b62e
+/deepseek-account-models-come-from-the-account-listing/migration:
+  en: 7ce26a5a1926b292
+  zh: 35dfc17997834e4d