kdzhang-hub/dsh-wallpaper

dsh-wallpaper（backdrop-bridge-dsh 0.6.0）

把本机 Wallpaper Engine 素材库带进 DeepSeek Harness：浏览、预览并一键设为自适应玻璃背景；需要时也可直接交给 Wallpaper Engine 或 Windows 桌面。

dsh-wallpaper 将本机 Wallpaper Engine 创意工坊、本地项目和你上传的图片集中到 Harness 侧边栏的一个「壁纸」入口。源码、问题追踪和安全更新以 GitHub 仓库 为准。

由于 npm 上已存在同名包 dsh-wallpaper@0.1.1，当前 npm 分发、CLI 与 DSH bundle 技术标识为 backdrop-bridge-dsh；这不影响项目和仓库名称 dsh-wallpaper。

你能做什么

- 管理同一份本地图库：自动发现 Wallpaper Engine 创意工坊和本地项目，也支持上传自己的图片；可按标题、标签和类型搜索筛选，新增素材会实时同步到图库，无法监听时自动降级为定时刷新。
- 一张壁纸，三个去向：设为 DeepSeek Harness 全窗口背景；交给 Wallpaper Engine 播放 Scene、视频或网页壁纸；或将静态图片设为 Windows 原生桌面壁纸。
- 让 Harness 随壁纸自适应：自动取色、半透明玻璃、暗化、亮度、铺满/完整显示、动图/视频播放或静态预览、手动双主题色和安全预设均可调整；设置会跨刷新和多窗口保留。
- 在不同窗口中都好用：右侧图库可拖动调宽，也支持键盘微调；窄窗口自动切为全屏，避免面板挤压内容。
- 让 Agent 也能控制：可让 DeepSeek 列出、搜索、随机切换壁纸，或清除 Harness 背景，并查询 Wallpaper Engine 与当前桌面状态。
- 默认只在本机工作：不上传壁纸、不发送遥测；Harness 背景与 Windows 桌面相互独立，不会误改另一端。

原 dsh-wallpaper-skin 的活动依赖已经合并到本插件；旧源码目录可以保留作回滚备份，但不应再与本插件同时加载。

开源许可、素材与归属

本项目代码和文档按 Apache-2.0 许可证发布。该许可只覆盖本仓库贡献者有权授权的内容；完整边界见 NOTICE.md。

- npm 包不包含 Wallpaper Engine 工程、Steam Workshop 下载、预览图、视频、scene.pkg 或用户上传内容。壁纸仍属于各自权利人，使用或再分发前由使用者自行确认许可。
- 本项目与 Wallpaper Engine、Steam、Steam Workshop、DeepSeek 和 DeepSeek Harness 的权利人没有官方关联、背书或赞助关系。
- 文中 ATRI-Theme-DSH 仅作为“背景 + 半透明面板 + 双强调色 + 可调设置”的视觉行为参考；本包不包含其角色素材、宿主核心补丁或构建哈希选择器。未来若引入外部代码或素材，维护者必须在 NOTICE.md 记录来源、版本和许可证。

公开发布前仍需要版权持有人填写真实的代码托管地址、问题追踪地址和私密安全报告渠道；原因及检查项见 PUBLISHING.md。

安全边界与 Harness 背景行为

- 背景层位于独立的负层级堆叠上下文并永久 pointer-events:none。宿主属性识别、媒体加载或其他皮肤适配失败时，只会关闭壁纸显示，绝不会隐藏聊天、SSH、文件区、编辑器或任何 Harness 交互。
- 图库是独立右侧抽屉，不替换聊天区；「壁纸」入口优先紧跟 SSH，SSH 缺失时才回退到任务板或“新建会话”。宿主侧栏重渲染后会校验父节点和相邻顺序再放回。
- 右侧抽屉左缘可拖动调宽，支持键盘左右方向键与 Home/End；宽度在本机浏览器保存，窗口窄于 760px 时自动全屏，避免横向溢出。

- MP4/WebM 使用独立的固定  层，静音、循环、cover 播放；页面隐藏时暂停，恢复可见时继续。
- Wallpaper Engine scene.pkg 不能由浏览器直接解码，因此使用项目的 preview.gif、preview.jpg 等预览图。
- 扫描时会读取预览分辨率（上传图片也会读取），并优先选择项目根目录中更高分辨率的 wallpaper / background / preview 图片。自动适配以全窗口铺满为优先：普通高清素材使用 cover，左右不会留空；需要保留完整画面时可手动选择“完整显示”。短边不足 720px 的 Scene 预览始终走“模糊环境填充 + 不模糊 contain 主体”，并按实际放大倍率做轻量细节与色彩补偿，避免把小图直接裁切拉满全屏；该补偿不会把低分辨率预览伪装成真实高清素材。
- 系统启用“减少动态效果”或视频加载失败时自动回退到预览图。
- 所有 GIF 背景都会从其自身帧延迟计算循环时长，并提前跳过末尾 15%（至少 120ms、最多 300ms）：插件在重置前会捕获接近安全结束点的当前帧，保持该冻结帧；新 GIF 在后台稳定约 140ms 后才淡入，以避免循环边界或首帧的黑/白闪屏。此策略不修改 Wallpaper Engine 原始文件；MP4/WebM 继续使用浏览器原生循环。
- 背景层 pointer-events: none，不接管鼠标或键盘事件；侧栏、对话区、文件区和 Composer 采用深色半透明玻璃与可调 backdrop-filter，形成可见毛玻璃质感。正文固定为高对比浅色以保证阅读，壁纸取色仍驱动边框、活动项和按钮。弹窗、菜单、代码和编辑器保持更高不透明度。
- 每次应用壁纸都会在浏览器内对当前图片或视频海报取色，自动派生面板、边框、按钮、活动项和悬停色；不依赖固定壁纸或本机主题。
- 「界面适配设置」可调背景暗化（0–100%）、壁纸亮度（50–150%）、铺满/完整显示、面板不透明度（15–90%）、输入区不透明度（30–100%）、毛玻璃强度（0–32px），并可在自动取色和手动双强调色之间切换。
- 可选安全预设仅定义双强调色、标题、空态和提示文案；不会接受 HTML、脚本、远程 URL 或任意 CSS，未选预设时完全使用自动适配。
- 自动模式从每张壁纸派生主强调色和第二强调色，分别驱动标题/活动项与主按钮/发送按钮；手动模式可覆盖两种颜色。默认暗色遮罩为 35%、面板不透明度为 52%、输入区不透明度为 84%、毛玻璃为 8px。
- 设置写入共享状态，刷新、重启和多窗口同步后仍保留。
- 共享状态原子保存到 ~/.dsh/dsh-wallpaper/skin-state.json，多个窗口通过 revision 轮询、窗口聚焦和 BroadcastChannel 同步。
- 首次启动且宿主尚无状态时，会尝试迁移旧键 dsh.wallpaperskin.skin；迁移成功后删除旧键。
- 「壁纸」入口由独立观察器固定在 SSH 下方；宿主侧栏重渲染把节点移动到其他位置时会自动放回。
- 打开图库后，插件会监听 Wallpaper Engine 创意工坊、本地项目和上传目录的变化，并以长轮询立即同步到图库；监听不可用的网络盘会自动降级为每 5 秒刷新一次。窗口恢复到前台时也会立即刷新。新下载的壁纸会自动出现在图库中，但绝不会未经操作自动替换当前 Harness 背景。
- 「动态背景」可在“播放动图 / 视频”和“静态预览（停止播放）”间切换。静态预览会冻结 Harness 中的 GIF 或视频画面，不会暂停 Wallpaper Engine 或修改 Windows 桌面。
- dsh-wallpaper install 从本地开发目录安装时会创建 Profile 内的安全链接，而不是复制一个缺少依赖的半包；从 npm 正常安装时继续使用包管理器安装的完整依赖树。两种方式都不会写死用户名或盘符。

Agent 工具

- wallpaper_list：列出 Wallpaper Engine、本地项目和上传图片。
- wallpaper_harness：apply / random / clear 控制 Harness 背景，可传 scrim、panelOpacity、inputOpacity、blur、paletteMode、accentColor 和 secondaryAccentColor。
- wallpaper_apply：只控制 Windows/Wallpaper Engine 桌面，保留 0.1 版 we / native / random 契约。
- wallpaper_status：报告 Wallpaper Engine 发现状态和当前桌面壁纸。

本机回环 API

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/dsh-wallpaper/status | 引擎发现状态与当前桌面壁纸 |
| GET | /api/dsh-wallpaper/list | 图库；支持 q / type / tag，返回 revision 与监听状态 |
| GET | /api/dsh-wallpaper/library-watch?revision=&timeout= | 本机素材目录变化的长轮询通知；最大等待 25 秒 |
| GET | /api/dsh-wallpaper/preview?p=... | 兼容旧客户端的白名单图片预览 |
| GET/HEAD | /api/dsh-wallpaper/media?id=... | 按扫描 ID 流式提供 Harness 媒体；支持单段 HTTP Range |
| GET | /api/dsh-wallpaper/skin | 读取共享 Harness 状态及解析后的媒体描述 |
| POST | /api/dsh-wallpaper/skin | { action, id?, scrim?, panelOpacity?, inputOpacity?, blur?, brightness?, backgroundFit?, motionMode?: 'play'|'static', presetId?, paletteMode?, accentColor?, secondaryAccentColor?, expectedRevision? } |
| GET/POST | /api/dsh-wallpaper/scene-bridge | 读取或受控操作 Scene 高清桥；当前只接受显式本地 helper，未知下载会拒绝 |
| POST | /api/dsh-wallpaper/apply | 旧桌面接口：{ id, mode, imagePath? } |
| POST | /api/dsh-wallpaper/upload?name=... | 上传图片，最大 64 MB |

所有路由都限制为同源本机回环请求。media 只接受壁纸 ID，不接受绝对路径；视频通过 createReadStream 发送，不会整体读入内存。

前置条件

- Windows 上可运行的 DeepSeek Harness Web Profile；先至少启动一次 dsh web，让 DSH_HOME/profiles/web/ 存在。
- 可运行 Harness 的 Node.js/npm 环境。插件依赖 @deepseek-ai/dsh-tools@^0.1.0-rc.6、@deepseek-ai/schemastery@^3.18.1，并要求 @deepseek-ai/cordis@^4.0.1 由宿主提供。
- Wallpaper Engine 不是启动插件的硬性前提：没有它时，Wallpaper Engine 图库与 WE 桌面播放不可用；插件上传的图片和已有本地配置仍可使用。要播放 Scene、视频或 Web 桌面壁纸，必须安装并运行 Wallpaper Engine。

配置
插件默认通过 Windows 注册表、Steam 的 libraryfolders.vdf 和常见安装目录自动发现 Wallpaper Engine，通常不需要填写路径。只有自动发现失败时才使用可选覆盖项：

- id: wallpaper
name: 'backdrop-bridge-dsh'
config:
enabled: true
announceToAgent: true
installDir: '' # 可选，仅自动发现失败时填写
workshopDir: '' # 可选
uploadsDir: '' # 可选，默认 ~/.dsh/dsh-wallpaper/uploads
repkgPath: '' # 可选，默认关闭
repkgSha256: '' # 可选但推荐，配置后不匹配即拒绝运行

安装、验证与卸载

现在即可用：从 GitHub 获取并安装

当前版本尚未发布到 npm；请使用下面的 GitHub 安装流程。PowerShell 中执行：

git clone https://github.com/kdzhang-hub/dsh-wallpaper.git
cd dsh-wallpaper
corepack pnpm install --frozen-lockfile
node .\bin\dsh-wallpaper.mjs doctor
node .\bin\dsh-wallpaper.mjs install

先至少启动一次 dsh web，让 DSH_HOME/profiles/web/ 存在。doctor 的 JSON 输出应包含 profileFound: true；install 后应包含 packageFound: true 和 registered: true。随后重启一次 dsh web，在 SSH 下方打开“壁纸”。

如果 DSH 主目录不在默认位置，在执行 doctor 和 install 前指定它：

$env:DSH_HOME = 'D:\path\to\.dsh'
node .\bin\dsh-wallpaper.mjs doctor
node .\bin\dsh-wallpaper.mjs install

安装后怎么用

1. 重启 dsh web，在左侧栏 SSH 下方点击 壁纸。首次打开会扫描本机 Wallpaper Engine 创意工坊和本地项目；可用搜索框、类型筛选和 刷新 查找素材。
2. 在任意壁纸卡片上按目标选择一个操作：
- 设为 Harness 背景：仅替换 DeepSeek Harness 的全窗口背景，不会改动 Windows 桌面。
- WE 播放：让 Wallpaper Engine 将该项目作为桌面壁纸播放。适用于 Scene、视频和网页壁纸；需要 Wallpaper Engine 已安装并运行。
- Windows 静态：将该项目的静态图片预览设为 Windows 桌面。只适用于 jpg/png/bmp/webp 等静态图片；GIF、视频和 Scene 请使用前两种方式。
3. 顶部的 随机 Harness 会随机切换 Harness 背景，随机桌面 会随机切换桌面壁纸，刷新 会重新扫描本机图库。
4. 展开 界面适配设置，可按需要调整背景遮罩、面板/输入区不透明度、毛玻璃、亮度，以及“铺满裁切”或“完整显示”。“动态背景”可选播放动图/视频，或在 Harness 中静态预览；还可选择自动取色或手动双主题色、启用安全预设；恢复自动适配 可还原默认外观。这些设置只影响 Harness 的显示效果。
5. 想恢复默认界面时点击 清除 Harness 背景。它只清除 Harness 背景，不会停止 Wallpaper Engine 或恢复 Windows 桌面壁纸。

也可以使用自己的图片：点击 上传并设为 Harness，选择 jpg/jpeg/png/bmp/gif/webp 图片；或者输入一张本地静态图片的绝对路径，点击 设为 Windows 桌面。上传的图片只保存到本机。

Scene 在浏览器中只能显示项目提供的预览图；若预览图很小，Harness 会用环境填充避免粗暴拉伸。想得到完整的动态 Scene 效果，请使用 WE 播放。

npm 发布后：使用 CLI

当 backdrop-bridge-dsh@0.6.0 已发布到 npm 后，才可以使用：

npx backdrop-bridge-dsh@0.6.0 doctor
npx backdrop-bridge-dsh@0.6.0 install

两种安装方式完成后，都应确认聊天、SSH、文件区、编辑器、菜单和键盘操作仍可用。

手动安装（供 Profile 维护者使用）

在活动 Web Profile 的 package.json 中安装包并注册 bundle；下面是需要合并的字段，不要覆盖已有依赖或 bundles：

{
"dependencies": {
"backdrop-bridge-dsh": "^0.6.0"
},
"dsh": {
"profile": {
"bundles": ["backdrop-bridge-dsh"]
}
}
}

然后在该 Profile 目录使用其现有包管理器安装依赖并重启 Harness 一次。install 会从 bundles 中移除旧的 dsh-wallpaper 条目并注册 backdrop-bridge-dsh，但不会删除旧包文件，便于人工回滚。避免同时注册 backdrop-bridge-dsh 与已归档的 dsh-wallpaper-skin。

本地开发时可以临时使用 link:，该路径必须由开发者按自己电脑填写，不属于发布配置。Profile 只加载 /plugins/backdrop-bridge-dsh/client.js。

卸载

以下命令只操作当前指定的 DSH Profile：

npx backdrop-bridge-dsh@0.6.0 uninstallmarkdown
npx backdrop-bridge-dsh@0.6.0 uninstall --purge  # 同时删除托管包、状态、上传素材和 Scene 缓存

uninstall 默认只移除 Profile 注册，保留已复制的包、状态、上传素材和缓存以便恢复；只有显式 --purge 才删除它们。删除前请自行备份需要保留的上传素材。

本地数据、进程与网络边界

- 首次扫描会读取当前用户可访问的 Steam 注册表项、libraryfolders.vdf、Wallpaper Engine 项目目录及其 project.json/预览文件；扫描结果只用于本机图库和本地回环 API。
- 插件会在 ~/.dsh/dsh-wallpaper/ 写入 skin-state.json、上传图片、Scene 缓存，以及 Windows 原生壁纸所需的受管 PowerShell helper。CLI install 还会修改目标 Profile 的 package.json 和 node_modules/dsh-wallpaper。
- 只有用户在界面中选择、调用 Agent 工具或请求本机 API 时，插件才会启动 Wallpaper Engine 的本机控制命令或设置 Windows 原生壁纸。Harness 背景操作不会改变 Windows 桌面；桌面操作也不会改变 Harness 背景。
- 0.6.0 不上传壁纸、不发送遥测、不会下载或自动执行 Scene helper。路由仅接受本机回环请求；详见 API 一节及 SECURITY.md。

可移植性

- 不依赖用户名、固定盘符、当前壁纸 ID 或 Harness 构建生成的哈希类名。
- 客户端通过稳定语义属性和 CSS 变量适配界面，并从每台电脑当前选择的壁纸运行时取色。
- 自动取色会同时生成侧栏、对话区和输入区的半透明表面，以及符合对比度要求的主文字、次文字、弱文字、链接、边框和强调色；更换壁纸后这些语义颜色会一起更新。
- Wallpaper Engine 可安装在任意 Steam 库；插件优先读取注册表与 libraryfolders.vdf，常见盘符仅作为发现失败时的兜底。

限制

- 目标环境为 Windows；WE 桌面模式需要 Wallpaper Engine 可用。
- 本版本不尝试在浏览器里运行 scene.pkg；Scene 完整动态效果仍由 Wallpaper Engine 桌面播放。
- 低清环境模式只能减少放大和裁剪，不能凭空恢复 scene.pkg 内的原始细节；需要完整高清 Scene 时仍应使用 WE 播放，或后续配置受信任的可选 Scene 解包桥。
- Scene 高清桥默认关闭。RePKG 官方目前没有可直接使用的官方 Release helper；本版本不会下载未知二进制。后续开源仓库建立固定版本、HTTPS 和 SHA-256 清单后，才可安全安装对应 helper；接口和发布契约见 docs/scene-helper.md。
- Windows 原生桌面只接受 jpg/png/bmp/webp 等静态图片；GIF、Scene 和视频请使用 Harness 或 WE 操作。

维护与发布

- 贡献规则见 CONTRIBUTING.md，安全问题见 SECURITY.md，版本变化见 CHANGELOG.md。
- 对外发布前执行 PUBLISHING.md 的技术检查和人工验收；不要把本机 DSH Profile、node_modules、壁纸、测试上传文件、密钥或绝对路径提交到公开仓库。