AnacondaKC/dsh-custom-css

dsh-custom-css

DSH WebUI 自定义 CSS 插件（官方 bundle 形态，client-half 插件）。

在设置面板新增「外观 / Custom CSS」页：粘贴任意 CSS 即时改变 WebUI 观感，样式持久化到宿主设置（$DSH_HOME/settings.yaml），所有访问该 GUI 的浏览器共享，多浏览器实时同步。

功能

- 粘贴/编辑 CSS 后 500ms 防抖自动保存到宿主，所有浏览器实时同步
- revision 乐观并发控制：远端修改与本地草稿冲突时暂停自动保存，用户可选择采用远端版本或显式覆盖
- 保存、同步、冲突和错误状态反馈；失败后可手动重试或放弃草稿
- 可导入 .css 文件，或上传 JPEG/PNG/WebP 背景图（压缩后以 data URI 存入 CSS，CSS 总量上限 1,048,576 个字符）
- 安全模式：URL 带 ?dsh-custom-css=off 时本页不注入自定义样式，设置页仍可用于恢复
- 读、写均走 trusted-host 信任模型：本机与 --trusted-host 声明的远程地址都可修改共享样式
- 未保存草稿存于本浏览器 localStorage，刷新不丢失
- 中英文案
- 附带旗舰演示主题 examples/dsh-aurora-nexus.css，完整覆盖官方语义色、排版、动效、阴影、滚动条与 Shiki 接口

旗舰演示主题：Aurora Nexus

Aurora Nexus 主题效果

examples/dsh-aurora-nexus.css 是本项目的完整能力演示：同时适配亮色/暗色，覆盖全部官方 --dsw-alias-、--dsw-specific-、静态色阶、排版、动效、阴影、滚动条和 Shiki token，并通过官方主题标记、ARIA role、data- 与少量集中管理的 CSS Modules 选择器增强主框架、侧栏、会话、输入栏、设置、弹窗、菜单、Markdown、代码块和轨迹视图。

使用方式：打开「设置 → 自定义CSS」，复制该文件全文并粘贴。插件会将样式保存到宿主并同步给所有连接到当前 DSH GUI 的浏览器。主题不加载远程字体或图片，并完整处理 prefers-reduced-motion、高对比度和强制色模式。

架构

src/index.ts         host half：注册 settings namespace dsh-custom-css + 双 RPC 通道
src/rpc.ts           读通道 /dsh-custom-css-read（trusted-host）+ 写通道 /dsh-custom-css-write（trusted-host）
src/client/          browser half：设置页 + 样式注入（）+ 宿主同步

宿主设置经自定义 RPC 读写（Web 设置 API api.settings. 只服务白名单 namespace，插件 namespace 不可达）。

构建与挂载

pnpm build                                        # tsc + tsdown + 产物校验
dsh plugin --profile web add /path/to/dsh-custom-css
dsh --profile web --dump-config | grep custom-css # 确认进入 bundles
重启 dsh web 后生效；浏览器 DevTools 检查：
window.__DSH_BOOT__.entries 含 dsh-custom-css
document.head 出现

开发态 dsh web --dev 下改 src/client/** 后重新构建，浏览器经内置 client-hmr 原地热替换（无需刷新）。

测试

pnpm test   # RPC 契约 + controller 状态机（冲突/草稿/权限）

恢复路径

- 样式异常：URL 加 ?dsh-custom-css=off 打开本页；随后清空输入框或关闭开关并保存
- 配置损坏：删除 $DSH_HOME/settings.yaml 中 dsh-custom-css 段后重启
- 安全提示：CSS 和背景图会同步给同一宿主的所有浏览器。仅应向受信任的 --trusted-host 访问者开放该 GUI，勿粘贴来源不明的 CSS。