@skzhang/dsh-appearance

Readme

# @skzhang/dsh-appearance

DSH Web 界面的外观设置插件：一个「外观」设置页，管理主题、字体、字号、会话流密度与液态玻璃。

![外观设置：主题](assets/settings-themes.png)

## 功能

### 主题

- **DSH 主题**：DSH 浅色、DSH 深色、DSH 跟随系统。三种模式与 DSH 自带的 `ui-theme.preference` 双向同步——在任一处切换，另一处跟着走。
- **主题预设**：浅色有 GitHub Light、Catppuccin Latte、Ayu Light；深色有 Catppuccin、Dracula、GitHub、Ayu、Everforest、Gruvbox、Linear、Codex。
- 浅色与深色**各自记住**一个选中预设。选择跟随系统时，预设控件隐藏，由系统在这两个已保存的选择之间切换。

预设不是只换背景色：插件从每个预设的 10 个种子色推导整套 DSH token——背景层级、分割线与卡片边框、输入框、菜单、选中与悬浮态、滚动条、代码块、toast/tooltip、侧边栏填充与导航态，共 90 余个。推导用 `color-mix` 做透明度与混色，因此同一套规则在浅色和深色预设上都能保持可读。写入位置与官方主题一致（`body` 层），否则自定义预设会被 body 级 token 覆盖、表现为侧边栏不生效。

### 字体与排版

- **UI 字体 / 代码字体**：填本机已安装的字体名，输入框带候选下拉；候选来自宿主对系统字体目录的扫描（macOS、Windows、Linux 各自的路径）。
- **UI 字号 / 代码字号**：10–24px / 9–24px。
- **字体平滑**：macOS 平滑或浏览器默认，通过 CSS `-webkit-font-smoothing` 生效——只影响网页 CSS 文本，不改变系统级原生控件。
- **会话流密度**：调整会话条目（消息、工具调用、思考等）之间的基础间距，0 为最紧凑。展开的过程容器保持它自己更紧的节奏。
- **工具调用行间距**：只使用自然流布局的 `padding-block` 增加上下内边距，不写固定高度、不参与核心的窗口化测量。

![外观设置：液态玻璃与排版](assets/settings-effects.png)

### 液态玻璃

只作用于页面里**真实存在**的浮层表面：`role="menu"`（右键菜单、下拉与子菜单）和 `role="dialog"[aria-modal=true]`（对话框）。可调模糊、透光与浮层范围（兼容模式 / 浮层增强）。

透光有一个下限：无论滑杆拉到哪，菜单都保持可读。关闭开关时插件会主动清掉 `dsh-desktop-assist` 可能留下的玻璃样式，避免两层半透明叠加。

### 持久化

外观设置通过 DSH 的 settings seam 存进 `settings.yaml`：

- 宿主分区**已有用户层**时，启动直接采用宿主的值；
- 宿主**从未接受过写入**（无用户层）时，保留本地选择并把它补写到宿主——否则每次加载都会被宿主的默认值抹掉；
- 写入失败按指数退避重试，直到分区内容与本地一致；`memory` 模式的页面只依赖 localStorage。

![会话界面](assets/conversation.png)

## 安装

```sh
# 从 npm
dsh plugin --profile web add @skzhang/dsh-appearance

# 或从仓库
dsh plugin --profile web add github:shkzhang/dsh-appearance
```

重启 `dsh web` 或重新打开 Desktop 后生效。装好后在**设置 → 外观**里调整。

插件自带构建好的 `lib/`，安装时不会在你的机器上触发构建，也不需要 `allowBuilds` 授权。

## 配置

插件无需配置，全部设置都在「外观」页里。宿主侧只有一处：`cordis.patch.yml` 往 profile 里插入插件条目。

## 开发

```sh
npm run build   # 由 src/ 生成 lib/
npm test        # node:test，12 项
```

`src/client.js` 是浏览器端的源码，`scripts/build.mjs` 把它包进 DSH 的 module-loader 外壳生成 `lib/client.js`；`src/index.js` 是宿主端，直接复制成 `lib/index.js`。产物不做压缩，便于在浏览器 Sources 面板里直接阅读。

浏览器端还导出 `__internals`（预设表、token 推导、store），让持久化与配色逻辑可以脱离 DOM 用 `node:test` 覆盖。

## 致谢

本插件的主题预设与字体设置功能，在动机上受到两个插件的启发，在此致谢：

- [NoNameLeGo/dsh-catppuccin-theme](https://github.com/NoNameLeGo/dsh-catppuccin-theme)（MIT）——DSH 的主题注册方式；
- [warmwine/dsh-ui-font](https://github.com/warmwine/dsh-ui-font)（MIT）——DSH 的字体设置入口。

这两个插件的设置入口各自独立，用起来需要在多个页面之间切换。本插件把它们收敛到一个页面，并在此之上补了液态玻璃、会话流密度与工具行间距。**实现是重新写的**：上述插件通过 Claude Code 风格的主题键（`promptBorder`、`autoAccept` 等）定义配色，本插件则从种子色推导 90 余个 DSH token，两者的键名与推导方式没有重叠。各主题预设的**色值**来自各自的官方调色板——Catppuccin 的色值属于 Catppuccin 项目（MIT），其余来自对应主题的公开配色。

## 许可证

[MIT](LICENSE)