dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-rc.2/python-ptc-removal/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Python PTC runtime packages, external providers, SDK renderers and Python-specific binding APIs are removed; migrate to TypeScript PTC."
+---
+
+# Python PTC removal
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-experimental-ptc-runtime-python` is no longer published or included in this repository. Custom compositions that select it must migrate to [`@deepseek-ai/dsh-ptc-runtime-node`](../../../../packages/ptc-runtime/ptc-runtime-node/README.md). Shipped profiles already select the Node provider. `dsh-tool-executor-ptc` also removes support for external `PtcRuntime` providers reporting `language: 'python'`: prompt assembly or execution through the selected executor, or creation of a `/run-code` tool with a non-TypeScript provider, fails with `ToolContextUnavailableError` / `TOOL_CONTEXT_UNAVAILABLE`. The package no longer exports `jsonSchemaToPy` or `renderToolsSdkPy`.
+
+## Migration
+
+1. In the `cordis.yml` or profile patch that selects the Python provider, replace that row's `name` with `@deepseek-ai/dsh-ptc-runtime-node`. Remove its Python runtime `config`; configure Node limits separately when needed. Node also requires `fs` and `subprocess` alongside `sandbox` and `sandboxPolicy`. Reuse the existing providers; for a local composition missing them, mount `@deepseek-ai/dsh-fs-local` and `@deepseek-ai/dsh-subprocess-local` in the same execution world.
+2. Replace any external Python PTC provider and remove imports of `jsonSchemaToPy` and `renderToolsSdkPy`. Use the TypeScript `renderToolsSdk` API where SDK rendering is needed. `dsh-ptc-runtime` replaces `PORTABLE_RESERVED_WORDS` with `RESERVED_BINDING_WORDS` and removes `DUNDER_MEMBER`; remove Python-specific binding-name checks.
+3. Rewrite Python `run_code` programs as TypeScript. For fresh execution per call, set `config.executionMode: per-call`; see the [Node runtime configuration](../../../../packages/ptc-runtime/ptc-runtime-node/README.md).
+4. Re-enable `workflow-ptc`, `tool-workflow`, and any previously enabled `tool-ralph` rows that were disabled solely for the Python provider, if those workflows are still wanted.
+5. Run the affected profile with `--dump-config` and confirm its PTC runtime row selects `@deepseek-ai/dsh-ptc-runtime-node` with no Python provider row remaining. Run a PTC task and confirm that its TypeScript program completes.
+
+The Harness Python client in `python/sdk`, its packaged runtime wheel, and Python environments used by other tools are unaffected. Existing Session logs retain their recorded output.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/python-ptc-removal/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Python PTC 运行时包、外部提供方、SDK 渲染器和 Python 专属绑定 API 均已移除，须迁移到 TypeScript PTC。"
+---
+
+# 移除 Python PTC
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-experimental-ptc-runtime-python` 不再发布，也不再包含于本仓库。选择该包的自定义组合必须迁移到 [`@deepseek-ai/dsh-ptc-runtime-node`](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md)。已发布 profile 已经选择 Node 提供方。`dsh-tool-executor-ptc` 也移除了对报告 `language: 'python'` 的外部 `PtcRuntime` 提供方的支持：通过已选中的执行器组装提示词、执行程序，或使用非 TypeScript 提供方创建 `/run-code` 工具，会以 `ToolContextUnavailableError` / `TOOL_CONTEXT_UNAVAILABLE` 失败。该包不再导出 `jsonSchemaToPy` 或 `renderToolsSdkPy`。
+
+## 迁移
+
+1. 在选择 Python 提供方的 `cordis.yml` 或 profile patch 中，将对应行的 `name` 替换为 `@deepseek-ai/dsh-ptc-runtime-node`。移除该行的 Python 运行时 `config`；如有需要，单独配置 Node 限制。除了 `sandbox` 和 `sandboxPolicy`，Node 还需要 `fs` 与 `subprocess`。复用已有提供方；本地组合若缺少它们，在同一执行环境中挂载 `@deepseek-ai/dsh-fs-local` 与 `@deepseek-ai/dsh-subprocess-local`。
+2. 替换任何外部 Python PTC 提供方，移除 `jsonSchemaToPy` 与 `renderToolsSdkPy` 导入。需要渲染 SDK 时使用 TypeScript 的 `renderToolsSdk` API。`dsh-ptc-runtime` 将 `PORTABLE_RESERVED_WORDS` 替换为 `RESERVED_BINDING_WORDS`，并移除 `DUNDER_MEMBER`；删除 Python 专属的绑定命名检查。
+3. 将 Python `run_code` 程序改写为 TypeScript。如需每次调用都使用全新执行环境，设置 `config.executionMode: per-call`；参见 [Node 运行时配置](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md)。
+4. 如果仍需使用相关工作流，重新启用仅因 Python 提供方而禁用的 `workflow-ptc`、`tool-workflow`，以及此前启用过的 `tool-ralph` 行。
+5. 为受影响的 profile 添加 `--dump-config` 并运行，确认其 PTC 运行时行选择 `@deepseek-ai/dsh-ptc-runtime-node`，且不再保留 Python 提供方行。运行一个 PTC 任务并确认其 TypeScript 程序完成。
+
+`python/sdk` 中的 Harness Python 客户端、其打包运行时 wheel，以及其他工具使用的 Python 环境均不受影响。已有 Session 日志保留其记录的输出。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/session-status-package/guide.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Session status types and the useSessionStatus hook move to @deepseek-ai/dsh-client-ui-session-status/client, ctx.uiSession.sessionStatus becomes an injected service, and completion reminders follow Host reading records."
+---
+
+# Session status moves to `@deepseek-ai/dsh-client-ui-session-status` and completion reminders follow Host reading records
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-session/client` no longer exports `SessionStatus`, `SessionStatusSnapshot`, or `UseSessionStatus`, and ui-session no longer declares or provides the `useSessionStatus` root hook. Both now belong to the Client plugin [`@deepseek-ai/dsh-client-ui-session-status`](../../../../packages/client/ui-session-status/README.md), one Web bundle row with a Host reading service and the Client table. A Client composition that loads ui-session without ui-session-status has no status table and no `useSessionStatus` hook.
+
+`ctx.uiSession.sessionStatus` is now the separate `uiSession.sessionStatus` service. Reading it through `ctx.uiSession.sessionStatus.getSnapshot()` and `subscribe()` keeps its form, but a plugin that reads it without injecting `'uiSession.sessionStatus'` fails with `cannot get property "uiSession.sessionStatus" without inject`. Components of a plugin without that injection fail with `useSessionStatus is not a function` after the table unloads. `ctx.uiSession` now has the type `UiSessionService`, which extends the unchanged `UiSession` class with members such as `sessionStatus`; a value annotated as `UiSession` does not show `sessionStatus`.
+
+Pending interactions stay in ui-session: `ctx.uiSession.registerPendingInteraction(precedence)`, `SessionPendingInteractionBase`, `SessionPendingInteractionMap`, `SessionPendingInteraction`, and `PendingInteractionPublisher` keep their names, behavior, and `@deepseek-ai/dsh-client-ui-session/client` export. Extensions of `SessionPendingInteractionMap` keep targeting that module. ui-session additionally exposes the read-only `ctx.uiSession.pendingInteractions` source.
+
+`completionUnread` follows Host-memory reading records shared by every Client and changes through Host completions, explicit marks, and visible main-view acknowledgement; only a main-view switch, including a reload, clears a manual mark. The open viewed Session hides its unacknowledged turn; earlier history reads as read. The required `completionFailed` field marks an unread Session whose latest turn failed. The new `mark(sessionId, unread)` rejects until `readingReady` reports the Host baseline.
+
+This affects Client plugins and tests that import the three status types, construct `SessionStatus` values, render components that read `useSessionStatus`, or read `ctx.uiSession.sessionStatus`.
+
+## Migration
+
+1. Import `SessionStatus`, `SessionStatusSnapshot`, and `UseSessionStatus` from `@deepseek-ai/dsh-client-ui-session-status/client`. A package that only imports these types, for example in tests, declares `@deepseek-ai/dsh-client-ui-session-status` in `devDependencies` and its TypeScript project references.
+2. A package whose components call `useSessionStatus` also lists the package in `dsh.client.inject`, adds `import type {} from '@deepseek-ai/dsh-client-ui-session-status/client'` when it imports none of the types, and adds `'uiSession.sessionStatus'` to the Cordis `inject` of the plugin that registers them.
+3. Each plugin that reads `ctx.uiSession.sessionStatus` adds `'uiSession.sessionStatus'` to `inject`; one that needs only the effective pending request may subscribe to `ctx.uiSession.pendingInteractions` instead.
+4. Where code passes `ctx.uiSession` through a parameter or field annotated as `UiSession` and then reads `sessionStatus`, annotate it as `UiSessionService` from `@deepseek-ai/dsh-client-ui-session/client`.
+5. Leave `registerPendingInteraction` calls and `declare module '@deepseek-ai/dsh-client-ui-session/client'` augmentations of `SessionPendingInteractionMap` unchanged.
+6. Add `completionFailed` to `SessionStatus` values in tests and fixtures, and script Host reading records to drive `completionUnread`.
+7. A custom composition that loads `@deepseek-ai/dsh-client-ui-session` also loads `@deepseek-ai/dsh-client-ui-session-status` as a plugin row, so its Host reading service and `useSessionStatus` are available.
+8. Confirm that the plugin type-checks, that a Session row still shows its running or waiting indicator, and that a Session finishing outside the main view shows an unread reminder.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/session-status-package/guide.zh.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "会话状态类型与 useSessionStatus hook 移到 @deepseek-ai/dsh-client-ui-session-status/client，ctx.uiSession.sessionStatus 改为需要注入的服务，完成提醒改为跟随宿主阅读记录。"
+---
+
+# 会话状态移到 `@deepseek-ai/dsh-client-ui-session-status`，完成提醒改由宿主阅读记录提供
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-session/client` 不再导出 `SessionStatus`、`SessionStatusSnapshot` 或 `UseSessionStatus`，ui-session 也不再声明或提供根 hook `useSessionStatus`。它们现在属于 Client 插件 [`@deepseek-ai/dsh-client-ui-session-status`](../../../../packages/client/ui-session-status/README.zh.md)，即 Web bundle 中同时提供宿主阅读服务和前端状态表的一行。只加载 ui-session、不加载 ui-session-status 的 Client 组合没有状态表，也没有 `useSessionStatus` hook。
+
+`ctx.uiSession.sessionStatus` 现在是独立的 `uiSession.sessionStatus` 服务。通过 `ctx.uiSession.sessionStatus.getSnapshot()` 和 `subscribe()` 读取的写法不变，但未注入 `'uiSession.sessionStatus'` 就读取它的插件会报错 `cannot get property "uiSession.sessionStatus" without inject`。未注入该服务的插件，其组件会在状态表卸载后报错 `useSessionStatus is not a function`。`ctx.uiSession` 的类型改为 `UiSessionService`，它在不变的 `UiSession` class 之上加入 `sessionStatus` 等成员；标注为 `UiSession` 的值看不到 `sessionStatus`。
+
+待交互仍归 ui-session：`ctx.uiSession.registerPendingInteraction(precedence)`、`SessionPendingInteractionBase`、`SessionPendingInteractionMap`、`SessionPendingInteraction` 和 `PendingInteractionPublisher` 的名称、行为以及从 `@deepseek-ai/dsh-client-ui-session/client` 的导出都不变。扩展 `SessionPendingInteractionMap` 的声明继续指向该模块。ui-session 另外提供只读的 `ctx.uiSession.pendingInteractions` 数据源。
+
+`completionUnread` 跟随宿主内存中、由所有前端共享的阅读记录，因宿主完成轮次、主动标记和可见主视图的确认而变化；只有主视图切换到该会话（包括刷新后恢复）会自动清除手动标记。正在查看且已打开的会话不显示尚未确认的轮次；宿主启动前已有的历史按已读处理。新增的必填字段 `completionFailed` 标记最近一轮失败的未读会话。新增的 `mark(sessionId, unread)` 在 `readingReady` 报告取得宿主基线之前会拒绝。
+
+受影响的是导入这三个状态类型、构造 `SessionStatus` 值、渲染读取 `useSessionStatus` 的组件，或读取 `ctx.uiSession.sessionStatus` 的 Client 插件和测试。
+
+## 迁移
+
+1. 从 `@deepseek-ai/dsh-client-ui-session-status/client` 导入 `SessionStatus`、`SessionStatusSnapshot` 和 `UseSessionStatus`。只导入这些类型（例如只在测试中导入）的包，在 `devDependencies` 和 TypeScript 项目引用中声明 `@deepseek-ai/dsh-client-ui-session-status`。
+2. 组件调用 `useSessionStatus` 的包，另外在 `dsh.client.inject` 中列出该包；不导入任何上述类型时加入 `import type {} from '@deepseek-ai/dsh-client-ui-session-status/client'`；并在注册这些组件的插件的 Cordis `inject` 中加入 `'uiSession.sessionStatus'`。
+3. 每个读取 `ctx.uiSession.sessionStatus` 的插件把 `'uiSession.sessionStatus'` 加入 `inject`；只需要生效待交互请求的插件，可以改为订阅 `ctx.uiSession.pendingInteractions`。
+4. 代码把 `ctx.uiSession` 传给标注为 `UiSession` 的参数或字段、之后又读取 `sessionStatus` 时，把标注改为 `@deepseek-ai/dsh-client-ui-session/client` 的 `UiSessionService`。
+5. `registerPendingInteraction` 调用和对 `SessionPendingInteractionMap` 的 `declare module '@deepseek-ai/dsh-client-ui-session/client'` 扩展保持不变。
+6. 在测试和 fixture 的 `SessionStatus` 值中加入 `completionFailed`，并编排宿主阅读记录来驱动 `completionUnread`。
+7. 加载 `@deepseek-ai/dsh-client-ui-session` 的自定义组合同时以插件行加载 `@deepseek-ai/dsh-client-ui-session-status`，使其宿主阅读服务和 `useSessionStatus` 可用。
+8. 确认插件通过类型检查、会话行仍显示运行或等待标记，并且在主视图之外结束的会话显示未读提醒。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shared-search-filter/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "ui-primitives no longer exports rankByName, and popupSelect commands no longer accept searchMode."
+---
+
+# Shared search filter replaces rankByName and searchMode
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-primitives` exported `rankByName(items, query)`, which ranked items by an ordered subsequence of `name` or `label`. It is removed. `@deepseek-ai/dsh-client-ui-commands` accepted `searchMode: 'substring' | 'fuzzy-label'` on a `popupSelect` command spec and exported the `PopupSearchMode` type; both are removed. Every popup now filters its options one way: labels match fuzzily and details match as substrings, ranked within each group. The shared search is [`TextSearchIndex`](../../../../packages/util/text-search/README.md) in `@deepseek-ai/dsh-util-text-search`. Plugin authors who import `rankByName`, or who set `searchMode` or import `PopupSearchMode`, are affected.
+
+## Migration
+
+1. Replace `rankByName(items, query)` with a `TextSearchIndex` imported from `@deepseek-ai/dsh-util-text-search`: build `new TextSearchIndex(items, item => ({ fuzzy: [item.name, item.label] }))` when the list changes, and call `index.search(query)` per query. Add that package to the plugin's `devDependencies` for a Client plugin or `dependencies` for a Host plugin. Put descriptions or other long text in `substring`, and pass every language of a `LocalizedText` through `localizedValues`.
+2. Delete `searchMode` from each `popupSelect` spec and remove any `PopupSearchMode` import.
+3. Confirm the plugin typechecks, and that typing part of an option label in its popup still finds that option.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shared-search-filter/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "ui-primitives 不再导出 rankByName，popupSelect 命令不再接受 searchMode。"
+---
+
+# 共享搜索过滤器取代 rankByName 和 searchMode
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-primitives` 曾导出 `rankByName(items, query)`，它按 `name` 或 `label` 的有序子序列对条目排序。该函数已移除。`@deepseek-ai/dsh-client-ui-commands` 曾在 `popupSelect` 命令规格上接受 `searchMode: 'substring' | 'fuzzy-label'`，并导出 `PopupSearchMode` 类型；两者均已移除。现在每个弹窗都用同一种方式过滤选项：标签模糊匹配，详情按子串匹配，选项在各自分组内排序。共享搜索是 `@deepseek-ai/dsh-util-text-search` 中的 [`TextSearchIndex`](../../../../packages/util/text-search/README.zh.md)。受影响的是导入 `rankByName`、设置 `searchMode` 或导入 `PopupSearchMode` 的插件作者。
+
+## 迁移
+
+1. 把 `rankByName(items, query)` 替换为从 `@deepseek-ai/dsh-util-text-search` 导入的 `TextSearchIndex`：列表变化时构建 `new TextSearchIndex(items, item => ({ fuzzy: [item.name, item.label] }))`，每次查询时调用 `index.search(query)`。把该包加入插件的依赖：Client 插件加入 `devDependencies`，Host 插件加入 `dependencies`。把描述或其他长文本放进 `substring`，并通过 `localizedValues` 传入 `LocalizedText` 的所有语言。
+2. 从每个 `popupSelect` 规格中删除 `searchMode`，并移除所有 `PopupSearchMode` 导入。
+3. 确认插件通过类型检查，并确认在其弹窗中键入选项标签的一部分仍能找到该选项。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shell-fs-tool-error-codes/guide.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "bash and pwsh report unadvertised sandbox_permissions and run_in_background as ToolArgsError, JOB_BACKGROUND_DISABLED is removed, and read_image reports MODEL_DOES_NOT_SUPPORT_IMAGES instead of IMAGE_UNSUPPORTED_MODEL."
+---
+
+# Shell and read_image failures use consolidated error codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Three `tool/result` error identities recorded by v0.2.2-rc.2 change:
+
+| Failure | v0.2.2-rc.2 | Now |
+| --- | --- | --- |
+| `bash` or `pwsh` receives `sandbox_permissions` and `justification` in a composition without a sandboxing executor | `SandboxEscalationError` / `SANDBOX_ESCALATION_UNAVAILABLE` | `ToolArgsError` / `INVALID_ARGS` |
+| `bash` or `pwsh` receives `run_in_background: true` with `enableRunInBackground: false` | `JobError` / `JOB_BACKGROUND_DISABLED` | `ToolArgsError` / `INVALID_ARGS` |
+| `read_image` runs on a model route without image input | `ImageInputError` / `IMAGE_UNSUPPORTED_MODEL` | `ImageInputError` / `MODEL_DOES_NOT_SUPPORT_IMAGES` |
+
+In both shell cases the schema does not advertise the rejected argument, so the model's fix is to drop it. When only one of `sandbox_permissions` and `justification` reaches `bash`, `pwsh`, `write`, `edit`, or `apply_patch` without a sandboxing backend, the call previously failed the pairing check with `SandboxEscalationError` / `SANDBOX_ESCALATION_INVALID_ARGUMENT`; it now reports `INVALID_ARGS` as well. These calls are rejected before any approval request.
+
+The shell messages now start with `invalid arguments: `, and the escalation message names both fields: `invalid arguments: sandbox_permissions and justification are not available in this composition (no sandboxing executor to escalate)`. `SANDBOX_ESCALATION_UNAVAILABLE` keeps its meaning for compositions that have a sandboxing executor but no approval service, calling Agent, or approval channel.
+
+`JOB_BACKGROUND_DISABLED` is removed from `JOB_ERROR_CODES` and the `JobErrorCode` type in `@deepseek-ai/dsh-jobs`. `ImageInputErrorCode` in `@deepseek-ai/dsh-tool-fs` replaces `IMAGE_UNSUPPORTED_MODEL` with `MODEL_DOES_NOT_SUPPORT_IMAGES`, the value subagent attachments and Session attachment rejections already use.
+
+## Migration
+
+1. In analytics or retry rules that read `tool/result` `error`, treat v0.2.2-rc.2 `JOB_BACKGROUND_DISABLED` results as `INVALID_ARGS` and `IMAGE_UNSUPPORTED_MODEL` as `MODEL_DOES_NOT_SUPPORT_IMAGES`. For `SANDBOX_ESCALATION_UNAVAILABLE`, `error` alone does not identify the shell case: treat a v0.2.2-rc.2 `bash` or `pwsh` result as `INVALID_ARGS` only when its message contains `no sandboxing executor to escalate`, and keep every other `SANDBOX_ESCALATION_UNAVAILABLE` result unchanged. Session logs keep the values they were written with.
+2. Replace TypeScript references to `'JOB_BACKGROUND_DISABLED'` or `'IMAGE_UNSUPPORTED_MODEL'`; `pnpm run typecheck` reports any that remain.
+3. Update text matchers that expect the earlier shell messages, which had no `invalid arguments: ` prefix and named only `sandbox_permissions`.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shell-fs-tool-error-codes/guide.zh.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "bash 与 pwsh 把 schema 未公开的 sandbox_permissions 与 run_in_background 报为 ToolArgsError，删除 JOB_BACKGROUND_DISABLED，read_image 改报 MODEL_DOES_NOT_SUPPORT_IMAGES 而非 IMAGE_UNSUPPORTED_MODEL。"
+---
+
+# Shell 与 read_image 的失败改用统一的错误 code
+
+[English](guide.md) | 中文
+
+## 变更
+
+v0.2.2-rc.2 记录的三种 `tool/result` 错误标识发生变化：
+
+| 失败 | v0.2.2-rc.2 | 现在 |
+| --- | --- | --- |
+| 在没有沙箱执行器的组合中，`bash` 或 `pwsh` 收到 `sandbox_permissions` 与 `justification` | `SandboxEscalationError` / `SANDBOX_ESCALATION_UNAVAILABLE` | `ToolArgsError` / `INVALID_ARGS` |
+| `enableRunInBackground: false` 时，`bash` 或 `pwsh` 收到 `run_in_background: true` | `JobError` / `JOB_BACKGROUND_DISABLED` | `ToolArgsError` / `INVALID_ARGS` |
+| `read_image` 运行在不支持图像输入的模型路由上 | `ImageInputError` / `IMAGE_UNSUPPORTED_MODEL` | `ImageInputError` / `MODEL_DOES_NOT_SUPPORT_IMAGES` |
+
+两个 shell 情形中，被拒绝的参数都没有出现在 schema 里，模型的修正办法是去掉它。在没有沙箱后端时，若 `bash`、`pwsh`、`write`、`edit` 或 `apply_patch` 只收到 `sandbox_permissions` 与 `justification` 之一，此前会在配对校验中以 `SandboxEscalationError` / `SANDBOX_ESCALATION_INVALID_ARGUMENT` 失败；现在同样报 `INVALID_ARGS`。这些调用会在任何审批请求之前被拒绝。
+
+shell 消息现在以 `invalid arguments: ` 开头，升权消息同时点名两个字段：`invalid arguments: sandbox_permissions and justification are not available in this composition (no sandboxing executor to escalate)`。对于有沙箱执行器、但缺少审批服务、调用方 Agent 或审批通道的组合，`SANDBOX_ESCALATION_UNAVAILABLE` 的含义不变。
+
+`@deepseek-ai/dsh-jobs` 的 `JOB_ERROR_CODES` 与 `JobErrorCode` 类型删除了 `JOB_BACKGROUND_DISABLED`。`@deepseek-ai/dsh-tool-fs` 的 `ImageInputErrorCode` 用 `MODEL_DOES_NOT_SUPPORT_IMAGES` 替换 `IMAGE_UNSUPPORTED_MODEL`，子 agent 附件与 Session 附件拒绝已在使用这个值。
+
+## 迁移
+
+1. 读取 `tool/result` `error` 的统计或重试规则中，把 v0.2.2-rc.2 的 `JOB_BACKGROUND_DISABLED` 结果视为 `INVALID_ARGS`，把 `IMAGE_UNSUPPORTED_MODEL` 视为 `MODEL_DOES_NOT_SUPPORT_IMAGES`。仅凭 `error` 无法从 `SANDBOX_ESCALATION_UNAVAILABLE` 中分出 shell 情形：只有 v0.2.2-rc.2 的 `bash` 或 `pwsh` 结果的消息含 `no sandboxing executor to escalate` 时，才视为 `INVALID_ARGS`；其余 `SANDBOX_ESCALATION_UNAVAILABLE` 结果保持原义。Session 日志保留写入时的值。
+2. 替换 TypeScript 中对 `'JOB_BACKGROUND_DISABLED'` 或 `'IMAGE_UNSUPPORTED_MODEL'` 的引用；`pnpm run typecheck` 会报出剩余的引用。
+3. 更新那些期望旧 shell 消息的文本匹配：旧消息没有 `invalid arguments: ` 前缀，且只点名 `sandbox_permissions`。

package/kb/extra/web-styling.md

@@ -1,39 +1,57 @@
-# Web UI style reference
-
-English | [中文](web-styling.zh.md)
-
-This reference defines styling ownership and component rules for browser client packages. The current token values live in [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/); this document does not duplicate that generated-by-source inventory.
-
-## Ownership
-
-[`ui-theme`](../packages/client/ui-theme/README.md) owns the `--dsw-*` static scale, semantic aliases, typography, motion, gradients, shadows, scrollbar styles, and light/dark preference. [`ui-layout`](../packages/client/ui-layout/README.md) applies the resolved theme snapshot to the document. Feature packages consume semantic aliases and do not define another global theme.
-
-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.
-- 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.
-- 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. 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 [archived styling-system Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) records framework rationale.
+# Web UI style reference
+
+English | [中文](web-styling.zh.md)
+
+This reference defines styling ownership and component rules for browser client packages. The current token values live in [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/); this document does not duplicate that generated-by-source inventory.
+
+## Ownership
+
+[`ui-theme`](../packages/client/ui-theme/README.md) owns the `--dsw-*` static scale, semantic aliases, typography, motion, gradients, shadows, scrollbar styles, and light/dark preference. [`ui-layout`](../packages/client/ui-layout/README.md) applies the resolved theme snapshot to the document. Feature packages consume semantic aliases and do not define another global theme.
+
+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. The ui-theme color-token spec rejects static palette references and hex, color-function, `white`, and `black` literals in feature stylesheets and static palette references in feature scripts; `box-shadow` values, mask properties, alpha-0 literals, and its listed artwork and pre-theme files are exempt.
+- Keep theme selectors out of feature component CSS. Light/dark overrides belong to the theme owner.
+- 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.
+- 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

@@ -1,39 +1,57 @@
-# Web UI 样式参考
-
-[English](web-styling.md) | 中文
-
-本文规定浏览器客户端包的样式职责归属与组件规则。当前 token 值位于 [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/)；本文不重复这份由源码生成的清单。
-
-## 职责归属
-
-[`ui-theme`](../packages/client/ui-theme/README.zh.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.zh.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。
-
-全局样式表归 `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 不得包含主题选择器。明暗主题覆盖属于主题所有方。
-- 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
-- 当组件约定要求保留列结构时，源码文本、终端输出和 diff 行不得换行；使用共享滚动条样式，不得定义组件专用滚动条选择器。
-- 呈现规则写在 CSS 中。React 内联样式可以传递组件局部自定义属性值，但不得编码主题分支。
-- 添加过渡动画或仅悬停可见的控件时，保留清晰可见的键盘焦点和减少动态效果行为。
-- 支持的引擎上，圆角继承 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="corner-radii-and-settings-cards"></a>
-## 圆角与设置卡片
-
-圆角尺度、组件尺寸映射、正圆与胶囊例外、嵌套 hover，以及设置卡片的底色与描边统一由 [DSH 统一圆角规范](ui-radius.zh.md)定义。
-
-## 变更系统
-
-在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[已归档的样式系统 Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) 记录框架依据。
+# Web UI 样式参考
+
+[English](web-styling.md) | 中文
+
+本文规定浏览器客户端包的样式职责归属与组件规则。当前 token 值位于 [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/)；本文不重复这份由源码生成的清单。
+
+## 职责归属
+
+[`ui-theme`](../packages/client/ui-theme/README.zh.md) 负责 `--dsw-*` 静态色阶、语义别名、排版、动效、渐变、阴影、滚动条样式以及明暗主题偏好。[`ui-layout`](../packages/client/ui-layout/README.zh.md) 将解析后的主题快照应用到文档。功能包使用语义别名，不得另行定义全局主题。
+
+全局样式表归 `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。不得复制静态色板值或在其中写入颜色字面量。ui-theme 的 color-token spec 拒绝功能样式表中的静态色板引用与十六进制、颜色函数、`white` 和 `black` 字面量，以及功能脚本中的静态色板引用；`box-shadow` 值、遮罩属性、alpha 为 0 的字面量，以及其列出的插图和主题加载前文件不受此限制。
+- 功能组件 CSS 不得包含主题选择器。明暗主题覆盖属于主题所有方。
+- 字体大小必须与行高配对；已有角色匹配时使用主题排版变量。
+- 当组件约定要求保留列结构时，源码文本、终端输出和 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) 记录框架依据。