界面定制工坊 yoli-mi/dsh-client-ui-custom

Dsh-Client-UI-Custom

Awesome DSH Plugin

中文 · English

简介

Dsh-client-ui-custom 是一个纯前端插件，为用户提供浮动历史记录条、用户消息 md 渲染、外观调试、插件市场、快捷键、用量统计和动效功能。

- 修改了通用设置项 —— 在「设置 → 通用」里新增历史记录条（位置、数量）和用户消息 Markdown 渲染开关；
- 修改了插件项 —— 在「设置 → 插件」里新增「插件市场」；
- 新增了四个设置页 —— 「外观」「快捷键」「用量统计」「动效」。

所有功能默认关闭，不配置时保持与原生界面一致，全程零 shell 改动。

宣传视频

▶ 点击观看插件宣传视频（B 站）

功能选择（按需安装）

插件由七个相互独立的功能模块组成：appearance（外观）、shortcuts（快捷键）、 usage（用量统计）、history（历史记录条）、markdown（用户消息 Markdown 渲染）、marketplace（插件市场）、motion（动效）。可在插件配置里用 features 白名单选择要安装的功能：

- id: ui-custom
name: '@ha-na-bi/dsh-client-ui-custom'
config:
features: [shortcuts, usage] # 只安装「快捷键」+「用量统计」

features 缺省或为空时，七个功能全部启用。

设置改动一览

| 位置 | 类型 | 内容 |
| 设置 → 外观 | 新增页面 | 主题定制，包括壁纸、玻璃、强调色、表面不透明度、字体与质感 |
| 设置 → 快捷键 | 新增页面 | 自定义快捷键，包括新建对话、切换模型、思考强度等 |
| 设置 → 应用用量 | 新增页面 | 用量统计，使用四窗口聚合、趋势图，展示会话用量排行 |
| 设置 → 动效 | 新增页面 | 对话/侧边栏/新建对话入场动效与选中框动效，含三套一键预设 |
| 设置 → 通用 | 修改原有页 | 新增浮动历史条（可调节位置，数量）、用户消息 Markdown 渲染开关 |
| 设置 → 插件 | 修改原有页 | 新增「插件市场」，收录第三方插件目录 |

外观（设置 → 外观）

外观设置给用户留出极大的自定义空间，你可以按需选择背景、玻璃档位、强调色（可自动从背景取色）、各表面不透明度、色调渐变、暗色遮罩、字体与字号、主题色滚动条与内嵌晕影，还能把 ui-theme 的主题偏好（浅色 / 深色 / 跟随系统）合并进本栏。改动通过 ui-custom settings 命名空间保存并即时生效（主题实时重渲染，无需重启）。

预览—— 主题定制支持小窗预览。

也支持全屏预览，按 F2 即可退出。

预设（Preset） —— 插件内置六种预设，每个预设都有独立风格（预设可独立生效，你自己的 wallpaper 仍会叠加在它之下）：

| id | 名称 | 风格 |
| ink-teal | Ink Teal 黛青 | 青玉色渐变，静谧沉稳 |
| ink-blue | Ink Blue 黛蓝 | 黛蓝渐变，深邃克制的蓝 |
| dusty-rose | Dusty Rose 藕荷 | 藕荷色渐变，温润柔和的粉 |
| apricot-gold | Apricot Gold 杏金 | 杏金色渐变，温雅低调的金 |
| mist-gray | Mist Gray 雾灰 | 雾灰色渐变，清冷安静的灰蓝 |
| ink-violet | Ink Violet 墨紫 | 墨紫色渐变，沉静神秘 |

更多美术选择后续会扩展进这份列表 —— 见 src/client/presets.ts。

玻璃档位 —— glass 是透明度的开关；显式设置 wallpaperBlur 时总是优先于档位的默认半径：

| 档位 | 模糊 | 饱和度 | 气质 |
| off | 0px | 1.0 | 不透明，无玻璃 |
| light | 6px | 1.15 | 轻微玻璃 |
| frosted | 14px | 1.25 | 强毛玻璃（默认） |
| mica | 22px | 1.1 | 柔和静态质感，保留壁纸色相 |

主题配置项 —— 所有字段均可选；显式配置永远优先于预设：

| 键 | 类型 | 默认值 | 含义 |
| preset | string | '' | 预设 id（见上表）；'' = 不使用预设 |
| wallpaper | string | '' | 壁纸 URL/路径（Web 可访问）；空字符串 = 插件保持关闭 |
| wallpaperBlur | number 0–60 | 玻璃档位默认 | #root 模糊半径（px）；显式值优先于玻璃档位 |
| glass | enum | frosted | off / light / frosted / mica（见玻璃档位表） |
| accent | string | #4176e6 | 强调色，整套 deepseek 色阶由它派生 |
| autoAccent | boolean | false | 从壁纸自动派生强调色（成功后覆盖 accent） |
| surfaceOpacity | number 0–100 | 100 | 主表面不透明度（聊天/细节列） |
| sidebarOpacity | number 0–100 | 100 | 侧栏不透明度 |
| chatSurfaceOpacity | number 0–100 | 100 | 聊天列不透明度（经 --dsw-chat-surface） |
| inputOpacity | number 0–100 | 100 | 输入框不透明度 |
| codeBlockOpacity | number 0–100 | 100 | 代码块/行内代码不透明度 |
| darkSurfaceOpacity | number 0–100 | surfaceOpacity | 暗色模式表面不透明度（独立档位） |
| gradient | string | '' | 亮色模式下叠加在壁纸上的渐变；空 = 无 |
| darkScrim | number 0–100 | 0 | 暗色模式下壁纸上的遮罩强度 |
| fontFamily | string | '' | 字体栈覆盖；空 = 主题默认 |
| scrollbarAccent | boolean | false | 滚动条使用强调色 |
| vignette | boolean | false | 应用根节点的柔和内嵌晕影 |
| customCss | string | '' | 原样追加的自定义 CSS（逃生舱） |
| customVars | object | {} | 额外写到 上的 CSS 自定义属性（逃生舱） |

完整示例：

config:
preset: 'ink-teal'
wallpaper: 'https://example.com/wall.jpg'
glass: 'mica' # 或 wallpaperBlur: 8 自定义半径 autoAccent: true # 强调色由壁纸自动派生 chatSurfaceOpacity: 70 customCss: |
.some-hashed-class { border-radius: 16px; }
customVars:
'--my-accent-soft': 'rgb(255 127 178 / 0.3)'

快捷键（设置 → 快捷键）

新增的设置页，提供可自定义的键位绑定。值存在 ui-custom settings 命名空间里，运行时的修改无需重启即可生效（loader 配置作为组合层 base，「恢复默认」会回到 loader 默认值）。

| 动作 | 作用 |
| newConversation | 新建对话（与侧栏「新建会话」按钮一致） |
| switchModel | 循环切换到会话目录中的下一个模型（循环；新模型使用自身默认思考强度） |
| cycleThinking | 循环切换当前模型的思考强度（off → … → max，循环） |
| sendMessage | 输入框发送手势（默认 Enter） |
| newline | 输入框换行手势（默认 Shift+Enter） |
| usagePanel | 呼出应用用量面板（默认未绑定，可在设置中开启，如 Mod+Alt+U） |
| defaultWorkspace | newConversation 打开的目标工作区（空 = 当前/最近） |
| modelShortcuts | 一对一模型直达：每个组合键跳到指定模型（combo / provider / model） |

实例：

config:
shortcuts:
newConversation: 'Mod+Alt+N'
switchModel: 'Mod+Alt+M'
cycleThinking: 'Mod+Alt+T'

习惯 Enter 换行？把发送改为 Mod+Enter、换行改为 Enter 即可（两个手势同时命中时发送优先）：

config:
shortcuts:
sendMessage: 'Mod+Enter'
newline: 'Enter'

模型动作走与内置模型选择器相同的 session.models / session.selectModel RPC，输入区的模型显示会自动同步；被寻址的子代理会话会被跳过（与 UI 一致）。
不带 Mod 的组合键在输入框聚焦时不会触发，避免劫持正常打字。

用量统计（设置 → 应用用量）

用量统计页会统计展示各会话的用量总和（token-meter + session-stats），用户可自选时间跨度（当前年内到最近三天）。页面展示 总 / 输入 / 输出 Token、缓存命中、使用时长、会话数与步数，并带用量趋势图与会话排行。
会话列表行已携带 Host 计算好的投影基线，无需额外 RPC。

面板可通过快捷键在任何界面呼出。

动效（设置 → 动效）

新增的设置页，为 Web 客户端的各个界面提供 Apple 风格的入场动效。每一类动效都有 独立的开关与样式选择，互不牵连；也可一键应用整套预设。开关与样式存于 ui-custom settings 命名空间，修改实时生效。

对话入场动效 —— 载入或切换对话时，消息逐行错峰出现，而不是瞬间跳出；每次切换都会重放动画。6 种样式：淡入上浮 / 轻柔淡入 / 上浮放大 / 右侧滑入 / 模糊显影 / 轻盈缩放。

侧边栏动效 —— 打开 Web 时侧边栏会话树逐项层叠出现，展开工作区时行项浮现，当前会话行描出常驻的选中框。4 种样式：左侧滑入 / 轻柔淡入 / 纵向展开 / 自上而下。

新建对话动效 —— 新建对话时，欢迎界面与输入区柔和入场。4 种大表面样式：轻柔显影 / 轻柔淡入 / 柔和绽放 / 柔和缩放。

设置界面动效 —— 打开设置时面板从左下角向中间扩张、关闭反向收缩；切换左侧标签时高亮与页面内容淡入。可单独关闭，关闭后设置面板立即出现/消失。

一键预设 —— 流畅 / 优雅 / 极简三套方案，把整套开关与样式一次应用到位，无需逐项调试；应用后仍可自由微调。
所有动效都尊重系统「减弱动态效果」（prefers-reduced-motion），开启时自动降级为短暂淡入；侧边栏选中框在关闭时完全移除。

通用设置项的改动

在「设置 → 通用设置」里新增内容：

浮动历史条（位置 / 数量） —— 记录某段会话的历史内容：
- 位置：left / right / off（默认 off，关闭时不显示）；
- 数量：显示最近多少回合（默认 10，0 = 全部）；
- 点击某段历史条目即可平滑滚动到对应消息，条目来自已挂载的会话快照，纯 DOM 跳转，无额外 RPC；
- 支持悬挂：在消息操作行（复制/分支之间）可选择将某段会话悬挂到历史条上，置顶回合忽略数量限制、始终显示并带有强调色边框）。

用户消息 Markdown 渲染 —— 默认关闭；开启后你自己的消息按 Markdown 渲染（标题、列表、代码块、@子代理 / @技能 引用等），关闭时与原生纯文本外观一致。

插件项的改动

在「设置 → 插件」里新增第三个 tab 「插件市场」，通过调用Github API 发现带有dsh-plugin topic的项目，为用户提供第三方 DSH 插件目录。

安装

方式一（推荐）：通过 DSH 插件中心或命令行安装：

dsh plugin --profile web add git+https://github.com/yoli-mi/dsh-client-ui-custom.git

方式二：手动在 Web profile 的补丁层加入浏览器 roster 行 —— ~/.dsh/profiles/web/cordis.patch.yml（或你 profile 中对应的 dsh.client roster）：

- id: ui-custom
name: '@ha-na-bi/dsh-client-ui-custom'
config:
preset: 'ink-teal' # 选择预设；下面任意字段会覆盖它 wallpaper: '/my-wall.jpg' wallpaperBlur: 14

然后重启 dsh web。产物（lib/）随仓库分发，安装时无需构建。

若安装报 pnpm: Command failed ... git ls-remote，多为网络到 GitHub 不稳定，重试或配置代理即可；若提示需要 allowBuilds，按提示把对应键加入 ~/.dsh/profiles/web/pnpm-workspace.yaml 后重跑安装命令。

开发（自行构建）

pnpm install
pnpm build # tsc 刷新 lib/types 声明 + tsdown 打包 lib/ 三个产物
pnpm test # vitest：149 项测试（含 DSH 0.1.2 模块表下的加载回归）

构建已自包含（tsdown.config.ts 不再引用仓库外文件）。注意：tsc 全量类型检查需要与插件目标时代匹配的 DSH profile 工作区——公共 npm 上的 @deepseek-ai/ 版本与 rc.5 时代有偏差，pnpm build 允许在该偏差下继续产出（rolldown 转译不做类型检查），测试与产物回归是主要验收面。

工作原理

- 浏览器半区先解析 preset（presets.ts），按 DEFAULTS ← 预设 ← 配置 合并并对每个字段做钳制（config.ts），再把 --dsu- 自定义属性写到 （apply.ts）。runner 会把 roster 行的 config 作为
apply(ctx, config) 的第二个参数传入。
- 样式表（custom.module.css）消费这些变量，用比主题表更高优先级的选择器在 body / body[data-ds-dark-theme] 上重新声明主题 token，插件总是赢得级联，且不修改任何插件或 shell 源码。
- 毛玻璃给 #root 加 backdrop-filter，半透明表面透过它显示壁纸。
- 聊天列旋钮依赖 ConversationRoot 读取
var(--dsw-chat-surface, var(--dsw-alias-bg-base)) —— 一行完全向后兼容
的回退写法（没有该 token 的原生 Harness 行为与之前完全一致），见 packages/client/ui-conversation。
- 框架结构：

packages/client/ui-custom/
├── src/client/
│ ├── index.ts # 插件入口：解析预设 → 规范化 → 应用 │ ├── config.ts # CustomThemeConfig、DEFAULTS、normalizeConfig（类型收窄+钳制） │ ├── presets.ts # ThemePreset 注册表 —— 美术选择的扩展面 │ ├── apply.ts # config → DOM：--dsu-* 变量、customCss、customVars │ ├── custom.module.css # 消费 --dsu-* 变量的 token 覆盖 │ └── … # 其余功能子目录（appearance/ settings/ usage/ marketplace/ history/ pin/ markdown/ motion/） ├── tests/ # 配置管线单元测试 └── README.md # 本文档（中文 / English 双语）

注意事项

- DSH 0.1.2 兼容（v0.1.0-rc.7 起）：客户端 bundle 不再
require("@deepseek-ai/dsh-client-runtime/client") —— DSH 0.1.2 已将该包
移出客户端模块表，旧版会在模块加载阶段整体失败。插件内置了等价的 snapshot store（src/client/snapshot-store.ts），行为不变。
- profile 的 cordis.patch.yml 改动需要重启 dsh web 才生效。
- 壁纸必须能被浏览器访问（例如放在 Web 服务静态根目录下，或外部 URL）。
- 插件自带的设置页（外观、快捷键、用量统计等）修改实时生效、无需重启；通过内置「插件配置」页直接编辑 loader 层配置暂不支持（待 ui-settings-plugins 的 schema）。

概览

Dsh-client-ui-custom 是纯前端插件，提供浮动历史条、用户消息 Markdown 渲染、外观自定义、插件市场、键盘快捷键和用量统计。

- 在通用设置中新增 —— 设置 → 通用下新增几行，用于浮动历史条（位置 / 数量）和用户消息 Markdown 渲染开关；
- 在插件设置中新增 —— 设置 → 插件下新增「插件市场」；
- 新增三个设置页 —— 外观、快捷键、用量统计。

所有功能默认关闭；不做配置时，界面与原生完全一致，零 shell 改动。

功能选择（按需安装）

插件由七个相互独立的功能模块组成：appearance、shortcuts、usage（用量统计）、history（历史条）、markdown（用户消息 Markdown 渲染）、marketplace（插件市场）和 motion（入场动画）。用插件配置里的 features 白名单选择要安装哪些：

- id: ui-custom
name: '@ha-na-bi/dsh-client-ui-custom'
config:
features: [shortcuts, usage] # install only shortcuts + usage stats

features 缺失或为空时，七个功能全部启用。

设置一览

| 位置 | 类型 | 内容 |
| 设置 → 外观 | 新页面 | 自定义主题：壁纸、玻璃、强调色、表面不透明度、字体与纹理 |
| 设置 → 快捷键 | 新页面 | 自定义键位：新建会话、切换模型、思考强度、模型直达等 |
| 设置 → 应用用量 | 新页面 | 用量统计：按可选时间跨度聚合，带趋势图和会话排行 |
| 设置 → 动效 | 新页面 | 会话 / 侧边栏 / 新建会话的入场动效、选择框、三个一键预设 |
| 设置 → 通用 | 新增行 | 浮动历史条（位置 / 数量可调）、用户消息 Markdown 开关 |
| 设置 → 插件 | 新增标签页 | 「插件市场」：第三方插件目录 |

外观（设置 → 外观）

外观提供很大的自定义空间：你可以选择壁纸、玻璃程度、强调色（可选从壁纸自动推导）、各表面不透明度、色调渐变、暗色遮罩、字体与缩放、强调色滚动条和内嵌暗角，并把 ui-theme 的主题偏好（浅色 / 深色 / 跟随系统）合并到这一节。改动通过 ui-custom 设置命名空间保存，并立即生效（主题实时重渲染，无需重启）。
预览 —— 主题支持小窗预览。

也支持全屏预览 —— 按 F2 退出。

预设 —— 插件内置六套预设，每套风格各不相同（预设可以单独使用，你自己的 wallpaper 仍会叠在它下面）：

| id | 名称 | 外观 |
| ink-teal | Ink Teal 黛青 | 玉青渐变，安静沉稳 |
| ink-blue | Ink Blue 黛蓝 | 深蓝渐变，克制深邃 |
| dusty-rose | Dusty Rose 藕荷 | 藕荷渐变，温暖柔和的粉 |
| apricot-gold | Apricot Gold 杏金 | 雅致内敛的暖金 |
| mist-gray | Mist Gray 雾灰 | 清冷安静的灰蓝雾感 |
| ink-violet | Ink Violet 墨紫 | 深紫，宁静神秘 |

后续还会加入更多美术方案，扩展这张列表 —— 见 src/client/presets.ts。

玻璃层级 —— glass 是透明度开关；显式写出的 wallpaperBlur 始终覆盖层级自带的默认半径：

| 层级 | 模糊 | 饱和度 | 观感 |
| off | 0px | 1.0 | 不透明，无玻璃效果 |
| light | 6px | 1.15 | 轻微玻璃 |
| frosted | 14px | 1.25 | 强磨砂玻璃（默认） |
| mica | 22px | 1.1 | 柔和静态纹理，保留壁纸色调 |

主题配置项 —— 每个字段都可选；显式写出的值始终优先于预设：

| 键 | 类型 | 默认值 | 含义 |
| preset | string | '' | 预设 id（见上表）；'' = 不用预设 |
| wallpaper | string | '' | 壁纸 URL/路径（网络可访问）；空字符串则关闭插件 |
| wallpaperBlur | number 0–60 | 玻璃默认值 | #root 上的模糊半径（px）；显式值覆盖玻璃层级 |
| glass | enum | frosted | off / light / frosted / mica（见玻璃层级表） |
| accent | string | #4176e6 | 强调色；整套 deepseek 色阶都由它推导 |
| autoAccent | boolean | false | 从壁纸自动推导强调色（成功时覆盖 accent） |
| surfaceOpacity | number 0–100 | 100 | 主表面不透明度（聊天/详情栏） |
| sidebarOpacity | number 0–100 | 100 | 侧边栏不透明度 |
| chatSurfaceOpacity | number 0–100 | 100 | 聊天栏不透明度（通过 --dsw-chat-surface） |
| inputOpacity | number 0–100 | 100 | 输入框不透明度 |
| codeBlockOpacity | number 0–100 | 100 | 代码块 / 行内代码不透明度 |
| darkSurfaceOpacity | number 0–100 | surfaceOpacity | 深色模式表面不透明度（独立开关） |
| gradient | string | '' | 叠在壁纸上的浅色主题渐变；空 = 无 |
| darkScrim | number 0–100 | 0 | 深色主题在壁纸上的遮罩强度 |
| fontFamily | string | '' | 覆盖字体栈；留空则用主题默认值 |
| scrollbarAccent | boolean | false | 用强调色给滚动条着色 |
| vignette | boolean | false | 在应用根节点加一层柔和的内嵌暗角 |
| customCss | string | '' | 原样追加的自定义 CSS（逃生通道） |
| customVars | object | {} | 额外写入 的 CSS 自定义属性（逃生通道） |

完整示例：

config:
preset: 'ink-teal'
wallpaper: 'https://example.com/wall.jpg'
glass: 'mica' # or wallpaperBlur: 8 for a custom radius
autoAccent: true # accent derived from the wallpaper
chatSurfaceOpacity: 70
customCss: |
.some-hashed-class { border-radius: 16px; }
customVars:
'--my-accent-soft': 'rgb(255 127 178 / 0.3)'

快捷键（Settings → Shortcuts）

新增一个设置页，可以自定义按键绑定。这些值存放在 ui-custom 设置命名空间里，所以运行时改动立即生效，不用重启（loader 配置充当组合基底，Reset 会还原成 loader 默认值）。

| 动作 | 作用 |
| newConversation | 开启新会话（等同于侧边栏的 New Session 按钮） |
| switchModel | 切换到会话目录里的下一个模型（循环；新模型从它自己的默认推理强度开始） |
| cycleThinking | 循环切换当前模型的推理强度（off → … → max，循环） |
| sendMessage | 输入框的发送手势（默认：Enter） |
| newline | 输入框的换行手势（默认：Shift+Enter） |
| usagePanel | 弹出应用用量面板（默认未绑定——在 Settings 里启用，例如 Mod+Alt+U） |
| defaultWorkspace | newConversation 打开时所在的工作区（留空 = 当前/最近） |
| modelShortcuts | 一对一模型跳转：每个组合键直达指定模型（组合键 / 服务商 / 模型） |

示例：

config:
shortcuts:
newConversation: 'Mod+Alt+N'
switchModel: 'Mod+Alt+M'
cycleThinking: 'Mod+Alt+T'

习惯用 Enter 换行？把发送设为 Mod+Enter，换行设为 Enter（两个手势同时命中时，发送优先）：

config:
shortcuts:
sendMessage: 'Mod+Enter'
newline: 'Enter'

模型相关动作走的是和内置模型选择器相同的 session.models / session.selectModel RPC，所以输入框里显示的模型会保持同步；带地址的子代理会话会被跳过（和 UI 一致）。不带 Mod 的组合键在输入框获得焦点时不会触发，所以绝不会劫持正常打字。

用量统计（Settings → App Usage）

用量统计页会汇总每个会话在用户可选时间跨度内的总用量（token-meter + session-stats），跨度从当前年份一直到最近三天。它显示 总 / 输入 / 输出 token、缓存命中、 使用时长，以及会话与步数统计，外加使用趋势图和会话排行。会话列表行已经带上宿主算好的投影基线，不需要额外 RPC。

面板可以从任意界面用快捷键弹出。

动效（Settings → Motion）

新增设置页，把 Apple 风格的入场动效带到 Web 客户端的各个界面。每种动效都有自己的开关和样式选择器——彼此独立——整套组合可以一键预设一次应用。开关和样式放在 ui-custom 设置命名空间，立即生效。

对话入场动效——对话加载或切换时，消息逐行层叠进入，而不是一次性弹出；每次访问都会重放动画。六种样式：fade-up / gentle fade / rise & scale / slide-in / blur-in / gentle scale。

侧边栏动效——Web 加载时会话树层叠进入，工作区行在所属分组展开时淡入，当前对话行描出常驻选中框。四种样式：slide-in from left / gentle fade / expand / drop-in。

新对话动效——全新对话的欢迎对话框和输入框柔和登场。四种大界面样式：soft reveal / gentle fade / gentle bloom / soft zoom。

设置外壳动效——设置对话框从左下角展开，关闭时收起；切换时导航高亮和页面内容淡入。可以单独关掉，关掉后面板瞬间出现和消失。

一键预设——Fluid / Elegant / Minimal 一次应用整套开关和样式，不用逐项调；之后仍可随意编辑。

所有动效都遵循系统「减少动态效果」偏好（prefers-reduced-motion），开启时降级为短暂交叉淡入；关闭时侧边栏选中框完全移除。

通用设置新增项

Settings → General 下的新增内容：

浮动历史条（位置 / 数量）——记录对话历史：
- 位置：left / right / off（默认 off——关闭时隐藏）；
- 数量：显示最近多少轮（默认 10，0 = 全部）；
- 点击条目平滑滚动到对应消息；条目来自已挂载的会话快照，所以跳转是纯 DOM 操作——不需要额外 RPC；
- 支持固定：在消息操作行（复制和分支之间）可以把某一轮固定到历史条上；固定的轮次忽略数量限制，始终显示，并带强调色边框。

用户消息 Markdown 渲染——默认关闭；开启后你自己的消息按 Markdown 渲染（标题、列表、代码块、@subagent / @skill 引用……）；关闭时和原生纯文本一样。

插件设置新增内容

在「设置 → 插件」下新增第三个标签页 「插件市场」：它会调用 GitHub API，发现带有 dsh-plugin 话题标签的项目，提供一份 第三方 DSH 插件的目录。

安装

方式 A（推荐）：通过 DSH 插件中心或命令行：

dsh plugin --profile web add git+https://github.com/yoli-mi/dsh-client-ui-custom.git

方式 B：手动往 web 配置档的补丁层加一行浏览器名单——~/.dsh/profiles/web/cordis.patch.yml（或你配置档里对应的 dsh.client 名单）：

- id: ui-custom
name: '@ha-na-bi/dsh-client-ui-custom'
config:
preset: 'ink-teal' # pick a preset; any field below overrides it
wallpaper: '/my-wall.jpg'
wallpaperBlur: 14

然后重启 dsh web。产物（lib/）随仓库一起发布，所以安装时永远不需要构建。

如果安装失败并报 pnpm: Command failed ... git ls-remote，通常是连 GitHub 不稳定——重试或配置代理。如果它要求 allowBuilds，把它打印出的那个键加到 ~/.dsh/profiles/web/pnpm-workspace.yaml，再重新执行安装命令。

开发（自行构建）

pnpm install
pnpm build # tsc refreshes lib/types declarations + tsdown bundles lib/
pnpm test # vitest: 149 tests (incl. the DSH 0.1.2 module-table load regression)

构建是自包含的（tsdown.config.ts 不再导入仓库之外的任何东西）。注意，想要一次完全干净的 tsc 类型检查，需要一个与插件目标年代匹配的 DSH 配置档工作区——公共 registry 上的 @deepseek-ai/ 版本已经偏离 rc.5 年代，所以 pnpm build 有意容忍这些偏差错误（rolldown 转译时不做类型检查）；测试套件和打包回归才是验收关口。

工作原理

- 浏览器端先解析 preset（presets.ts），按 DEFAULTS ← preset ← config 合并，并对每个字段做钳制（config.ts），然后把 --dsu- 自定义属性写到 上（apply.ts）。运行器把名单行的 config 作为第二个参数传给 apply(ctx, config)。
- 样式表（custom.module.css）消费这些变量，并在 body / body[data-ds-dark-theme] 上重新声明主题 token，选择器的优先级高于主题样式表，所以插件总能赢下层叠——不改动任何插件或外壳源码。
- 毛玻璃效果给 #root 加上 backdrop-filter，半透明表面透过它显示壁纸。
- 聊天栏旋钮依赖 ConversationRoot 读取 var(--dsw-chat-surface, var(--dsw-alias-bg-base))——一行代码，完全向后兼容的兜底（没有这个 token 时，原生 Harness 行为与之前完全一致）。见 packages/client/ui-conversation。
- 框架布局：

packages/client/ui-custom/
├── src/client/
│ ├── index.ts # 插件入口：解析预设 → 归一化 → 应用 │ ├── config.ts # CustomThemeConfig、DEFAULTS、normalizeConfig（类型收窄 + 数值钳制） │ ├── presets.ts # ThemePreset 注册表 —— 美术选择的扩展面 │ ├── apply.ts # 配置 → DOM：--dsu- 变量、customCss、customVars │ ├── custom.module.css # token 覆盖，消费 --dsu- 变量 │ └── … # 其余功能子目录（appearance/ settings/ usage/ marketplace/ history/ pin/ markdown/） ├── tests/ # 配置流水线单元测试 └── README.md # 本文件（中文 / English 双语）

说明

- 兼容 DSH 0.1.2（自 v0.1.0-rc.7 起）：客户端 bundle 不再 require @deepseek-ai/dsh-client-runtime/client —— DSH 0.1.2 把该包从客户端模块表里移除了，旧 bundle 会在模块加载阶段直接挂掉。现在内置了一份等价的 snapshot store（src/client/snapshot-store.ts），行为不变。
- 改动配置档的 cordis.patch.yml 后，必须重启 dsh web 才生效。
- 壁纸必须能被浏览器访问到（比如放到 web 服务器的静态根目录下，或者用外部 URL）。
- 插件自己的设置页面（Appearance、Shortcuts、App Usage……）改完立即生效，不用重启；目前还不支持直接通过内置的 Plugin Configuration 页面改加载器层配置（等 ui-settings-plugins schema）。