鲸鱼美化包 nlqh7/dsh-beautify

@nlqh/dsh-beautify

DSH 社区插件 · 一站式美化包：鲸鱼光标 / 子代理小鲸鱼 / 29 套主题 / 自定义皮肤 / 声音与设置

每个子代理都是一只独立、完整、可互动的小鲸鱼，默认贴着主鲸鱼底边排成一行（从侧栏右缘起向右排，不钻侧栏）；主鲸鱼本身可拖动、点击回弹、换皮；29 套主题、10 态光标，所有声音都能单独控制。

3 只子代理小鲸鱼 + 报到气泡

🚀 安装

DSH Hub 搜索 @nlqh/dsh-beautify → 安装即用，无需配置。装好后：

- 屏幕右下角出现主鲸鱼；
- 启动子代理 → 自动出现对应小鲸鱼；
- 设置 → 外观 → 主题 / 光标 / 声音 / 壁纸。

兼容性：面向 DSH 0.1.6-alpha.2 及以后（清单声明 engines.dsh: ">=0.1.6-alpha.2"、dsh.manifestVersion: 1）。
alpha.2 与更早的 0.1.0-rc.8 客户端插件契约不同，同一份构建无法同时兼容：

| | rc.8 | alpha.2（本版） |
| store | @deepseek-ai/dsh-client-runtime | @deepseek-ai/dsh-client-store |
| ClientContext | dsh-client-runtime/client | @deepseek-ai/cordis |
| renderer 类型合并 | 来自 ui-slots | @deepseek-ai/dsh-client-ui-renderer/client |

版本号与 tag 谱系：alpha.2 谱系的 tag 带 -alpha2 后缀（如 v0.5.4-alpha2）；git tag -l 里不带后缀的 v0.4.0–v0.7.0 全部指向 alpha.2 迁移之前的旧谱系提交 —— 按 tag 拉代码前先确认后缀。详见 CHANGELOG。

✨ 功能

🐳 子代理小鲸鱼 — 每只都是完整插件

5 只子代理 + 主鲸鱼 + 碰撞推开

| 特性 | 说明 |
| 1:1 生命周期 | 每个子代理 = 一份完整小鲸鱼；入场→出现，离场→离开（带"呱"声） |
| 错开报到 | 同时到达时逐只跳出来（间隔 ~170ms），每只"叽"一声，并在自己头顶冒一个「报到！」小气泡 |
| 点击回弹（q 弹） | 按下瞬间弹一下（squash & stretch），配合叫声一按一响；hover 不弹 |
| 摸多了会生气 | 10 秒内连按满 8 次 → 左右抖动 + 气话气泡，15 秒冷静期内不重复触发 |
| 可单独拖动 / 摸头 | 拖到任意位置自动吸附墙壁；鼠标放上去立刻变系统手型（grab） |
| 碰撞体积 | 松手时与主鲸鱼/其他小鲸鱼重叠自动弹开，永不重叠 |
| 独立声音开关 | 菜单里可单独关掉子代理叫声，不影响主鲸鱼 |
| 点击 ≠ 拖动 | 位移 < 5px 视为点击，不触发吸附/锁定 |
| 小巧落地 | 同款图但尺寸为主鲸鱼 30%（64–128px），首次出现原地淡入落地，不浮空 |

🖱️ 鲸鱼光标 — 10 种状态逐态可控

默认箭头 / 链接手型 / 文本 / 忙碌 / 禁止 / 十字准星 / 背景 / 画笔 / 帮助 / 拖动。

- 拖动默认用系统原光标（grabbing 手感最自然）；摸头（hover 主鲸鱼）→ 立刻恢复系统手型
- 状态开关里可单独把每态切回皮肤；自定义皮肤可上传 10 张图分别覆盖各态，尺寸 24–64px

🎨 29 套主题 + Wallpaper Engine 桥接

悟空 / 晨雾山水 / 夕港 / 橘子洲头 / 人民的 AI / 芙宁娜 / Reze / Firefly / DeepSeek / miku / 女仆系列 / 云鲸纸面 / 大肥鱼 / claude-eva / dream-* ……（内置 + 暗/亮双套，共 29 套）。

WE 桥接：装本机 WE 后，用各自电脑的 WE 壁纸，不占包体积。扫描本机 WE 壁纸（web HTML/JS 动画 + 视频），设置 → 外观 → 壁纸引擎一键切换、随时刷新。
壁纸模式下自动挂起当前主题（色板与装饰一并隐藏），界面回归 dsh 默认观感、壁纸全屏干净显示；关闭壁纸后主题完整还原。配暗化 / 模糊 / 边框 / 玻璃 4 个滑块微调。
切换是缓动的：挂载淡入、换壁纸时新旧交叉淡出淡入、关闭时淡出后再卸下主题 —— 不会有"啪一下"的突变；prefers-reduced-motion 下自动改为瞬时切换。切到别的标签页时壁纸视频自动暂停。

WE 壁纸生效：壁纸穿透主题背景显示

WE 壁纸选择器：扫描本机 Wallpaper Engine 壁纸

🦢 深海女仆工坊（默认主题 · vendored）

默认主题：新装 / 未设置过主题时，直接启用深海女仆工坊。

深海女仆工坊：左右双女仆立绘 + 藏蓝金边 UI + 主鲸鱼

海军蓝 + 金色调色板，水墨山水背景 + 候鸟女仆角色，提供暗色 / 亮色两套皮肤。

- 聊天界面女仆大尺寸清晰显示（96vh），输入区/操作按钮始终浮在女仆之上不挡操作
- 新会话 / 新绘画等非聊天视图女仆固定在背景层（z=2），让位给弹窗与输入区；轨迹视图不显示女仆
- 深浅两档是两套底图：浅色档瓷白纸面 + 宫殿；深色档换成夜宫图，可读性遮罩用夜底色

深海女仆工坊 · 浅色档：瓷白纸面聊天态

深海女仆工坊 · 深色档：夜宫图 + 夜底 scrim + 深色玻璃卡

🐋 挂件菜单与气泡

- 随机台词：点击气泡切换（峰谷时段 / 今日已用 / 卖萌吐槽 / rua 动图），每段完整停留 5 秒
- 每轮对话消耗：每轮结束弹出本轮消耗（真实 usage 换算，非估算），可开关、可自定义自动关闭秒数
- 峰谷文案三选一；v4-pro 3 倍价按官方 2026-08 定价换算
- 滚动条避让、锚点位置记忆、多币种优先取 CNY 正余额、并发会话分桶（主会话与子代理不串账）

🔊 声音系统

主鲸鱼点击/拖动（press / release）、子代理点击/报到/离开 cry、用量气泡（令牌模式），总音效开关 + 音量；2 个音效包可选（小黄鸭 / fx1）。

⚙️ 设置

设置弹窗跟随主题自身明暗（不是宿主偏好），暗色主题下弹窗也是深色；外观页统一管理明暗模式、纯色/壁纸主题、光标、玻璃与壁纸参数。

📸 截图

上面各节已内嵌 7 张（01 / 04 / 05 / 06 / 07 / 11 / 12）。docs/screenshots/ 里另有 5 张未内嵌：

| 文件 | 场景 |
| 08-maid-settings-light.png | 设置弹窗（浅色档）区域裁图：编号导航 + 外观/主题面板 |
| 09-maid-settings-dark.png | 同一弹窗的深色档：弹窗跟随主题自身明暗，不跟宿主 |
| 10-maid-sidebar.png | 会话侧栏竖条：海军蓝底 + 金边 + 会话行 / 工作区 |
| 13-appearance-light.png | 设置 → 外观（浅色档）整屏：明暗模式 / 纯色主题 / 主题计数胶囊与「选择」按钮 / 壁纸引擎入口 |
| 14-appearance-dark.png | 同一页的深色档：胶囊与行底在夜底上同样可辨 |

🔑 Key References（关键引用）

发布到 DSH Hub 需要这些文件齐全，DSH Hub 在安装时会读取它们：

| 引用 | 位置 | 作用 |
| 包清单 | package.json | name: @nlqh/dsh-beautify、dsh.bundle.patch 声明 |
| 发布协议 | cordis.patch.yml | 顶层 YAML 数组，insert 声明本包要注入的 loader 条目 |
| 服务端入口 | lib/index.js | Cordis loader 看到的服务端插件实现（/wallpaper-engine/、/dsh-whale/ 路由） |
| 浏览器端 | lib/client.js | 浏览器端 apply 入口（注入主题 / 光标 / 设置 / 子代理监听） |
| 鲸鱼脚本 | src/whale-widget.js | 主鲸鱼 + 小鲸鱼 widget（拖动、吸附、碰撞、气泡、声音） |
| 主题 | src/client/themes.ts | 29 套 DreamSkin 预设 |
| 壁纸 | src/client/wallpapers.ts | 内嵌壁纸 base64（≈1.65 MB） |
| 光标 | src/client/cursor-images.ts | 10 态光标图 |
| 声音 | assets/Ya.mp3 / assets/D.mp3 | 主鲸鱼（Ya1/Ya2）+ 子代理（D1/D2）音效 |
| 角色图 | assets/DSniang1.png | 主鲸鱼 + 小鲸鱼共用图（透明背景、完整角色） |
| 反应 GIF | assets/reactions/.gif + assets/rua.gif | 生气 / 摸头 / 闲置 / rua 动图 |

发布校验：DSH Hub 读 dsh.bundle.patch → 解析 cordis.patch.yml（entryListSchema：顶层数组）→ 校验 insert[].name 与 package.json#name 一致。

🛠️ 本地开发

git clone https://github.com/nlqh7/dsh-beautify.git
cd dsh-beautify
pnpm install
pnpm dsh web # 需要在 DSH harness monorepo 内

改 src/client/ 后必须重建产物并重启实例，宿主把 bundle 常驻内存：

node node_modules/tsdown/dist/run.mjs # → lib/client.js

小贴士：WorkBuddy 环境下 git push 会被 helper-selector 卡住，用环境变量 GITHUB_TOKEN + URL 内嵌绕过：

git -c credential.helper= push "https://x-access-token:${GITHUB_TOKEN}@github.com/nlqh7/dsh-beautify.git" master

📜 License & Credits

License: CC BY-NC-SA 4.0

Credits:
- MeteorNOX/DeepSeek-Balance-Whale-Widget — 余额显示与鲸鱼 UI 灵感
- zhu1090093659/dsh-web-ui — 深海女仆工坊皮肤（vendored, CC BY-NC-SA）
- Aibie07/whale-girl-desktop-pet — 反应 GIF 播放机制参考
- 角色立绘：DSniang1.png（CC BY-NC-SA）
- assets/reactions/.gif：来自 B 站 UP 主「赤风RED」的「蓝色大肥鱼」表情包，版权归原作者所有，仅随本插件作非商业展示用途；如需另行使用请获取 UP 主本人授权
- DSH 社区 @nlqh7 制作维护