dsh-plugin-guide 0.3.42 → 0.4.1

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

@@ -1,10 +0,0 @@
-# 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
-/:
-  en: 41d772192075e133
-  zh: 0eb190f00f396176
-/tool-execution-pipeline:
-  en: f2811b12640c6f8e
-  zh: 9e0323523dcbb04c

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

@@ -1,65 +0,0 @@
-<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
-     Run `pnpm run gen-doc-graphs` to regenerate. -->
-
-# 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 `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
-
-```mermaid
-flowchart TD
-  model["Assistant message contains tool-call block"]
-  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
-  presentCall["UI pending card<br/>presentCall(args)"]
-  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
-  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
-  denied["denied or approval refused<br/>tool body skipped"]
-  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
-  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
-  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"]
-  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
-  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
-  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
-  allResults["Tool batch settled<br/>recorded tool/result events complete"]
-  presentResult["UI completed card<br/>presentResult(args, result)"]
-  model --> toolCall
-  toolCall --> presentCall
-  toolCall --> pre
-  pre -->|allow| guards
-  guards -->|allow| around
-  guards -->|deny| denied
-  guards -.->|throw| normalized
-  around --> toolBody
-  pre -->|deny| denied
-  pre -->|ask| approval
-  approval -->|allowed-once| guards
-  approval -->|rejected, cancelled, unavailable| denied
-  approval -.->|throw| normalized
-  denied --> project
-  pre -.->|throw| normalized
-  toolBody --> fsGate
-  fsGate --> toolBody
-  toolBody --> owned
-  toolBody --> around
-  around --> project
-  project --> post
-  project -.->|throw| normalized
-  around -.->|wrapper throws| normalized
-  post -.->|throw| normalized
-  post --> finalize
-  normalized --> finalize
-  finalize --> final
-  final --> toolResult
-  toolResult --> presentResult
-  toolResult --> allResults
-  allResults --> context
-```
-
-Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
-
-Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.

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

@@ -1,67 +0,0 @@
-<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
-     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-execution-pipeline.md` 重新记录配对。 -->
-
-# 工具执行流水线
-
-[English](tool-execution-pipeline.md) | 中文
-
-此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `projectContent` 在执行后策略之前安装已准备内容；`finalizeContent` 和 `tools/result` 在此之后运行。
-
-```mermaid
-flowchart TD
-  model["Assistant message contains tool-call block"]
-  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
-  presentCall["UI pending card<br/>presentCall(args)"]
-  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
-  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
-  denied["denied or approval refused<br/>tool body skipped"]
-  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
-  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
-  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"]
-  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
-  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
-  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
-  allResults["Tool batch settled<br/>recorded tool/result events complete"]
-  presentResult["UI completed card<br/>presentResult(args, result)"]
-  model --> toolCall
-  toolCall --> presentCall
-  toolCall --> pre
-  pre -->|allow| guards
-  guards -->|allow| around
-  guards -->|deny| denied
-  guards -.->|throw| normalized
-  around --> toolBody
-  pre -->|deny| denied
-  pre -->|ask| approval
-  approval -->|allowed-once| guards
-  approval -->|rejected, cancelled, unavailable| denied
-  approval -.->|throw| normalized
-  denied --> project
-  pre -.->|throw| normalized
-  toolBody --> fsGate
-  fsGate --> toolBody
-  toolBody --> owned
-  toolBody --> around
-  around --> project
-  project --> post
-  project -.->|throw| normalized
-  around -.->|wrapper throws| normalized
-  post -.->|throw| normalized
-  post --> finalize
-  normalized --> finalize
-  finalize --> final
-  final --> toolResult
-  toolResult --> presentResult
-  toolResult --> allResults
-  allResults --> context
-```
-
-文件系统的先读后编辑检查位于 `tool-fs` 之下，通过 `fs/*` 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；`ctx.approval` 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 `tools/execute` 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 `finalizeContent` 回调强制执行其同步且仅限内容的不变式。随后，`tools/result` 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。PTC mode 会将保留的 `run_code` 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 `tool/ptc-dispatch`、将拒绝呈现为具有约束力的驳回，并省略 `additionalContexts`，以保持调用与结果相邻。
-
-维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。

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

@@ -1,31 +0,0 @@
-# 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: e736416ec85d6e16
-  zh: 0edf60fccc867295
-/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: 7fe4eb7707e6a9f3
-  zh: be7530a05c205e27
-/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

@@ -1,117 +0,0 @@
-# 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. 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 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
-
-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 |
-|---|---|---|
-| 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, 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.
-
-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

@@ -1,117 +0,0 @@
-# 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 留给包围它们的面板或对话框，不用于这些入口。输入框统计控件与上下文占用率入口使用紧凑控件的 R8 和主题曲线，包含 hover、展开与焦点状态。
-
-代码块、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 − 内缩距离)；两段圆弧同心且使用 `round` | 外层 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

@@ -1,16 +0,0 @@
-# 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

@@ -1,22 +0,0 @@
----
-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

@@ -1,22 +0,0 @@
----
-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

@@ -1,16 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
----
-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

@@ -1,25 +0,0 @@
----
-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

@@ -1,16 +0,0 @@
-# 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

@@ -1,18 +0,0 @@
----
-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

@@ -1,18 +0,0 @@
----
-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/bundled-python-tests/guide.i18n.yaml

@@ -1,16 +0,0 @@
-# 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/bundled-python-tests/guide.md
-/:
-  en: 985656162a55b14a
-  zh: c32bda15938879e5
-/numpy-and-pandas-upstream-tests-require-a-separate-environment:
-  en: ec0ae29022f8ce8c
-  zh: f5e49682b842544d
-/numpy-and-pandas-upstream-tests-require-a-separate-environment/change:
-  en: 41410ee875be7975
-  zh: b052e7b3c8fb096b
-/numpy-and-pandas-upstream-tests-require-a-separate-environment/migration:
-  en: 00c4b10f8df805e7
-  zh: 06ef0fbda56c9acf