dsh-theme-synthwave

📖 English documentation: README_en.md

给 DSH（DeepSeek Harness）Web UI 用的合成波 / Synthwave 主题插件。

单包同时包含 host 端（配置读取、媒体文件服务）与 client 端（主题 token、霓虹发光、背景媒体、字号缩放），安装即用。背景支持本地图片轮播或视频，面板可半透明透出媒体，并带有可配置的霓虹 glow、模糊与全局字号缩放。

DSH 版本适配：v0.3.0 起适配 DSH v0.1.6-alpha.2。0.1.6 的三处相关变化均已跟进：① 浏览器端入口按「loader 行名 == 包清单 name」精确匹配，本插件的补丁行名与 bundle id 已统一为小写包名；② 插件配置迁入侧边栏「插件」管理页（plugins.bundle.config keyed 槽位，按包名挂到本插件的详情页），不再使用左下角设置面板；③ 客户端插件需声明 inject 服务依赖（['slots', 'theme']），避免并行激活竞态导致主题不生效。更早的 DSH 版本（≤ 0.1.5）请使用 v0.2.1。

✨ 功能

• 霓虹发光 hover/focus：对链接、按钮、role="button" 等可点击控件添加多层 text-shadow 发光，hover/focus 时切换颜色。
• 半透明面板透出背景：通过 background.baseAlpha 调整应用底色/侧边栏透明度，透出背后的图片或视频。
• 背景图片轮播：多张图片按顺序或随机轮播，可配置透明度和切换间隔。
• 背景视频：支持本地视频或 http(s) 视频地址，可配置循环、静音与 object-fit。
• 背景媒体/默认气泡模糊：blur 0~40px，只作用于渲染层，不修改源文件。
• 根字号缩放 fontScale：通过根字号缩放文本，避免 Firefox 下 CSS zoom 导致的命中区域和弹窗定位异常。
• 深浅色自适应 token：深色模式保持合成波霓虹观感；浅色模式自动切换为浅底深字，避免白字看不清。
• 配置页快捷入口：在侧边栏「插件」→ 点击「dsh-theme-synthwave」进入插件详情页，在配置区块提供「打开配置文件」「复制路径」按钮，快速打开或复制当前 profile 的 config.dsh-theme-synthwave.jsonc。
• 媒体记录可移除：在配置页中可移除已设置的视频，并逐张移除图片列表中的任意图片，改动即时写回本地配置。
• 编辑安全：配置文件编辑器支持「取消」撤销未保存修改；配置文件解析出错时自动兜底为默认配置（不改动原文件），并在界面给出提示。

🚀 快速开始

1. 安装插件

   # 本地目录
   dsh plugin --profile web add link:<本仓库根目录>
   
   # Git 仓库（发布到 GitHub 后）
   dsh plugin --profile web add "git+https://github.com/<你的用户名>/dsh-theme-synthwave.git"
   
   # npm（发布后）
   dsh plugin --profile web add @1mlightyears/dsh-theme-synthwave
   

   Git 安装说明：git+ 安装拉取的是源码（不是构建产物），DSH/pnpm 会在安装后运行本包的 prepare 脚本，从 src/ 构建出 lib/。pnpm ≥10 出于安全默认拒绝运行 git 依赖的 prepare：第一次 add 会失败，dsh 会提示把 pnpm 打印的确切包键复制进该 profile 的 pnpm-workspace.yaml，例如：

   allowBuilds:
     '@1mlightyears/dsh-theme-synthwave': true
   

   然后重新执行 add 即可。建议锁定 commit（git+https://…git#<sha>），确保后续推送不会悄悄改变实际运行的代码。

   如果你的仓库是 monorepo 且插件在子目录中：

   dsh plugin --profile web add "git+https://github.com/<你的用户名>/<repo>.git#subdirectory=path/to/dsh-theme-synthwave"
   

2. 创建/编辑配置

   首次打开页面时，插件会自动在当前 profile 目录生成 config.dsh-theme-synthwave.jsonc（使用内置默认值）。你也可以参考 config.dsh-theme-synthwave.example.jsonc 手动创建。配置文件位于当前 profile 目录，而不是会话工作区。

3. 准备背景素材

   准备好图片/视频素材后，在配置界面上传（参见下方配置段落）。

4. 重启并刷新

   首次安装后重启 DSH，浏览器打开页面后硬刷新即可看到效果。之后修改 config.dsh-theme-synthwave.jsonc 只需硬刷新页面。

⚙️ 配置

也可以在侧边栏「插件」管理页中点击「dsh-theme-synthwave」进入插件详情页，直接打开或复制当前 profile 的配置文件路径。（DSH 0.1.6 起插件配置经 plugins.bundle.config 槽位呈现在插件管理页的详情页里，取代旧版「插件配置」列表卡片与「设置 → 插件」标签页。）

截图为 v0.2.x 的「设置 → 插件」旧位置；v0.3.0 起配置表单位于侧边栏「插件」管理页的插件详情页（点击「dsh-theme-synthwave」进入）。

插件会在当前 profile 目录（通常为 $DSH_HOME/profiles/<profile>/）查找 config.dsh-theme-synthwave.jsonc；不存在时自动用内置默认值创建一份。config.dsh-theme-synthwave.example.jsonc 是带逐项注释的参考模板，可直接照注释修改。

在插件详情页的配置表单中可直接完成常用操作：选择/上传图片或动态背景、从「当前背景媒体」列表移除动态背景或单张图片、通过 URL / 裸文件名快速应用媒体源、设置动态背景的自动播放策略与缓存时长、一键清理所有已缓存的动态背景，以及编辑配置文件原文（「保存」写入，「取消」撤销未保存修改）。若配置文件解析失败，插件会临时套用默认配置且不改动原文件，并在界面提示你删除该文件让其自动重建默认配置，或参考示例文件修复。

移动端自动播放说明：动态背景较大，为节省流量，移动端默认不自动播放（background.video.autoplay 默认为 never）。只要本机已缓存该动态背景（Cache Storage 命中；远程 HTTP 访问等非安全上下文没有 Cache Storage，此时按缓存天数内的浏览器 HTTP 缓存命中与本地加载记录判定），就会自动播放、不再消耗流量；否则页面会显示一个按钮等待用户授权——内容已在本机时为「播放背景视频（无需流量）」（例如自动播放被浏览器策略拦截的场合），未缓存时为「加载动态背景」（按需标注文件大小，远程 URL 大小未知），点击后才下载并播放。按钮拦截期间背景会先展示定格首帧（字节已就位时）或图片轮播（未配置图片时为默认气泡）兜底。

一个不带注释的精简示例：

{
  "textGlow": {
    "enabled": true,
    "alpha": 0.6,
    "hoverAlpha": 0.85,
    "blurEm": 0.30,
    "colors": ["#ff2a6d"],
    "hoverColors": ["#05d9e8"],
    "suppressHoverFill": true
  },
  "fontScale": 1.15,
  "background": {
    "baseAlpha": 0.5,
    "blur": 2,
    "defaultEffect": 1,
    "video": {
      "path": "background.mp4",
      "loop": true,
      "muted": true,
      "objectFit": "cover",
      "autoplay": "never",
      "cacheDays": 30
    },
    "images": {
      "paths": ["background.jpg"],
      "alpha": 0.85,
      "intervalMs": 60000,
      "order": "sequential"
    }
  }
}

修改 config.dsh-theme-synthwave.jsonc 后，浏览器硬刷新页面即可重新拉取配置；安装/卸载插件本身才需要重启 DSH。

🔌 服务端点

路径	说明
GET /synthwave-theme-config	返回解析后的 JSON 配置（含configPath），供浏览器端应用。
POST /synthwave-theme-config/open	使用系统默认方式打开当前 profile 的配置文件。
POST /synthwave-theme-config/remove	移除动态背景记录，或从图片列表中移除指定图片，并写回配置。
POST /synthwave-theme-config/video-options	设置动态背景的自动播放策略（autoplay）与缓存天数（cacheDays）。
GET /synthwave-theme-media/<文件名>	读取并返回背景图片/动态背景字节（上限 512MB，按缓存天数带 Cache-Control）。

❓ 常见问题

• 背景媒体没有显示：确认 config.dsh-theme-synthwave.jsonc 位于当前 profile 目录、媒体路径可解析，并已硬刷新页面。相关参数说明见 config.dsh-theme-synthwave.example.jsonc。若配置了视频：视频等待加载（按钮）或获取失败期间会自动展示图片轮播（未配置图片时为默认气泡）兜底，视频播放后被覆盖。
• 视频没有声音：背景视频默认静音，这是浏览器自动播放策略的预期行为；详见 config.dsh-theme-synthwave.example.jsonc 中的 video.muted 注释。
• 移动端动态背景不自动播放：这是为节省流量的刻意设计（见上文的“移动端自动播放说明”）。点按「加载动态背景」按钮即可播放；本机已有缓存时会自动播放。
• 如何清理缓存的动态背景：在配置页的「动态背景选项」中点击「清理所有缓存动态背景」，会删除浏览器本地的动态背景缓存并提示已清理的数量与总大小。

📁 项目结构

.
├── src/
│   ├── host/
│   │   └── index.ts          # host 端：读取配置、服务媒体与配置端点
│   └── client/
│       ├── index.ts          # client 端：token / glow / 背景 / 模糊 / 字号缩放
│       └── ConfigForm.ts # 配置表单：打开/复制配置文件、媒体管理与编辑器（挂载于插件管理页）
├── lib/                      # 构建产物（勿手改）
│   ├── index.js
│   └── client.js
├── build/                    # vendored DSH client-bundle 构建 preset
├── cordis.patch.yml          # bundle 补丁
├── tsdown.config.ts          # tsdown 构建入口
├── config.dsh-theme-synthwave.example.jsonc  # 配置模板
└── package.json

🛠️ 开发

pnpm install   # 同时会触发 prepare 脚本自动构建 lib/
pnpm build     # tsdown → lib/index.js + lib/client.js

构建产物输出到 lib/，发布前无需手动修改 lib/ 内容。注意：host 端代码在 DSH 进程启动时加载，修改后需要重启 dsh --profile web 进程；仅刷新浏览器只会重载 client 端。

📄 License

Apache-2.0