DSH 自定义背景插件（dsh-bg-plugin）

为 DSH Web GUI 添加可自定义的背景图片或视频：支持远程 URL 与本地文件（文件夹浏览），带背景清晰度调节；设置面板保持默认外观，不跟随背景变化。

两种安装形态：

形态	文件	特点
静态安装版（推荐）	package.json + cordis.patch.yml + lib/	作为 DSH 插件包装入 Web profile，重启后常驻，不依赖会话
动态插件版	host.js + client.js + define.json	通过 cordis_define 在会话中动态加载，重启后消失

文件说明

文件	内容
package.json	插件包清单（dsh.client 声明 + dsh.bundle.patch）
cordis.patch.yml	挂载声明：把插件行插入 Web profile 组合树
lib/index.js	Host 半边（静态版）：webServer 提供 /dsh-bg/api/state、/list、/set、/media、/orb/status 路由
lib/client.js	Client 半边（静态版）：设置页 UI（Tab：主应用 / 悬浮球），fetch 直连 API 路由
host.js	动态版 Host 源码（cordis_define 的 code.host）
client.js	动态版 Client 源码（cordis_define 的 code.client）
define.json	动态版完整重新安装载荷
README.md	本文档

安装（静态安装到 DSH）

# 在 DSH 所在机器上，把本目录作为本地开发插件装入 web profile：
dsh plugin --profile web add link:<本目录绝对路径>
# 例：dsh plugin --profile web add link:D:\DSH插件\dsh-bg-plugin

然后重启 DSH（dsh web）。启动后：

• 设置 → 背景：出现「自定义背景」设置页；
• 浏览器加载 /plugins/dsh-bg-plugin/client.js，Host 注册 /dsh-bg/api/* 路由。

卸载：

dsh plugin --profile web remove dsh-bg-plugin

桌面端（Electron）支持

插件同时支持 DSH 网页端与桌面端（Electron）——两端只需各自安装一次，状态文件共用。

桌面端与网页端是两个独立的 DSH 实例（不同 profile、不同运行时、甚至不同 DSH 版本），因此要分别安装：

	网页端	桌面端
profile	$DSH_HOME/profiles/web	$DSH_HOME/profiles/desktop
安装 CLI	全局 dsh（如 dsh plugin --profile web add …）	桌面端自带 CLI：<安装目录>\resources\runtime\cli\bin\dsh.cmd
页面载体	浏览器 http://127.0.0.1:<port>/?token=…	Electron 窗口加载同一套 HTTP 页面（宿主经 IPC 下发 authenticatedUrl 与索引注入）

桌面端安装（Windows 示例）：

& "D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add link:D:\DSH插件\dsh-bg-plugin

要点：

• 桌面端 profile 是应用专属管理的：普通 dsh --profile desktop … 会被拒绝（profile "desktop" is managed exclusively by the Electron application），只有桌面端自带 CLI 的 插件子命令被放行，所以必须用上表中的 dsh.cmd。
• 安装后需重启桌面端 App 才会加载（重启会中断正在进行的会话，会话可恢复）。
• 已核对的 0.2.0-rc.2 契约（与 0.1.1-rc.2 一致）：/plugins/<id>/client.js 路由、__ModuleLoader__.load({id, factory})、package.json 的 dsh.client 字段、settings.section 槽位、theme.overrideTokens、webServer.register({kind, path, handler})、设置面板 [role="dialog"][aria-modal="true"]、fs 服务。
• 背景状态 $DSH_HOME/.dsh-bg-state.json 由两个 profile 共用，因此在任意一端调整后，另一端重启即恢复同一背景。

动态版安装（会话级，重启失效）

读取 define.json 作为 cordis_define 参数（plugin.kind: 'existing'、pluginId: 'dshbg-1'；若不存在则 kind: 'new' + idPrefix: 'dshbg'），再用返回的 packageId 执行 cordis_run 并在 GUI 批准。

功能

• 设置页入口：侧边栏「设置」→ 新增一页「背景」（settings.section，id dsh-bg）
  • 启用 / 禁用开关
  • 媒体来源：图片 / 视频 URL（粘贴链接）/ 本地文件（输入文件夹路径或「浏览文件夹…」→ 列出文件 → 点击应用）
    • 图片格式：png/jpg/jpeg/gif/webp/bmp/avif/svg
    • 视频格式：mp4/m4v/webm/ogv/ogg/mov/mkv（浏览器可播放的容器；单文件 ≤ 64MB）
  • 图片：预览图上框选展示区域（拖动框选 / 拖动选框移动 / 拖四角缩放）
  • 视频：真实 <video> 元素渲染，object-fit: cover 等比铺满屏幕（自动裁掉超出部分，不拉伸、不裁剪、无需框选），静音循环自动播放
  • 背景清晰度（0–100%）、恢复默认
• 持久化（静态版）：所有调整自动保存到 $DSH_HOME/.dsh-bg-state.json（默认 C:\Users\<你>\.dsh\.dsh-bg-state.json）；刷新页面、重启 DSH 后自动恢复状态并重应用背景（含上次的本地媒体与裁切区域）。
• 框选展示区域（静态版，仅图片）：选择图片后，设置页显示预览图——拖动框选展示区域、拖动选框移动、拖四角调整大小；区域以图片分数 {fx,fy,fw,fh} 存储并持久化。背景渲染用纯 CSS（calc/max + vw/vh）把裁切区域等比放大铺满视口、区域中心对准屏幕中心，窗口缩放自动跟随。视频不使用该机制。
• 动态版额外提供 Run 卡片快捷开关（tool.view.cordis，动态专属座位，静态版不含）；动态版为会话级，不持久化。

设置页结构（Tab）

设置 → 背景 现在是一页两 Tab：

Tab	内容
主应用背景	上面列出的全部功能（媒体来源、框选、清晰度、恢复默认）
悬浮球	悬浮球（dsh-orb-cordis）状态检测、安装引导、面板背景支持（写入补丁）、悬浮球背景设置、与主应用双向同步

悬浮球页的检测走宿主路由 GET /dsh-bg/api/orb/status：

• installed：当前 profile 的 node_modules/dsh-orb 是否存在（读 $DSH_PROFILE_DIR，不从本包做模块解析——本包常以 junction 安装，解析会走真实路径而找不到）；
• running：它自己的端点是否活着（401/403 也算活着，只有 404 或连不上才算没运行）；
• patched：是否已写入本插件的面板背景补丁。

悬浮球面板背景（写入补丁，需确认）

悬浮球的展开面板背景写死在它的 floating.css，且没有对外接口，因此只能改它的文件。本插件做成"点击才动、且可还原"：

1. 「启用（首次弹窗确认）」→ 浏览器弹窗列出将覆盖的文件，同意才继续；

2. 写入前把原文件完整备份到 $DSH_HOME/.dsh-bg-orb-backup/<时间戳>/（含 manifest）；

3. 只覆盖两个文件：

   • dist/helper/assets/floating.html —— 放宽 CSP，允许本机 http://127.0.0.1:* 的图片/视频；
   • dist/helper/lib/main.js —— 助手主进程加一个背景控制器（每 3 秒轮询本插件 GET /dsh-bg/api/orb，用 executeJavaScript 在面板内注入背景层：图片/视频 + 可读性蒙层 + 框选区域渲染）。

   它的 floating.css、shell.js、preload.cjs、宿主代码一律不动；

4. 重启 DSH 后生效；本页「撤销补丁」可从备份逐字节还原。

背景层一定在面板框内（补丁 v2 起）：注入的样式给 #panel 加 isolation: isolate 建层叠上下文，背景层用 z-index:-1 垫在面板内容之下，于是它

• 随面板的展开/收起缩放动画一起动（不再脱离面板"飘"在外面）；
• 由 border-radius: inherit + overflow: hidden 裁成与面板一致的圆角矩形，不会溢出面板。

补丁版本与更新：/orb/status 返回 patchVersion 与 patchLatest；已装旧版时显示「更新补丁」按钮，点击先从备份还原原文件、再写入新版（幂等）。

锚点不匹配（例如悬浮球升级后结构变了）会明确报错并不改动任何文件。

悬浮球框选（比例锁定为面板比例）

• 悬浮球面板 = 340×440 窗口 − 10px chrome ×2 → 面板卡片 320×420（比例 ≈0.762）；
• patched 助手实测面板尺寸并回报 POST /dsh-bg/api/orb/metrics，设置页据此把框选宽高比锁死为面板比例，铺进面板不会变形；
• 交互：预览图上拖动即框选（比例恒定）、拖动选框平移、「按面板比例铺满（最大框）」、「清除框选（整图 cover）」；
• 渲染：有框选时用 background-size: (100/fw)% (100/fh)% + background-position 精确取区（比例已锁故不变形）；未框选时 cover 居中；视频不框选（按原比例铺满）。

悬浮球背景与双向同步

• 悬浮球背景独立于主应用：可分别设 URL / 本地文件（本地列表复用「主应用背景」页选定的文件夹）、独立清晰度与框选；
• 双向同步按钮：「主应用 → 悬浮球」/「悬浮球 → 主应用」互相复制（媒体、类型、清晰度），并把目标侧框选重置为铺满（两侧比例不同，直接搬会变形；同步后可在目标侧重新框选）；
• 安全阀：源一侧还没有选媒体时，同步会被拒绝（返回「还没有选择背景媒体，已取消同步」），绝不会把空背景覆盖到另一侧；
• 悬浮球配置存于 $DSH_HOME/.dsh-bg-state.json 的 orb 分区，与主应用分区互不影响。

状态留底与误操作找回

每次写状态文件前都会自动留底，任何一次误覆盖都能找回：

文件	说明
$DSH_HOME/.dsh-bg-state.prev.json	上一份内容（每次保存前覆盖写入）
$DSH_HOME/.dsh-bg-state.bak-<时间戳>.json	时间戳快照，最多保留 3 份、间隔 ≥10 分钟

「主应用背景」页底部有 「恢复上一份设置」 按钮（POST /dsh-bg/api/state/restore，先弹窗确认，成功后自动重载页面）。

相关路由：GET/POST /dsh-bg/api/orb（读取/写入，patched 助手轮询它）、POST /dsh-bg/api/orb/set（选媒体）、GET /dsh-bg/api/media/orb（媒体字节）、POST /dsh-bg/api/sync（双向同步）、POST /dsh-bg/api/orb/patch、POST /dsh-bg/api/orb/unpatch、POST /dsh-bg/api/state/restore（恢复上一份）。

自动更新（设置页最下面）

设置页最底部有一个 「自动更新」勾选项，默认开启：

• 开启时：打开设置页会检查 GitHub main 分支的版本，发现新版本就自动下载并覆盖本插件文件，然后提示「重启 DSH 后生效」；
• 覆盖前把现有文件备份到 $DSH_HOME/.dsh-bg-update-backup/<时间戳>/；
• 也可以手动点「检查更新」/「立即更新」；
• 本地版本读 package.json；远端版本读仓库 main 分支的 package.json；
• 走 api.github.com（raw.githubusercontent.com 在部分网络下 DNS 不通，API 的 raw 接口可用）；
• 更新文件清单：package.json、lib/index.js、lib/client.js、lib/orb-patch.js、README.md、LICENSE；
• 网络不可用时静默跳过，不影响其它功能。

相关路由：GET/POST /dsh-bg/api/update（检查，结果缓存 5 分钟）、POST /dsh-bg/api/update/apply（应用更新）。

工作原理

1. 背景层：注入 body::before 固定层（position:fixed; z-index:-1）承载图片（静态版用 <style> 元素注入，动态版用 styles.insert）；视频则在 z-index:-2 注入真实 <video> 元素层。
2. 半透明表面：theme.overrideTokens 把 4 个背景 token（--dsw-alias-bg-base / -layer-1 / -layer-2 / --dsw-specific-sidebar-fill）覆盖为半透明色（浅色/深色各一套），让图片从应用底层透出；清晰度越高表面越透明。
3. 设置面板豁免：设置面板（[role="dialog"][aria-modal="true"]）内部重新声明这 4 个 token 的 DSH 原始色值（取自设计平台基础样式），因此面板始终 100% 不透明、保持默认外观。
4. 本地图片传输：Host 注册 /dsh-bg/api/* 路由（ctx.effect 内注册，随插件生命周期清理），用 fs 服务读取图片字节（fs.contains 防路径穿越），客户端以相对 URL 作为 CSS 背景。
5. 路径读取不受沙箱限制：fs 沙箱只拦截写入，读取任意目录均可；若「浏览文件夹」的系统选择器不可用，可直接粘贴文件夹路径。

注意事项 / 历史踩坑

• webServer.register 返回的注销函数不会自动随插件 fiber 清理，必须包在 ctx.effect(() => webServer.register(...)) 里，否则停止/更新后路由泄漏，下次注册同路径会报 duplicate exact route。
• 动态版路由路径每次运行随机生成（/dsh-bg/img-<random>），避免与旧版本残留路由冲突；静态版使用固定路径（进程重启即全新）。
• 客户端 slots.register、theme.overrideTokens 由 client runner 自动挂到 fiber（动态版），静态版同样依赖 cordis 服务自身的生命周期。
• Host 沙箱的 btoa 是 UTF-8 编码，不能用于二进制图片转 base64；本地图片走 HTTP 路由而非 RPC 传字节。
• dsh plugin --profile web add link:<路径> 用 pnpm 建立 junction 链接（NTFS），改动源码目录即可热更新，重启 DSH 生效。