dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-credential-modes/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "DeepSeek 网页搜索与获取从 DeepSeek 模型路由取得端点；共享的 baseURL、apiKeyEnv 与 apiKey 字段已移除，改用按能力区分的字段。"
+---
+
+# DeepSeek 网页搜索与获取跟随 DeepSeek 模型路由
+
+[English](guide.md) | 中文
+
+## 变更
+
+过去，DeepSeek Search API 与 Fetch API（`web-deepseek-api`）把凭据发往同一个共享的 `baseURL`（默认 `https://api.deepseek.com/v1/tools`）：会话最近一次模型请求使用 `deepseek-account` 路由且用户已登录时发送账号令牌，否则发送 `apiKeyEnv`（默认 `DEEPSEEK_API_KEY`）下的密钥或字面 `apiKey`。现在每个能力沿用相同的路由规则，但端点取自路由：在 `deepseek-account` 上把账号令牌发往账号路由的 origin 加 `/v1/tools`；其他情况（包括未登录的账号会话）把 `deepseek-official` 路由 `apiKeyEnv` 下的密钥发往该路由的 origin 加 `/v1/tools`，因此 `DEEPSEEK_BASE_URL` 现在也会改变 Search 与 Fetch 的端点。没有 `deepseek-official` 路由时，把 `DEEPSEEK_API_KEY` 发往 `https://api.deepseek.com/v1/tools`；已挂载的路由设置无法解析时，操作直接失败。`baseURL`、`apiKeyEnv` 与 `apiKey` 字段已移除；已保存的值可以正常加载，但会被忽略。只要设置 `searchBaseURL` 或 `searchApiKeyEnv` 中的任一项（Fetch 为 `fetchBaseURL` 或 `fetchApiKeyEnv`），就会把该能力固定到其自己的端点（默认 `https://api.deepseek.com/v1/tools`）和密钥（默认 `DEEPSEEK_API_KEY`），且从不发送账号令牌。这些字段只能在 YAML 中设置。没有设置这些 YAML 字段、没有设置 `DEEPSEEK_BASE_URL`、也没有自定义模型基础地址的用户不受影响。
+
+## 迁移
+
+1. 在 `web-deepseek-api` 条目上设置过 `baseURL`、`apiKeyEnv` 或字面 `apiKey` 的用户：对 Search 与 Fetch 分别比较原端点和密钥与路由现在发送的值，即 DeepSeek 模型提供方基础地址的 origin 加 `/v1/tools`，以及该提供方的 `apiKeyEnv`。两者都一致时，删除旧字段。否则把成对字段 `searchBaseURL` 与 `searchApiKeyEnv`（Fetch 为 `fetchBaseURL` 与 `fetchApiKeyEnv`）设为原端点和原密钥引用；即使其中一个原值与路由的值相同，也要两个字段都设置：成对字段中未设置的一项回退到 `https://api.deepseek.com/v1/tools` 或 `DEEPSEEK_API_KEY`，不会继承路由的值。设置过字面 `apiKey` 时，把该值以某个引用存入凭据存储或启动环境，并使用该引用。单独配置的能力从不发送账号令牌。确认：`dsh` 正常启动，且搜索和抓取都到达预期端点，没有凭据错误。
+2. 设置了 `DEEPSEEK_BASE_URL` 或为 DeepSeek 模型提供方设置了自定义基础地址、且该主机不提供 `/v1/tools` 的用户：把同一对字段设为 `https://api.deepseek.com/v1/tools` 和该端点接受的密钥引用。确认：搜索返回结果。

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-default-provider/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The shipped Search default moves from legacy Messages search to the DeepSeek Search API, and the optional Exa and Perplexity search packages are removed."
+---
+
+# Search defaults to the DeepSeek Search API; Exa and Perplexity are removed
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Previously, the shared base composition set `web.searchProvider` to `deepseek-official`: each search was an auxiliary Messages request to `web-search-deepseek`'s endpoint, sending `Perform a web search for the query: <query>` to `deepseek-v4-flash` with a server-side `web_search` tool, billed as model tokens. Now it sets `deepseek-search-api`: each search is one direct request to the DeepSeek Search API, without a model request, and may incur Search API charges instead of model tokens. That request sends `query`, `count`, `need_content: false`, and, unless `web-deepseek-api.sendOriginalQuestion` is `false`, the user's latest prompt cut to 128 characters as `ori_question`. Its credential and endpoint follow the [DeepSeek model route](../web-search-credential-modes/guide.md). Compositions that set `web.searchProvider` themselves see no change, and Fetch still defaults to `http`.
+
+The optional packages `@deepseek-ai/dsh-web-search-exa` (provider `exa`) and `@deepseek-ai/dsh-web-search-perplexity` (provider `perplexity`) are removed. A row naming either package no longer loads, and `searchProvider: exa` or `searchProvider: perplexity` names no provider.
+
+## Migration
+
+1. To keep legacy Messages search, set `searchProvider: deepseek-official` in the `config` of the `@deepseek-ai/dsh-web` row, or select DeepSeek (legacy) in the Web search provider menu on the Web search and fetch settings page. Confirm: that menu shows DeepSeek (legacy), and a search appends a `web/deepseek-search-llm-request` event to the Session log.
+2. Deployments that mounted Exa or Perplexity: delete the `@deepseek-ai/dsh-web-search-exa` or `@deepseek-ai/dsh-web-search-perplexity` row from `cordis.yml` or the profile patch, remove `EXA_API_KEY` or `PERPLEXITY_API_KEY` if nothing else uses it, and set `searchProvider` to `deepseek-search-api` or `deepseek-official`, or delete it to take the default. Confirm: `dsh` starts without a load error for either package, the Web search provider menu shows the chosen provider, and a search returns results.

package/kb/extra/upgrade-guide/v0.2.2-alpha.2/web-search-default-provider/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "交付的 Search 默认值从旧版 Messages 搜索改为 DeepSeek Search API，可选的 Exa 与 Perplexity 搜索包已移除。"
+---
+
+# Search 默认使用 DeepSeek Search API；Exa 与 Perplexity 已移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+过去，共享的基础组合把 `web.searchProvider` 设为 `deepseek-official`：每次搜索都是发往 `web-search-deepseek` 端点的一次辅助 Messages 请求，以 `Perform a web search for the query: <query>` 调用带服务端 `web_search` 工具的 `deepseek-v4-flash`，按模型 token 计费。现在它设为 `deepseek-search-api`：每次搜索是一次直接发往 DeepSeek Search API 的请求，不调用模型，可能产生 Search API 费用而非模型 token 费用。该请求发送 `query`、`count`、`need_content: false`，并且除非 `web-deepseek-api.sendOriginalQuestion` 为 `false`，还会把用户最近一条提示截取前 128 个字符作为 `ori_question` 发送。其凭据和端点跟随 [DeepSeek 模型路由](../web-search-credential-modes/guide.zh.md)。自行设置了 `web.searchProvider` 的组合不受影响，Fetch 仍默认为 `http`。
+
+可选包 `@deepseek-ai/dsh-web-search-exa`（提供方 `exa`）与 `@deepseek-ai/dsh-web-search-perplexity`（提供方 `perplexity`）已移除。指名任一包的条目不再能加载，`searchProvider: exa` 或 `searchProvider: perplexity` 也不再对应任何提供方。
+
+## 迁移
+
+1. 要继续使用旧版 Messages 搜索，在 `@deepseek-ai/dsh-web` 条目的 `config` 中设置 `searchProvider: deepseek-official`，或在「网页搜索与获取」设置页的「网页搜索提供方」菜单中选择 DeepSeek（旧版）。确认：该菜单显示 DeepSeek（旧版），且每次搜索都会向会话日志追加一个 `web/deepseek-search-llm-request` 事件。
+2. 挂载过 Exa 或 Perplexity 的部署：从 `cordis.yml` 或 profile 补丁中删除 `@deepseek-ai/dsh-web-search-exa` 或 `@deepseek-ai/dsh-web-search-perplexity` 条目；若 `EXA_API_KEY` 或 `PERPLEXITY_API_KEY` 不再被其他地方使用，一并移除；再把 `searchProvider` 设为 `deepseek-search-api` 或 `deepseek-official`，或删除该字段以采用默认值。确认：`dsh` 启动时没有这两个包的加载错误，「网页搜索提供方」菜单显示所选提供方，且搜索返回结果。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/chat-process-activity-context/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Chat ProcessActivity gains a context category, and the running activity uses RunningProcessActivity."
+---
+
+# Chat `ProcessActivity` adds `context`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ProcessActivity`, exported from `@deepseek-ai/dsh-client-ui-chat/client`, gains the member `context`. A closed process group whose members are all Context injections reports it as its only category. `ProcessActivitySummary.running` is now typed as the new exported `RunningProcessActivity`, which excludes `context`. This affects extensions that switch exhaustively over `ProcessActivity` or map every member to a label or icon.
+
+## Migration
+
+1. Add a `context` branch wherever code handles every `ProcessActivity` member, for example in a `Record<ProcessActivity, …>` or a `switch` ending in `assertNever`.
+2. Type values read from `summary.running` as `RunningProcessActivity` when they need not cover `context`.
+3. Run the extension's typecheck and confirm it compiles without a missing-member error.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/chat-process-activity-context/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Chat 的 ProcessActivity 新增 context 类别，运行中活动改用 RunningProcessActivity。"
+---
+
+# Chat `ProcessActivity` 新增 `context`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-chat/client` 导出的 `ProcessActivity` 新增成员 `context`。成员全部为上下文注入的已结束过程组以它作为唯一类别。`ProcessActivitySummary.running` 的类型改为新导出的 `RunningProcessActivity`，该类型不含 `context`。对 `ProcessActivity` 做穷尽 switch 或为每个成员映射文案、图标的扩展受影响。
+
+## 迁移
+
+1. 在处理全部 `ProcessActivity` 成员的位置补上 `context` 分支，例如 `Record<ProcessActivity, …>` 或以 `assertNever` 结尾的 `switch`。
+2. 读取 `summary.running` 且无需覆盖 `context` 的值，类型改为 `RunningProcessActivity`。
+3. 运行扩展的类型检查，确认没有缺少成员的编译错误。

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/subagent-names/guide.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "Subagent control and Team task tools address agents by name, list_agents rows change, and subagent catalogs write payload version 3."
+---
+
+# Subagent tools address agents by name
+
+English | [中文](guide.zh.md)
+
+## Change
+
+New subagents have sibling-unique names in their creator's `subagent/catalog`. The root is `lead`; descendant names are paths such as `reviewer/checker`. The [subagent runtime](../../../../packages/subagent/subagent/README.md#agent-names) defines naming rules. Historical children keep their Session ids. Scripts, PTC, SDK callers, and transcripts must adopt these changes:
+
+- `send_message({ agent_id, message })` becomes `send_message({ agent, message })`, and `interrupt_agent({ agent_id })` becomes `interrupt_agent({ agent })`. `agent` accepts a name or a Session id. A call that still passes `agent_id` fails argument validation.
+- `subagent`, `subagent_fork`, and `subagent_oar` accept an optional `name`. They return `started subagent <name>` with result `{ kind: 'activation', name }`.
+- `list_agents` returns `{ name, status, description? }` rows instead of rows with `kind`, `id`, `label`, `parent`, `depth`, and `reason`. Unreadable branches report `corrupt`, `unsupported`, or `unavailable` as `status`. Text rows read `<name> [<status>] — <description>`.
+- Team task results replace `ownerId` with `owner`, the owner's name. `team_task_list` and `team_task_update` accept a name as `owner`. To list tasks without an owner, use `unowned: true` instead of `owner: "unowned"`.
+- Local and parent-delivered external creation write `subagent/catalog` payload version 3. Releases before this one reject catalogs that contain it, so they cannot open Sessions that create subagents after upgrading. See the [persistence acknowledgement](../../../persistence-changes/2026-11-02-subagent-catalog-names.md).
+- `SubagentActivation` has a required `name` field, and `SubagentActivationSpec` accepts an optional `name`.
+
+## Migration
+
+1. In scripts, PTC programs, and SDK calls, rename the `agent_id` argument of `send_message` and `interrupt_agent` to `agent`. Pass the name that `list_agents` or the start receipt reports; a saved Session id still works.
+2. Update parsers of `list_agents` output to read `name`, `status`, and `description`. Only complete named paths encode creators: the prefix before the last `/`, or `lead` without `/`. Unnamed children or ancestors cause Session-id fallback; these rows expose neither creator nor depth.
+3. Update Team task consumers to read `owner` instead of `ownerId`. Host code that calls `ctx.agentTeams` still reads `ownerId`; display `ownerName ?? ownerId`. New assignments persist optional `ownerName`; historical records remain unchanged. Older projections reject named tasks; see the [acknowledgement](../../../persistence-changes/2026-11-02-team-task-owner-names.md).
+4. Read `name` instead of `subagentId` from delegation tool results. Update recorded transcripts or fixtures that contain `agent_id` arguments, `started subagent <Session id>` receipts, identity runtime context text, `Agent <Session id> sent a message` signatures, `Background subagent <Session id>` notices, or the earlier `list_agents` rows. Signatures and notices now use names.
+5. Add `name` when constructing `SubagentActivation` values. Code that reads catalog rows can read the optional `name` field.
+6. Upgrade every process that opens the same Session store before creating subagents. Older releases cannot open Sessions that contain catalog payload version 3.
+7. To confirm the change, start a subagent with `name: "reviewer"` and check that the receipt reads `started subagent reviewer`, that `list_agents` lists `reviewer`, and that `send_message({ agent: "reviewer", message })` succeeds.

package/kb/extra/upgrade-guide/v0.2.2-alpha.3/subagent-names/guide.zh.md

@@ -0,0 +1,29 @@
+---
+kind: upgrade-guide
+description: "Subagent 控制工具和 Team 任务工具按名称寻址 agent，list_agents 行格式改变，subagent 目录写入第 3 版载荷。"
+---
+
+# Subagent 工具按名称寻址 agent
+
+[English](guide.md) | 中文
+
+## 变更
+
+新 subagent（子智能体）在创建者的 `subagent/catalog` 中拥有同级唯一的名称。根为 `lead`；后代名称是 `reviewer/checker` 这样的路径。[subagent 运行时](../../../../packages/subagent/subagent/README.zh.md#agent-names)定义名称规则。升级前创建的子级继续以 Session id 作为名称。脚本、PTC、SDK 调用方和 transcript（文本记录）需要适配以下变更：
+
+- `send_message({ agent_id, message })` 改为 `send_message({ agent, message })`，`interrupt_agent({ agent_id })` 改为 `interrupt_agent({ agent })`。`agent` 接受名称或 Session id。仍传入 `agent_id` 的调用无法通过参数校验。
+- `subagent`、`subagent_fork` 和 `subagent_oar` 接受可选的 `name`。它们返回 `started subagent <name>`，结果为 `{ kind: 'activation', name }`。
+- `list_agents` 返回 `{ name, status, description? }` 行，取代含 `kind`、`id`、`label`、`parent`、`depth` 和 `reason` 的行。不可读分支以 `status` 报告 `corrupt`、`unsupported` 或 `unavailable`。文本行格式为 `<name> [<status>] — <description>`。
+- Team 任务结果以 `owner`（所有者名称）取代 `ownerId`。`team_task_list` 和 `team_task_update` 的 `owner` 接受名称。查询无所有者任务时，用 `unowned: true` 替代 `owner: "unowned"`。
+- 本地创建和父级投递的外部创建写入第 3 版 `subagent/catalog` 载荷。本版本之前的发布会拒绝包含该载荷的目录，因此无法打开升级后创建过 subagent 的 Session。参见[持久化确认记录](../../../persistence-changes/2026-11-02-subagent-catalog-names.zh.md)。
+- `SubagentActivation` 新增必需字段 `name`，`SubagentActivationSpec` 接受可选的 `name`。
+
+## 迁移
+
+1. 在脚本、PTC 程序和 SDK 调用中，将 `send_message` 和 `interrupt_agent` 的 `agent_id` 参数改名为 `agent`。传入 `list_agents` 或启动回执报告的名称；已保存的 Session id 仍可使用。
+2. 更新 `list_agents` 输出的解析器，读取 `name`、`status` 和 `description`。只有完整命名路径编码创建者：最后一个 `/` 之前的前缀，不含 `/` 时为 `lead`。未命名的子级或祖先导致回退到 Session id；这些行既不提供创建者，也不提供深度。
+3. 更新 Team 任务消费方，读取 `owner` 而非 `ownerId`。调用 `ctx.agentTeams` 的 host 代码仍读取 `ownerId`；展示时读取 `ownerName ?? ownerId`。新分配会持久化可选的 `ownerName`，历史记录保持不变。旧投影会拒绝带名称的任务；参见[确认记录](../../../persistence-changes/2026-11-02-team-task-owner-names.zh.md)。
+4. 从委派工具结果读取 `name` 而非 `subagentId`。更新包含 `agent_id` 参数、`started subagent <Session id>` 回执、身份运行时上下文文本、`Agent <Session id> sent a message` 署名、`Background subagent <Session id>` 通知或旧 `list_agents` 行的录制 transcript 或 fixture。署名和通知现在使用名称。
+5. 构造 `SubagentActivation` 值时添加 `name`。读取目录行的代码可读取可选的 `name` 字段。
+6. 在创建 subagent 之前，升级所有打开同一 Session 存储的进程。旧版本无法打开包含第 3 版目录载荷的 Session。
+7. 验证迁移：以 `name: "reviewer"` 启动一个 subagent，确认回执为 `started subagent reviewer`，`list_agents` 列出 `reviewer`，且 `send_message({ agent: "reviewer", message })` 成功。

package/kb/extra/web-styling.md

@@ -20,20 +20,38 @@ Global style sheets belong in `ui-theme/src/styles/`. Component styles live besi
 - Pair font sizes with line heights and use the theme typography variables when an existing role matches.
 - Keep source text, terminal output, and diff lines unwrapped when their component contract requires column preservation; use the shared scrollbar styles rather than component-specific scrollbar selectors.
 - Put presentation in CSS. Inline React styles may pass component-local custom-property values but must not encode theme branches.
-- Preserve keyboard focus visibility and reduced-motion behavior when adding transitions or hover-only controls.
+- A relative `url()` in a plugin stylesheet points to a file in the package's `src/client/assets/`, and the build rewrites it to the [package asset](../packages/client/AGENTS.md#dependency-declaration) URL. `data:`, `#fragment`, `/`-rooted, scheme, and empty `url('')` references stay unchanged, a relative file reference with a fragment or query fails the build, and stylesheets from dependencies are not rewritten.
+- Put `:hover` selectors under `@media (hover: hover)`, independently of viewport width. Keep selected, expanded, pressed, and keyboard-focus styles outside that condition. Without hover, actions remain visible or accessible through an explicit control; pointer handlers ignore touch when opening hover-only previews. Preserve keyboard focus visibility and reduced-motion behavior.
 - 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.
+- Floating panels preserve horizontal anchor alignment when neither vertical side fits. Try vertical window bounds before a fallback that also clears horizontal anchoring; every candidate reserves the window edge and frame margins.
+
 - 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. 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="input-capabilities"></a>
+## Input capabilities
+
+`pointer` and `hover` describe the primary pointing device chosen by the browser; `any-hover` considers every available pointing device. None detects a physical keyboard.
+
+- Use `(pointer: coarse)` for presentation that depends on pointing accuracy, such as touch-sized controls and text fields.
+- Keep CSS hover effects under `(hover: hover)` so a touch-first layout remains usable without hover.
+- JavaScript hover previews use `(any-hover: hover)` when accepting mouse entry and ignore touch entry. A secondary mouse can therefore open a preview even when the touchscreen remains the primary pointer. Enabling all CSS hover styles through `any-hover` would also enable them for touch-generated `:hover` states.
+
+On a mixed-input device, a mouse preview can appear while the primary-pointer CSS hover style stays inactive. Keyboard focus and shortcut hints follow actual keyboard interaction independently of these capability queries; [Menu and input modality](../packages/client/ui-primitives/README.md#input-modality) define the shared behavior.
+
 <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.
 
+## Review the assembled design
+
+Use the [UI review baseline](ui-design-review-cases.md#review-baseline) to combine these material and typography rules with radius, responsive behavior, feedback and artwork guidance across the [entire page or modal](ui-design-review-cases.md#whole-interface-review). Compare all regions and same-role elements within that unit; individually compliant components can still form doubled edges, inconsistent grouping or clipped focus indicators. This document and the theme remain the styling owners.
+
 ## 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 [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

@@ -20,20 +20,38 @@
 - 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
 - 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
 - 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
-- 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
+- 插件样式表中的相对 `url()` 指向本包 `src/client/assets/` 中的文件，构建会将其改写为[包资源](../packages/client/AGENTS.md#dependency-declaration) URL。`data:`、`#fragment`、以 `/` 开头、带 scheme 的引用以及空 `url('')` 引用保持不变，带片段或查询串的相对文件引用会让构建失败，依赖包中的样式表不会被改写。
+- 将 `:hover` 选择器放在 `@media (hover: hover)` 内，不依赖视口宽度。选中、展开、按下和键盘焦点样式保留在该条件之外。无 hover 时，操作保持可见或通过明确控件访问；打开纯悬停预览的指针事件处理忽略触摸。保留清晰可见的键盘焦点和减少动态效果行为。
 - 支持的引擎上，圆角继承 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 的点状下划线。紧凑 Thinking Markdown 保持 tertiary 文字色和默认点状下划线（[紧凑展示](../packages/client/ui-primitives/README.zh.md#rendering-agent-output)）。带文字的锚点另以 ui-primitives 的 `LinkIconMedium` 分类图形（随 `currentColor`）作前置；目的地是已知外部站点时改用该站点自己的标记而非地球；workflow 成员链接与只包图片的锚点不带图形，工具行文件链接保持其灰色点线示能。
 
+<a id="input-capabilities"></a>
+## 输入能力
+
+`pointer` 与 `hover` 描述浏览器选定的主指针，`any-hover` 则考虑所有可用指针。三者都不检测物理键盘。
+
+- `(pointer: coarse)` 用于依赖指针精度的呈现，例如适合触摸的控件和文本框尺寸。
+- CSS 悬停效果保留在 `(hover: hover)` 下，使以触屏为主的布局无需悬停也能使用。
+- JavaScript 悬停预览在接受 mouse 进入事件时使用 `(any-hover: hover)`，并忽略 touch 进入事件。因此，即使触屏仍是主指针，外接鼠标也能打开预览。如果通过 `any-hover` 启用全部 CSS 悬停样式，触摸产生的 `:hover` 状态也会应用这些样式。
+
+混合输入设备上，鼠标预览可以出现，而基于主指针的 CSS 悬停样式保持关闭。键盘焦点和快捷键提示根据实际键盘交互显示，不依赖这些能力查询；共享行为见 [Menu 与输入方式](../packages/client/ui-primitives/README.zh.md#input-modality)。
+
 <a id="corner-radii-and-settings-cards"></a>
 ## 圆角与设置卡片
 
 圆角尺度、组件尺寸映射、正圆与胶囊例外、嵌套 hover，以及设置卡片的底色与描边统一由 [DSH 统一圆角规范](ui-radius.zh.md)定义。
 
+## 审查组装后的设计
+
+按 [UI review 基准](ui-design-review-cases.zh.md#review-baseline)，在[整页或整个弹窗](ui-design-review-cases.zh.md#whole-interface-review)中综合判断材质、字体、圆角、响应式行为、反馈和图案。统一比较这个范围内的所有区域与同角色元素；组件分别合规，组合后仍可能出现双描边、分组不一致或焦点被裁切。本规范与主题继续拥有样式规则。
+
 ## 变更系统
 
 在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[已归档的样式系统 Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) 记录框架依据。