设置界面统一美化 leogottadothebest/dsh-settings-beautify

dsh-settings-beautify

一套贯穿 DSH 所有设置界面的设计语言。

License: MIT
npm version

它能做什么

DSH 的设置界面由大量插件组合而成，历史上每一页都说着略有不同的排版与表面语言——页面标题 16/18/22px 不一，解释文字 12/13/14px 不一，卡片圆角 8/10/12px 不一，控件各自有各自的高度与焦点样式。

dsh-settings-beautify 把所有设置页面统一到同一套设计语言上：

- 架构：每一页都由相同的三段层级构成——标题 → 解释 → 具体内容（通用设置保持偏好行形式，即同一层级关系的紧凑变体）。
- 排版：所有页面标题一个字号，所有解释一个字号，所有条目标题、条目解释各一个字号——无论页面由哪个插件贡献。
- 表面：统一的卡片圆角/描边/底色、统一的行、控件、焦点环、标签页、徽章与滚动条，全部由 DSH 自身的 --dsw- token 驱动，浅色 / 深色 / 跟随系统主题自然生效。
- 动效：克制的悬停微动效与过渡，尊重 prefers-reduced-motion，可单独关闭。
- 可扩展：任何页面——包括其他插件贡献的页面（例如已归档对话列表）——只需在根节点加一个属性（data-dshb-scan）即可套用同一设计语言，其余交给 DOM 归一化器处理。
- 无界面化：插件不会在设置导航栏添加任何条目——没有自己的设置页。偏好可选、仅存于 localStorage。

插件无需改动 DSH 源码：它观察设置面板，为每个结构角色打上稳定的 data-dshb- 属性（内置类名是构建期哈希，不可依赖），再由作用域样式表在其上应用设计语言。

覆盖范围

| 界面 | 内置支持 |
| 设置外壳（导航栏、头部、关闭、滚动条） | ✅ |
| 通用 General —— 每一条偏好行（语言、外观、字号、回车行为、智能体预设、权限预设等） | ✅ |
| 模型 Models | ✅ |
| 智能体预设 Agent presets | ✅ |
| 插件 Plugins（标签页、卡片、配置字段） | ✅ |
| 插件市场 Plugin market（已安装清单页） | ✅ |
| 桌面 Desktop（配置文件、网络、通知） | ✅ |
| 任何在根节点添加 data-dshb-scan 的第三方页面（例如已归档对话页） | ✅ |

安装

从插件市场

dsh-settings-beautify 遵循 DSH Community Market 的包规范（dsh.bundle.patch + dsh.client 清单），可从市场安装，或使用：

dsh plugin --profile add dsh-settings-beautify

手动安装（开发）

pnpm add dsh-settings-beautify # 安装到当前 Profile 的包集合
并通过 Profile patch 声明 bundle 入口，例如：
- insert:
- id: dsh-settings-beautify
name: dsh-settings-beautify

安装后重启 DSH Desktop（或刷新 Web 窗口）即自动生效——设置导航栏不会新增任何条目。

偏好（无界面化）

插件没有自己的设置页。偏好从浏览器 localStorage 的 dsh-settings-beautify:prefs 键读取：

| 键 | 取值 | 效果 |
| enabled | true / false | 应用设计语言，或恢复 DSH 原始外观。 |
| density | compact / default / comfortable | 行与列表间距。 |
| motion | true / false | 卡片悬停微动效。prefers-reduced-motion 始终优先。 |

默认值：{"enabled": true, "density": "default", "motion": true}。如需调整，在浏览器控制台执行：

window.DSHB.setPrefs({ density: "compact" }) // 或 { enabled: false }、{ motion: false }

不触碰任何主机文件或设置命名空间。

设计语言

完整规范——token、层级、间距/圆角/动效刻度，以及 data-dshb- 属性契约——见 docs/DESIGN.zh.md。速览：

| 角色 | 字体 | 颜色 |
| 页面标题 | 18px / 600 / 26px | --dsw-alias-label-primary |
| 页面解释 | 13px / 400 / 20px | --dsw-alias-label-tertiary |
| 组标题 | 14px / 600 / 22px | --dsw-alias-label-primary |
| 条目标题 | 14px / 500 / 22px | --dsw-alias-label-primary |
| 条目解释 | 13px / 400 / 20px | --dsw-alias-label-tertiary |
| 正文 | 14px / 400 / 22px | --dsw-alias-label-primary |
| 辅助文字 | 12px / 400 / 18px | --dsw-alias-label-tertiary |

卡片：12px 圆角 · --dsw-alias-border-l2 · --dsw-alias-bg-layer-3（相对面板抬升）。控件：8px 圆角、36px 最小高度、品牌色焦点环。标题与下方注释小字之间的距离在所有被覆盖的页面上统一为 4px（--dshb-gap-title-desc，与 DSH 行内一致）。半径等均以 --dshb- token 化，未来版本可平滑提供其他外观方案。

为其他插件页面接入

DOM 归一化器自动覆盖内置页面。对于你自己插件的页面，二选一：

1. 在页面根节点添加 data-dshb-scan（被托管在设置对话框内的第三方节同样适用）——归一化器会用同样的标题/解释/卡片/行/控件规则泛化处理，标题 → 注释间距也会统一为 4px；或
2. 直接使用属性（data-dshb-page-title、data-dshb-item-title、data-dshb-card 等）获得完全控制。

见扩展契约。

设计说明

插件刻意保持无界面化：只重绘设置界面本身。如果你更希望有一个可见的控制页，那是一个很小的后续改动——提个 issue，可以在偏好开关后面加上。

开发

pnpm install
pnpm check # 语法检查
pnpm test # DOM 归一化器的 jsdom 测试（91 条断言）
pnpm sync-styles # 由 lib/client.js 重新生成 lib/styles/settings.css

测试套件在 jsdom 中重建真实 DSH 设置 DOM（通用条目、模型卡片、插件标签页/字段、桌面分组、一个接入的第三方页面），并断言完整的 data-dshb-* 标记契约。

兼容性

- DSH Desktop 2.x（内置 Web UI）。当前适配至 2.0.10：设置外壳/行/卡片契约与 2.0.5 一致，插件市场页与桌面设置页在 2.0.10 重构后已按新结构刷新（市场卡片标题→来源小字、分区标题→说明均为 4px；桌面设置页标题/分组/选项说明同样归一到 4px）。
- 若设置界面整体回到未美化状态，先检查同一 Profile 里的其他插件是否仍在启动时使用被新版移除的宿主 API（例如 @deepseek-ai/dsh-typert-protocol 自 0.1.2-rc.1 起不再导出 TypertRemoteFailure）——单个插件导入失败会让整棵插件树无法加载，beautify 也会随之不生效。归一化器是防御性的：无法识别的部分一律保持原样。
- 样式表只在设置面板作用域内生效；设置之外的界面不会被重绘。

安全

无网络请求、无主机 API、无文件读写、无远程代码。偏好仅存于 localStorage。见 SECURITY.zh.md。

许可证

MIT —— 见 LICENSE。