viphzz/whale-girl-assistant

whale-girl-assistant

DeepSeek Harness（DSH）网页版右下角的一只小鲸鱼娘看板娘。

你让它干活的时候，她会在角落里跟着忙活；任务一完成，她就蹦起来撒彩屑、放一段庆祝音效。所有动画和声音都是浏览器本地生成的，不依赖任何外部服务。

特点

- 三种状态各有专属动画：空闲时上下漂浮、工作时快速抖动、完成时跳跃 + 发光 + 彩屑
- 音效使用真实 WAV 文件播放（不是粗糙的合成音），每次播放带轻微随机音高，不机械
- 浮层点穿（pointer-events: none），右下角出现的小鲸鱼娘永远不会挡住你点页面上的东西
- 可换皮肤、可静音，都是点击按钮的事
- 一键安装脚本，开箱即用

快速开始（一键安装）

Windows 上打开 PowerShell，运行：

powershell -ExecutionPolicy Bypass -File install.ps1

脚本会从 GitHub 下载全部文件到 %USERPROFILE%\.dsh\whale-girl-assistant\，自动生成好带本机路径的 host.js，并写一个 ACTIVATE.txt。

然后打开 DSH 网页版，把 ACTIVATE.txt 里的那句话粘给 DSH（或直接说「加载 whale-girl-assistant 插件」）：

使用 C:\Users\你的用户名\.dsh\whale-girl-assistant 目录下的 host.js 和 client.js 创建动态 Cordis 插件 whale-girl-assistant 并运行

DSH 会完成插件的定义和运行。首次需要批准浏览器端激活——批准后小鲸鱼娘就出现在右下角了。

也可以加参数指定安装目录：
powershell -ExecutionPolicy Bypass -File install.ps1 -Base "D:\tools\whale-girl"

手动安装（不用脚本的话）

1. 把 host.js、client.js、assets/ 放到任意目录（记得改 host.js 顶部的 BASE 常量为该目录的绝对路径）
2. 在 DSH 会话里说「用这两个文件创建动态 Cordis 插件并运行」
3. 批准浏览器端激活

立绘（皮肤）

| 文件 | 说明 |
|---|---|
| assets/skins/skin-default.png | 默认立绘，仓库内置一枚 OpenMoji 鲸鱼（CC BY-SA 4.0，可自由分发） |
| assets/skins/skin-custom-1.png | 你自己的立绘，放到这个文件名即可，点 🎨 按钮在皮肤间切换 |
| assets/skins/skin-custom-2.png | 同上，第三个皮肤 |

图片要求：PNG 格式、透明背景、宽高建议 400×400 左右、单张不超过约 500KB。放进目录后重启插件（或重新运行）即可生效。

⚠️ 版权提示：请只使用你有权再分发的图片。本仓库不会包含任何未经授权的角色立绘。

音效

音效来自 Freesound（CC0 猫娘语音/女孩笑声）和 Kenney 界面音效包（CC0）。授权详情见 assets/sfx/SOURCES.md。

| 文件 | 内容 | 来源 |
|---|---|---|
| idle.mp3 | "喵！" 猫娘语音 | Freesound 625317 · DarkNightPrincess |
| work-start.mp3 | 短促的喵 | Freesound 336012 · Mike_bes |
| work-tick.wav | 短滴答 | Kenney Interface Sounds |
| complete.mp3 | 小女孩咯咯笑 | Freesound 346903 · Lewicha |

想换音效：用同名的文件覆盖 assets/sfx/ 下对应文件即可（支持 wav / mp3 / ogg），无需改代码。

使用方法

- 点一下小鲸鱼娘：播放空闲音（同时解锁浏览器音频——Chrome/Edge 首次需要一次用户点击才允许出声）
- 🔊 按钮：静音 / 恢复
- 🎨 按钮：切换立绘（有多张皮肤时可用）

状态变化是自动的：DSH 的 Agent 开始处理消息时她会进入「工作中」，本轮结束回到「完成/空闲」。

⚠️ 注意：DSH 的动态插件定义存在于会话进程中，重启 DSH 后需要重新加载一次（再次把 ACTIVATE.txt 里的那句话发给 DSH 即可）。一键安装的资源和脚本是持久的，只是「定义并运行」这一步要重做。

工作原理

DSH 基于 Cordis 插件体系。本插件是动态 Cordis 插件，拆成两个半区：

Node 进程（Host 半区）                浏览器页面（Client 半区）
─────────────────────                ─────────────────────
监听 agent/status 事件        ◄─────► 注册 shell.overlay 槽位浮层
记录 空闲/工作中 + 完成次数            每 400ms 轮询 get-state
get-assets：读图片/音效文件            解码 WAV → WebAudio 播放
→ base64 data URI 传给页面            CSS 动画驱动三态表现

状态感知

- Host 端监听 agent/status 事件（按 agent 作用域过滤，子代理的噪音不会误触），把 running→idle 的跳变记为一次「完成」。
- Client 端没有事件通道，只能每 400ms 轮询一次 host.call('get-state')。轮询周期 400ms，状态变化感知延迟很小。

资源传输

- Client 沙箱禁止 fetch，图片和音效由 Host 用 fs 服务读取文件，转成 data: URI 一次性传给浏览器（get-assets），之后浏览器本地解码使用。
- ⚠️ 一个坑：Host 沙箱里没有 Buffer，内置 btoa 会把字符串按 UTF-8 文本编码——直接用它转 PNG/WAV 二进制，高字节（128-255）会被多字节转义，图片损坏、声音失真。所以 host.js 里手写了一个直接操作字节数组的 base64 编码器，逐字节正确。

音频播放

- WAV 以 data URI 传入，Client 用 atob 手工转成 ArrayBuffer（因为 fetch 被禁），再用 WebAudio 的 decodeAudioData 解码。
- 播放时给 playbackRate 加 ±5% 随机值，同一音效每次听上去略有差异，避免机械重复感。

为什么动画在右下角

Client 半区通过 ctx.slots.inject('shell.overlay', ...) 注册到 DSH 页面框架级的浮层槽位。这个槽位本身就是点穿的、不占布局，是最适合放看板娘的位置。

目录结构

whale-girl-assistant/
├── install.ps1            # 一键安装脚本（Windows）
├── host.js.template       # Host 半区模板（install.ps1 替换 __BASE__ 生成 host.js）
├── client.js              # Client 半区（浏览器端）
├── assets/
│   ├── skins/
│   │   └── skin-default.png   # 内置默认立绘（OpenMoji，CC BY-SA 4.0）
│   └── sfx/
│       ├── idle.mp3           # "喵！"猫娘语音（Freesound CC0）
│       ├── work-start.mp3     # 短喵（Freesound CC0）
│       ├── work-tick.wav      # Kenney 界面音效（CC0）
│       ├── complete.mp3       # 女孩笑声（Freesound CC0）
│       ├── LICENSE-kenney.txt # Kenney 授权
│       └── SOURCES.md         # 音效来源说明
├── LICENSE                 # MIT
└── README.md

常见问题

重启 DSH 后小鲸鱼娘不见了？
动态插件的定义在会话进程里，重启后需要重新把 ACTIVATE.txt 的指令发给 DSH 一次。

点了角色没声音？
浏览器策略要求一次用户手势后才能出声——先点一次小鲸鱼娘或 🔊 按钮解锁。

图片显示成破损图标？
说明 base64 编码有误，确认用的是 host.js 里的 bytesToBase64（不要用沙箱内置 btoa）。

立绘不生效？
确认图片放在 assets/skins/ 下且文件名匹配（skin-default.png 或 skin-custom-N.png），然后重启插件让 Host 重新读取资源。

许可

- 代码：MIT License
- 内置立绘：OpenMoji 项目（CC BY-SA 4.0）
- 音效：Kenney（CC0）
- 用户自备的立绘素材版权归原作者所有，请自行确认授权