deepseek-harness-desktop/packages/skins/whale-song

一句话定位

「鲸吟（Whale Song）」是 dsh web GUI 的主题皮肤插件，把界面换成深海鲸语女神氛围：左侧蓝发女神与鲸群、右侧大面积留白的纯氛围画作为背景，冰蓝/浅青/深海军蓝/钴蓝冷色板加金色细线点缀重映射全部主题 token，半透明面板让背景透出。它只改变 DOM 外观，不影响模型请求和对话数据。

核心能力

• 在浏览器全视口挂载深海鲸语氛围画背景（base64 内嵌的 1920×1080 WebP，无需联网下载）
• 把 dsh 主题色板重映射为冰蓝 / 浅青 / 深海军蓝 / 钴蓝冷色体系 + 金线点缀（CSS alias token 全量重写，包括滚动条、链接、按钮、对话框、菜单、git graph 节点等组件）
• 让主面板、侧边栏、菜单等大面积表面变为半透明，让背景画透出来
• 注入自定义 favicon（官方 DeepSeek 蓝色鲸鱼图标，PNG data URL，非 SVG）
• 跟随宿主基础主题实时切换亮/暗遮罩（冰蓝薄纱 ↔ 深海军蓝夜航纱），由 MutationObserver 监听 data-ds-dark-theme 变化自动重绘
• 关闭（dispose）时完整撤回：移除 body 属性、按原值还原背景图、移除注入的 favicon

技术实现

• 语言: TypeScript + CSS Modules
• 关键依赖: @deepseek-ai/cordis（仅类型导入，effect 生命周期）、lightningcss（CSS 编译）、tsdown（构建，使用仓库共享 shared/tsdown.client.ts 预设）
• 架构模式: DSH 客户端半区插件；apply(ctx) 通过 ctx.effect(...) 注册 disposer，关闭时按 ThemePresenter 规范撤回所有写入；不注入任何 cordis 服务、不发事件，host 半区 src/index.ts 是空壳（apply 为 noop）
• 入口文件: src/index.ts（host 侧空壳）+ src/client/index.ts（核心逻辑，106 行）+ src/client/art.ts（内嵌背景画与图标）

适用场景

喜欢深海奇幻氛围插画、冰蓝/海军蓝冷色配色的普通用户，把 dsh web GUI 换成更有故事感的视觉风格。安装并激活后，整个界面背景变成深海鲸群氛围画，面板变成带磨砂感的半透明，深海军蓝底搭配冰蓝/金线强调色，不影响任何对话和模型行为。适合日常长时间使用、希望界面有沉浸氛围感的人群。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/skins/whale-song

安装完成后还需要激活：

dsh-skin use whale-song

配置项

本插件无需额外配置。apply() 内部通过 ctx.effect(...) 自动注册 disposer，无需用户手动维护生命周期；亮/暗遮罩切换由 MutationObserver 监听宿主主题属性全自动完成。

常见问题

Q: 这个皮肤影响我的对话记录和模型请求吗？

A: 不影响。它只修改浏览器 DOM（背景图、面板颜色、favicon），不注入任何 cordis 服务、不发请求、不触碰模型 API，也不会修改 KV Cache 行为。

Q: 一次能同时启用多个皮肤吗？

A: 不能。同一时刻只激活一个皮肤，切换时新皮肤接管、旧皮肤完整卸载；切换用 dsh-skin use whale-song。

Q: 关闭后会留下痕迹吗？

A: 不会。effect disposer 会撤回它写入的所有内容：移除 body 属性、按 CSSOM 规范读取并按原值还原背景图、移除注入的 favicon，原页面样式完整恢复。这点由 tests/apply.spec.ts 的"retracts everything on dispose"用例守护。

Q: 装了之后为什么界面没变？

A: 仅安装到 profile 不等于已激活。还需要执行 dsh-skin use whale-song 才会套用该皮肤。

Q: 支持深色模式吗？

A: 支持。皮肤会跟随宿主基础主题切换：深色模式下遮罩换成深海夜航深海军蓝纱（rgba(6,14,36,...) 系），亮色模式下是冰蓝薄纱（rgba(240,246,252,...) 系），由 MutationObserver 监听 body[data-ds-dark-theme] 实时重绘背景，无需重新挂载。

Q: 鲸群背景图是哪来的，为什么安装包不大却能离线显示？

A: 图片以 base64 data URL 内嵌在 src/client/art.ts 里（约 150KB 的 1920×1080 WebP），皮肤完全不依赖任何外部静态资源，离线也能正常显示。原概念图的海报文字（DEEPSEEK / 鲸吟·深寻 / ARCHIVE）已重新生成移除，避免界面文字与背景打架。需要换画时可按文件头注释的 node scripts/embed-skin-art whale-song WHALE_ART <imagePath> 1920 重新生成。

Q: favicon 替换成什么，会和原版冲突吗？

A: 替换为官方 DeepSeek 蓝色鲸鱼图标（deepseek.com 原版 favicon 转 PNG 的 225×225 data URL），与原版同款；激活后浏览器标签页图标就显示它，关闭皮肤后自动恢复原 favicon。

Q: 第一次安装需要先本地构建吗？

A: 不需要。通过 git 链接安装时 prepare 脚本会自动构建 lib/；但 pnpm ≥10 首次安装 git 依赖可能需要把打印的包键加入 pnpm-workspace.yaml 的 allowBuilds 列表再重试。

上手难度

入门 — 一条命令安装、一条命令激活，没有任何配置项，普通用户即可上手。

已知问题与限制

• 同一时刻只能激活一个皮肤；切换会完全卸载当前皮肤
• 故意不在祖先元素上使用 backdrop-filter 模糊：会破坏 fixed 定位覆盖层（如设置面板）的包含块，使其被锁在父容器内；半透明通过 token 层（--dsw-alias-bg-*、--dsw-specific-sidebar-fill）实现
• 鲸群背景图为内嵌 base64（约 150KB），会增加少量 bundle 体积
• 当前源码内未发现 TODO / FIXME / HACK 等显式已知问题