dsh-plugin-dev-kb 1.1.0 → 1.4.0

package/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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` 不再报告缺失的模块或导出。

package/kb/extra/upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "The Automation tasks optional bundle is removed; the Web composition mounts Schedule itself."
+---
+
+# Automation tasks bundle removed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.2.0-rc.2, switching on Automation tasks in the Plugins page appended `@deepseek-ai/dsh-experimental-schedule-bundle` to `dsh.profile.bundles` in `$DSH_HOME/profiles/<name>/package.json`. That bundle inserted the `time-context`, `schedule`, and `ui-schedule` rows.
+
+The next release removes the bundle. `@deepseek-ai/dsh-web-app` mounts `schedule` and `ui-schedule` in every Web profile, and the `standard`, `cordis`, and `ptc` presets declare the clock reading and the four `schedule_*` tools; `minimal` declares neither ([details](../../../subsystems/schedule.md)).
+
+Loading a profile removes `@deepseek-ai/dsh-experimental-schedule-bundle` from its `dsh.profile.bundles` and rewrites `package.json`; other manifest fields are kept. Stored tasks and delivery records stay on disk and remain in use.
+
+## Migration
+
+1. Start `dsh` once with each affected profile; no manual edit is needed. A profile directory that another tool writes must drop the entry from `dsh.profile.bundles` itself.
+2. Keep overrides on `schedule` and `ui-schedule` in `cordis.patch.yml` or a `--patch` overlay; the Web composition carries those rows. A top-level override on `time-context` no longer matches a row, because the clock row belongs to the presets ([time-context](../../../../packages/context/time-context/README.md)); delete it.
+3. Confirm: `dsh.profile.bundles` no longer lists the bundle, the Plugins page shows no failed Automation tasks entry, and the sidebar shows Automation tasks with the previously stored reminders.

package/kb/extra/upgrade-guide/v0.2.0-rc.2/schedule-bundle-retired/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "“自动化任务”可选 bundle 已移除；Web 组合自行挂载 Schedule。"
+---
+
+# “自动化任务” bundle 已移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.0-rc.2 中，在插件管理页开启“自动化任务”会把 `@deepseek-ai/dsh-experimental-schedule-bundle` 追加到 `$DSH_HOME/profiles/<name>/package.json` 的 `dsh.profile.bundles`。该 bundle 插入 `time-context`、`schedule` 和 `ui-schedule` 三行。
+
+下一版本移除该 bundle。`@deepseek-ai/dsh-web-app` 在每个 Web profile 中挂载 `schedule` 和 `ui-schedule`，`standard`、`cordis` 和 `ptc` preset 声明时钟读数和四个 `schedule_*` 工具；`minimal` 两者都不声明（[详情](../../../subsystems/schedule.zh.md)）。
+
+加载 profile 时会从其 `dsh.profile.bundles` 中删除 `@deepseek-ai/dsh-experimental-schedule-bundle` 并重写 `package.json`；其他 manifest 字段保持不变。已存储的任务和投递记录仍保留在磁盘上并继续使用。
+
+## 迁移
+
+1. 用每个受影响的 profile 启动一次 `dsh`，无需手动编辑。由其他工具写入的 profile 目录需要自行从 `dsh.profile.bundles` 删除该条目。
+2. 保留 `cordis.patch.yml` 或 `--patch` overlay 中针对 `schedule` 和 `ui-schedule` 的覆盖项；Web 组合包含这两行。顶层针对 `time-context` 的覆盖项不再匹配任何行，因为时钟行属于 preset（[time-context](../../../../packages/context/time-context/README.zh.md)）；请删除它。
+3. 确认：`dsh.profile.bundles` 不再列出该 bundle，插件管理页不再显示异常的“自动化任务”条目，且侧栏显示“自动化任务”并列出之前存储的提醒。

package/kb/extra/upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest/guide.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "Subpath plugins no longer read display text or icons from an exported <subpath>/package.json; they use locale meta and <subpath>/icon."
+---
+
+# Subpath plugins read `<subpath>/icon` instead of `<subpath>/package.json`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.2.0-rc.2, Plugin Manager and Settings read a subpath plugin such as `my-plugins/search` through `my-plugins/search/package.json` when the package exported it: `name` and `description` filled missing locale fields, and `icon` supplied the row image. A subpath is not a package, so the next release never reads a `package.json` for it. Its title and description come only from `my-plugins/search/locale/*.json`, and its image comes from the exported `my-plugins/search/icon` resource. Package-root plugins keep their `package.json` text and `icon`; when `icon` is omitted, an exported `./icon` supplies the image. Authors of packages that export subpath `package.json` files are affected.
+
+## Migration
+
+1. Move the subpath manifest's `name` and `description` into `meta.title` and `meta.description` of the subpath locale files, and export them, for example `"./search/locale/*.json": "./locale/search/*.json"`.
+2. Replace the subpath manifest's `icon` with an icon export and publish its target:
+
+   ```json
+   {
+     "exports": { "./search/icon": "./assets/search.svg" },
+     "files": ["assets/search.svg"]
+   }
+   ```
+
+3. Remove the `./search/package.json` export and its file.
+4. Run `pnpm run verify-package-meta` in a DSH checkout, or open Plugin Manager, and confirm the subpath row shows its title, description, and image.

package/kb/extra/upgrade-guide/v0.2.0-rc.2/subpath-plugin-display-manifest/guide.zh.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "子路径插件不再从导出的 <子路径>/package.json 读取展示文本和图标，改用 locale meta 和 <子路径>/icon。"
+---
+
+# 子路径插件改读 `<子路径>/icon`，不再读 `<子路径>/package.json`
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.0-rc.2 中，插件管理页和设置页会在包导出 `my-plugins/search/package.json` 时，通过它读取 `my-plugins/search` 这样的子路径插件：`name` 和 `description` 补全缺失的 locale 字段，`icon` 提供行图片。子路径不是包，因此下一版本不再为它读取任何 `package.json`。其标题和描述只来自 `my-plugins/search/locale/*.json`，图片来自导出的 `my-plugins/search/icon` 资源。包根插件保留 `package.json` 文本和 `icon`；省略 `icon` 时，导出的 `./icon` 提供图片。受影响的是导出子路径 `package.json` 的包作者。
+
+## 迁移
+
+1. 将子路径清单的 `name` 和 `description` 移到子路径 locale 文件的 `meta.title` 和 `meta.description`，并导出这些文件，例如 `"./search/locale/*.json": "./locale/search/*.json"`。
+2. 用图标导出替换子路径清单的 `icon`，并发布其目标文件：
+
+   ```json
+   {
+     "exports": { "./search/icon": "./assets/search.svg" },
+     "files": ["assets/search.svg"]
+   }
+   ```
+
+3. 删除 `./search/package.json` 导出及其文件。
+4. 在 DSH 仓库中运行 `pnpm run verify-package-meta`，或打开插件管理页，确认子路径行显示标题、描述和图片。

package/kb/extra/web-styling.md

@@ -10,8 +10,10 @@ This reference defines styling ownership and component rules for browser client
 
 Global style sheets belong in `ui-theme/src/styles/`. Component styles live beside their component as CSS Modules. A component may define a local custom property when its value is part of that component's layout or presentation contract; shared colors, typography, elevation, and motion belong to the theme package.
 
+<a id="component-rules"></a>
 ## Component rules
 
+- Reuse the control before restyling one: the [ui-primitives component catalog](../packages/client/ui-primitives/README.md#component-catalog) is the only channel that crosses feature packages, and a deliberate visual difference belongs in a prop there rather than in a second copy ([reference](../packages/client/ui-primitives/README.md)).
 - Use CSS Modules and `clsx`; do not add a component library or Tailwind.
 - Use `--dsw-alias-*` semantic tokens in feature components. Do not copy static palette values or write literal colors there.
 - Keep theme selectors out of feature component CSS. Light/dark overrides belong to the theme owner.
@@ -21,9 +23,17 @@ Global style sheets belong in `ui-theme/src/styles/`. Component styles live besi
 - Preserve keyboard focus visibility and reduced-motion behavior when adding transitions or hover-only controls.
 - Rounded corners inherit the global superellipse smoothing from ui-theme's `corner-shape.css` on supporting engines. Pair `corner-shape: round` with every full-round `border-radius` (`50%`, `100%`, or a pill radius) so circles and capsules keep circular arcs; the ui-theme corner-shape spec enforces the pairing.
 - Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)`, `var(--dsw-elevation-prominent)`, or the composer's `var(--dsw-elevation-soft)` (larger blur at lower alpha): the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
+- Existing and new dropdown, context, submenu, and selection menus use `Menu` or wrap custom content in `MenuSurface`. The material is the theme-owned `--dsw-menu-surface-fill` plus `--dsw-menu-backdrop-filter`; feature and platform CSS must not override either. The ui-theme menu spec rejects unwrapped menu/listbox renderers, material overrides, and token redefinitions. The schedule-owned `TaskMenu` and `ClockPicker` retain their existing containers and material as explicit exceptions ([owner](../packages/client/ui-schedule/README.md)).
+- Modal backdrops, including settings and confirmation dialogs, retain their translucent dark mask without blur. The theme sets `--dsw-mask-blur` to `none`; Desktop-owned modal overlays also leave the parent page unfiltered.
+- Menu background filtering stays on an isolated layer so nested menus and fixed overlays retain their positioning and backdrop. On macOS, `MenuSurface` adds an opaque backing behind page content only within each menu’s bounds, allowing Chromium to blur content over native vibrancy; CSS anchors follow placement and size, and unmounting removes the backing. Overlays without this backing use `--dsw-specific-menu`, whose theme-owned macOS fill is 94% opaque to keep underlying text from bleeding through. Other elevated surfaces using that fill pair it with the same filter on their own isolated background when they contain fixed overlays.
 - Flat borders and separators that use a neutral `--dsw-alias-border-*` token draw at `0.5px` — buttons, inputs, cards, row dividers, and separators drawn as filled boxes (menu separators, the conversation header seam, markdown `hr`, vertical rails) share the hairline weight, which Chromium paints as one device pixel. Dashed affordances and state-colored borders keep 1px; spinner ring tracks keep their width through the spec's explicit allowlist. The ui-theme elevation spec rejects wider neutral solid borders.
-- Clickable artifact links (markdown anchors, prose file mentions, web source and fetch links, produced-file chips, workflow member links) color through `--dsw-alias-link` at `font-weight: 500`, with no underline at rest and a dotted 3px-offset underline on hover/focus. Text-leading anchors also lead with the ui-primitives `LinkIcon` category glyph riding `currentColor`; workflow member links and image-only anchors carry no glyph, and tool-row file links keep their grey dotted affordance ([clickable-link Agent Note](../.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md)).
+- Clickable artifact links (markdown anchors, prose file mentions, web source and fetch links, produced-file chips, workflow member links) color through `--dsw-alias-link` at `font-weight: 500`, with no underline at rest and a dotted 3px-offset underline on hover/focus. Compact Thinking Markdown keeps tertiary text color and a resting dotted underline ([compact presentation](../packages/client/ui-primitives/README.md#rendering-agent-output)). Text-leading anchors also lead with the ui-primitives `LinkIconMedium` category glyph riding `currentColor`, which for a well-known external host is that site's own mark instead of the globe; workflow member links and image-only anchors carry no glyph, and tool-row file links keep their grey dotted affordance.
+
+<a id="corner-radii-and-settings-cards"></a>
+## Corner radii and settings cards
+
+The [DSH unified corner-radius standard](ui-radius.md) defines the radius scale, component size mapping, circle and capsule exceptions, nested hover geometry, and settings-card fills and strokes.
 
 ## Changing the system
 
-Add or change a shared token in the owning `ui-theme` sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the [testing policy](testing.md); the [styling-system Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.md) records framework rationale.
+Add or change a shared token in the owning `ui-theme` sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the [testing policy](testing.md); the [archived styling-system Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) records framework rationale.

package/kb/extra/web-styling.zh.md

@@ -10,8 +10,10 @@
 
 全局样式表归 `ui-theme/src/styles/` 所有。组件样式以 CSS Modules 形式放在组件旁。当某个值属于该组件的布局或呈现约定时，组件可以定义局部自定义属性；共享颜色、排版、层级和动效属于主题包。
 
+<a id="component-rules"></a>
 ## 组件规则
 
+- 重新设计控件样式之前先复用控件：[ui-primitives 组件目录](../packages/client/ui-primitives/README.zh.md#component-catalog)是唯一跨功能包的通道，有意的视觉差异应作为那里的一个 prop，而不是另起一份拷贝（[参考](../packages/client/ui-primitives/README.zh.md)）。
 - 使用 CSS Modules 和 `clsx`；不得添加组件库或 Tailwind。
 - 功能组件使用 `--dsw-alias-*` 语义 token。不得复制静态色板值或在其中写入颜色字面量。
 - 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
@@ -21,9 +23,17 @@
 - 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
 - 支持的引擎上，圆角继承 ui-theme `corner-shape.css` 的全局超级椭圆平滑。每个正圆 `border-radius`（`50%`、`100%` 或胶囊半径）必须配对 `corner-shape: round`，使圆形与胶囊保持圆弧；ui-theme 的 corner-shape spec 强制这一配对。
 - 高层级表面（菜单、浮层、对话框、面板、悬浮按钮、输入框）设 `border: 0` 并使用 `box-shadow: var(--dsw-elevation-panel)`、`var(--dsw-elevation-prominent)` 或输入框专用的 `var(--dsw-elevation-soft)`（更大模糊、更低透明度）：0.5px 发丝描边是第一层投影，`--dsw-elevation-stroke-color` 可按表面或状态重绑或抑制描边。不得将 `--dsw-alias-border-*` border 与 lv/elevation 投影配对——ui-theme 的 elevation spec 会拒绝；状态色 border（warn 面板）保持真 border。
+- 存量和新增的下拉菜单、上下文菜单、子菜单及选择菜单使用 `Menu`，自定义内容用 `MenuSurface` 包裹。材质由主题的 `--dsw-menu-surface-fill` 和 `--dsw-menu-backdrop-filter` 组成；功能及平台 CSS 不得覆盖两者。ui-theme 菜单检查拒绝未使用共享容器的 menu/listbox 渲染、材质覆盖和 token 重定义。计划任务自有的 `TaskMenu` 与 `ClockPicker` 是明确例外，保留现有容器和材质（[所属包](../packages/client/ui-schedule/README.zh.md)）。
+- 设置、确认框等模态弹窗保留黑色半透明遮罩，不模糊背景。主题将 `--dsw-mask-blur` 设为 `none`；Desktop 自有模态浮层也不对父页面施加模糊。
+- 菜单背景模糊绘制在独立图层上，保证嵌套菜单和 fixed 浮层的定位及背景采样。macOS 上，`MenuSurface` 仅在各菜单范围内、页面内容后方添加实色底层，使 Chromium 能在原生透明材质上模糊页面内容；CSS 锚点跟随位置及尺寸，卸载时移除底层。没有该底层的浮层使用 `--dsw-specific-menu`，主题在 macOS 上将其设为 94% 不透明度，防止下方文字透出。其他使用该填充的浮起表面也须配套同一模糊；包含 fixed 浮层时，将两者绘制在独立背景层上。
 - 使用中性 `--dsw-alias-border-*` token 的平面边框与分割线一律 `0.5px`——按钮、输入框、卡片、行分割线，以及以填充盒绘制的分隔线（菜单分隔、对话标题栏接缝、markdown `hr`、竖向轨道线）共用发丝线粗细，Chromium 将其绘制为一个设备像素。dashed 记号与状态色 border 保持 1px；spinner 圆环经 spec 的显式豁免保留原宽度。更宽的中性 solid border 会被 ui-theme elevation spec 拒绝。
-- 可点击产物链接（Markdown 锚点、正文文件引用、网页来源与抓取链接、产物 chips、workflow 成员链接）经 `--dsw-alias-link` 着色、`font-weight: 500`，默认无下划线，hover/focus 时为 3px offset 的点状下划线。带文字的锚点另以 ui-primitives 的 `LinkIcon` 分类图形（随 `currentColor`）作前置；workflow 成员链接与只包图片的锚点不带图形，工具行文件链接保持其灰色点线示能（[可点击链接 Agent Note](../.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.zh.md)）。
+- 可点击产物链接（Markdown 锚点、正文文件引用、网页来源与抓取链接、产物 chips、workflow 成员链接）经 `--dsw-alias-link` 着色、`font-weight: 500`，默认无下划线，hover/focus 时为 3px offset 的点状下划线。紧凑 Thinking Markdown 保持 tertiary 文字色和默认点状下划线（[紧凑展示](../packages/client/ui-primitives/README.zh.md#rendering-agent-output)）。带文字的锚点另以 ui-primitives 的 `LinkIconMedium` 分类图形（随 `currentColor`）作前置；目的地是已知外部站点时改用该站点自己的标记而非地球；workflow 成员链接与只包图片的锚点不带图形，工具行文件链接保持其灰色点线示能。
+
+<a id="corner-radii-and-settings-cards"></a>
+## 圆角与设置卡片
+
+圆角尺度、组件尺寸映射、正圆与胶囊例外、嵌套 hover，以及设置卡片的底色与描边统一由 [DSH 统一圆角规范](ui-radius.zh.md)定义。
 
 ## 变更系统
 
-在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[样式系统 Agent Note](../.agents/notes/implemented/process/2026-07-19-web-styling-system.zh.md) 记录框架依据。
+在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[已归档的样式系统 Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) 记录框架依据。