前言¶

DSH 网页端跑久了，界面就是一片实色：画布底色、侧边栏底色都是固定的语义色 token。想换张背景图，通常只有两条路：要么改主题文件覆盖 --dsw-alias-bg-base、--dsw-specific-sidebar-fill，改完哪些组件会跟着变、深浅色模式各是什么效果，往往要靠反复试；要么干脆不动，接受默认外观。

dsh-wallpaper 走的是另一条路：照片放在页面最底层的固定图层上，画布和侧边栏改成半透明语义色让图透出来，其余卡片、按钮、文字配色原样不动。所有参数集中在「设置 → 壁纸」里实时调。下面介绍它的定位、安装和用法。

这是什么¶

dsh-wallpaper 是 DSH 生态里的一个网页端客户端插件，维护者是 dingzhen-114514，仓库在 https://github.com/dingzhen-114514/dsh-wallpaper ，社区目录页在 https://www.skillhub.cn/plugins/dingzhen-114514/dsh-wallpaper 。它解决的问题很窄：给 DSH 网页端（桌面版或 dsh web）加一张照片背景，并提供一组不用重启就能生效的实时设置。

它属于「趣味换装」分类，仓库当前 1 star，license 为 MIT。

核心功能¶

下面是 README 中列出的能力，均可核对。

• 真实背景图：一个 background-size: cover 的固定图层，窗口缩放、页面滚动都不跑位。
• 只覆盖两个语义色：画布 --dsw-alias-bg-base 和侧边栏 --dsw-specific-sidebar-fill。组件自身的卡片、按钮、文字配色不动，深浅色主题各自保留原色相。
• 五个可调参数：画布透明、侧边栏透明、薄纱、亮度、柔化（模糊）。拖动即时生效，防抖后写入 Host。
• 换图：点「选择图片…」或把图片拖进面板，支持 webp / png / jpg / jpeg / gif / avif / bmp，单张上限 24 MB，按扩展名给出正确 Content-Type。
• 一键恢复内置图：清空当前图片，回到仓库自带的 assets/placeholder.webp。
• 失败隔离：Host 半边零静态 import、逐条路由 try/catch；浏览器半边声明 inject: ['slots']。任何一步失败只会让设置页或背景消失，插件条目照常激活。

安装与启用¶

前置条件是 DSH 0.2.1 及以上，桌面版和 dsh web 都适用，插件跑在网页端。

README 给出的安装方式是把仓库克隆到本地，然后用自带的脚本挂进 profile：

git clone https://github.com/dingzhen-114514/dsh-wallpaper.git
cd dsh-wallpaper
node scripts/install.mjs            # 默认装进 desktop 配置
# node scripts/install.mjs --profile work    # 或者指定另一个 profile

脚本只做三件事，全部是本地目录操作，不发布到 npm：

1. 在 ~/.dsh/profiles/desktop/node_modules/@local/dsh-wallpaper 建一个指向本仓库的目录链接（不复制文件，改代码立即生效）；
2. 给 profile 的 package.json 加上 "@local/dsh-wallpaper": "link:<本仓库路径>"；
3. 把包名加进 dsh.profile.bundles，包内自带的 cordis.patch.yml 会在启动时插入加载行。

然后要重启 DSH。 配置里的 bundle 列表只在启动时读取、不监听变化；重启后打开「设置 → 壁纸」。包名带 @local/ 作用域，是因为它通过 link: 装进 profile、不发布到 npm，clone 到哪个目录都行。

卸载同样走脚本：

node scripts/install.mjs --remove   # 移出 bundles、删掉依赖与链接

重启 DSH 即恢复原样。个人设置仍在 ~/.dsh/wallpaper/，想彻底清掉连这个目录一起删。

典型用法¶

打开「设置 → 壁纸」，界面是下面的一组控件，括号里是 README 给出的默认值：

「图片」卡片里可以预览当前图、选择新图（或拖放）、恢复内置图。底部状态行会显示「已保存」「已恢复内置图」这类结果。

换成自己的图¶

README 给了三种方式，任选其一：

1. 设置页里点「选择图片…」或拖放，存到 ~/.dsh/wallpaper/wallpaper-<时间戳>.<扩展名>；
2. 把图直接存成仓库根目录的 wallpaper.webp，这个文件已被 .gitignore 忽略，不会误提交别人的图；
3. 不想要内置图时什么都不用做，assets/placeholder.webp 自动兜底。

实现上值得留意的一点¶

照片本身在固定层，应用本体在上一层。浏览器半边把设置写成 documentElement 上的 CSS 变量：--dw-canvas-a、--dw-sidebar-a、--dw-veil-a、--dw-brightness、--dw-blur、--dw-image。样式表用这些变量合成浅色（rgb(255 255 255 / var(--dw-canvas-a))）和深色（rgb(21 21 23 / var(--dw-canvas-a))，由 body[data-ds-dark-theme] 区分）两版底色。因为只改语义别名，任何依赖 --dsw-alias-* 的组件都会自动得到正确的对比度，不需要逐个组件打补丁。

图片 URL 带 ?rev=<mtime>-<size>，换图后浏览器不会拿旧缓存。

Host 和浏览器两边的配合大致如下。数据落在 ~/.dsh/wallpaper/state.json（$DSH_HOME 优先），启动诊断写 ~/.dsh/wallpaper/boot.log。插件提供四条路由：

state.json 的字段是 enabled、image（绝对路径或 null）、canvas、sidebar、veil（0–100）、brightness（50–150）、blur（0–12）。

README 还写了两条写 DSH 客户端插件时的硬约束，值得单独记：

1. 浏览器半边必须在自己导出的插件对象上写 inject: ['slots']。Cordis 的 context 是代理，读未声明的服务属性会直接抛 cannot get property "slots" without inject，这个异常会让整个客户端条目激活失败，桌面壳报成 web boot: 1 entry did not activate，页面起不来，只能禁用插件。
2. Host 半边不要写静态 import，路由逐条 try/catch。某条路由注册失败时插件仍然激活，错误落在 boot.log，不至于把装饰性插件变成启动阻断。

排错入口有两个：~/.dsh/wallpaper/boot.log 看 Host 激活与每条路由的结果；桌面壳的网页端启动崩溃报告在 %APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-web-boot.log。

适用场景与注意¶

适合的场景很明确：想在 DSH 网页端或个人配置里放一张背景图，同时不希望卡片、按钮、文字的颜色被背景对比度带跑。它只动画布和侧边栏两处语义色，改的是视觉氛围，不是主题。

安装前需要注意几件事：

• 这个插件是社区插件，与 DeepSeek / 幻方没有官方从属关系，目录页也是独立站点。插件以当前 DSH 进程的权限运行，会读写 ~/.dsh/wallpaper/ 下的文件并提供 HTTP 路由，安装前应读完源码、确认许可证（MIT）和 files 里打包的脚本。
• README 声明的验证环境是 Windows + DSH 桌面版 0.2.1-rc.5（Electron 44 / Node 24）。Host 半边只用 ctx.webServer.register 与 node:fs，路径全部走 DSH_HOME，据称 dsh web 与桌面版通用，但其他平台没有列出验证结论。
• 安装脚本在非 Windows 上退化为普通符号链接，junction 类型仅在 Windows 生效。
• 如果同时装了别的改主题插件，两边都写 --dsw-alias-bg-base，最终效果取决于加载顺序。
• 仓库自带的 assets/placeholder.webp 是程序生成的渐变图，可直接使用。自己提交图片时只提交拥有权利的文件。

结尾¶

dsh-wallpaper 做的事情很小：一张照片、两个语义色、五个可调参数，换来的是一个不用重启就能反复试的网页端背景。它把失败面控制在装饰层，不会把启动流程拖住，这才是它真正值得借鉴的地方。

目录页：https://www.skillhub.cn/plugins/dingzhen-114514/dsh-wallpaper

GitHub：https://github.com/dingzhen-114514/dsh-wallpaper