社区维护的 DeepSeek Harness WebUI 外观扩展。它把浅色/深色配色、背景图、透明度、字体、VS Code 主题映射和自定义 CSS 集成进 DSH 原生“设置 → 外观”页面，并把完整配置持久化在插件自己那条约 profile entry 的 Config 里（DSH 0.2.0-rc.2 的配置表单是唯一写入方）。
[!IMPORTANT]
0.2.0 已迁移为官方 DSH Profile Bundle。安装时不会修改、复制或重新编译官方 DSH 源码。本项目不是 DeepSeek 官方发行物。
壁纸与统一强调色展示
展示图和配置图已去除真实工作区、路径与会话内容；其作用是演示插件外观，实际控件以当前 DSH 版本为准。
功能一览
| 能力 | 行为 |
|---|
| 浅色 / 深色 / 跟随系统 | 继续使用 DSH ui-theme 的模式选择，并分别维护浅色与深色配色 |
| 统一强调色 | 同时映射品牌色、业务状态色和信息按钮 token，使对话标签、文件夹、链接、焦点、光标与发送按钮保持一致 |
| 背景图 | 支持 HTTP(S) URL、本地图片上传和四个内置渐变预设 |
| 透明度与遮罩 | 表面透明度控制内容层可见度；独立遮罩保证文字可读 |
| 字体 | 可设置 UI 字体和代码字体，并提供常用预设 |
| VS Code 主题导入 | 从主题 JSON 的 colors 字段映射五类核心颜色 |
| 自定义 CSS | 文本或 .css 文件实时注入，并随配置持久化 |
| 布局快捷操作 | 折叠/展开侧边栏，打开/关闭详情栏 |
| Host 持久化 | 刷新、卸载/重载插件或重启 DSH 后恢复；写入后会从 Host user layer 精确回读确认 |
展示
配置页面
外观配置页面
设置页直接嵌入 DSH 原有设置面板，不建立第二套配置程序。浅色和深色各自保存一套强调色、文字、背景与侧边栏颜色；切换方案只编辑目标方案，不会覆盖另一套颜色。
一处配色，覆盖主要交互状态
强调色 token 覆盖示意
早期版本只覆盖 brand-primary，因此发送按钮、文件夹、链接和当前对话标签仍可能保留 WebUI 默认蓝色。正式版把同一个强调色投射到这些语义 token：
--dsw-alias-brand-primary
--dsw-alias-brand-primary-new-colorprimary-new-color
--dsw-alias-state-business-primary
--dsw-alias-state-business-tertiary
--dsw-alias-button-info-fill
--dsw-alias-button-info-hover
禁用按钮仍保留组件自身的降透明度规则；只有可交互/激活状态使用配置的强调色。
已验证快照
| 项目 | 值 |
|---|
| 插件包 | @deepseek-ai/dsh-client-ui-appearance 0.3.1 |
| 官方 DSH | 0.2.0-rc.2（npm 发布的客户端包） |
| DSH 基线 | npm:@deepseek-ai/dsh-client-*@0.2.0-rc.2 |
| 验证日期 | 2026-09-29 |
| 正式源码与构建产物 | packages/client/ui-appearance/ |
| 安装机制 | 根目录 package.json + cordis.patch.yml Profile Bundle |
| 持久化位置 | 插件 entry ui-appearance 的 Config.config（volatile() 字符串） |
版本对应：0.3.x 面向 DSH 0.2.0-rc.2（官方桌面版内置的运行时）；0.2.x 面向 0.1.1-rc.2，在桌面版上无法激活。装之前先确认你的 DSH 版本，否则设置里不会出现「外观」。
发布目录的文件数和 SHA-256 树摘要记录在 integration/tested-snapshot.json，可由脚本逐文件复核。
旧版 host.js / prototype.client.js 已移入 legacy-prototype/，仅用于历史参考。它只在浏览器内存中保存配置，不是推荐安装方式。
安装到官方 DSH 0.2.0-rc.2
前提
- 已安装并能运行官方
@deepseek-ai/dsh 0.2.0-rc.2
- Node.js
^22.19.0 或 >=24.0.0
- Windows PowerShell 5.1 或 PowerShell 7+（仅安装辅助脚本需要）
- 安装前建议备份
$DSH_HOME/profiles/<profile>/cordis.patch.yml
自动安装
git clone https://github.com/Zhen-WushuiLingchun/dsh-easy-appearance.git
cd dsh-easy-appearance
./scripts/verify-rc2-compat.ps1
./scripts/install-into-dsh.ps1
脚本验证 DSH 版本，然后调用官方 Profile Bundle 安装命令：
dsh plugin --profile web add .
也可以安装打包后的 .tgz；仓库发布 0.3.1 后还可以直接使用 GitHub 源：
dsh plugin --profile web add D:\path\to\deepseek-ai-dsh-client-ui-appearance-0.3.1.tgz
dsh plugin --profile web add github:Zhen-WushuiLingchun/dsh-easy-appearance
完全退出并重新启动 dsh web 或 DSH Desktop，设置中应出现“外观”。安装过程只修改所选 DSH home 的 profiles/web 依赖与 bundle 列表，不修改官方程序目录。自定义 profile 可使用 ./scripts/install-into-dsh.ps1 -Profile my-web。
配置说明
主题与配色
- 主题模式：浅色、深色或跟随系统；模式选择仍由 DSH
ui-theme 管理。
- 配色目标：可以先选“配色 · 浅色/深色”，再编辑对应方案。
- 强调色：对话标签、文件夹、链接、发送按钮、选中状态和焦点状态。
- 前景/次要文字：主要正文与辅助信息。
- 背景/侧边栏：基础 WebUI 表面；启用壁纸时基础背景 token 会透明化。
- 对比度：对表面明暗做统一调整。
- 表面透明度：越低越能看到壁纸；选择图片时自动调到 50%，100% 时壁纸被不透明表面遮住。
背景图
- 在“图片 URL”中填写
https://... 或 data:image/...；
- 通过“本地上传”选择图片，浏览器会使用
FileReader 转为 data URL；
- 较大的内嵌图片仍完整持久化，但 URL 输入框只显示估算大小，避免 Electron 把数 MB Base64 绑定到文本控件时出现绘制留白；
- 使用“暮色紫、深海蓝、翡翠绿、暖橙”内置预设；
- 调整遮罩透明度，在壁纸可见度和文字对比度之间取平衡。
壁纸只绘制在一个 body 画布上。启用后，共享基础背景 token 变为透明，避免多个嵌套容器重复叠加 50% 透明度而把图片盖住。
VS Code 主题
选择 VS Code 主题 JSON 后，插件读取顶层 type 与 colors，并把可用字段映射到强调色、背景、前景、次要文字和侧边栏。tokenColors、全部边框和复杂状态色暂不映射。
字体与自定义 CSS
- UI 字体：支持任意 CSS
font-family，并提供 Inter、微软雅黑与默认值；
- 代码字体：提供 JetBrains Mono、Fira Code、SF Mono 与默认值；
- 自定义 CSS：支持直接编辑或载入
.css 文件，实时写入插件自己的 <style>；
- 覆盖主题 token 时，通常需要
body 选择器与 !important，设置页内置模板可作为起点。
持久化原理
ui-appearance 就是插件自己那条约 profile entry，它的 cordis Config 只有一个 volatile() 字符串字段 config：浏览器把完整 AppearanceConfig 序列化进去，0.2.0-rc.2 的配置表单（ctx.configForms.get('ui-appearance')）是唯一写入方，每次保存后回读并比对完整字符串。写入落在 profile 的补丁层：
$DSH_HOME/profiles/<profile>/cordis.patch.yml
文件结构类似：
- id: ui-appearance
config:
config: '{"colors":{"light":{},"dark":{}},"wallpaper":{"url":"data:image/..."}}'
实际 JSON 同时包含：
colors.light / colors.dark
contrast
surfaceOpacity
wallpaper.url / wallpaper.scrim
fonts.ui / fonts.code
customCss
因此颜色、透明度、字体、自定义 CSS 和上传后的背景图都会在刷新及 DSH 重启后恢复。上传图片的 data URL 也在同一个持久值内，所以大图会显著增大 cordis.patch.yml；本版本尚未建立单独的图片资产库。
远程且非 loopback 的浏览器不会获得高权限 settings API，此时插件只能保持当前页面内存状态。这是安全边界，不是持久化故障。
验证与开发
校验发布快照与安装合约
./scripts/verify-tested-snapshot.ps1
./scripts/verify-rc2-compat.ps1
node --test tests/*.test.mjs
npm pack --dry-run
本快照的本机验证结果：
- Profile Bundle 合约测试：3/3 通过；
- 外观源码组件测试：3 个文件、8 项通过；
- 对 npm 发布的 DSH
0.2.0-rc.2 客户端包完成 Host 与 client 全量构建（npm install && npm run build，无需 DSH 源码树）；
- 真实
.tgz 已通过官方 CLI 安装到隔离 Web profile，首页与插件 bundle 均返回 HTTP 200；
- Host RPC 能发现
ui-appearance，并完整读回现存约 10.5 MB 的主题/壁纸 JSON；
- 安装前后测试 home 的
cordis.patch.yml 摘要不变，刷新与重启后壁纸和主题继续生效；
- 同一 profile 已通过浏览器与 DSH Desktop 嵌入页面兼容检查。
GitHub Actions 会重复执行 bundle 合约、rc2 版本、快照摘要、真实 profile 安装和发布包内容检查。
故障排查
设置中没有“外观”
运行 dsh plugin --profile web list 和 dsh plugin --profile web why @deepseek-ai/dsh-client-ui-appearance。确认依赖存在后完全退出并重启 dsh web 或 Desktop；无需修改官方 DSH 源码或手工重建 WebUI。
Desktop 使用的 profile 名是 desktop，请对应执行 dsh plugin --profile desktop list。
Desktop 启动即报“应用无法启动”（entry did not activate）
0.2.0 在 Electron 托管的 desktop profile 上会让浏览器入口停在 pending (waiting for service: settingsScope)；Desktop 的启动审计把“有待激活条目”视为致命错误，于是弹出“应用无法启动或已意外停止”。0.2.1 只把硬依赖改成延迟注入，因此不再崩溃、但设置页仍然不出现；真正修好的是 0.3.0——它改用 0.2.0-rc.2 的配置表单 API。升级到 0.3.0 即可：
dsh plugin --profile desktop remove @deepseek-ai/dsh-client-ui-appearance
dsh plugin --profile desktop add D:\path\to\deepseek-ai-dsh-client-ui-appearance-0.3.1.tgz
若应用已卡在该对话框，先点“禁用第三方插件、备份 profile patch 并重启”恢复启动，再执行上面的重装命令。
图片已经配置，但页面看不到
- 确认“表面透明度”低于 100%；
- 暂时减小遮罩层透明度；
- 检查
cordis.patch.yml 的 entry 的 config 字段 是否仍包含 wallpaper.url；
- 强制刷新页面以加载最新 Web bundle；
- 若使用远程 URL，确认浏览器可以直接访问该图片。
Desktop 的背景图控件之间出现大片空白
确认使用 0.3.0 或更高版本。上传图片仍保存在 entry 的 config 字段 中，但超过 4 KiB 的 data:image/... 不再直接绑定到 URL 输入框；设置页会显示图片估算大小。
发送按钮、文件夹或链接仍是默认蓝色
确认使用的是本仓库正式包，而不是 legacy-prototype；完全重启 DSH 后再强制刷新页面。
重启后配置丢失
查看设置页底部保存状态，并确认当前浏览器通过 loopback 地址访问 DSH。不要只检查浏览器 localStorage；正式版的权威数据在 Host user settings 中。
更新与移除
升级前备份 $DSH_HOME/profiles/<profile>/cordis.patch.yml，然后再次运行 dsh plugin --profile web add <新包或 GitHub 源>。
如需停用，运行 dsh plugin --profile web remove @deepseek-ai/dsh-client-ui-appearance。该命令会从 profile 移除插件包与 bundle，但不会主动删除插件 entry 的 config 字段，以后重新安装仍可恢复主题。只有明确决定彻底清除时，才应另行备份再删除 cordis.patch.yml 中那条 ui-appearance 覆盖。
隐私与安全边界
- 不要把
$DSH_HOME/profiles/<profile>/cordis.patch.yml 提交到公共仓库；
- 本地上传图片以内联 data URL 保存，可能包含私人图片且体积很大；
- 本仓库忽略常见 DSH home、凭据、会话与本地设置路径；
- 自定义 CSS 能改变当前 WebUI 的显示，请只导入自己信任的 CSS；
- 文档展示图经过隐私化处理，不包含原始工作区和对话数据。
仓库结构
assets/ README 图片与项目图标
package.json 可安装的 Profile Bundle 清单
cordis.patch.yml 向 Web profile 注入 ui-appearance
packages/client/ui-appearance/ Host、浏览器源码与 rc2 构建产物
integration/tested-snapshot.json 发布快照摘要
scripts/ 安装与一致性校验脚本
legacy-prototype/ 旧内存态原型，仅供参考
.github/workflows/verify.yml 持续集成验证
贡献
Issue 和 Pull Request 欢迎围绕当前已验证基线提交。涉及新版 DSH 的兼容修改，请同步更新 Profile Bundle、依赖版本、快照记录和验证证据；不要提交个人 cordis.patch.yml、会话数据或私有壁纸。
许可证
MIT License。社区维护和商标说明见 NOTICE。
