Hermes 主题引擎（Theme Engine）

Hermes Agent 桌面端的美化插件：壁纸 + 分区玻璃效果 + 文字可读性增强。

当前版本 v3.17（theme-engine/plugin.js）。

功能

背景媒体

• 图片 / 视频壁纸，类型自动识别（按扩展名 + MIME，识别失败自动换方向重试）
• 壁纸存档：选择文件时把文件本体存入 IndexedDB，重启 / 切页 / 重载插件后自动恢复
• 也可手填本地路径或网址（与存档互斥）
• 壁纸不透明度 / 模糊（带边缘补偿）/ 填充方式（铺满 / 完整显示）/ 兜底颜色
• 遮罩（自动跟随深浅色 / 加深 / 提亮）用于压背景保文字可读
• 视频后台省电：窗口隐藏时自动暂停；遵循系统"减弱动态效果"

玻璃效果（全局 / 独立双模式）

• 全局模式：一套参数（界面不透明度 + 全局模糊 + 色彩饱和）应用到所有分区
• 独立模式：9 个分区各自调不透明度 + 模糊，分区选中时界面闪蓝框高亮范围

分区	覆盖范围（选择器经真实 DOM 验证）
对话区	主内容底色、代码卡片（--ui-chat-surface-background 及 editor-surface 类）
左侧栏	会话列表（sidebar-surface 类，排除 aside；[data-slot=sidebar]、[data-tree-group]）
右侧栏	右侧文件树 / 资料面板（aside 元素，同类名但用 :not(aside) 与左栏分离）
输入区	底部输入框与 HUD 玻璃带（--dt-card、[data-hud-glass]）
消息气泡	气泡、卡片、小弹窗（--ui-chat-bubble-background、--dt-user-bubble、--ui-card）
设置界面	软件设置等全屏浮层卡片 + 浮层内导航列（[data-overlay-surface] 子树）
终端	内嵌终端（--ui-terminal-surface-background）
对话框	模态弹窗、时间线气泡（[data-slot=dialog-content] 等）
菜单浮层	右键菜单、下拉、选择器（dropdown/select/popover-content）

• 看板等非聊天整页：几何兜底扫描自动接管（面积 ≥40% 且背景不透明或带渐变的元素），归设置界面层

文字可读性

• 文字对比度：四级文字色向纯黑（浅色主题）/ 纯白（深色主题）插值，纯 CSS 色阶无竞态
• 文字光晕：paint-order: stroke fill 反向色描边（浅色主题白晕、深色主题黑晕），壁纸深浅混合区域也可读

其他

• 深浅色自动跟随（MutationObserver + matchMedia），切主题瞬时正确
• 自定义 CSS、配置导出导入（剪贴板）、二次确认恢复默认
• 命令面板：打开设置 / 玻璃开关 / 背景开关 / 界面结构快照（排查用）

安装

%LOCALAPPDATA%\hermes\desktop-plugins\theme-engine\plugin.js

复制 theme-engine/plugin.js 到上述路径，然后 Ctrl+K → 重载桌面插件。

稳定性要点（与宿主对抗的坑，改动前必读）

• 宿主 translucency.ts 会响应式 toggle data-hermes-glass 属性 → 本插件所有规则用自有标记 data-te-glass + data-te-v，并有属性哨兵自动补回
• body { background: var(--ui-chat-surface-background) } 会把对话区变量染到全窗口 → background 简写 + 双属性 + !important 压制
• 浮层遮罩 [data-overlay-surface] 自带 backdrop-filter，形成"背景采样根"使卡片模糊失效 → 显式禁掉遮罩自身的
• sidebar-wrapper 是全屏宽包装（shadcn），挂模糊会糊全屏；sidebar-container/inner 在 Hermes 中不存在 → 左栏用 [data-slot=sidebar]
• --dt-user-bubble 是 --ui-chat-bubble-background 的别名，但类名不同 → 模糊选择器两个都要挂
• Electron 网页层拿不到文件真实路径 → 壁纸持久化必须存 IndexedDB 而非路径

目录

theme-engine/   当前版本插件（安装这个）
_archive/       历史版本（bg-video v1 英文版、损坏中间版 2355）

版本史

• v3.17 用户气泡模糊修复（--dt-user-bubble 别名）
• v3.16 浏览器实测重写全部分区选择器；浮层遮罩采样根修复
• v3.15 侧栏局部容器、浮层导航列归属设置层
• v3.14 文字对比度纯 CSS 色阶 + 文字光晕
• v3.13 自有双标记 + 属性哨兵（偶发失效根治）
• v3.12 源码定位 OverlayView 卡片划归设置界面层
• v3.11 可见性路由判定
• v3.10 设置层目标移交气泡层
• v3.9 页面路由重定向
• v3.8 兜底扫描覆盖背景图/渐变
• v3.7 结构快照诊断
• v3.6 body 背景简写压制
• v3.5 壁纸 IndexedDB 存档 + 几何兜底扫描
• v3.4 页面级背景类纳入分区
• v3.3 全局/独立双模式、文字加深
• v3.2 全透明默认、壁纸饱和
• v3.0–3.1 全面重构：分区体系、自动识别
• v2.x（bg-video）英文 UI 初版