dsh-whale-musume
sutera-diffusus/dsh-whale-musume
DeepSeek Harness용 고래 소녀 동반 앱입니다. 업적 45개, 일일 퀘스트와 주간 체크인, 미니게임 3개, 아트 92개, 대사 620개, 성장 일지, 날씨·축제 반응, 도구별 작업 포즈를 제공합니다. JSON 파일 또는 마이그레이션 코드로 기기 간 저장 데이터를 내보내고 가져올 수 있으며 접근성 모드도 있습니다. MiMo TTS 브리지는 선택 사항입니다. 데이터는 호스트 localStorage에 저장되고 텔레메트리는 없습니다. DSH desktop 0.2.0-rc.2에서 검증됐으며 0.2.1-rc.1/rc.2와 레거시 0.1.x 웹에 호환됩니다.
설치
dsh plugin --profile web add github:sutera-diffusus/dsh-whale-musumeREADME
鲸鱼娘 · dsh-whale-musume
DeepSeek Harness 的桌宠看板娘:安静陪你写代码,工作一开始她就抱起笔记本,绝不插嘴。
一分钟上手 · 看看她长什么样 · 她有什么 · 常见问题 · English
动图由 @kingOfSoySauce 录制(PR #37),已收进仓库,不依赖外链。
为什么是鲸鱼娘
大部分桌宠要么只是「会动的图」,要么会在你专注时抢注意力。鲸鱼娘的三条硬规则:
| 原则 | 具体做法 |
|---|---|
| 不打断你 | 工作态(有工具在跑)绝不弹话、不乱切姿势;所有闲聊、关怀、播报都只在待机时发生 |
| 不抢你的焦点 | 默认是纯装饰:aria-hidden、不拦截键盘、不覆盖业务 DOM、不改任何内置包文件;连焦点都要你主动开无障碍模式才拿得到 |
| 不给你添隐私负担 | 无遥测、不上传、默认零外部请求;台词播报、关键词感知、余额、无障碍这些会读内容/金额的功能全部默认关闭 |
而且她是真的会看你在干什么:不是定时随机换图,而是读取宿主的结构化标记(工具卡状态、会话运行标记、终端块)来判断你在忙什么,再决定摆哪个姿势、要不要闭嘴。
目录
- 一分钟上手
- 看看她长什么样
- 她适合谁
- 她有什么
- 兼容性
- 第一次使用
- 使用说明
- 设置面板
- 更新 / 回滚 / 卸载
- 版本更新
- 数据与隐私
- 常见问题
- 故障排查
- 路线图
- 项目结构
- 开发与测试
- 参与贡献
- 致谢
- License
一分钟上手
最简:从 npm 装(不需要 git ls-remote 预检,网络受限时更稳):
# 桌面端(Electron 壳)——把路径换成你的安装位置
$Desktop = "D:\DeepseekHarnessDesktop"
$Cli = "$Desktop\resources\app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\cli.js"
$env:ELECTRON_RUN_AS_NODE = "1"
& "$Desktop\DeepSeek Harness.exe" --expose-internals $Cli plugin --profile desktop add dsh-whale-musume
# 旧版 Web profile
dsh plugin --profile web add dsh-whale-musume
也可以继续从 GitHub 源装(等价;想跟 main 最新提交时用这个):
dsh plugin --profile web add github:Sutera-Diffusus/dsh-whale-musume
装完重启宿主(桌面端重启应用;旧版 Web 重启 dsh web 后 Ctrl+F5),她就出现在右下角了。
镜像同步提示:新包在 npmmirror 上可能短暂显示
0.0.0-stage(发布占位版本)。看到这个版本不要装;在插件管理器的 Registry 选择器切到 npm 官方源,或等镜像同步。官方源核验:npm view dsh-whale-musume version --registry=https://registry.npmjs.org应为2.5.2。
从插件市场或
dsh plugin add装不上时,见安装失败排查。日志被截成只剩[exit 1]、走 git 源时的git ls-remote超时、还有allowBuilds提示,那一节都写了。
装完怎么确认她真的进来了?
在宿主页面按 F12 打开控制台,执行:
window.__dshWhaleMusumeBooted // true
document.querySelectorAll('[data-dsh-whale-root]').length // 1
getComputedStyle(document.querySelector('[data-dsh-whale-root]')).display // "block"(首页可见)
window.__dshWhaleMoeDebug // state 非 "hidden",含当前姿势/视图等信息
四项都对说明安装成功。任一项不对,见故障排查。
另有一种脚本安装(注入前端资源 + 自带备份回滚),只适合主题集成或没有组合包支持的旧环境:见
scripts/apply-theme.mjs。两种方式二选一,不要混用。
看看她长什么样
| 待机陪伴 | 工作状态联动 |
|---|---|
![]() | ![]() |
| 默认悬浮在右下角,随机喝咖啡、伸懒腰 | 检测到工具运行,抱起笔记本,带淡蓝光晕 |
| 摸头互动 | 投喂互动 |
|---|---|
![]() | ![]() |
| 单击摸头,脸红立绘 + 爱心星星飞出 | 右键投喂,提升饱食度与好感度 |
| 悬浮形态(可拖拽) | 立绘总览(90+ 张) |
|---|---|
![]() | ![]() |
| 200px 默认尺寸,拖到她喜欢的地方 | 状态 / 互动 / 成长 / 游戏 / 天气 / 节日 / 梗表情 |
更多素材:交互动作总览 · 新增立绘总览 · 宣传海报 v1 / v2 / v3 / v4
她适合谁
- 你想要的不只是「会动的挂件」,而是一个有进度可攒的桌宠:每日任务、周签到、45 个成就、三个小游戏、成长日记。
- 你同时用 DSH 桌面端和旧版 Web,或者经常换机器——她有跨端存档导出/导入。
- 你在意本地优先:数据只在宿主 localStorage,无遥测,卸载即走;203 项测试覆盖核心逻辑与交互接线。
- 如果你只想要 Live2D 级动画或独立桌面透明窗,同类里有更专精的项目;鲸鱼娘的重点是「陪伴系统」。
她有什么
🐋 本体与行为
| 特性 | 说明 |
|---|---|
| 悬浮 / 侧栏 / 底栏 / 迷你 / 自动 | 五种形态,按视图自动切换;默认 200px 悬浮 |
| 拖拽 + 惯性 | 拖拽时切换「被拎起来」立绘,身体随光标方向摇摆;松手后按瞬时速度滑行一段并旋转回正,撞到屏幕边缘会「抓住」边缘停住;轻放只做一次轻微回弹,位置在滑行结束后才保存 |
| 动势遮断过渡 | 待机 ↔ 工作之间用「下压 → 换图 → 弹起」过渡,不叠影、不闪黑;后台标签页被浏览器暂停换图动画时有 1.6s 超时兜底 |
| 唤回入口 | 在设置里关掉她之后,左下角留一枚 🐋 按钮,点一下就叫回来,不会再「消失得找不着」 |
💼 工作状态联动
| 特性 | 说明 |
|---|---|
| 忙闲联动 | 检测到工具运行自动切「抱笔记本工作」,带淡蓝光晕与「工作中」标签 |
| 按工具类型细分姿态 | 跑命令 / 改文件 / 搜索 / 测试 / 评审 / 部署 / 调试各有对应姿势;识别不了就回落通用姿态,绝不乱猜 |
| 工作期稳定 | 工作中不切小剧场、不插话;信号短暂中断时姿势继续钉住(工作台 8s / 其他页 4s),不抽搐 |
| 点击反应 | 工作中点她会随机出现「害羞抱电脑」或「偷吃内存条」,不打断工作状态 |
📈 养成与成就
- 基础数值:心情、好感度、饱食度、等级、连续签到、陪伴时长
- 每日任务:3 个槽位每日自动刷新,完成领好感奖励
- 周签到:本周 7 格签到板,集满 1 / 3 / 7 天有里程碑奖励
- 羁绊等级:Lv3 解锁新待机动作、Lv5 称号「鲸汐守护者」、Lv7 隐藏彩蛋
- 45 个成就 + 成就墙:互动类 / 陪伴类 / DSH 用量类 / 游戏类 / 任务类,已解锁高亮、未解锁灰显;新增「百日之约」「一年之约」与翻翻乐四项
- 成长日记:按时间记录羁绊升级、成就解锁等节点,倒序显示最近 12 条
💬 台词与陪伴
- 530+ 条台词:全场景覆盖,可爱为主,叠加打工人 / 摸鱼 / DDL / 画饼 / 发疯文学等安全梗
- 梗关键词表情:命中 13 个关键词(kyun、OMG、doge、sike、膜拜、peace、怀疑人生、waku waku 等)现场变身表情包
- 5–8 分钟主动闲聊:按当前任务内容本地分类贴题,工作态绝不插嘴;深夜 23:00–5:59 不主动打扰
- 心情分层:心情低落时温柔、高涨时元气;羁绊等级解锁专属台词
- 天气陪伴:城市留空即零联网;填写后走 Open-Meteo(免费无需 Key),附带雨 / 雪 / 雷闪 / 风 / 雾 / 热浪 / 霜雾等全屏氛围特效,工作态自动降档
- 主动关怀:久坐提醒(连续忙 25 分钟)/深夜劝休息/卡住陪伴(状态停滞 8 分钟)/回来打招呼(离开超 3 分钟),两次之间至少隔 15 分钟
- 工作态台词两档(issue #24):干活时的思考 / 工具 / 成功 / 出错台词共用随机冷却窗口——话痨 15–40 秒、安静 90–240 秒,窗口之内只说一句;思考与工具台词按当前任务话题取词(与主动闲聊同一套本地分类),成功 / 出错保留各自语料。待机问候与天气不受影响,默认话痨
- 可选台词播报:检测到宿主装有
dsh-xiaomi-tts服务时才会出现「台词播报」开关,默认关闭;未安装、未配置或播放失败都不影响原有交互
🎀 互动与视觉
- 分区点击:头 / 肚子 / 尾巴三区独立判定,各有专属立绘、特效与台词
- 点击特效:爱心 / 星星 emoji 飞出;三连击触发星星眼庆祝 + 粒子特效 + 旋转动画
- 90+ 张立绘:待机、工作中、思考、离开、成长四态、游戏四态、天气三态、节日五套(圣诞 / 万圣 / 中秋 / 春节 / 情人节,当天自动换装)
- 三个小游戏:戳泡泡·泡泡派对(4×4 网格,普通 / 星星 / 炸弹,连击加分,30 秒一局)、接点心(键盘或鼠标追落下的点心,躲炸弹)、鲸鱼翻翻乐(4×4 记忆配对,复用 16 张现有立绘,60 秒、连击加成、零失误通关);三种游戏共享每日 3 局养成奖励上限,鼠标 + 键盘双通道可达
🧩 工程特性
- 零侵入:纯前端注入 + 一个只读静态资源路由,不改任何内置包文件
- 无构建步骤:仓库里的
assets/就是运行产物,装入即用 - 立绘预加载:首屏只预载 5 张常用姿势,其余 90+ 张在空闲时段每 120ms 取一张,冷启动切姿势不迟滞;预取失败完全静默
- 无障碍模式(默认关闭):可 Tab 聚焦、Enter / 空格摸头、方向键微调位置(Shift 加速),状态变化经
aria-live播报 - 主题跟随:跟随宿主明暗主题,只影响气泡/菜单这类 UI,立绘不做滤镜,不改画风
- 可测试性:核心状态机与表现层分离,单元测试可直接
node --test跑
兼容性
| 宿主 | 支持 | 说明 |
|---|---|---|
DeepSeek Harness 桌面端 0.2.0-rc.2 | ✅ 已实测 | 那个构建的 GUI 默认 127.0.0.1:19387。安装/回滚见0.2.0 部署手册 |
DeepSeek Harness 桌面端 / Web 0.2.1-rc.1~0.2.1-rc.5、0.2.2-rc.1 | ✅ 静态契约 | 对照上游 tag 的源码、本机 0.2.2-rc.1 app.asar 的 DOM 标记扫描与单元测试,没有在真实 Electron 里做视觉复跑。0.2.1 的桌面端端口改为系统分配(--port 0),不要再假设 19387。差分见0.2.1 契约与部署差分;2.5.1 的核对结论见发布说明 |
0.2.0-rc.1、0.2.1-alpha.1~alpha.5、0.2.2-alpha.2 / alpha.3、未来的 0.2.3~0.2.x | ⚠️ 可装但不承诺 | 2.5.3 起 engines.dsh 已放行整条 0.2.x 线;这些版本没有逐版本实测,矩阵里标 unknown。装得上,但遇到行为问题请带 DSH 版本与日志反馈 |
DSH 0.3.0 起(含 alpha) | ❌ 拒绝 | 大版本契约未核对,门禁保持在 <0.3.0-0,不会被未来 alpha 自动放进来的 |
旧版 Web profile(DSH 0.1.x) | ✅ 已实测 | 0.1.0-rc.6 及以上;设置面板在 0.1.1-rc.2 实测。再早的 0.1.0 预发布没有 dsh.bundle 安装通道,不在支持范围 |
| 其他 profile(headless / acp 等) | ➖ 无界面 | 没有浏览器界面,桌宠无处显示 |
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11(当前桌面端的支持范围) |
| Node.js | 18+(仅脚本安装方式需要;组合包安装不需要) |
| 浏览器 | Edge / Chrome 最新版 |
数据不互通:桌面端主窗口 origin 是
dsh-app://app,旧版 Web 是http://127.0.0.1:<端口>,两边localStorage(whale-moe:*)互不相通,也不会自动迁移。详见数据与隐私。
桌面端适配了哪些契约差异?(给插件作者看的)
v2.2.0 适配桌面端时,逐条核对了 DSH 0.2.0-rc.2 的真实契约并写了证据文档(docs/desktop-0.2.0-rc.2-contract.md):
| 契约点 | 0.2.0-rc.2 的变化 | 我们的处理 |
|---|---|---|
| 工具卡标记 | [data-role="tool"] 等旧标记 0 命中 | 改用 [data-tool](值 = 工具名)+ 同元素 data-state |
| 忙态判定 | 工具卡完成后仍留在 DOM(ok/stopped) | 只有 running / preparing 算「正在工作」 |
| 会话运行 | 新增 [data-chat-running](仅运行时挂载) | 作为最干净的活信号 |
| 终端 | [data-slot="terminal"] 不存在 | 改用 [data-terminal] |
| 输入框 | 变成 contenteditable | 改用 [data-composer-input] |
| 主题 | 明暗写在 body[data-ds-dark-theme](空串=暗) | 补齐识别,旧 data-theme/class 保留为回落 |
| 设置面板 | 常驻引导弹窗也是 role="dialog" | 判据收敛到 [data-shortcut-modal="settings"] |
| 客户端模块 | 惰性 CJS:副作用须在 factory 物化期 | boot() 从 apply() 移入 factory |
| 引导弹窗 | 刷新后常驻的 OnboardingModal | 不再误判为设置页(否则桌宠会被隐藏) |
这些行为都补了回归断言(test/desktop-client.test.mjs,34 项)。
v2.4.0 又对照了 tag dsh-v0.2.1-rc.2(见 docs/desktop-0.2.1-rc.2-contract.md):上表这些标记都还在,选择器没有改。变的是安装门禁——从 DSH 0.2.1-alpha.4 起优先读顶层 engines.dsh。本包的范围是 >=0.1.0-rc.6 <0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-rc.1 || 0.2.1-rc.2。0.2.1-rc.1 / 0.2.1-rc.2 标成 compatible 的依据是这份静态核对加单元测试,不是实机验收。
第一次使用
装好后按顺序试一遍,一分钟知道她好不好用:
- 点她一下 —— 脸红立绘 + 爱心特效;
- 连点三次 —— 星星眼庆祝 + 粒子特效 + 旋转动画;
- 拖着她走 —— 切「被拎起来」立绘、跟随光标摇摆,松手后滑行一小段并保存位置;
- 右键她 —— 投喂 / 戳一下 / 夸夸 / 三个小游戏 / 回到原位 / 打开设置;
- 跑一次工具调用 —— 她自动抱起笔记本,带淡蓝光晕;
- 打开 设置 → 看板娘 —— 15 个开关、养成数据、成就墙、成长日记都在这里;
- 换电脑前 —— 设置 → 看板娘 → 跨端迁移,导出存档或复制迁移码。
使用说明
拖拽
- 按住她移动,松手后位置自动保存;移动超过 4px 才进入拖拽状态(所以单击不会误触发拖拽)
- 右键 → 回到原位 恢复默认右下角
右键菜单
| 菜单项 | 效果 |
|---|---|
| 投喂小点心 | 提升饱食度与好感度,触发吃东西立绘 |
| 戳一下 | 降低心情,触发生气立绘 |
| 夸夸鲸鱼娘 | 提升心情与好感度,触发星星眼 |
| 小游戏:戳泡泡 | 打开 30 秒一局的泡泡派对 |
| 小游戏:接点心 | 键盘 / 鼠标追点心,躲炸弹 |
| 小游戏:鲸鱼翻翻乐 | 4×4 记忆配对,60 秒,连击与零失误加成 |
| 回到原位 | 清除保存的悬浮位置 |
| 打开设置 | 跳到 DSH 设置 → 看板娘 |
设置面板
路径:DSH 设置 → 看板娘(共 15 个胶囊开关 + 「工作中台词」话痨/安静两档 + 8 个折叠分组)。
| 分组 | 内容 |
|---|---|
| 陪伴表现 | 如何称呼我、她的自称(留空回落到「鲸鱼娘」)、看板娘开关、台词气泡、台词播报(可选)、粒子效果、关键词感知、摸鱼提醒、深夜模式、工具细分、拖拽惯性、主动关怀、无障碍、工作中台词(话痨 / 安静)、桌宠大小(80–240px,自适应) |
| 天气 | 天气城市、选填 API Key、天气特效开关 |
| 余额 | 余额关心开关、余额显示数字开关、当前余额与档位 |
| 日常与养成 | 今日任务 / 本周签到 / 称号(标签页收纳) |
| 成就墙 | 45 个成就,已解锁高亮、未解锁灰显 |
| 成长日记 | 羁绊升级、成就解锁等关键节点,倒序显示最近 12 条 |
| 跨端迁移 | 导出 / 导入存档(JSON),或复制 / 粘贴迁移码;带走好感度、等级、成就、任务、游戏记录与日记 |
| 数据与重置 | 重置悬浮位置、重置养成数据 |
默认关闭(涉及读取聊天内容或账户金额):关键词感知、余额关心、余额显示数字、台词播报、无障碍。
手机 / 触屏:直接触摸拖动桌宠;长按 500 ms 打开右键菜单(菜单里可直接切换「桌宠尺寸」);≤600px 的窄屏默认 130px。
跨端迁移(桌面端 ↔ 旧版 Web)
养成数据存在宿主 origin 的 localStorage 里,换桌面端、换电脑或换 profile 时不会自动跟过去。入口:设置 → 看板娘 → 跨端迁移。
- 导出存档:下载一份 JSON,包含心情 / 好感度 / 饱食度 / 等级 / 签到 / 成就 / 任务 / 游戏记录 / 成长日记 / 称呼。不含悬浮位置、天气城市与经纬度。
- 复制迁移码:只带核心进度(数值 / 成就 / 日记 / 称呼),适合聊天窗口里直接发给另一台设备。
- 导入:选 JSON 文件或粘贴
WM1-…迁移码,确认后覆盖同名数据;桌宠会立即重读,不用刷新页面。 - 迁移码带校验和,复制少一段会明确报错,坏码不会改动现有存档。
更新 / 回滚 / 卸载
更新
# 桌面端:升级后重启桌面端应用
& "$Desktop\DeepSeek Harness.exe" --expose-internals $Cli plugin --profile desktop add github:Sutera-Diffusus/dsh-whale-musume
# 旧版 Web:升级后重启 dsh web 并 Ctrl+F5
dsh plugin --profile web add github:Sutera-Diffusus/dsh-whale-musume
更新不会动你的养成数据(whale-moe:* 留在宿主 origin 的 localStorage 里)。
卸载
# 桌面端
& "$Desktop\DeepSeek Harness.exe" --expose-internals $Cli plugin --profile desktop remove dsh-whale-musume
# 旧版 Web
dsh plugin --profile web remove dsh-whale-musume
组合包方式无任何残留文件改写,卸载即干净移除;养成数据仍保留,重装后还在。只想让她暂时消失的话,直接关掉设置面板里的「看板娘」开关即可。
脚本安装方式
脚本会在 DSH_WHALE_BACKUP(默认系统临时目录)生成备份,回滚:
node scripts/apply-theme.mjs --rollback "<backup dir>"
版本更新
| 版本 | 日期 | 主题 | 要点 | 链接 |
|---|---|---|---|---|
| v2.5.3 | 2026-11-08 | 兼容全部 0.2.x | engines.dsh 放宽为 >=0.1.0-rc.6 <0.3.0-0:0.2.0-rc.1、0.2.1 / 0.2.2 的 alpha 与未来 0.2.3 线均可安装,未逐版本实测的标 unknown;0.3.0 起仍拒绝 | Release · Notes |
| v2.5.2 | 2026-11-06 | 手机触屏 + 桌宠大小 | 见下方要点 | Release · Notes |
| v2.5.1 | 2026-11-06 | 兼容 DSH 0.2.1-rc.3–0.2.2-rc.1 + 修透明隐身 | 见下方要点 | Release · Notes |
| v2.5.0 | 2026-10-21 | 翻翻乐 + 跨端迁移 | 第三个小游戏「鲸鱼翻翻乐」(16 张现有立绘、60 秒、连击/零失误);设置面板新增「跨端迁移」(JSON 导出/导入 + 迁移码,导入后热重载);新增 6 个成就(翻翻乐 4 + 百日/一年 2),成就总数 45 | Release · 说明 |
| v2.4.0 | 2026-10-19 | 适配 DSH 0.2.1-rc.2 | 补 engines.dsh;0.2.1-rc.1 / 0.2.1-rc.2 按静态契约标为 compatible(未跑真实 Electron);0.2.0-rc.2 与旧版 Web 仍放行;DOM 选择器无增删 | Release · 说明 |
| v2.3.0 | 2026-10-14 | 工作中台词两档 + 菜单不再被裁 | 见下方要点 | Release · Notes |
| v2.2.1 | 2026-10-01 | 贴边不再跑出屏幕 | 见下方要点 | Release · Notes |
| v2.2.0 | 2026-09-29 | 适配 DeepSeek Harness 桌面端 | 桌面端(Electron 壳,内嵌 DSH 0.2.0-rc.2)适配:惰性 CJS 引导时机、DOM 契约([data-tool] / [data-chat-running] / [data-terminal] / contenteditable 输入框)、主题属性(body[data-ds-dark-theme])、设置面板判据;修复首屏误判工作态 | Release · 说明 |
| v2.1.0 | 2026-09-14 | 会说话,也不会凭空消失 | 可选 MiMo TTS 台词播报;修复弹窗导致桌宠永久消失(改为右下 mini);修复设置面板注册时序;余额优先 CNY 账户;新增 GitHub Actions CI | Release |
| v2.0.1 | 2026-09-05 | 商城兼容性声明 | dsh.compatibility.dshReleases 兼容矩阵;恢复与商城目录固定 Commit 的血缘 | CHANGELOG |
| v2.0.0 | 2026-08-28 | 余额 · 工具 · 日记 | 余额显示与播报、立绘预加载、按工具类型切换姿态、拖拽惯性、主动关怀、无障碍模式、成长日记、主题适配 | Release |
| v1.5.0 | 2026-08-28 | 自定义自称 + 找回入口 | 自定义看板娘自称;关掉后左下角留唤回按钮 🐋 | Release |
| v1.4.2 | 2026-08-28 | 适配 DSH 0.1.1-rc.2 | 修复出错后永久停留「翻车」立绘;修复设置入口无反应;bundle 自带设置面板 | Release |
- 完整逐条变更见 CHANGELOG.md
- 全部历史版本在 Releases(个别版本只发 CHANGELOG 未单独打 Release,如 v2.0.1)
数据与隐私
| 项目 | 事实 |
|---|---|
| 数据存放 | 宿主窗口的 localStorage,键名以 whale-moe: 开头(桌面端 origin 为 dsh-app://app) |
| 跨端迁移 | 不迁移:桌面端与旧版 Web 的 origin 不同,两边数据互不相通 |
| 遥测 | 无。不上传数据、不发送统计 |
| 外部请求 | 默认零外部请求。天气需你填写城市才会请求 Open-Meteo(免费、无需 Key);城市留空即零联网 |
| 余额功能 | 默认关闭。开启后只访问本机余额代理 127.0.0.1:3020(上游请求在代理侧完成,浏览器侧不直连外部);关掉「余额显示数字」后界面只显示档位措辞,截图不泄露金额 |
| 凭据 | 不含任何 API Key;天气 API Key(选填)也只存在本机 localStorage |
| 对宿主的影响 | 纯前端注入,不修改任何内置包文件与业务 DOM;卸载即干净移除 |
常见问题
刷新后看不到她,最可能是什么原因?
- 确认插件已启用:settings 里能看到「看板娘」栏目,
window.__dshWhaleMusumeBooted === true; - 确认「看板娘」开关是开的(设置 → 看板娘 → 陪伴表现);
- 如果你在设置面板里 —— 她是按设计隐藏的(设置页不该有装饰盖住界面),关掉设置面板就回来;
- 桌面端装完必须重启应用,只刷新页面不一定够。
桌面端数据是空的,我的好感度和成就不见了?
这是预期行为:桌面端 origin 是 dsh-app://app,与旧版 Web 的 http://127.0.0.1:<端口> 不是同一个存储域,whale-moe:* 不会自动带过来。目前没有内置迁移工具,需要在新环境重新养成。
她会不会偷看我的聊天内容?
默认不会。只有你主动打开「关键词感知」后,她才会在本地匹配聊天里的 13 个梗关键词来变身表情包 —— 匹配在浏览器内完成,不外发。余额相关功能同理,默认关闭。
她会不会影响我复制代码 / 挡住按钮?
她只占右下角一小块,且只操作自己的节点:不拦截键盘、不覆盖业务 DOM、不修改任何内置文件。默认 aria-hidden,读屏软件不会被她打扰。要拖走她直接按住拖即可。
能换角色吗?能做主题皮肤吗?
本仓库是「角色 + 表现层」,不提供主题包能力(v1.1.5 起 apply 不再注册主题选项)。想要别的角色,可以对照本项目结构二次开发;状态机(assets/whale-moe-core.js)与表现层(assets/dsh-whale-moe.js)是分离的,替换表现层即可。
卸载会留下什么吗?
组合包方式不留文件残留(不改内置包、不写配置),只有 localStorage 里的养成数据会保留;想彻底清掉,在设置 → 看板娘 → 数据与重置里重置,或清空该 origin 的站点数据。
故障排查
| 现象 | 处理 |
|---|---|
| 刷新后看不到她 | 确认安装命令输出成功 / 插件已启用;强制刷新(Ctrl+F5);检查设置面板「看板娘」开关 |
| 设置面板里没有「看板娘」栏目 | 确认 DSH 版本与安装方式匹配;slots 服务不可用时会跳过面板但桌宠本体不受影响(控制台会有 [dsh-whale-musume] 告警) |
| 桌面端装完没变化 | 重启桌面端应用(不是刷新页面) |
| 图片不更新 / 立绘错位 | 强制刷新;资源 URL 带版本号,浏览器缓存过旧时清理站点缓存 |
| 在设置里关掉了找不到她 | 左下角有 🐋 唤回按钮,点一下 |
| 拖拽误触发 | 移动超过 4px 才进入拖拽;单击不会触发 |
| 想恢复默认位置 | 右键 → 回到原位 |
| 播报没声音 | 「台词播报」需要宿主装了 dsh-xiaomi-tts 且你已打开该开关;未安装时该开关不显示 |
| 两种安装方式混用了 | 先用对应方式完整卸载/回滚,再任选一种重装 |
安装失败排查(从插件市场 / dsh plugin add 装不上)
先说结论:鲸鱼娘是纯前端插件包——package.json 没有 prepare、没有任何 dependencies、产物随仓库提交,安装过程不需要任何构建。所以安装失败几乎总是卡在「GitHub 连不连得上」或「profile 的 registry 解不解析得出」这两个外部条件上,与插件代码无关。v2.5.0 起已发布 npm(包名 dsh-whale-musume),优先用 npm 安装;只有从 GitHub 源安装时才会走 git 预检。
| 日志里的关键行 | 属于 | 处理 |
|---|---|---|
git ls-remote ... failed / failedAt: 'spec-host' | 本机到 GitHub 的链路 | 见「网络自查」 |
ERR_PNPM_NO_MATCHING_VERSION / 404 ... not found | registry 镜像还没同步到这个版本 | 见「registry 与镜像」 |
Ignored build scripts: <包名> | pnpm 拦下了构建脚本(本插件不会出现) | 见「allowBuilds 是误报」 |
只有 [exit 1]、没有关键行 | 日志被截断 | 贴 <DSH Home>\profiles\<profile>\hub.log 与 .plugin-manager\logs\operation-*\pnpm.log 到 issue |
registry 与镜像:报 ERR_PNPM_NO_MATCHING_VERSION 时,先确认镜像有没有滞后——换官方源重试(GUI:添加插件对话框的 Registry 选择器选「npm 官方源」)。镜像滞后通常几小时内自愈,多数情况直接重试即可,不需要改任何配置文件。
网络自查:
# 超过 10 秒没输出 = 本机到 GitHub 不通或过慢
git -c credential.helper= ls-remote -- https://github.com/Sutera-Diffusus/dsh-whale-musume.git HEAD
# 需要代理时(端口换成你自己的)
git config --global http.https://github.com.proxy http://127.0.0.1:7890
DSH 在 git 安装前会用 git ls-remote 做一次默认 5 秒超时的连通性预检(githubConnectionTimeoutMs);预检超时就直接判失败(failedAt: 'spec-host')。上面这条命令能在 5 秒内返回,安装才有机会走完。
allowBuilds 提示对鲸鱼娘是误报:git 形式安装失败时,DSH 常会追加一句「add the exact key pnpm printed above under allowBuilds in <DSH Home>/profiles/<profile>/pnpm-workspace.yaml」。这句话只看安装参数是不是 git 形式,不看插件要不要构建。判据很简单:pnpm 必须先打印一行 Ignored build scripts: <包名>,才轮到 allowBuilds;没有那一行就不要改这个文件(本包无依赖、无 prepare,不存在需要放行的构建脚本)。
绕开 git 与 registry(最稳):用 Release 资产,zip 不做 git 预检、不碰 registry、没有 prepare 步骤。
- 从 Releases 下载
dsh-whale-musume-plugin-v<版本>.zip与SHA256SUMS-v<版本>.txt,解压得到dsh-whale-musume/; - 在解压目录的上一级,按本地路径安装(
$Desktop/$Cli的取值见桌面端部署文档):
$env:ELECTRON_RUN_AS_NODE = "1"
& "$Desktop\DeepSeek Harness.exe" --expose-internals $Cli plugin --profile desktop add "<解压路径>\dsh-whale-musume"
# 旧版 Web
dsh plugin --profile web add "<解压路径>\dsh-whale-musume"
- 校验 zip:
Get-FileHash .\dsh-whale-musume-plugin-v<版本>.zip -Algorithm SHA256与SHA256SUMS里的值对比。
怎么确认装上了:
# 清单里有她:dependencies 与 dsh.profile.bundles 各出现一次
Get-Content "$DshHome\profiles\desktop\package.json"
Test-Path "$DshHome\profiles\desktop\node_modules\dsh-whale-musume\lib\client.js"
(Get-ChildItem "$DshHome\profiles\desktop\node_modules\dsh-whale-musume\assets\generated" -File).Count # 92
桌面端装完要重启应用(不是刷新页面)。页面侧可以看 window.__dshWhaleMusumeBooted === true、document.querySelectorAll('[data-dsh-whale-root]').length === 1。
版本没更新时先卸载再装:add 对已安装实例不覆盖版本,remove + add 是拿到新版最稳的方式。养成数据(whale-moe:*)存在宿主 origin 的 localStorage 里,重装后还在。
路线图
不承诺时间,但方向明确。想投票或补充,去 Discussions 或 Issues 说一声。
- 导出数据的增量合并:当前导入是覆盖同名数据;后续支持「只补进度、不降级」的合并模式
- 桌面端验收脚本更新:
npm run qa里的动效/CDP 验收仍按旧版 Web 的假设写的,需要补一版面向桌面端的 - 英文文档补齐:
README.en.md与文档的英文版同步到与中文同级 - 可选角色包:把表现层抽出接口,让别人能替换成自己的角色
已知限制(不是待办,是当前边界):
- 桌面端目前只在 Windows 10 / 11 验证;macOS / Linux 桌面端未验证
- npm 包已发布:
dsh plugin add dsh-whale-musume;GitHub 源安装仍保留(dsh plugin add github:Sutera-Diffusus/dsh-whale-musume) npm run qa/qa:soak面向旧版 Web 环境,桌面端请用tools/cdp-verify-whale.mjs与tools/cdp-contract-whale.mjs
项目结构
dsh-whale-musume/
├─ assets/ # 运行产物(仓库即产物,无构建步骤)
│ ├─ dsh-whale-moe.css # 看板娘样式与动效
│ ├─ dsh-whale-moe.js # DOM 表现层、状态调度、交互
│ ├─ whale-moe-core.js # 纯函数状态机(可单元测试)
│ ├─ peek-calibration.json # 探头立绘校准数据
│ └─ generated/ # 92 张立绘(状态/互动/成长/游戏/天气/节日/梗表情)
├─ lib/
│ ├─ index.js # 宿主插件:只读资源路由 /api/dsh-whale-musume/assets
│ └─ client.js # 客户端插件:注入样式/状态机/表现层 + 注册设置面板
├─ scripts/
│ ├─ apply-theme.mjs # 脚本安装 / 回滚 / 设置注入
│ ├─ gen-assets.py # 立绘生成管线(第三方图像接口,密钥走环境变量)
│ ├─ build-assets.py # 立绘资产构建
│ ├─ build-review.py # 立绘审阅页
│ └─ slice-batch.py # 海报切图
├─ test/
│ ├─ *.test.mjs # 单元与契约测试
│ ├─ desktop-client.test.mjs # 桌面端(0.2.0-rc.2)契约与回归断言
│ ├─ dsh-engines.test.mjs # engines.dsh 与 0.2.1 矩阵
│ ├─ cdp-whale-moe.mjs # 旧版 Web 的 CDP 全量验收
│ ├─ motion-qa.mjs / soak-work.mjs # 动效质量与 60s 压测
│ └─ showcase-*.mjs # 立绘/动作总览生成
├─ tools/
│ ├─ dom-stub.mjs # 零浏览器 DOM 桩(客户端契约断言底座)
│ ├─ cdp-verify-whale.mjs # 一次性 headless 基础验收
│ ├─ cdp-contract-whale.mjs # 一次性 headless 契约验收
│ └─ asar.mjs # 只读 asar 工具(桌面端勘察)
├─ docs/
│ ├─ desktop-0.2.0-rc.2-contract.md # 桌面端 0.2.0-rc.2 契约审计(实机)
│ ├─ desktop-0.2.0-rc.2-deploy.md # 桌面端部署/回滚/卸载手册
│ ├─ desktop-0.2.0-rc.2-acceptance.md # 桌面端 0.2.0-rc.2 验收报告
│ ├─ desktop-0.2.1-rc.2-contract.md # 0.2.1-rc.2 契约差分(静态,未跑 Electron)
│ ├─ desktop-0.2.1-rc.2-deploy.md # 0.2.1 相对 0.2.0 手册的部署差分
│ ├─ release-notes-v2.5.0.md # v2.5.0 Release 说明
│ ├─ npm-publish.md # npm 发布/回滚手册
│ ├─ release-notes-v2.4.0.md # v2.4.0 Release 说明
│ └─ images/ # logo、运行截图与立绘总览
├─ .github/
│ ├─ workflows/test.yml # CI:Node 18 / 22 上跑 npm test
│ ├─ release.yml # Release 更新日志分类规则
│ └─ ISSUE_TEMPLATE/ # Issue / PR 模板
├─ LICENSE · README.md · README.en.md · CHANGELOG.md · SECURITY.md · CONTRIBUTING.md
└─ CODE_OF_CONDUCT.md
开发与测试
# 单元与契约测试(无需浏览器/服务器)
npm test
# 等价命令(显式列出全部测试文件)
node --test test/*test.mjs
# 动效质量检查(需要旧版 Web 测试副本运行在 3181 端口)
node test/motion-qa.mjs
# 旧版 Web 的 CDP 全量验收(需要副本 + Edge/Chrome CDP 9223)
node test/cdp-whale-moe.mjs
开发约定见 CONTRIBUTING.md:改动 assets/ 表现层后请一并跑 npm test,涉及桌面端选择器/信号的改动请核对 docs/desktop-0.2.0-rc.2-contract.md 与 docs/desktop-0.2.1-rc.2-contract.md。
参与贡献
- 🐛 发现 bug → 提 Issue(有模板,会问版本与复现步骤)
- 💡 想要功能 / 有想法 → Discussions
- 🔧 提 PR → 先读 CONTRIBUTING.md,一提交一事,
fix:/feat:/chore:前缀 - 🔒 安全漏洞 → 不要开公开 Issue,见 SECURITY.md
- 🤝 交流准则 → 参与讨论与提 PR 即表示同意 CODE_OF_CONDUCT.md
- ⭐ 用着顺手 → 给个 Star 是最实在的支持,也能让更多 DSH 用户看到她
致谢
- @SuteraWu —— 项目作者,立绘与表现层的主要实现
- @ppy-web —— MiMo TTS 台词播报联动(v2.1.0)
- @icemaple77 —— 修复弹窗导致桌宠永久消失、余额优先 CNY 账户(v2.1.0)
- @Lurantis —— 早期贡献
- @ClutchBear —— 非官方 Windows 原生移植 workbuddy-whale-musume(Rust,与本仓库无隶属关系,不是官方 Windows 版)。MIT 归属已在 #17 确认
- @kingOfSoySauce —— README 待机动图录制(PR #37,v2.5.1 收进仓库)
- 也感谢 DeepSeek Harness 提供的插件体系,以及各插件目录的收录与实测:awesome-deepseek-harness、awesome-dsh-plugins、WhaleHub、dshbase、dsh-meme-hub
License
MIT © Sutera-Diffusus





