dsh-plugin-guide 0.3.21 → 0.3.23

package/references/official-docs/docs/tool-execution-pipeline.i18n.yaml

@@ -1,6 +1,10 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for tool-execution-pipeline.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/tool-execution-pipeline.md
-tool-execution-pipeline.md: f9d3d145bb3d7c271882942b4adc100f53a55290
-tool-execution-pipeline.zh.md: 3bfa6f358ee8482feaa9d26541e495b86a02e515
+/:
+  en: 41d772192075e133
+  zh: 0eb190f00f396176
+/tool-execution-pipeline:
+  en: f2811b12640c6f8e
+  zh: 9e0323523dcbb04c

package/references/official-docs/docs/tool-execution-pipeline.md

@@ -3,7 +3,7 @@
 
 # Tool Execution Pipeline
 
-This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `finalizeContent` and `tools/result` run afterward.
+This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
 
 ```mermaid
 flowchart TD
@@ -18,6 +18,7 @@ flowchart TD
   toolBody["Registered tool execute() body"]
   fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
   owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
+  project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
   post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
   normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
   finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
@@ -39,13 +40,15 @@ flowchart TD
   approval -->|allowed-once| guards
   approval -->|rejected, cancelled, unavailable| denied
   approval -.->|throw| normalized
-  denied --> post
+  denied --> project
   pre -.->|throw| normalized
   toolBody --> fsGate
   fsGate --> toolBody
   toolBody --> owned
   toolBody --> around
-  around --> post
+  around --> project
+  project --> post
+  project -.->|throw| normalized
   around -.->|wrapper throws| normalized
   post -.->|throw| normalized
   post --> finalize

package/references/official-docs/docs/tool-execution-pipeline.zh.md

@@ -5,7 +5,7 @@
 
 [English](tool-execution-pipeline.md) | 中文
 
-此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `finalizeContent` 和 `tools/result` 在此之后运行。
+此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `projectContent` 在执行后策略之前安装已准备内容；`finalizeContent` 和 `tools/result` 在此之后运行。
 
 ```mermaid
 flowchart TD
@@ -20,6 +20,7 @@ flowchart TD
   toolBody["Registered tool execute() body"]
   fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
   owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
+  project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
   post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
   normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
   finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
@@ -41,13 +42,15 @@ flowchart TD
   approval -->|allowed-once| guards
   approval -->|rejected, cancelled, unavailable| denied
   approval -.->|throw| normalized
-  denied --> post
+  denied --> project
   pre -.->|throw| normalized
   toolBody --> fsGate
   fsGate --> toolBody
   toolBody --> owned
   toolBody --> around
-  around --> post
+  around --> project
+  project --> post
+  project -.->|throw| normalized
   around -.->|wrapper throws| normalized
   post -.->|throw| normalized
   post --> finalize

package/references/official-docs/docs/ui-radius.i18n.yaml

@@ -0,0 +1,31 @@
+# Bilingual-pair consistency record for ui-radius.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/ui-radius.md
+/dsh-unified-corner-radius-standard:
+  en: e29e91bf80386fff
+  zh: 0bfca32865bcdfff
+/dsh-unified-corner-radius-standard/summary:
+  en: 9f7d83fc6c1e56ff
+  zh: 1bfd616392982482
+/dsh-unified-corner-radius-standard/table-of-contents:
+  en: aad65e4a8399adbb
+  zh: e76b80d421b17992
+/dsh-unified-corner-radius-standard/scope-and-authority:
+  en: cd8120cba5566e19
+  zh: 65359436088c8bc5
+/dsh-unified-corner-radius-standard/select-the-radius:
+  en: 06ddd6bf9ef1e48c
+  zh: 4c42d0c9266a00e8
+/dsh-unified-corner-radius-standard/reuse-tokens-and-preserve-deliberate-shapes:
+  en: fb6d50f3139ad186
+  zh: 668cb0c02bd22167
+/dsh-unified-corner-radius-standard/nested-geometry-and-hover:
+  en: 3920921700d8ad1c
+  zh: fc99da8a5e905a27
+/dsh-unified-corner-radius-standard/settings-card-materials:
+  en: 85e7e63183df06d1
+  zh: 1da2b44083d7ebe2
+/dsh-unified-corner-radius-standard/apply-and-verify:
+  en: 2f6f10e45b27c19b
+  zh: 9eb5fd964c643be6

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

@@ -0,0 +1,115 @@
+# DSH unified corner-radius standard
+
+English | [中文](ui-radius.zh.md)
+
+## Summary
+
+Choose consistent corner radii by component role and size, and align nested regions, hover fills, backgrounds, and strokes. This standard covers buttons, cells, cards, menus, dialogs, and avatars in DSH Web and Desktop.
+
+## Table of Contents
+
+- [Scope and authority](#scope)
+- [Select the radius](#radius-scale)
+- [Reuse tokens and preserve deliberate shapes](#shapes)
+- [Nested geometry and hover](#nested-hover)
+- [Settings card materials](#settings-cards)
+- [Apply and verify](#verification)
+
+<a id="scope"></a>
+## Scope and authority
+
+This reference defines the DSH Web and Desktop radius scale and its component rules. A local visual adjustment stays scoped to the named component or family and does not automatically change the global scale.
+
+The [Web UI style reference](web-styling.md) defines general styling ownership. Shared values live in [`base.css`](../packages/client/ui-theme/src/styles/base.css), and curve behavior lives in [`corner-shape.css`](../packages/client/ui-theme/src/styles/corner-shape.css). Update the theme implementation and both language versions of this standard together when changing a rule.
+
+<a id="radius-scale"></a>
+## Select the radius
+
+H means designed outer height in CSS pixels, including borders. R means CSS `border-radius`, before the browser clamps overlapping corners. Choose the component role first, then its size variant; width, label length, incidental wrapping, and content expansion do not independently select a larger radius.
+
+| Role | Typical dimensions or examples | Radius | Shared token |
+|---|---|---|---|
+| Small detail | Below H20; keycaps, inline code, tiny controls | R4 | `--dsw-radius-xs` |
+| Compact control | H20–28; small buttons, compact icon buttons, compact menu items | R8 | `--dsw-radius-sm` |
+| Standard control or single-line cell | H32–40; buttons, inputs, selects, navigation rows | R12 | `--dsw-radius-md` |
+| Large control or grouped content | Large buttons, deliberately multiline cells, nested form groups | R16 | `--dsw-radius-lg` |
+| Independent content card | Settings cards, message bubbles, guide entry cards | R20 | `--dsw-radius-xl` |
+| Main enclosing surface | Composer, dialogs, main or floating panels | R28 | `--dsw-radius-panel` |
+
+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.
+
+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.
+
+<a id="shapes"></a>
+## Reuse tokens and preserve deliberate shapes
+
+Reuse `ui-primitives` controls before adding feature-owned geometry. Use `box-sizing: border-box` for fixed outer dimensions. Filled, outline, ghost, loading, and disabled variants keep the same size and radius; hover, pressed, selected, and focus states do not change the radius.
+
+Consume the named tokens instead of introducing local values such as 10px, 14px, 18px, or 24px for ordinary controls and cards. Schedule controls, Desktop onboarding, account notices, and shortcut controls retain their package-owned geometry; the [radius exception record](../packages/client/ui-theme/tests/expected/radius-exceptions.expected.json) pins each permitted file, selector, and declaration rather than exempting whole packages. A family-specific property may refer to a shared token, as `--dsl-guide-entry-radius` does. Geometry derived from a real inset may use `calc()`; it is not an additional scale tier.
+
+Ordinary rounded surfaces use the theme's `superellipse(1.5)` curve where supported. `corner-shape` is not inherited: the theme applies it to elements and their `::before`/`::after`. Unsupported engines retain ordinary circular corners. Do not introduce component-specific smoothing that makes a fill and its outline curve differently.
+
+Preserve intentional circles and capsules: avatars and status dots use `50%`; explicit pills and full-round tracks may use `999px`. Pair every such full-round declaration with `corner-shape: round` in the same rule. Do not turn every button into a capsule just because its height is small. Tiny drawing details, such as glyph marks or miniature tracks, may retain their established local geometry; they do not justify arbitrary radii on surrounding controls.
+
+Both the avatar container and its `img` must remain circular; an image that inherits only `border-radius` still needs an explicit `corner-shape: round` or must inherit the curve from its circular container. Keep equal width and height on both. See [Account settings](../packages/client/ui-settings-account/README.md#use-this-package) for account avatar sizes.
+
+Edge-to-edge docked surfaces and adjoining cells may use R0 on shared edges. A header, footer, or image flush with a card rounds only its exposed outer corners; preserve square internal joins rather than rounding every child on all four sides.
+
+<a id="nested-hover"></a>
+## Nested geometry and hover
+
+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 |
+| 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.
+
+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.
+
+For a split guide card, put the shared radius and clipping on the outer card; give the flush inner buttons square corners. Each button may keep its own hover color, while the outer card clips both fills to one contour. Keep dropdown menus outside the clipped subtree through the existing portal. Preserve a visible keyboard focus treatment rather than clipping an external focus ring away.
+
+```css
+.entry {
+  border-radius: var(--dsl-guide-entry-radius);
+  overflow: hidden;
+}
+
+.main,
+.trigger {
+  border-radius: 0;
+}
+```
+
+The enclosing guide sets `--dsl-guide-entry-radius: var(--dsw-radius-xl)`. Do not give the inner buttons their own R28 ends while the outer card is R20.
+
+<a id="settings-cards"></a>
+## Settings card materials
+
+Account profile, balance, model-provider, preset, and plugin cards share this default material. Selected, warning, error, and expanded states may use their existing semantic colors while retaining the geometry.
+
+```css
+.card {
+  border-radius: var(--dsw-radius-xl);
+  border: 0.5px solid var(--dsw-alias-settings-card-stroke);
+  background: var(--dsw-alias-settings-card-fill);
+}
+```
+
+The theme resolves the card fill to `--dsw-alias-bg-layer-2` and the stroke to `--dsw-alias-border-l4` on `body`, where palette aliases exist. Feature styles consume these aliases in both palettes. Nested editors use R16 and the existing module fill. Account usage/top-up links follow H36/R12 Button geometry; authorization buttons use the shared Button.
+
+Flat neutral borders use the shared 0.5px hairline. Elevated menus, popovers, dialogs, and panels use `border: 0` with the existing `--dsw-elevation-*` material, whose shadow includes the hairline. Do not add a second neutral border over that stroke or add a shadow to an ordinary settings card merely to distinguish its tab. Preserve semantic state-colored borders and the existing translucent-menu backdrop behavior.
+
+<a id="verification"></a>
+## Apply and verify
+
+1. Inspect the requested components together with their shared primitives, overlays, pseudo-elements, and sibling variants. Classify roles before replacing values; do not map every occurrence of one old radius to the same new token.
+2. Change the shared owner where appropriate, then align dependent fills, child corners, clipping, and state styles. Keep independent child cards on their own tier.
+3. Compare actual rendered outer size, radius, curve, fill, and stroke in light and dark themes. Inspect normal, hover, pressed/selected, disabled, and keyboard-focus states where applicable; for split buttons, hover both halves. Check a narrow layout and longer labels when they can affect the component.
+4. Use the existing radius, corner-shape, and elevation stylesheet guards and the smallest relevant browser scenario. The radius guard rejects off-scale literals and unknown tokens; it cannot determine whether a valid token is appropriate for a component or whether two rendered contours align. Confirm those visually.
+5. Follow repository validation and documentation requirements for the actual diff. Update affected expectations only after confirming the intended appearance. Report the resulting rule, tested surfaces, and any unverified states; do not add tests that merely repeat CSS values for a trivial local adjustment.

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

@@ -0,0 +1,115 @@
+# DSH 统一圆角规范
+
+[English](ui-radius.md) | 中文
+
+## 概述
+
+按组件用途和尺寸选择统一圆角，并对齐嵌套区域、hover、底色与描边。适用于 DSH Web 和 Desktop 中的按钮、cell、卡片、菜单、对话框与头像。
+
+## 目录
+
+- [范围与依据](#scope)
+- [选择圆角](#radius-scale)
+- [复用 token，保留有意设计的形状](#shapes)
+- [嵌套几何与 hover](#nested-hover)
+- [设置卡片材质](#settings-cards)
+- [应用与验证](#verification)
+
+<a id="scope"></a>
+## 范围与依据
+
+本参考文档规定 DSH Web 和 Desktop 的圆角尺度及组件应用规则。局部视觉调整限定在指定组件或组件族内，不自动改变全局尺度。
+
+通用样式职责见 [Web UI 样式参考](web-styling.zh.md)。共享数值位于 [`base.css`](../packages/client/ui-theme/src/styles/base.css)，曲线行为位于 [`corner-shape.css`](../packages/client/ui-theme/src/styles/corner-shape.css)。修改规则时同步更新主题实现及本规范的中英文版本。
+
+<a id="radius-scale"></a>
+## 选择圆角
+
+H 表示以 CSS 像素计、包含边框的设计外部高度。R 表示浏览器压缩相互重叠的圆角之前的 CSS `border-radius`。先确定组件用途，再确定尺寸变体；宽度、文字长度、偶发换行和内容展开都不单独决定使用更大的圆角。
+
+| 用途 | 典型尺寸或示例 | 圆角 | 共享 token |
+|---|---|---|---|
+| 小细节 | 低于 H20；键帽、行内代码、微型控件 | R4 | `--dsw-radius-xs` |
+| 紧凑控件 | H20–28；小按钮、紧凑图标按钮、紧凑菜单项 | R8 | `--dsw-radius-sm` |
+| 标准控件或单行 cell | H32–40；按钮、输入框、选择器、导航行 | R12 | `--dsw-radius-md` |
+| 大控件或分组内容 | 大按钮、明确设计为多行的 cell、嵌套表单组 | R16 | `--dsw-radius-lg` |
+| 独立内容卡片 | 设置卡片、消息气泡、引导入口卡片 | R20 | `--dsw-radius-xl` |
+| 主容器 | 对话输入框、对话框、主面板或悬浮面板 | R28 | `--dsw-radius-panel` |
+
+拟定控件尺寸落在档位之间时，优先复用已有的公共尺寸变体。高卡片仍是卡片，不因高度超过按钮就升到 R28。专门设计为多行的 cell 使用 R16；普通按钮的文字发生换行时，仍保留其按钮变体。
+
+具体默认值：`Button` 的 `sm` 使用 H28/R8，`md` 使用 H36/R12，包含描边变体。标准 H32 输入框和 H36 选择器使用 R12。“工作区文件”和“新建终端”引导入口统一使用 R20，包含仅标题与带描述的变体。R28 留给包围它们的面板或对话框，不用于这些入口。
+
+代码块、diff 与文件预览共用 R16：包括改动文件入口卡片、交付文件卡片、通用附件文件卡片和悬停预览浮层。改动文件与交付文件卡片内部的 40px 文件图标底框作为组件特例，四角统一使用 R10。各自的 hover 保持同一轮廓。
+
+<a id="shapes"></a>
+## 复用 token，保留有意设计的形状
+
+添加功能自有的几何规则前，优先复用 `ui-primitives` 控件。固定外部尺寸使用 `box-sizing: border-box`。填充、描边、ghost、加载中和禁用变体保持相同尺寸与圆角；hover、按下、选中和焦点状态不改变圆角。
+
+普通控件和卡片使用具名 token，不新增 10px、14px、18px、24px 等局部数值。计划任务控件、Desktop 引导、账号通知和快捷键控件保留所属包的几何规则；[圆角例外记录](../packages/client/ui-theme/tests/expected/radius-exceptions.expected.json)逐项固定允许的文件、选择器及声明，不豁免整个包。组件族专用属性可引用共享 token，例如 `--dsl-guide-entry-radius`。由真实内缩距离派生的几何可使用 `calc()`；它不构成新的尺度档位。
+
+普通圆角表面在支持时使用主题的 `superellipse(1.5)` 曲线。`corner-shape` 不会继承：主题将它应用于元素及其 `::before`/`::after`。不支持的引擎保留普通圆弧。不要添加组件专用的平滑规则，导致底色与外框使用不同曲线。
+
+保留有意设计的圆形与胶囊：头像和状态点使用 `50%`；明确的胶囊与全圆轨道可使用 `999px`。每个此类全圆声明都在同一规则中配对 `corner-shape: round`。不要因为高度较小就把所有按钮变成胶囊。图形标记或微型轨道等细小绘制细节可保留既有局部几何，但不能据此给外围控件使用任意圆角。
+
+头像的容器和内部 `img` 都要保持正圆；图片不能只继承 `border-radius`，还必须显式使用 `corner-shape: round`，或从正圆容器继承曲线。图片和容器均保持宽高相等。账号头像的具体尺寸见[账号设置](../packages/client/ui-settings-account/README.zh.md#use-this-package)。
+
+贴边停靠表面与相邻 cell 的共用边缘可以使用 R0。紧贴卡片的标题栏、底栏或图片仅对外露的外围拐角设置圆角；保留内部拼接处的直角，不要给每个子元素的四角都加圆角。
+
+<a id="nested-hover"></a>
+## 嵌套几何与 hover
+
+修改子元素圆角前，先区分以下三种关系：
+
+| 关系 | 规则 | 示例 |
+|---|---|---|
+| 同心内缩 | 内层 R = max(0, 外层 R − 内缩距离)；使用相同曲线 | 外层 R16，内缩 4，内层 R12 |
+| 底色紧贴容器边缘 | 由外框决定可见圆角；裁切底色或继承相应圆角 | 两个独立 hover 区域组成的分体按钮卡片 |
+| 容器内独立的卡片或表单组 | 按子元素用途选择档位；不机械减去全部父级内边距 | R20 设置卡片内的 R16 编辑器 |
+
+标准菜单使用外层 R16、4px 内边距、R12 菜单项。紧凑菜单使用外层 R12、4px 内边距、R8 菜单项。公共 `SegmentedControl` 使用外层 R12、4px 内缩、R8 分段和指示器；`SegmentedTabs` 使用外层 R16、4px 内缩、R12 分段和指示器。修改内边距时，同步保持指示器偏移、宽度计算、子菜单对齐与指针桥接区域一致。
+
+单个可点击表面在自身绘制 hover。贴边的伪元素或覆盖层使用与可见外框相同的圆角和曲线。避免单独给底色设置圆角，导致背景与边框之间出现月牙状空隙。
+
+对于分体式引导卡片，在外层卡片设置共享圆角和裁切，贴边的内部按钮使用直角。各按钮可保留独立的 hover 颜色，由外层卡片把两块底色裁切到同一轮廓。通过既有 portal 将下拉菜单放在裁切子树之外。保留可见的键盘焦点样式，不要把外部焦点环一并裁掉。
+
+```css
+.entry {
+  border-radius: var(--dsl-guide-entry-radius);
+  overflow: hidden;
+}
+
+.main,
+.trigger {
+  border-radius: 0;
+}
+```
+
+外围引导页设置 `--dsl-guide-entry-radius: var(--dsw-radius-xl)`。外层卡片为 R20 时，不要再给内部按钮设置独立的 R28 端部。
+
+<a id="settings-cards"></a>
+## 设置卡片材质
+
+账号资料、余额、模型提供商、预设与插件卡片共用以下默认材质。选中、警告、错误和展开状态可以使用既有语义色，同时保持几何一致。
+
+```css
+.card {
+  border-radius: var(--dsw-radius-xl);
+  border: 0.5px solid var(--dsw-alias-settings-card-stroke);
+  background: var(--dsw-alias-settings-card-fill);
+}
+```
+
+主题在色板别名所在的 `body` 上，将卡片底色解析为 `--dsw-alias-bg-layer-2`，描边解析为 `--dsw-alias-border-l4`。功能样式在明暗主题中均使用这些别名。嵌套编辑器使用 R16 和既有模块底色。账号的查询用量、充值链接遵循 H36/R12 的 Button 几何；授权按钮使用公共 Button。
+
+平面中性边框使用共享的 0.5px 发丝线。具有层级阴影的菜单、浮层、对话框和面板使用 `border: 0` 与既有 `--dsw-elevation-*` 材质，其阴影已包含发丝描边。不要在该描边上再叠一层中性边框，也不要仅为区分设置 tab 就给普通设置卡片加阴影。保留语义状态色边框与既有的半透明菜单背景效果。
+
+<a id="verification"></a>
+## 应用与验证
+
+1. 一并检查指定组件、其公共原语、覆盖层、伪元素和同类变体。先按用途分类再替换数值；不要把同一个旧圆角的所有出现位置机械映射到同一新 token。
+2. 适合时修改共享所有方，再对齐依赖它的底色、子元素圆角、裁切和状态样式。独立子卡片保留自己的用途档位。
+3. 在明暗主题中比较实际渲染的外部尺寸、圆角、曲线、底色和描边。按适用范围检查默认、hover、按下或选中、禁用及键盘焦点状态；分体按钮需悬停两侧。组件可能受影响时，检查窄布局和较长文案。
+4. 使用既有的 radius、corner-shape、elevation 样式表检查，以及最小相关浏览器场景。圆角检查会拒绝未纳入尺度的字面量和未知 token；它不能判断合法 token 是否适合某组件，也不能判断两个渲染轮廓是否贴合。这些需要视觉确认。
+5. 根据实际差异遵循仓库验证和文档要求。确认目标外观后再更新受影响的预期结果。报告最终规则、已测试界面及未验证状态；不要为简单局部调整添加仅重复 CSS 数值的测试。

package/references/official-docs/docs/upgrade-guide/v0.1.7-rc.2/schedule-optional-bundle/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.1.7-rc.2/schedule-optional-bundle/guide.md
+/:
+  en: 224d57a22f38ba26
+  zh: 1472851dde2bf9c3
+/schedule-moves-into-the-automation-tasks-optional-bundle:
+  en: 138f715e3a260eb6
+  zh: eff22703b2c79915
+/schedule-moves-into-the-automation-tasks-optional-bundle/change:
+  en: b1b250e677c23b10
+  zh: b71c1591ea4f9ce5
+/schedule-moves-into-the-automation-tasks-optional-bundle/migration:
+  en: 656fea5dc45f8310
+  zh: 8dfe16d2fdacf71a

package/references/official-docs/docs/upgrade-guide/v0.1.7-rc.2/schedule-optional-bundle/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "The Web composition no longer carries the Schedule rows; the Automation tasks optional bundle inserts them."
+---
+
+# Schedule moves into the Automation tasks optional bundle
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.1.7-rc.2, `@deepseek-ai/dsh-web-app` carried the `time-context`, `schedule`, and `ui-schedule` rows with `disabled: true`. Turning Schedule on in the Plugins page, or by hand, wrote id-targeted overrides such as `- id: schedule` with `disabled: false` into `$DSH_HOME/profiles/<name>/cordis.patch.yml` or a `--patch` overlay.
+
+The next release removes the three rows from the Web composition. `@deepseek-ai/dsh-experimental-schedule-bundle`, shown as Automation tasks in the Plugins page's Official group, inserts them. Every installation ships the bundle switched off.
+
+Profiles that enabled Schedule by id lose it after upgrading: the loader warns `patch: entry schedule not found` (and the same for `time-context` and `ui-schedule`), the `schedule_*` tools and the Automation tasks page disappear, and stored reminders stop being delivered. Stored tasks and delivery records remain on disk.
+
+## Migration
+
+1. Open Plugins, find Automation tasks in the Official group, and switch it on. The switch appends `@deepseek-ai/dsh-experimental-schedule-bundle` to `dsh.profile.bundles` in `$DSH_HOME/profiles/<name>/package.json`; for a profile edited by hand, add that entry yourself.
+2. Keep existing overrides that set other fields on `schedule`, `time-context`, or `ui-schedule`, such as `deliveryHistoryDays`; they apply again once the bundle inserts the rows. Overrides that only set `disabled: false` are redundant and can be deleted.
+3. Confirm: restart `dsh web`, check that startup logs no `patch: entry ... not found` warning for the three ids, and that the sidebar shows Automation tasks with the previously stored reminders.

package/references/official-docs/docs/upgrade-guide/v0.1.7-rc.2/schedule-optional-bundle/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Web 组合不再包含 Schedule 的三行；改由“自动化任务”可选 bundle 插入。"
+---
+
+# Schedule 移入“自动化任务”可选 bundle
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.1.7-rc.2 中，`@deepseek-ai/dsh-web-app` 以 `disabled: true` 包含 `time-context`、`schedule` 和 `ui-schedule` 三行。在插件管理页或手动开启 Schedule，会向 `$DSH_HOME/profiles/<name>/cordis.patch.yml` 或 `--patch` overlay 写入按 id 定位的覆盖项，例如 `- id: schedule` 加 `disabled: false`。
+
+下一版本从 Web 组合中移除这三行。插件管理页“官方”分组中的“自动化任务”，即 `@deepseek-ai/dsh-experimental-schedule-bundle`，负责插入它们。每个安装都自带该 bundle，默认关闭。
+
+按 id 开启 Schedule 的 profile 升级后会失去 Schedule：loader 警告 `patch: entry schedule not found`（`time-context` 和 `ui-schedule` 同理），`schedule_*` 工具和自动化任务页面消失，已存储的提醒不再投递。已存储的任务和投递记录仍保留在磁盘上。
+
+## 迁移
+
+1. 打开插件管理页，在“官方”分组中找到“自动化任务”并开启。开关会把 `@deepseek-ai/dsh-experimental-schedule-bundle` 追加到 `$DSH_HOME/profiles/<name>/package.json` 的 `dsh.profile.bundles`；手动维护的 profile 需自行添加该条目。
+2. 保留为 `schedule`、`time-context` 或 `ui-schedule` 设置其他字段的覆盖项，例如 `deliveryHistoryDays`；bundle 插入这些行后它们重新生效。只设置 `disabled: false` 的覆盖项已无作用，可以删除。
+3. 确认：重启 `dsh web`，检查启动日志中这三个 id 不再出现 `patch: entry ... not found` 警告，且侧栏显示“自动化任务”并列出之前存储的提醒。

package/references/official-docs/docs/upgrade-guide/v0.1.7-rc.2/transcript-view-legacy-normal/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.1.7-rc.2/transcript-view-legacy-normal/guide.md
+/:
+  en: 7d7e527ed3c87db1
+  zh: 4654dab85b66bcb0
+/legacy-normal-work-details-display-as-detailed:
+  en: 3c88b0b06094c162
+  zh: 9ae8ff49975824a9
+/legacy-normal-work-details-display-as-detailed/change:
+  en: 0e2287aa768141f3
+  zh: 035992a94129fd9e
+/legacy-normal-work-details-display-as-detailed/migration:
+  en: 6078ccce1ceacfd6
+  zh: 6a394cf5259c9965

package/references/official-docs/docs/upgrade-guide/v0.1.7-rc.2/transcript-view-legacy-normal/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "The legacy ui-chat.transcriptView value normal, and an unset value in non-Desktop Web, now display Detailed instead of Standard."
+---
+
+# Legacy `normal` work details display as Detailed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Host setting `ui-chat.transcriptView` selects Settings → General → Work details. In v0.1.7-rc.2 the client displayed the legacy saved value `normal` as `standard`, and every client used `standard` when the setting was missing, `null`, or invalid.
+
+From the next release:
+
+- A saved `normal` displays as `detailed` on Desktop and Web. The saved value on disk is not rewritten.
+- A missing, `null`, or invalid value displays as `detailed` in non-Desktop Web (the npm `dsh web` install). Desktop still uses `standard`.
+- Saved `compact`, `standard`, `detailed`, and `verbose` values are unchanged.
+
+Users who relied on the old reading see running Turns with process-group bodies expanded instead of collapsed summaries.
+
+## Migration
+
+1. To keep the previous presentation, open Settings → General → Work details and choose Standard. The client saves `standard` to `ui-chat.transcriptView`, which every later default change leaves untouched.
+2. Confirm: start a Turn that calls tools and check that its process group shows a collapsed summary with live task detail.

package/references/official-docs/docs/upgrade-guide/v0.1.7-rc.2/transcript-view-legacy-normal/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "旧值 ui-chat.transcriptView: normal，以及非 Desktop Web 中未设置的值，改为按“详细”而非“标准”展示。"
+---
+
+# 旧值 `normal` 的工作步骤展示改为“详细”
+
+[English](guide.md) | 中文
+
+## 变更
+
+Host 设置 `ui-chat.transcriptView` 对应设置 → 通用设置 → 工作步骤展示。在 v0.1.7-rc.2 中，客户端把旧保存值 `normal` 按 `standard` 展示；设置缺失、为 `null` 或无效时，所有客户端都使用 `standard`。
+
+从下一版本起：
+
+- 保存的 `normal` 在 Desktop 和 Web 中均按 `detailed` 展示，磁盘中的保存值不会被改写。
+- 设置缺失、为 `null` 或无效时，非 Desktop Web（npm 安装的 `dsh web`）按 `detailed` 展示；Desktop 仍使用 `standard`。
+- 已保存的 `compact`、`standard`、`detailed` 和 `verbose` 保持不变。
+
+依赖旧读取方式的用户会看到运行中轮次的过程组正文直接展开，而不是收起的摘要。
+
+## 迁移
+
+1. 如需保留原有展示，打开设置 → 通用设置 → 工作步骤展示并选择“标准”。客户端会把 `standard` 保存到 `ui-chat.transcriptView`，此后的默认值变化不影响该值。
+2. 确认：发起一个调用工具的轮次，检查其过程组显示收起的摘要和实时任务详情。

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/account-sign-in-errors/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/account-sign-in-errors/guide.md
+/:
+  en: 26d3106bedaf5410
+  zh: 0414d05784bcfc3e
+/account-sign-in-error-codes:
+  en: 8d92729fd1c381f0
+  zh: a526d1a54a583d2b
+/account-sign-in-error-codes/change:
+  en: f1bace911bbf5247
+  zh: bee091aef4b4a0e5
+/account-sign-in-error-codes/migration:
+  en: be6e29a39279aa38
+  zh: 29c34f23f3b172fa

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/account-sign-in-errors/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Account sign-in transport failures now report no-response instead of network."
+---
+
+# Account sign-in error codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`SignInErrorCode` adds `no-response`. Account state returned by `account/getState`, `account/startSignIn`, and `account/watch` reports this code when fetch fails before returning a Response, including request timeouts. These failures previously reported `network`. HTTP response errors still report `network`; authorization-attempt expiry still reports `expired`.
+
+## Migration
+
+1. Add `no-response` to validators and exhaustive handlers for `SignInAttemptView.errorCode` in clients of the account API or `@deepseek-ai/dsh-deepseek-account`.
+2. Show network troubleshooting for `no-response`. Keep generic failure handling for `network`, which also covers HTTP and account-detail retrieval failures.
+3. Confirm a failed login with `errorCode: 'no-response'` is accepted by the client and offers retry, while an HTTP error response retains generic failure handling.

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/account-sign-in-errors/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "账号登录传输失败现在报告 no-response，而非 network。"
+---
+
+# 账号登录错误码
+
+[English](guide.md) | 中文
+
+## 变更
+
+`SignInErrorCode` 新增 `no-response`。当 fetch 在返回 Response 前失败（包括单次请求超时）时，`account/getState`、`account/startSignIn` 和 `account/watch` 返回的账号状态报告此代码。这些失败此前报告 `network`。HTTP 响应错误仍报告 `network`；授权尝试到期仍报告 `expired`。
+
+## 迁移
+
+1. 在账号 API 或 `@deepseek-ai/dsh-deepseek-account` 的客户端中，为 `SignInAttemptView.errorCode` 的校验器和穷尽处理逻辑添加 `no-response`。
+2. 对 `no-response` 提示检查网络。对 `network` 保留通用失败处理；该代码也涵盖 HTTP 和账号详情获取失败。
+3. 确认客户端接受 `errorCode: 'no-response'` 的登录失败状态并提供重试，同时 HTTP 错误响应仍使用通用失败处理。

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/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/remove-runtime-invariants/guide.md
+/:
+  en: 3cb412fe69354a6b
+  zh: fbd2dd7abcd08ed7
+/runtime-invariant-plugins-are-removed:
+  en: 573fd5239a856cab
+  zh: edb2683d049a81b7
+/runtime-invariant-plugins-are-removed/change:
+  en: 58c246cfc02ab19d
+  zh: 4826b8cbb34e1363
+/runtime-invariant-plugins-are-removed/migration:
+  en: b42a35a30b792f84
+  zh: 0ddbccc4b93410a3

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "The runtime invariant registry package and every package's `./invariant` subpath export are removed."
+---
+
+# Runtime invariant plugins are removed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.2.0-rc.2, `@deepseek-ai/dsh-invariants` provided the `ctx.invariants` service, and workspace packages such as `@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-agent`, `@deepseek-ai/dsh-scope`, and `@deepseek-ai/dsh-agent-loop` published `./invariant` companion plugins that registered checks with it. The `sdk-minimal` profile mounted five of these rows with ids `invariants`, `session-invariant`, `agent-invariant`, `scope-invariant`, and `agent-loop-invariant`.
+
+The next release no longer publishes `@deepseek-ai/dsh-invariants`, `InvariantRegistry`, `InvariantInstaller`, `InvariantFailure`, `InvariantError`, or any `<package>/invariant` subpath. The `sdk-minimal` profile no longer contains the five rows. The `credentials/reference-updated`, `credentials/record-updated`, `authorization/settled`, and `llm/adapters-updated` emitters contain and log every listener failure, including errors with `code: 'INVARIANT'`, instead of rethrowing them.
+
+A `cordis.yml`, patch, or overlay that names a removed module fails to load it. A patch that targets one of the five `sdk-minimal` ids logs `patch: entry <id> not found`. TypeScript code that imports a removed module or symbol no longer compiles.
+
+## Migration
+
+1. Delete rows whose `name` is `@deepseek-ai/dsh-invariants` or ends in `/invariant` from `cordis.yml`, `$DSH_HOME/profiles/<name>/cordis.patch.yml`, and `--patch` overlays.
+2. Delete patch entries that target the ids `invariants`, `session-invariant`, `agent-invariant`, `scope-invariant`, or `agent-loop-invariant`.
+3. Remove `@deepseek-ai/dsh-invariants` from `package.json` dependencies and delete imports of it and of `<package>/invariant` subpaths. A plugin that relied on a rethrown `INVARIANT` failure from one of the four emitters must report the failure through its own channel.
+4. Confirm: `dsh` starts the profile without a module-not-found error or `patch: entry ... not found` warning, and `tsc` reports no missing module or export.

package/references/official-docs/docs/upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "运行时不变式注册表包和每个包的 `./invariant` 子路径导出均被移除。"
+---
+
+# 运行时不变式插件被移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.0-rc.2 中，`@deepseek-ai/dsh-invariants` 提供 `ctx.invariants` 服务，`@deepseek-ai/dsh-session`、`@deepseek-ai/dsh-agent`、`@deepseek-ai/dsh-scope`、`@deepseek-ai/dsh-agent-loop` 等 workspace 包发布向该服务注册检查的 `./invariant` 配套插件。`sdk-minimal` profile 挂载其中五行，id 为 `invariants`、`session-invariant`、`agent-invariant`、`scope-invariant` 和 `agent-loop-invariant`。
+
+下一版本不再发布 `@deepseek-ai/dsh-invariants`、`InvariantRegistry`、`InvariantInstaller`、`InvariantFailure`、`InvariantError`，也不再发布任何 `<package>/invariant` 子路径。`sdk-minimal` profile 不再包含这五行。`credentials/reference-updated`、`credentials/record-updated`、`authorization/settled` 和 `llm/adapters-updated` 的发出方会隔离并记录每个监听器失败，包括 `code: 'INVARIANT'` 的错误，不再重新抛出。
+
+引用已移除模块的 `cordis.yml`、patch 或 overlay 无法加载该模块。指向上述五个 `sdk-minimal` id 之一的 patch 会记录 `patch: entry <id> not found`。导入已移除模块或符号的 TypeScript 代码无法编译。
+
+## 迁移
+
+1. 从 `cordis.yml`、`$DSH_HOME/profiles/<name>/cordis.patch.yml` 和 `--patch` overlay 中删除 `name` 为 `@deepseek-ai/dsh-invariants` 或以 `/invariant` 结尾的行。
+2. 删除指向 id `invariants`、`session-invariant`、`agent-invariant`、`scope-invariant` 或 `agent-loop-invariant` 的 patch 条目。
+3. 从 `package.json` 依赖中移除 `@deepseek-ai/dsh-invariants`，并删除对它和 `<package>/invariant` 子路径的导入。依赖上述四个发出方重新抛出 `INVARIANT` 失败的插件，必须通过自己的通道报告该失败。
+4. 确认：`dsh` 启动该 profile 时没有模块未找到错误或 `patch: entry ... not found` 警告，`tsc` 不再报告缺失的模块或导出。