Yugitan/dsh-skin

dsh-skin — 自定义换肤工具（支持图片换肤）

📖 中文使用教程：使用教程.md · 📦 源码：github.com/Yugitan/dsh-skin · 🏷 dsh-plugin

一个用于 DeepSeek Harness Web 界面的可自定义换肤插件。它在 设置 → 通用 (Settings → General) 中添加了一个「换肤 / Skin」面板，让你可以：

- 通过一个开关一键开启/关闭换肤。
- 选择内置渐变预设（深海 Ocean / 极光 Aurora / 落日 Sunset / 薄荷 Mint / 樱花 Cherry）。
- 上传你自己的壁纸图片（PNG / JPG / WebP / GIF，≤ 10 MB）——存储在
~/.dsh/skins/ 下，并通过 /skins/ 提供访问（设置中不会因 base64 而臃肿）。
- 粘贴任意图片 URL（本地 /skins/... 或外部链接）。
- 调整填充方式（铺满/适应/拉伸/平铺）、位置、图片不透明度、背景模糊、
用于提升可读性的暗色遮罩，以及面板半透明度（玻璃效果）。
- 覆盖品牌强调色（色板 + 颜色选择器）。
- 将所有内容重置回默认外观。

效果预览 / Preview

dsh-skin 效果预览

所有内容都持久化在 DSH 用户设置文档中
（~/.dsh/settings.yaml → skin: 部分），重启后依然保留，并在 React 应用挂载前
重新应用（由宿主注入的启动样式，无闪烁）。

工作原理

- 宿主部分（lib/index.js，运行在 dsh web 进程中）
- 注册 skin 设置命名空间 + schema，
- 提供 POST /skin/upload（魔数字节图片嗅探，上限 10 MiB）和
GET/HEAD /skins/（不可变缓存，防路径遍历），
- 在 index HTML 中注入插件运行前的启动脚本/样式，将持久化的皮肤投射到
--dsh-skin- CSS 自定义属性以及 body[data-ds-skin] 属性上。
- 浏览器部分（lib/client.js，由客户端模块系统加载）
- SkinRuntime 将设置部分镜像为 CSS 自定义属性，
在  上切换 data-ds-skin / data-ds-skin-accent，并在激活后移除
宿主启动节点，
- 将「换肤 / Skin」行注册到 settings.general.item 插槽中
（顺序为 20，紧挨在内置的 Appearance 行下方）。

壁纸由一个固定的全视口 body::before 图层绘制
（z-index: -1），暗色遮罩由 body::after 绘制，应用界面则通过
--dsw-alias-bg- token 覆盖（!important 可覆盖 ui-layout ThemePresenter 的内联 token）实现半透明，
这样图片能透过面板显示，同时文字通过暗色遮罩保持可读。

安装到正在运行的配置中

一键安装 / 卸载（推荐）

在 dsh-skin/ 目录下，运行随附的管理脚本。它会完成全部
三步——模块安装、cordis.patch.yml 条目、宿主允许列表补丁——
并且是幂等的（可安全重复运行）：

node manage.mjs install        # 一键安装（复制模式，移动文件夹后依然安全）
node manage.mjs install --link # 开发模式：实时符号链接，浏览器 HMR 会拾取 client.js 的修改
node manage.mjs status         # 验证（同时检查正在运行的服务器 bundle）
node manage.mjs uninstall      # 一键卸载
node manage.mjs uninstall --clean   # 同时删除 ~/.dsh/skins/ 和 skin: 设置
node manage.mjs install --profile ~/.dsh/profiles/   # 自定义 profile
node manage.mjs --help

或者通过本包中的 npm 脚本：npm run plugin:install /
npm run plugin:uninstall / npm run plugin:status。

之后重启服务器并刷新浏览器：
dsh --profile web（或 npm exec @deepseek-ai/dsh web）。

安装模式。 install 默认会将一个自包含的插件复制到
/node_modules/dsh-skin，因此之后移动、重命名或
删除此源文件夹都不会破坏已安装的皮肤；
重新运行 install 即可用你的修改刷新副本。开发时使用 --link，
这样 profile 会直接链接到此文件夹，客户端 HMR
会在浏览器中热重载 lib/client.js 的修改，无需重新安装。
因文件夹被移动而遗留的悬空符号链接会在下一次 install 时
自动修复（无需 --force）。

从 GitHub 安装
bash
git clone https://github.com/Yugitan/dsh-skin.git
cd dsh-skin
node manage.mjs install        # 一键安装（链接 + 注册 + 打补丁）
重启服务器，然后刷新浏览器：
cd ~ && npm exec @deepseek-ai/dsh web

在新机器上，请在克隆目录内重新创建 node_modules 符号链接
（ln -s ~/.dsh/profiles/node_modules node_modules），或在那里运行 npm install，
以便 harness 能解析 react / @deepseek-ai/。

手动安装（高级）
bash
从本仓库根目录执行
PROFILE=~/.dsh/profiles/web
ln -s "$PWD/dsh-skin" "$PROFILE/node_modules/dsh-skin"

将以下内容追加到 $PROFILE/cordis.patch.yml：
yaml
- insert:
- id: skin
name: 'dsh-skin'

然后应用单行平台补丁（必需——见下文），并重启
服务器：dsh --profile web（或 npm exec @deepseek-ai/dsh web）。
bash
node patch-host.mjs        # 将 "skin" 设置命名空间添加到 API 网关允许列表
node patch-host.mjs --check

平台补丁（必需）。 DeepSeek Harness 的 API 网关
（dsh-host-apiproxy）只允许配置客户端读取/写入
硬编码的设置命名空间允许列表（WEB_SETTINGS_NAMESPACES）。
第三方命名空间——即使是通过 settings.register()
注册的——也会被以 settings-not-exposed 拒绝，因此皮肤行会渲染出来，但
每次切换/预设写入都会静默失败，且不会持久化任何内容（不会写入
settings.yaml）。patch-host.mjs 会幂等地将 "skin" 添加到
该允许列表（带有 --check / --revert 模式）。在任何
harness 重新安装/更新后重新运行它，然后重启服务器。

开发过程中，编辑 dsh-skin/lib/client.js——客户端 HMR 监视器
会轮询该 bundle 并在浏览器中热重载它，无需重启服务器
（使用 --link 安装时；在复制模式下需先重新运行 install）。

开发
- node manage.mjs install --link — 开发安装（实时符号链接 → HMR）。
- node patch-host.mjs — 重新应用单行 API 网关允许列表补丁
（--check 用于验证，--revert 用于撤销）；在重新安装 harness 后需要执行。
- node test-client.mjs / node test-runtime.mjs — 在 Node 中执行浏览器 bundle，
并使用 react-dom/server 渲染 Skin 行（冒烟测试 + 运行时投影 + 行操作）。
- node test-host.mjs — 在临时的 node:http 服务器上挂载上传/skins 处理器，
并测试上传、服务、路径穿越防护以及索引点击。
- 包内的 node_modules 符号链接指向 profile 模块回退位置，
以便 harness 无需安装即可解析 react / @deepseek-ai/。

可选配置

插件行接受一个 config 来重新定位图片存储根目录：
yaml
- id: skin
name: 'dsh-skin'
config:
root: /absolute/path/to/skins

默认值：~/.dsh/skins。