@beichen4461/dsh-client-ui-background

dsh Web GUI 的背景图主题插件：把自定义图片固定在整个 UI 背后，并让会话区与侧边栏半透明化，使图片透出。它保持色调无关 —— 通过覆盖 --dsw-* 语义 token 同时适配亮色/暗色模式，不触碰主题的其他部分。开关由 autoEnable 配置控制。

工作原理

Web 启动图不会把插件 config 传给浏览器侧，因此本插件拆成两半：

• Host 半：从 cordis.yml 条目读取配置，通过 webServer.tapIndex 把 backgroundImage / contentOpacity / blur / autoEnable 作为 :root CSS 变量（--dsh-bg-image、--dsh-bg-content-opacity、--dsh-bg-blur、--dsh-bg-enabled）嵌入每个被服务的 index 页面。backgroundImage 为本地文件路径时，启动时读取并内联为 data: URI（≤512KB）。
• 浏览器半（exports["./client"]，声明 dsh.client）：背景图预加载成功后注入一个样式表——body::before 固定背景层（含 blur）+ 用 !important 把内容层与侧边栏的 --dsw-* token 覆盖为半透明（light/dark 两套选择器分别覆盖，跟随当前色板）。autoEnable: false 时不注入任何内容；图片加载失败则不注入并告警。

使用

方式一（持久化，推荐）： 把插件条目写进 web profile 的 patch 层，之后直接 pnpm dsh web 即生效：

# 追加到 $DSH_HOME/profiles/web/cordis.patch.yml（注意用无 BOM 的 UTF-8 保存）
- insert:
    - id: ui-background
      name: '@beichen4461/dsh-client-ui-background'
      config:
        backgroundImage: '/bg.png'
        contentOpacity: 0.65

方式二（临时）： 通过 示例 overlay 启动：

pnpm dsh web --patch examples/ui-background/cordis.yml

方式三（一键命令，推荐新装用户）： 包内置 dsh-bg-setup 命令，安装后自动完成配置，无需手动编辑文件：

dsh-bg-setup --check                                  # 检查当前状态
dsh-bg-setup --image C:\pic\bg.png --opacity 0.65     # 写配置（≤512KB 自动内联；大图自动复制为前端 /bg.png）
dsh-bg-setup --image https://example.com/bg.jpg       # 或用完整 URL
dsh-bg-setup --disable                                # 关闭背景（autoEnable: false）

命令自动合并 cordis.patch.yml（无 BOM 保存）、处理背景图、输出下一步提示。

源码模式开发

日常改代码只需一条命令（构建 → 部署 → 看状态，配置保持不变）：

# 在插件目录 packages\client\ui-background 下：
pnpm dev
# 或仓库根：
node packages\client\ui-background\dev-setup.mjs

之后刷新页面即生效。换图/调参时才带参数：

pnpm dev -- --image C:\pic\bg.png --opacity 0.65 --blur 8

从仓库源码运行时

dsh 从 profile 安装目录（$DSH_HOME/profiles/node_modules）解析 overlay 插件，而不是仓库 workspace。pnpm run build 之后需要先把构建产物部署过去（每次重新 build 都要重复拷贝）：

$dest = "$env:USERPROFILE\.dsh\profiles\node_modules\@beichen4461\dsh-client-ui-background"
New-Item -ItemType Directory -Path $dest -Force | Out-Null
Copy-Item -Recurse packages/client/ui-background/lib $dest
Copy-Item packages/client/ui-background/package.json $dest

通过 npm 安装（npx @deepseek-ai/dsh web）时，包从 registry 解析，无需此步骤。

配置

| 字段 | 默认值 | 含义 | |---|---|---| | backgroundImage | /bg.png | 图片来源：站内绝对路径、完整 http(s) URL、data: URI，或本地文件路径（≤512KB，自动内联） | | contentOpacity | 0.88 | 内容层不透明度（0–1），越小背景图越透出 | | blur | 0 | 背景图模糊半径（px），>0 时呈现毛玻璃效果 | | autoEnable | true | 启动时自动激活对应色板的背景主题；false 则只注册主题不激活 |

图片放哪里

Web 前端从已安装的 dsh-web-frontend 包的 dist/ 目录提供——当前 profile 安装下是：

Copy-Item bg.png "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai\dsh-web-frontend\dist\bg.png"

替换图片文件只需刷新页面。更简单的方式： 把 backgroundImage 直接配置为本地文件路径（如 C:\pic\bg.png），插件启动时自动内联，无需放置任何文件；或使用完整 URL（https://… 或 data: URI）。修改配置需要重启。

分发给其他人使用

使用者拿到插件包（npm 发布 / tarball / 源码拷贝任一方式）后，按以下步骤安装：

1. 把包装进 dsh profile

dsh 从 $DSH_HOME/profiles/node_modules 解析插件，profile 是独立 workspace，需要把包装进去：

cd $env:USERPROFILE\.dsh\profiles\web
pnpm add <包名或 tarball 路径>   # 例如 pnpm add @beichen4461/dsh-client-ui-background，或 pnpm add ./beichen4461-dsh-client-ui-background-1.0.0.tgz

2. 在 profile patch 里启用插件

编辑 $DSH_HOME/profiles/web/cordis.patch.yml（必须用无 BOM 的 UTF-8 保存——Windows 记事本「另存为 → UTF-8」或 PowerShell 的 Set-Content -Encoding utf8NoBOM，带 BOM 会导致 YAML 解析异常）：

- insert:
    - id: ui-background
      name: '<实际包名>'
      config:
        backgroundImage: '/bg.png'
        contentOpacity: 0.65

3. 放背景图（二选一）

Copy-Item bg.png "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai\dsh-web-frontend\dist\bg.png"

或把 backgroundImage 配置为完整 URL（https://… 或 data: URI），无需放置任何文件。

4. 启动

pnpm dsh web

插件的依赖（cordis、dsh-client-ui-theme、dsh-host-webserver、schemastery）在发布版 dsh 中已自带，使用者无需额外安装。

分发者如何提供包

• npm 发布：pnpm publish 直接发布为 @beichen4461/dsh-client-ui-background；使用者 pnpm add @beichen4461/dsh-client-ui-background
• tarball：cd packages/client/ui-background && pnpm pack 生成 beichen4461-dsh-client-ui-background-<version>.tgz 发给对方，使用者 pnpm add <路径>.tgz
• 源码拷贝（对方有仓库且已 pnpm run build）：把 lib/ 与 package.json 拷进 $DSH_HOME/profiles/node_modules/@beichen4461/dsh-client-ui-background/（见上文「从仓库源码运行时」）

已知限制

• 暂无设置 UI：配置写在 cordis.yml overlay 中，覆盖层对整个进程生效，不按会话区分；关闭背景请把 autoEnable 设为 false。
• 开关基于 autoEnable 配置（host 注入 --dsh-bg-enabled），修改后 HMR 热重载即可生效，无需重启。
• 弹层层（--dsw-alias-bg-layer-*）刻意保持不透明，弹窗可读性不受影响。
• 覆盖目标为当前 shipped 的 alias token；未来的主题系统或自定义 --dsw-* 色板可能产生不同交互。
• 本地路径注入的图片 ≤512KB，超大图请先压缩或改用 URL。