Sutera-Diffusus/dsh-whale-musume

鲸鱼娘 · dsh-whale-musume

DeepSeek Harness 的桌宠看板娘：安静陪你写代码，工作一开始她就抱起笔记本，绝不插嘴。

一分钟上手 · 看看她长什么样 · 她有什么 · 常见问题 · English

为什么是鲸鱼娘

大部分桌宠要么只是「会动的图」，要么会在你专注时抢注意力。鲸鱼娘的三条硬规则：

原则 · 具体做法 不打断你 · 工作态（有工具在跑）绝不弹话、不乱切姿势；所有闲聊、关怀、播报都只在待机时发生 不抢你的焦点 · 默认是纯装饰：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.0。

从插件市场或 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.2 · ✅ 静态契约 · 对照 tag dsh-v0.2.1-rc.2 的源码与单元测试，没有在真实 Electron 里复跑。0.2.1 的桌面端端口改为系统分配（--port 0），不要再假设 19387。差分见0.2.1 契约与部署差分 旧版 Web profile（DSH 0.1.x） · ✅ 已实测 · 0.1.0-rc.6 及以上；设置面板在 0.1.1-rc.2 实测 其他 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 的依据是这份静态核对加单元测试，不是实机验收。

第一次使用

装好后按顺序试一遍，一分钟知道她好不好用：

1. 点她一下 —— 脸红立绘 + 爱心特效；
2. 连点三次 —— 星星眼庆祝 + 粒子特效 + 旋转动画；
3. 拖着她走 —— 切「被拎起来」立绘、跟随光标摇摆，松手后滑行一小段并保存位置；
4. 右键她 —— 投喂 / 戳一下 / 夸夸 / 三个小游戏 / 回到原位 / 打开设置；
5. 跑一次工具调用 —— 她自动抱起笔记本，带淡蓝光晕；
6. 打开 设置 → 看板娘 —— 15 个开关、养成数据、成就墙、成长日记都在这里；
7. 换电脑前 —— 设置 → 看板娘 → 跨端迁移，导出存档或复制迁移码。

使用说明

拖拽

• 按住她移动，松手后位置自动保存；移动超过 4px 才进入拖拽状态（所以单击不会误触发拖拽）
• 右键 → 回到原位 恢复默认右下角

右键菜单

菜单项 · 效果 投喂小点心 · 提升饱食度与好感度，触发吃东西立绘 戳一下 · 降低心情，触发生气立绘 夸夸鲸鱼娘 · 提升心情与好感度，触发星星眼 小游戏：戳泡泡 · 打开 30 秒一局的泡泡派对 小游戏：接点心 · 键盘 / 鼠标追点心，躲炸弹 小游戏：鲸鱼翻翻乐 · 4×4 记忆配对，60 秒，连击与零失误加成 回到原位 · 清除保存的悬浮位置 打开设置 · 跳到 DSH 设置 → 看板娘

设置面板

路径：DSH 设置 → 看板娘（共 15 个胶囊开关 + 「工作中台词」话痨／安静两档 + 8 个折叠分组）。

分组 · 内容 陪伴表现 · 如何称呼我、她的自称（留空回落到「鲸鱼娘」）、看板娘开关、台词气泡、台词播报（可选）、粒子效果、关键词感知、摸鱼提醒、深夜模式、工具细分、拖拽惯性、主动关怀、无障碍、工作中台词（话痨 / 安静） 天气 · 天气城市、选填 API Key、天气特效开关 余额 · 余额关心开关、余额显示数字开关、当前余额与档位 日常与养成 · 今日任务 / 本周签到 / 称号（标签页收纳） 成就墙 · 45 个成就，已解锁高亮、未解锁灰显 成长日记 · 羁绊升级、成就解锁等关键节点，倒序显示最近 12 条 跨端迁移 · 导出 / 导入存档（JSON），或复制 / 粘贴迁移码；带走好感度、等级、成就、任务、游戏记录与日记 数据与重置 · 重置悬浮位置、重置养成数据

默认关闭（涉及读取聊天内容或账户金额）：关键词感知、余额关心、余额显示数字、台词播报、无障碍。

跨端迁移（桌面端 ↔ 旧版 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.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）