dsh-image-skin

English | 中文

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 变量写到 `` 上，因此整个应用的配色随之改变。移除皮肤时调用返回的 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 契约）