媒体壁纸 laoye666-6/dsh-plugin-media-wallpaper

dsh-plugin-media-wallpaper

DeepSeek Harness（DSH）壁纸插件 —— 在 Web UI / 桌面版中更换图片或视频背景。

纯客户端插件：零服务端逻辑，所有设置保存在浏览器本地（localStorage），壁纸文件保存在浏览器 IndexedDB（支持大体积视频）。官方 Web 版与各类桌面版（Electron 壳）行为完全一致。

命名说明：npm 包名与 GitHub 仓库均为 dsh-plugin-media-wallpaper（npm 原名 dsh-plugin-wallpaper 已被他人占用，故改名）。

功能

- 图片 / 视频背景：GIF、动图 WebP、APNG、静态 PNG / JPEG 图片；MP4、WebM 视频（自动循环静音播放）
- 格式自动识别：按文件魔数嗅探（非扩展名），设置面板显示识别徽标
- 自带画质调节：压暗（0–90%）、亮度（20–200%）、高斯模糊（0–40px，自动防边缘露底）
- 界面色调跟随背景：canvas 取样主色混入界面表面（强度可调），视频播放时自动跟随画面变化
- 填充方式：填满（裁剪）/ 适应（完整显示）/ 拉伸 / 平铺
- 逐组件透明化：侧栏、顶栏（标题栏）、主内容区、右栏、卡片面板五个独立开关 + 表面不透明度滑杆
- 双设置入口：侧栏 → 设置 → 「壁纸」分区；以及 插件管理 → 本插件详情页
- 自动尊重系统「减弱透明度」可达性偏好；插件停用后界面完全还原（含样式回收）

版本兼容

- 面向 DSH 0.2.x（npm @deepseek-ai/dsh latest 0.2.0-rc.2 / master，机制已于 2026-10-03 对照 dsh-v0.2.1-alpha.1 源码逐项核对）
- 依赖的官方机制：dsh.client 清单、懒 CJS 工厂包装（window.__ModuleLoader__.load）、平台冻结模块表（react / react/jsx-runtime）、settings.section 与 plugins.detail.section 插槽、语义 token（--dsw-alias-* / --dsw-specific-sidebar-fill）、样式归属标记（data-plugin）
- AppFrame 结构识别失败时自动进入全局 token 兜底模式，不会白屏

构建（仅开发时需要）

cd dsh-plugin-wallpaper
npm install
npm run build # 产出 lib/index.js + lib/client.js
npm run typecheck # 可选：tsc --noEmit
npm run smoke # 可选：Node 最小 DOM 桩自检

安装使用无需构建：仓库内已提交预构建产物 lib/，git 安装直接可用。

安装到 DSH

方式一（推荐，国内网络）：npm 源安装 —— 自动走你配置的镜像（如 npmmirror.com），不触碰 GitHub：

dsh plugin --profile dshwallpaper add dsh-plugin-media-wallpaper
dsh --profile dshwallpaper # 启动该组合

方式二：GitHub 一条指令安装（任何机器）：

dsh plugin --profile dshwallpaper add github:laoye666-6/dsh-plugin-media-wallpaper

- 仓库内置预构建产物，拉取即用；插件无构建脚本，pnpm ≥ 10 亦无需授权（无需 allowBuilds）
- 首次使用会自动初始化 profile（以 @deepseek-ai/dsh-base 为第一个组合包）
- 安全建议：可锁定提交安装 —— github:laoye666-6/dsh-plugin-media-wallpaper#<commit-sha>

方式三（本机开发路径）：

dsh plugin --profile dshwallpaper add "E:\Deepseek Harness\dsh-plugin-wallpaper"

方式四（开发调试，免安装）：

dsh web --patch "E:\Deepseek Harness\dsh-plugin-wallpaper\cordis.patch.yml"

关于 profile 名（示例用 dshwallpaper；profile = DSH 的命名配置组合，位于 $DSH_HOME/profiles/<名字>/，决定启动时加载哪些 bundle）：

- 名字自己取，首次安装时不存在会自动创建（以 @deepseek-ai/dsh-base 初始化）；之后启动也用同名
- 自己命令启动：装和启用用同一个名字即可
- 桌面版（Electron 壳）：若其启动参数/快捷方式带 --profile xxx，就用那个名字安装，保证插件装进壳实际使用的组合
- 验证是否装对：dsh --profile dshwallpaper --dump-config，输出出现 # == dsh-plugin-media-wallpaper 一层即成功

安装后重启 dsh web 或桌面版客户端。

使用

1. 打开 设置 → 壁纸（或 插件管理 → Wallpaper 详情页）
2. 点击「选择图片 / 视频」，选择本地文件（格式自动识别）
3. 按需调整填充方式、模糊 / 亮度 / 压暗、色调跟随
4. 在「组件透明化」里控制各区域：开关开启 = 该区域透出壁纸（默认全开）；关闭 = 恢复该区域不透明（依赖结构识别，失败时该区域保持透明）
5. 「清除壁纸」删除文件并还原界面；「恢复默认」重置全部设置

验收清单

- [ ] 分别选择 GIF / APNG / 动图 WebP / PNG / JPEG / MP4 / WebM，徽标显示正确，背景正常渲染
- [ ] 视频自动循环静音播放，无声音、不挡鼠标
- [ ] 四种填充方式生效（视频平铺按填满处理并有提示）
- [ ] 模糊 / 亮度 / 压暗拖动即时生效且互不影响界面文字
- [ ] 开启色调跟随：界面表面混入壁纸主色；视频播放时色相随画面变化
- [ ] 五个透明开关分别只影响目标区域；表面不透明度滑杆生效
- [ ] 亮 / 暗主题切换后透明化颜色仍正确
- [ ] 禁用插件 / 清除壁纸后界面完全还原、无残留样式

已知限制

- 视频平铺（tile）改用「填满」代替（ 无法平铺）
- 色调取样对动图取首帧（对色调跟随足够稳定）
- 壁纸文件存于浏览器 IndexedDB：清理浏览器数据会丢失壁纸与设置（重新选择即可）
- 透明化基值取自官方 design-platform.css 当前语义（bg-layer 静态值含亮 / 暗分支）；若官方大版本重构 token，需同步更新 src/client/styles.ts

发布流程（维护者）

1. 修改代码 → npm run build && npm run typecheck && npm run smoke
2. 提交（必须包含更新后的 lib/，git 安装用户拿到的是预构建产物）
3. 发布，按渠道：
- npm（国内推荐渠道）：npm login 后执行 npm publish；npmmirror 会自动同步（也可 curl -X PUT https://registry.npmmirror.com/-/package/dsh-plugin-media-wallpaper/syncs 催一下）
- GitHub：网络可达时 git push origin main --tags（首次远端为 API 引导的历史，需 --force 对齐）；git push 不通时 npm run publish:api -- "commit message" 经 REST API 整树发布
4. 安装端锁定版本建议：npm 固定 dsh-plugin-media-wallpaper@<version>；GitHub 固定 #<commit-sha>

目录结构

├── package.json / cordis.patch.yml # dsh.bundle + dsh.client 声明 ├── scripts/build.mjs # esbuild 构建 + 官方懒 CJS 工厂包装 ├── scripts/smoke.mjs # Node 桩自检（包装格式/装配/插槽/投影/清理） ├── scripts/publish-api.mjs # 经 GitHub REST API 发布（git push 被阻断时的替代通道） └── src/ ├── index.ts # Host 半侧（空实现，纯客户端插件） └── client/ ├── index.ts # 浏览器入口（装配/清理） ├── state.ts # 设置 store + localStorage ├── storage.ts # IndexedDB 媒体存储 + objectURL ├── format.ts # 魔数格式识别 ├── layer.ts # 壁纸层（img背景/video + 滤镜 + 压暗） ├── surface.ts # AppFrame 打标 + 设置投影 + 兜底 ├── palette.ts # 主色取样（canvas 均值） ├── settings.tsx # 设置面板（双插槽复用） ├── styles.ts # 全局 CSS（data-plugin 归属标记） └── types.ts # 官方 API 的最小结构类型