背景替换 DevTarlow/dsh-background-swapper

背景替换

把你自己的照片放到 DeepSeek Harness 后面。

两种不同的背景。右边那张太空照片把 Blur 调高了。

Swap Background 就在左侧边栏 Settings 上方。点一下会打开一个小面板，你可以在里面添加照片、给它起名字，还能收藏一组常用背景。三个预设一键设定界面与照片之间的平衡，五个滑块微调照片的观感和透出程度，任何你喜欢的平衡都能以自己的名字保存下来。

你能做什么

- 添加照片。 把照片拖到面板上，或者选一个文件，起个名字，它就变成你的背景。
- 建一个图库。 每张保存的照片都会列在 Recent 里，最新的排在最前，每页六张。点一张就能切过去。
- 重命名或删除。 铅笔图标重命名，垃圾桶图标删除，Remove all photos 清空整个图库。
- 预设。 Wallpaper、Glass 和 Solid 一次设定全部三个不透明度滑块，当前选中的那个会保持高亮。Tint 和 Blur 不受影响，所以试预设永远不会毁掉你调好的照片。
- 保存你自己的观感。 同一行的 Save current 把三个不透明度按你起的名字存下来，这样你试完 Glass 还能一键找回自己的平衡。你的观感就排在自带预设旁边那一行，每个都带一个小 × 可以删掉，最多保留六个。
- Background opacity。 所有内容背后那一页有多实。调低它，照片就填满空白区域；调到 0% 照片完全裸露。初始值是 20%。
- Element opacity。 那一页之上的卡片、输入框和菜单有多实。调高它，照片在后面依然明亮的同时文字还能看清。初始值是 85%。
- Sidebar opacity。 左侧那一栏有多实。它单独移动，所以导航可以保持清晰，而面板变成玻璃质感，反过来也行。初始值是 85%。
- Tint。 一个滑块，从 Darken 100% 到 Lighten 100%，用在亮照片上文字难读的时候。
- Blur。 柔化照片，从 0 到 24 像素。
- Turn off。 隐藏照片，把界面恢复原样。什么都不会删。

安装

你需要 DeepSeek Harness，在浏览器或桌面应用里运行都行。

1. 在 Harness 里打开左侧边栏的 Plugins。
2. 按 Install。
3. 粘贴这个仓库的地址：

https://github.com/DevTarlow/dsh-background-swapper

4. 安装，然后刷新页面。

如果你更想用本地副本，就克隆仓库，改成粘贴文件夹的完整路径。安装对话框接受 GitHub 地址、包名或本地文件夹。
插件会加入你的 Harness，因此在你移除它之前，每个会话里都能用。

使用

Background 面板：当前照片、上传区域、Appearance 滑块，以及 Recent 图库

1. 点击 Settings 上方的 Swap Background。
2. 在 Add a photo 下，把图片拖到虚线框上，或按 Choose file。如果照片某一边超过 2560 像素，会先缩小，面板会告诉你发生了缩放。
3. 输入名称，按 Save。照片会被存下来，并立刻成为你的背景。
4. 从 Appearance 里的预设开始 —— Wallpaper、Glass 或 Solid —— 然后调整图库上方的滑块。拖动时就会生效，松手后片刻即保存，所以这些都没有 Save 按钮。看到满意效果后，按 Save current，输入名称，再按 Save，把这套搭配留到以后用。
5. 点击 Recent 里任意缩略图即可切换照片。Turn off 会清除当前照片，但不会删除它。

按 Escape，或点击面板外任意位置，即可关闭。

你的照片

照片存放在 Harness 里，不在插件内部：

~/.dsh/storages/background-swapper/
├── index.json your names, the current photo, the slider settings, and your saved looks
└── images/ one file per photo

除非你改过位置，Harness 的数据都放在 ~/.dsh。在 Windows 上，文件夹是 %USERPROFILE%\.dsh\storages\background-swapper。

照片存在那里，所以只要你打开的所有浏览器和桌面应用都指向同一个 Harness，它们看到的图库和外观就完全一致。

要备份图库，把那个文件夹复制到安全的地方。想从头开始，就删掉它：插件下次加载时会重新创建。

可选设置

插件加载时会从 cordis.patch.yml 读取这四个值。改完要重启 Harness。

| 设置 | 默认值 | 作用 |
| pageSize | 6 | Recent 里每页显示多少张照片。 |
| maxImageBytes | 16777216（16 MB） | 允许上传的最大照片。 |
| maxDimension | 2560 | 保存前照片最长边缩小到的尺寸。 |
| dataDir | 空 | 照片存放位置。留空表示上面显示的文件夹。 |

如果你更想用自己的值，就把同样的覆盖写进 Harness 配置档的补丁文件，这样以后重装也不会被替换掉：

- id: background-swapper
config:
pageSize: 9
maxImageBytes: 33554432

新安装默认使用 Wallpaper 预设 —— Background opacity 20%，Element opacity 和 Sidebar opacity 85% —— Tint 为 None，Blur 关闭。每个滑块旁的 Reset 链接会把它恢复成这些值，也就是 Wallpaper 设定的搭配。你保存的外观初始为空，和其他设置一起放在 index.json 里。

常见问题

照片太淡了，或者太抢眼。 用 Background opacity 调。调低，打开页面时照片露得更多；调高，页面更实。到 100% 时，照片只能从面板和侧边栏透出来；如果 Element opacity 和 Sidebar opacity 也都是 100%，那就什么都看不见了，面板上会这么提示。

界面太透，看不清。 调高 Element opacity；如果是左栏的问题，就调高 Sidebar opacity。两者都只让自己那一层变实，不会把照片从页面上拿掉，所以你不必再二选一。滑块淡化的是不同层：Background opacity 是承载一切的页面，Element opacity 是上面的面板，Sidebar opacity 是旁边的左栏。

照片上的文字难读。 设置 Tint 把它压暗，或者用 Blur 把它柔化。两者都保留效果；调高不透明度滑块只会把照片更多地藏到那一层后面。

预设会改什么？ 只改三个不透明度滑块——自带的和你保存的都一样。Tint 和 Blur 保持你离开时的样子，所以试预设永远不会毁掉调好的照片。Solid 保留选中的照片，但把它藏在完全不透明的界面后面；Turn off 则直接清掉照片。两者都会把它留在 Recent 里，点一下就能找回来。

我保存了一个外观，它去哪了？ 在预设行里，挨着 Wallpaper、Glass 和 Solid，右边有个小 × 可以删掉它。它和你的其他设置一起存在 index.json 里，所以每个浏览器和桌面应用里都有。最多保留六个。

为什么侧边栏看起来比别处更暗？ 侧边栏后面叠了两层半透明表面，主区域后面只有一层，所以滑块数值相同时，它总是显得更实一些。调低 Sidebar opacity 就能让它们一致。

换个浏览器还能用吗？ 能。库和设置都跟着 Harness 存，所以任何浏览器指向它，看到的都一样。

每个会话能有自己的背景吗？ 不能。一个背景作用于整个应用。

能用哪些图片格式？ PNG、JPEG、WebP、GIF 和 AVIF。动图 GIF 会继续动。SVG 文件会被拒绝。

上传后我的照片看起来不一样了。 任何一边超过 2560 像素的图片，保存前都会缩小，而缩小后的照片会重新编码，这会丢掉拍摄日期、位置之类的相机元数据。动图 GIF 永远不会被缩小。

移除它

打开 Plugins，找到 dsh-background-swapper，卸载它。界面立刻恢复正常。你的照片还留在上面那个文件夹里，所以如果想把磁盘空间也收回来，请自己删掉那个文件夹。

面向开发者

两个文件加一个存储辅助模块，没有构建步骤。

| 文件 | 运行于 | 负责 |
| index.js | Harness | apply(ctx, config) 和 /__background-swapper 路由 |
| store.js | Harness 侧 | 磁盘上的 index.json 和 images/ |
| client.js | 浏览器侧 | 背景绘制器和侧边栏面板 |

改动之前需要了解的事：

- 它不导入任何未提供给它的东西。 Harness 侧只用 Node 内置模块，浏览器侧只用 Web shell 已经提供的 React。正因如此，它才能在已发布的 dsh 上加载，无需构建。
- 照片绘制在 html::before 上，这是一个固定定位的伪元素，位于所有内容之后，所以应用自身的元素不受影响。
- 透视效果重新定义了主题的背景变量，用 color-mix() 混合它们原本就指向的同一组调色板色调。这些别名分成三组：框架和主体绘制的底色、浮在其上的面板、侧边栏列，每个滑块淡化一组。没有针对任何应用类名，所以重命名类名不会破坏任何东西。保存的外观就是这组 alpha 值加一个名称，因此加载它不会改变其他任何东西。
- 插件添加的一切都由 React 渲染，所以卸载它会精确还原界面。没有任何东西写入 document.body，也没有手动追加样式表。
- 上传会经过校验，id 会在索引中查找，所以请求永远无法指定磁盘上的路径。maxImageBytes 在 Harness 侧强制执行，maxDimension 在浏览器侧执行。
- PATCH /state 会拒绝它不认识的字段，而不是忽略它。两半一起发布，但分别加载——否则浏览器侧领先一个版本时，它的写入会收到 200 然后被丢弃，面板会显示某个设置已保存，下次重新加载时却消失了。
- 滑块的默认值只存在一处，即 store.js 中的 DEFAULT_SETTINGS，并随每次 GET /list 一起返回，这样面板的 Reset 链接就不会偏离它们。面板的 Wallpaper 预设重复了这些相同的数字，所以全新的库和 Reset 都会点亮它：改一个，另一个就该在同一个提交里改。

npm test

两个测试 harness 都在一秒内跑完，不需要浏览器。test/host.test.mjs 把路由挂载到裸的 node:http 服务器上，通过真实 HTTP 驱动整个接口面。test/client.test.mjs 把浏览器 bundle 加载到 stub 模块加载器上，检查注册项、绘制器输出的确切 CSS，以及面板的预设行：加载一个随附的外观、保存一个你自己的、再删除它。

编辑 client.js 然后刷新页面。编辑 index.js、store.js 或 cordis.patch.yml 然后重启 Harness。AGENTS.md 有完整的循环。

License

MIT。