前言¶
DSH 的界面背景默认是固定的。想在开发工作台里放几张自己的图片、或者一段视频循环播放，通常要手改主题文件和 CSS，改完顺序、间隔、透明度也都没处调。dsh-bg-carousel 把这件事做成了一个标准插件：把媒体文件丢进一个目录，界面背景就能自动轮换，目录、顺序、间隔、透明度都在面板里配置。
下面介绍这个插件的定位、核心功能、安装步骤和典型用法。
这是什么¶
dsh-bg-carousel 是一个标准 dsh bundle 插件，由 Jonah-Wu23 维护，当前版本 v0.3.0，npm 包名 @jonahwu/dsh-bg-carousel，代码采用 MIT License。一句话定位：图片与视频自动轮换的 DeepSeek Harness 界面背景。
它适配 dsh v0.1.2-rc.1 的 web 界面，架构分两端：
- 宿主端扫描媒体目录，通过 webServer 提供媒体路由与 API；
- 客户端在侧边栏底部注册「背景」入口，负责控制面板与背景渲染。
核心功能¶
图片与视频背景¶
图片支持 JPEG、PNG、WebP、SVG、GIF，按 body 背景渲染，表面叠一层压暗色，随亮暗主题自动取值。视频支持 MP4、WebM、MOV、HLS、FLV，静音自动播放，以 cover 方式铺满视口。
格式兼容性有环境差异：HLS 由 Safari 原生支持；FLV 需要 MSE 类扩展（如 flv.js）；Chromium 环境下这两类文件自动跳过，轮播继续。MOV 能否播放取决于容器内编码，H.264 通常可以播放。
混合轮换¶
图片和视频在同一个队列里轮换，推进规则如下：
- 间隔短于视频时长：截断当前视频并切换下一个；
- 间隔长于视频时长：视频播完后立即切换；
- 视频卡死：由定时器兜底推进。
环境限制自动播放时，视频停在首帧，定时器照常推进；无法解码的文件自动跳过并在浏览器控制台记录原因；全部媒体失败时暂停轮播并在面板提示。
顺序与透明度¶
缩略图支持拖拽排序，顺序立即生效并持久化到服务端设置，新增文件按字母序排在末尾。「面板不透明」滑杆实时调整界面 token 透明度，对图片和视频同样生效。
目录与缩略图¶
媒体目录可以在面板内手输，也可以点「选择」按钮调起宿主原生目录选择器（Windows 为系统文件夹对话框），支持绝对路径与工作区相对路径。「打开文件夹」由宿主在系统文件管理器中打开当前媒体目录，不依赖浏览器 file:// 链接。目录不可用时回退默认目录（工作区 backgrounds）并提示，轮播照常。
大图在宿主端按 320px 生成 JPEG 缩略图缓存（Windows 走 PowerShell System.Drawing），缓存目录在 ~/.dsh/bg-carousel/thumbs/；缩略图懒加载 + 异步解码，上百张高清图面板也不卡。
安装与启用¶
插件需要 webServer 与 client UI，建议安装到 web profile（或任何包含 @deepseek-ai/dsh-web-app 的 profile）；装到其他 profile 时插件静默待命，不影响启动。「选择目录」与「打开文件夹」依赖 dsh v0.1.2-rc.1 组合的 directoryPicker / openWorkspacePath 能力，插件不兼容 dsh v0.1.1-rc2 与 v0.1.2-alpha.1 之前的版本，安装前先确认 dsh 版本。
以下安装命令需要 pnpm 在 PATH 中，三种方式任选其一，每次只执行一条。
git 源安装：
dsh plugin --profile web add github:Jonah-Wu23/dsh-bg-carousel
或者直接装 GitHub Release 里的 tgz：
dsh plugin --profile web add https://github.com/Jonah-Wu23/dsh-bg-carousel/releases/download/v0.3.0/jonahwu-dsh-bg-carousel-0.3.0.tgz
也可以用本地路径，<...> 处填 tgz 文件路径或插件目录路径：
dsh plugin --profile web add <本地 tgz 或目录路径>
安装后重启 dsh 生效。卸载执行：
dsh plugin --profile web remove @jonahwu/dsh-bg-carousel
想从源码构建，需要一份 dsh 源码 checkout，PATH 中有 bash 与 Node.js，然后执行：
DSH_CHECKOUT=<dsh 源码 checkout> bash scripts/build.sh
脚本使用 checkout 内的 tsc 编译宿主端，tsdown 打包 client。运行时零新增依赖：client 只 require 平台种子模块 react，未引入 hls.js 或 flv.js，环境不支持的格式自动跳过。
典型用法¶
1、把图片和视频复制到媒体目录。默认是工作区的 backgrounds 目录，可以在面板里修改。注意大小限制：图片上限 64 MiB、视频 256 MiB。
2、重启 dsh 后，点击侧边栏底部的「背景」入口打开控制面板，面板会自动加载当前目录的媒体清单。
3、点击缩略图切换背景；拖拽缩略图排序；勾选「自动轮播」按设定间隔循环（intervalMs 取值 1500–120000 毫秒）；拖动「面板不透明」滑杆调整界面透明度（panelOpacity 取值 0.1–0.95）。
服务端 API¶
做二次开发或排查问题时，宿主在 {workspaceRoot} 下挂载了这些媒体路由与 API：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /dsh-bg/img/<name> |
按文件名返回媒体字节，缓存 1 小时，图片上限 64 MiB、视频 256 MiB |
| GET | /dsh-bg/thumb/<name> |
返回 320px JPEG 缩略图，未命中先回退原图字节并后台补生成 |
| GET | /dsh-bg/api/list |
返回 images、videos、media（混合清单）、dir、dirError 与设置 |
| POST | /dsh-bg/api/image |
按文件名返回 base64 data URL，限制 12 MiB，兼容旧版 client |
| POST | /dsh-bg/api/settings |
更新 intervalMs（1500–120000）、enabled、panelOpacity（0.1–0.95）、mediaDir、order |
media 为 {name, kind: 'image' | 'video'}[]，已按 order 排序；dirError 非空表示配置目录不可用、已回退默认目录。
适用场景与注意¶
适合的人群：想在 DSH 工作台放个人化背景又不想手改主题文件的开发者；有一批壁纸想按顺序或定时间隔轮换的；想在背景放一段循环视频的。
使用前注意：
- 插件以当前 dsh 进程权限运行，会读取媒体目录、写入缩略图缓存与服务端设置。安装前建议检查源码与许可证（MIT），确认无误再装；
- 插件基于 dsh v0.1.2-rc.1 开发，旧版本 dsh 下「选择目录」与「打开文件夹」不可用，甚至无法正常安装；
- 视频格式的可播性取决于浏览器环境，Chromium 下 HLS 与 FLV 会被自动跳过。
结尾¶
dsh-bg-carousel 用一个媒体目录加一个控制面板，把 DSH 界面背景的替换、图片视频混合轮播、排序和透明度这几件事串了起来，轮换推进和格式兼容的处理也比较细。装好插件、把文件复制进目录就能用。
- 社区插件目录（独立站点）：https://www.skillhub.cn/plugins/Jonah-Wu23/dsh-bg-carousel
- GitHub 仓库：https://github.com/Jonah-Wu23/dsh-bg-carousel
