图片配色皮肤 YouHui1/dsh-image-skin

dsh-image-skin

DSH web 插件：给 DeepSeek Harness 设置一张背景图，并根据图片的配色自动适配界面文字、背景、品牌色与边框色。

本插件使用 DeepSeek Harness 生成。

截图

| 效果图 | 设置页面 |
| 皮肤效果 | 皮肤设置页 |

功能

- 背景图：选择任意图片作为应用背景（自动缩小到 1600px JPEG，存储友好）。
- 配色自适应：从图片中抽取平均色 + 主色，派生出一整套 --dsw-alias- / --dsw-specific- 主题 token（背景表面、主/次/三级文字、品牌色、边框、按钮、代码块、侧边栏），同时给出 light / dark 两套，仍遵循你现有的浅色/深色偏好。
- 文字对比度保证：派生文字色时用 WCAG 相对亮度校验「文字 vs 表面」对比度（主/次文字 ≥4.5:1，三级/说明文字 ≥3:1），不足自动压暗/提亮。
- 不透明度：滑块控制主背景的不透明度；弹框/菜单/侧边栏等叠层只轻微跟随（始终 ≥80% 不透明），避免文字重叠。
- 填充方式：铺满 / 适应 / 拉伸（cover / contain / stretch）。
- 护目遮罩：在图片上叠一层按图片色调派生的白/黑蒙版，忙碌图片上的文字更好读。
- 自动明暗：可勾选「跟随图片」——图片偏亮则切浅色主题、偏暗则切深色主题；关闭或移除皮肤时恢复你原来的浅/深/系统偏好（通过 ctx.theme.register 注册一个空 token 的主题做方案载体，不覆盖你的持久化偏好）。
- 持久化：图片与全部选项存在 localStorage，刷新后自动恢复。
- 设置入口：注册一个「皮肤」设置分区（settings.section），随 DSH 语言自动切换中英文。

原理

插件通过两个官方接口完成所有工作，不改 DOM 结构、不硬编码产品选择器：

1. ctx.theme.overrideTokens(source, tokens) —— 在「当前主题」之上叠加一层 token 覆盖（{ '--dsw-alias-xxx': { light, dark } }）。主题呈现器会把这些 token 以内联 CSS 变量写到 <body> 上，因此整个应用的配色随之改变。移除皮肤时调用返回的 disposer 即可还原。
2. 注入一段静态 CSS —— body { background-image: var(--dsh-skin-bg-image), ...; }。图片 URL、填充方式与遮罩色通过自定义 token（--dsh-skin-bg-）传给主题呈现器，同样由 token 层统一管理、随层一起撤销。
3. ctx.theme.register + ctx.theme.setTheme（自动明暗） —— 勾选「跟随图片」时，按图片亮度注册一个空 token 的主题（colorScheme: light|dark）并设为当前方案；真正的配色仍来自 overrideTokens 层。内置偏好只有 light/dark/system 会写回 settings，自定义 id 是进程内的，因此不会覆盖你的持久化偏好；关闭或移除皮肤时恢复进入自动前的偏好。

目录结构

src/index.ts # host 半：无操作挂载点（皮肤完全在客户端） src/context-types.ts # 结构化的 ctx 类型镜像 + @deepseek-ai/cordis 扩展 src/client/index.tsx # client 半：overrideTokens + CSS 注入 + 设置分区注册 src/client/SkinSettings.tsx# 设置 UI（上传 / 预览 / 不透明度 / 移除） src/client/theme.ts # 调色板 → token 覆盖层 src/client/extract.ts # 图片缩小 + 主色/平均色/亮度抽取（canvas） src/client/color.ts # 纯色彩数学（RGB/HSL/亮度） src/client/store.ts # localStorage 持久化 cordis.patch.yml # bundle patch：把插件挂载进 profile scripts/build.mjs # esbuild 构建（host ESM + client 模块加载器包壳） scripts/smoke.mjs # 冒烟验证（host 导出 + client bundle 契约）

开发

需要 Node.js ≥ 22.13（pnpm 11 的要求）与 pnpm 11。

pnpm install
pnpm build # 产出 lib/index.js 与 lib/client.js（esbuild + tsc 声明）
pnpm typecheck # tsc --noEmit
pnpm smoke # 冒烟验证：host 导出 + client bundle 契约（无需浏览器）

兼容的 DSH 版本

DSH 在加载 bundle 前，会拿它声明的 @deepseek-ai/dsh- peerDependencies 与自身运行时版本比对，所以请切到与你在用的 DSH 对应的 tag：

| Tag | DSH 运行时 | slots 服务来自 |
| v1.1.0 | 0.2.0-rc.2（0.2.x） | @deepseek-ai/dsh-client-ui-renderer |
| v1.0.0 | 0.1.0-rc.6（0.1.x） | @deepseek-ai/dsh-client-runtime |

git checkout v1.1.0 # 配 dsh 0.2.x
git checkout v1.0.0 # 配 dsh 0.1.x

切 tag 不需要重新构建：两个 tag 的差异只在 manifest（peerDependencies、dsh.client.inject、版本号）和被擦除的类型文件里，产出的 lib/ bundle 相同。若要继续开发，切换后请跑一次 pnpm install——pnpm-lock.yaml 是按 tag 各自维护的。

上面这套 git checkout 只适用于本地 clone + link: 挂载。dsh plugin 没有"原地切换版本"这回事：它把参数原样转发给 pnpm，所以换版本就是换依赖 spec（在 profile 里 pnpm add <spec>，或 remove + add）。重启后加载新副本；git spec 的兼容性检查发生在 pnpm 跑完之后，不兼容的 tag 会被拒绝并回滚（见下）。

github: 安装会自己构建：package.json 声明了 prepare: pnpm build，pnpm 会在抓取 git 依赖后运行 prepare。但 pnpm 11 默认拦截该脚本，所以第一次尝试会故意失败并打印需要放行的确切键（见下面"从 GitHub 安装"）。开发请走 link:。

若 DSH 日志出现 skipping profile bundle "dsh-image-skin"，说明当前 tag 与运行时不匹配：请换 tag，而不是去授 dsh plugin allow-version 豁免。

安装到你的 web profile

方式一：本地开发（link 源码，推荐）

cd <本仓库目录>
pnpm install && pnpm build

一步安装并自动挂载（无需手改任何文件）
dsh plugin --profile web add link:<本仓库的绝对路径>

然后重启 DSH、浏览器硬刷新（Ctrl/Cmd+Shift+R）。dsh plugin 检测到 dsh.bundle.patch 会自动把插件追加进 dsh.profile.bundles。

方式二：从 GitHub 装某个 tag（不需要本地 clone）

1. 第一次会失败，并打印它需要的那个 allowBuilds 键
dsh plugin --profile web add github:YouHui1/dsh-image-skin#v1.1.0

2. 把打印出来的键贴进 ~/.dsh/profiles/web/pnpm-workspace.yaml，再重试 allowBuilds: 'dsh-image-skin@github:YouHui1/dsh-image-skin#<sha>': true
dsh plugin --profile web add github:YouHui1/dsh-image-skin#v1.1.0

键必须与 pnpm 打印的完全一致（含 commit SHA）：pnpm 会把 tag 解析成 commit，写成仓库级的 github:YouHui1/dsh-image-skin 是匹配不上的（实测被拒）。换 tag、或 tag 被移动，SHA 就变了，pnpm 会打印新键，需要重做第 1 步。prepare 跑的是 pnpm build，所以执行安装的机器需要 Node ≥ 22.13 并能访问注册表拉取 devDependencies。

本项目不发布到 npm（package.json 已设 "private": true），个人使用走方式一即可；如日后要公开发布，见 AGENTS.md。

注意：不要同时用两种方式挂载同一插件（会加载两份）。若 profile 的 cordis.patch.yml 里还残留旧的手写 insert 挂载行，切到 bundle 通道前先删掉。

卸载

bundle 通道（dsh plugin add 安装的）：

dsh plugin --profile web remove dsh-image-skin

这会移除依赖、卸载包，并自动把它从 dsh.profile.bundles 剔除。重启 DSH + 硬刷新即可。

手动 link 安装的：从 ~/.dsh/profiles/web/package.json 删掉 dsh-image-skin 依赖，从 cordis.patch.yml 删掉 image-skin 的 insert 块，再 pnpm install、重启。

清理皮肤数据：图片存于浏览器 localStorage 的 dsh-image-skin.v1，卸载前先在设置页点「移除皮肤」，或在 DevTools → Application → Local Storage 删除该键。

注意事项

- client 半改动只需硬刷新浏览器；host 半改动（本插件 host 为空）才需要重启 DSH。
- 图片以 data:image/jpeg 存进 localStorage，单张约几百 KB，远小于 5MB 配额。
- 移除皮肤会调用 overrideTokens 返回的 disposer，界面立即回到原主题。

已知限制

- 极端高饱和图片可能让个别表面色偏浓；已对背景饱和度做了封顶（sat ≤ 45），且弹框/菜单等叠层始终 ≥80% 不透明以保住可读性。

License

MIT

本项目为第三方社区插件，与 DeepSeek / DeepSeek Harness 无官方隶属关系；相关名称与标识归其各自所有者所有。