DeepSeek Harness 自定义背景插件（dsh-ui-customizer）

一个用于 DeepSeek Harness (DSH) Web 界面的外观自定义插件。它让你可以给主界面、边栏、顶栏三个区域分别上传背景图片，并自由拖拽定位、调节不透明度，还支持主题色、圆角和界面缩放。

---

✨ 功能特性

• 三区域独立背景：主界面、边栏、顶栏各自上传图片（自动压缩到 1920px、转 WebP），支持 填充 / 完整显示 / 平铺 三种显示方式
• 自由拖拽定位：在预览图上按住拖拽即可平移图片，展示你想展示的部分；也提供水平/垂直位置滑杆（0–100%）精确控制
• 不透明度语义：0% 完全不可见（显示背景色）、100% 全部可见、值越大越清晰
• 模糊 / 暗化：每个区域可单独加高斯模糊与暗化遮罩（提升可读性）
• 主题色：5 个预设 + 自选颜色，作用于品牌色 token，明暗模式同步生效
• 圆角 / 缩放：全局圆角（0 = 跟随默认）、界面整体缩放
• 无需任何「表面透明度」设置：背景直接绘制在界面表面层上，上传即见
• 健壮定位 + 半透明兜底：运行时定位真正盖住背景的布局元素；定位失败时自动降级为 token 半透明 + body 分层背景，任何结构下都可见
• 内置诊断：一键输出插件版本、各元素定位结果、已绘制元素数、持久化状态等，方便排障
• 配置 JSON 保存在浏览器 localStorage，图片本体存入 IndexedDB（不再受 5MB 配额限制）；刷新不丢、多标签页自动同步、可一键重置；IDB 不可用时自动回退内嵌存储

🔧 工作原理

接入方式（标准 DSH 客户端插件）

一个 DSH 客户端插件是一个 npm 包，通过三个约定接入：

约定	本包实现
package.json 声明 "dsh": { "client": { "platform": "web", "inject": [...] } }	声明浏览器插件及其依赖
exports["./client"] 指向成品 bundle	lib/client.js（手写、零构建）
bundle 通过 window.__ModuleLoader__.load({ id, factory }) 注册，工厂返回 { apply, inject }	标准 Cordis 插件

宿主侧的 dsh-client-modules 扫描已启用插件行，把 bundle 发布到 /plugins/<id>/client.js 并注入 window.__DSH_BOOT__；Web 外壳内核据此挂载插件。

背景绘制

界面真正「盖住背景」的层是几个布局元素，它们的 background 都是 var(--dsw-alias-bg-*)：

• 主界面：布局 frame（.pI_x6G_frame）+ 会话根（.wSkVaW_root）
• 边栏：边栏列（.pI_x6G_sidebarCol）+ 侧栏壳（.hHd-Xa_root）
• 顶栏：会话区 <header> 元素

本插件在运行时用 [class*="sidebarCol"] 等选择器定位这些元素，把背景复合值直接设为它们的内联 background，从而绕过「表面透明度」依赖、获得 100% 清晰度。

背景复合值层序：

[洗色层: linear-gradient(底色, 1-不透明度)]  <- 实现不透明度语义
[暗化层: linear-gradient(rgba(0,0,0, dim))]
[图片层: url(...) X% Y%/size repeat]         <- 位置、显示方式
[底色: var(--dsw-alias-bg-base) 等]          <- 自动跟随明暗模式

健壮性与兜底

• 会话根/边栏壳存在嵌套多层结构，插件除「直接子元素」外，还按「背景色 == token 解析色 且 面积足够大 / 命中特定 token」在子树内兜底扫描，结构变化也能命中
• 若主背景一个表面都没定位到，自动启用 token 半透明(0.9) + body 分层背景，保证可见
• MutationObserver 监听布局元素重挂载（切会话/热更新）自动重绘；theme/change 时按明暗模式重刷洗色层；插件卸载时清理所有内联背景
• 性能：元素定位结果带缓存，仅布局变更/换肤时重扫，拖动/滑杆只重绘；拖动预览走 rAF 节流；配置写入 trailing 防抖(300ms)，页面关闭前自动落盘

📦 安装

前置：已安装 DeepSeek Harness，并运行过一次 dsh web（会自动创建 profile 目录）。

方式 A：一键安装（推荐）

PowerShell 里粘贴这一行即可（自动下载、安装、写入配置）：

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12; irm https://raw.githubusercontent.com/vonPaulison/deepseek-harness-custom-background/main/install.ps1 | iex

装完重启 dsh web，刷新页面 → 设置 → 外观自定义。重复运行是安全的（幂等）。

不想直接执行远程脚本的话，也可以先下载 install.ps1 看一眼再运行，或改用下面手动方式。

方式 B：官方插件命令（需要 pnpm）

dsh plugin --profile web add <本仓库路径>

然后把下面这段合并进 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml：

- insert:
    - id: ui-customizer
      name: dsh-ui-customizer

方式 C：手动安装（无需 pnpm，本包零依赖、bundle 手写无构建）

# 1. 放入 web 配置目录的 node_modules
New-Item -ItemType Directory -Force $env:USERPROFILE\.dsh\profiles\web\node_modules | Out-Null
Copy-Item -Recurse <本仓库路径> $env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-ui-customizer

# 2. 把上面的 insert 段合并进 cordis.patch.yml

生效

• 重启 dsh web（或：若插件行已在运行实例中注册，直接 Ctrl+F5 强刷页面即可加载新 bundle）
• 打开 设置 → 外观自定义 开始使用

⚠️ 设置面板打开时会盖住主界面：上传/调整后请关闭设置面板再查看效果（卡片内的预览图可实时看位置与显示方式）。

🚀 使用

1. 进入 设置 → 外观自定义
2. 在「主界面背景 / 边栏背景 / 顶栏背景」三张卡片里分别「上传图片」
3. 在预览图上按住拖拽定位，或用位置滑杆微调
4. 调节不透明度（0=隐藏、100=最清晰）、模糊、暗化、显示方式
5. 可选：主题色、圆角、缩放；「重置全部」一键还原

🛠️ 故障排查

如果某个区域的背景没有显示：

1. 关闭设置面板再看（面板会盖住主界面）
2. 点设置页底部的「运行诊断」，查看：插件版本、三个区域是否已配图、各元素定位结果（frame / 边栏表面 / 顶栏 / 会话表面）、bg-base 解析色、已绘制元素数、明暗模式
3. 把诊断输出贴到 issue 里

🧩 自定义扩展

DSH Web 界面是 slot 树，第三方插件可注册/替换任意区域。可用插槽（声明于各 dsh-client-ui-* 包）：

• 全局：root、shell.overlay
• 侧栏：sidebar、sidebar.workspaces、sidebar.settings、sidebar.footer.action
• 会话/对话：conversation.session、conversation.composer（链式，可整体替换输入区）、conversation.chat.node、conversation.chat.turnTail、conversation.input.*、conversation.hero.*
• 设置：settings.trigger、settings.section、settings.general.item、settings.plugins.tab、settings.plugin.item
• 工具：tool.call.toolview、tool.view.cordis、details

注册方式：

// 直接注册（插槽已声明）
ctx.slots.register({ name: "settings.section", id: "...", order: 100, label: "..." }, Component);
// 声明注入（声明者激活后自动注册）
ctx.slots.inject("settings.general.item", () => ctx.slots.register({ ... }, Row));

主题层面：

// 覆盖任意 --dsw-alias-* token（明暗两个值都必须给）
ctx.theme.overrideTokens("你的插件id", { "--dsw-alias-brand-primary": { light: "#4176E6", dark: "#4176E6" } });
// 或注册一个完整可选的第三方主题
ctx.theme.register({ id: "my-theme", colorScheme: "dark", tokens: { ... } });

⚠️ 已知限制

• 设置与图片保存在浏览器本地（配置 JSON 在 localStorage，图片在 IndexedDB）：换浏览器/清缓存会丢；远程（非本机）浏览器不同步
• 布局元素通过类名/标签选择器定位（[class*="sidebarCol"]、header 等），DSH 未来大版本若改动结构需同步更新选择器
• 平铺 模式下位置以百分比偏移（图片大于区域时可能无明显位移）
• 圆角通过全局 CSS 规则实现（!important），头像等圆形元素做了豁免，属「尽力而为」
• 界面缩放依赖 zoom，仅 Chromium 系浏览器生效

📁 目录结构

dsh-ui-customizer/
├── package.json      # 插件清单：dsh.client 声明、exports、版本
├── lib/
│   ├── index.js      # 宿主(Node)半：空插件，让行在 Cordis 树上激活
│   └── client.js     # 浏览器半：window.__ModuleLoader__.load 手写 bundle
├── test/
│   └── simulate.cjs  # 模拟模块加载器全链路测试（Node 直接运行）
├── LICENSE
└── README.md

测试

node test/simulate.cjs lib/client.js

📄 License

MIT

---

本项目为 DeepSeek Harness 的第三方插件，与 DeepSeek 官方无直接关联；DSH 及 @deepseek-ai/dsh-* 包版权归其各自所有者。