一句话定位

为 DSH Web 端注入一只鲸鱼娘看板娘桌宠：可拖拽、可摸头养成、能感知工作状态并自动切换姿势，还会按节日、天气、聊天关键词变换立绘与台词；全部资源走本地路由，不发外部请求。

核心能力

• 悬浮拖拽：默认悬浮形态约 200px，鼠标拖拽时切换「被拎起来」立绘并跟随光标方向自然摇摆，松手自动保存位置
• 工作状态联动：检测到 DSH 工具运行信号（data-running / data-state="ongoing"）自动切到「抱笔记本」立绘与淡蓝光晕，期间不主动插嘴
• 立绘与表情库：90+ 张 WebP 立绘，覆盖待机 / 工作 / 互动 / 成长 / 游戏 / 天气 / 五套节日换装 / 13 种梗关键词表情
• 养成玩法：心情、好感度、饱食度、等级、连续签到、羁绊等级（Lv3/Lv5/Lv7 解锁专属内容）、39 个成就、每日任务与周签到
• 互动小游戏「戳泡泡·泡泡派对」：4×4 网格，普通 / 星星 / 炸弹三色泡泡，30 秒一局三档结算，支持鼠标与键盘双通道
• 分区点击互动：点鲸鱼娘的头 / 肚子 / 尾巴会触发各自专属立绘、特效与台词
• 天气陪伴：可填城市名（选填 API Key）拉取 Open-Meteo 免费天气数据，城市留空则零联网；并可开启全屏 canvas 氛围特效（雨 / 雪 / 雷闪 / 风 / 雾 / 热浪 / 霜雾 / 阴 / 晴）
• 台词与时令闲聊：530+ 条台词，分时问候（深夜 23:00–5:59 不主动打扰），心情分层台词，按当前任务话题本地贴话

技术实现

• 语言: JavaScript (ESM) + CSS（前端）；插件本体只用纯 Node 标准库
• 关键依赖: 无第三方 npm 依赖；仅使用 node:fs、node:path、node:url、浏览器内置 fetch / localStorage / MutationObserver
• 架构模式: DSH 标准组合包形态（dsh.bundle.patch + dsh.client.platform: web），单包双面：宿主端通过 Cordis webServer.register 注册只读静态资源路由，浏览器端通过 window.__ModuleLoader__.load 注入样式、状态机与表现层，零侵入
• 入口文件: lib/index.js（宿主端 Cordis 插件）+ lib/client.js（浏览器端 Web 模块）+ cordis.patch.yml（profile 插入点）

适用场景

写代码或与 DSH 长对话时，希望屏幕上有个可爱的小角色陪着、不打扰节奏但偶尔给点反馈的人；喜欢养成和成就收集、希望看到自己「陪伴时长」累积的人；以及想要节日换装、天气特效、摸头动画这类轻互动装饰的 DSH 用户。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Sutera-Diffusus/dsh-whale-musume

配置项

说明：以上配置项均通过看板娘自带齿轮菜单或 DSH 设置 → 看板娘面板修改，写入浏览器 localStorage 的 whale-moe:* 键，不需要编辑配置文件。

常见问题

Q: 安装后为什么没看到鲸鱼娘？

A: 宿主路由要在 dsh web 重启后才注册，安装完成后请重启 DSH 进程并用 Ctrl+F5 强制刷新页面。如果还看不到，按 F12 打开控制台检查是否报错 [dsh-whale-musume] 资源加载失败——通常是 /api/dsh-whale-musume/assets 路由没起来，需要确认 DSH 版本 ≥ 0.1.0-rc.6。

Q: 数据存在哪里？会上传吗？

A: 所有养成数据（心情、好感度、饱食度、等级、签到、成就、悬浮位置、天气城市等）都存在浏览器 localStorage，键名以 whale-moe: 开头。除可选天气功能调用 Open-Meteo 免费接口外，不发任何遥测或外部请求；卸载插件后这些 localStorage 需手动清理。

Q: 工作时她会一直说话打扰我吗？

A: 不会。检测到 DSH 工具运行（data-running 或 data-state="ongoing"）时自动切到「抱笔记本」工作姿势，期间不弹气泡、不切待机小剧场；聊天命中时只触发固定的「害羞抱电脑」「偷吃内存条」反应。工作信号消失后会按固定的 running → success → idle 链释放，不会出现随机打断。

Q: 怎么彻底关闭看板娘？

A: 三种方式任选其一：在齿轮菜单或 DSH 设置 → 看板娘里关闭「看板娘」总开关；在浏览器控制台执行 localStorage.setItem("whale-moe:pet", "0") 后刷新；或者右键鲸鱼娘在菜单里也能关闭。关闭后表现层完全不渲染、画布被摘除，仅保留开关数据。

Q: 天气陪伴需要付费 Key 吗？

A: 不需要。天气数据走 Open-Meteo 的免费公共接口，城市名留空时完全不联网；如需自定义请求频率可在设置里填入自有 API Key。所有立绘与样式仍由本地路由提供，不依赖任何 CDN。

Q: 拖拽位置会保存吗？怎么恢复默认？

A: 松开鼠标后位置写入 whale-moe:floatX / whale-moe:floatY，下次打开页面自动复原。右键鲸鱼娘选「回到原位」可清除这两个键恢复默认右下角位置。

上手难度

入门 — 安装后自动出现，齿轮菜单提供所有常用开关，无需阅读文档即可上手；进阶功能（分区点击、节日换装、天气特效）在设置面板里有分组说明。

已知问题与限制

• 后台 / 无头标签页中浏览器可能暂停 WAAPI 动画，源代码（assets/dsh-whale-moe.js:170-180）已设置 1.6 秒超时兜底强制落地新姿势；但极少数极端节流场景下首帧仍可能短暂空帧（v1.1.4 修复记录）
• 静态资源路由（lib/index.js:25-29）做路径穿越防护时，?v= 之类的版本查询串会被忽略；若在 URL 里追加 ?# 或非常规编码可能触发 400
• 仅在 DSH 0.1.0-rc.6 上做过端到端 CDP 验收，更早版本和 rc.7+ 行为未验证（README 124-130 行明确基线）
• 立绘大版本升级时由于浏览器缓存可能看到旧图，需 Ctrl+F5 强制刷新；资源 URL 自带版本号（?v=5）按理自动刷新（assets/dsh-whale-moe.js:14,159）
• 工作态检测依赖 DSH 前端的 data-running / data-state="ongoing" 等结构化信号（assets/dsh-whale-moe.js:36-43），若未来 DSH 改动这些属性，看板娘将无法自动切到工作立绘

dsh-whale-musume

鲸鱼娘——为 DeepSeek Harness 打造的桌面看板娘插件。

一只会陪你写代码的鲸鱼娘：待机安静陪伴，工作开始就抱起笔记本陪你干活；可以摸头养成、解锁成就，也可以拖着她到处走。所有资源本地运行，无遥测、无外部请求。

---

目录

• 特性
• 效果预览
• 安装要求
• 安装教程
• 使用说明
• 更新 / 回滚 / 卸载
• 数据与隐私
• 项目结构
• 开发与测试
• 故障排查
• License

---

特性

🐋 看板娘本体

• 默认悬浮形态（200px），支持鼠标拖拽；
• 拖拽时切换「被拎起来」立绘，身体随光标移动方向自然摇摆；
• 待机时保持稳定表情，随机出现喝咖啡、伸懒腰、吃东西等日常小动作；
• 待机与工作状态之间使用「下压 → 换图 → 弹起」的动势遮断过渡，不会叠影，不会闪黑。

💼 工作状态联动

• 检测到工具运行（data-running / data-state="ongoing"）自动切换为「抱笔记本工作」；
• 工作中带淡蓝光晕和「工作中」标签；
• 工作状态下点击她，会随机出现「害羞抱电脑」或「偷吃内存条」的反应，不会打断工作状态；工作期间保持 running 姿势稳定，不再随机切小剧场。

🎨 立绘与表情（90+ 张）

• 全场景立绘：待机、工作中、思考、离开，以及摸头 / 戳肚子 / 戳尾巴分区互动立绘；
• 成长立绘：升级、成就达成、每日任务完成、甩尾；
• 游戏四态（思考 / 小得意 / 获胜 / 惜败）、天气三态（打伞 / 冷 / 雪天）；
• 节日自动换装：圣诞 / 万圣 / 中秋 / 春节 / 情人节当天自动切换；
• 13 种梗表情关键词感知：kyun、OMG、doge、sike、膜拜、peace、怀疑人生、waku waku 等，命中即变身表情包。

💬 梗聊天与天气陪伴

• 530+ 条台词：全场景覆盖，可爱为主，叠加打工人、摸鱼、DDL、画饼、发疯文学等安全梗；
• 5–8 分钟主动闲聊：按当前任务内容本地分类贴题，不尬聊；工作态绝不插嘴；
• 分时问候：早上/上午/中午/下午/傍晚带关心话，深夜 23:00–5:59 不主动打扰；
• 心情分层台词：心情低落时温柔、高涨时元气，羁绊等级解锁专属台词（Lv3/Lv5/Lv7）；
• 天气陪伴：设置 → 看板娘 → 天气，填写城市（选填 API Key）并测试连接；Open-Meteo 免费无需 Key，城市留空零联网；
• 天气视觉特效：全屏氛围特效（雨/雪/雷闪/风/雾/热浪/霜雾），随真实天气自动切换，工作态自动降档，可在设置中关闭。

🎀 互动与特效

• 单击摸头：脸红立绘 + 爱心/星星 emoji 飞出；
• 分区互动：点她不同部位（头 / 肚子 / 尾巴）有专属立绘、特效与台词；
• 关键词表情：聊天命中 13 个梗关键词时，鲸鱼娘现场变身表情包；
• 三连击：星星眼庆祝 + 粒子特效 + 旋转动画；
• 右键菜单：投喂 / 戳一下 / 夸夸 / 小游戏：戳泡泡 / 回到原位 / 打开设置；
• 点击反应即时切换，不做拖沓过渡。

🫧 小游戏「戳泡泡·泡泡派对」

• 4×4 泡泡网格，普通/星星/炸弹三种泡泡，连击加分，30 秒一局三档结算；
• 鼠标点击 + 键盘方向键游标 + Enter 引爆 + Esc 退出，双通道可达；
• 每日 3 局养成奖励上限，多玩只计分不刷好感；
• 工作状态、设置页打开时均可正常游玩，仅页面隐藏时暂停；
• 刷新纪录、连击、首胜均有专属成就。

📈 养成与成就

• 心情、好感度、饱食度、等级、连续签到、陪伴时长；
• 每日任务：3 个任务槽每日自动刷新，完成领取好感奖励；
• 周签到：本周签到板 7 格，集满 1/3/7 天有里程碑奖励；
• 羁绊等级解锁：Lv3 新待机动作、Lv5 称号「鲸汐守护者」、Lv7 隐藏彩蛋；
• 39 个成就：互动类、陪伴类、DSH 用量类、游戏类、任务类；
• 设置面板内置成就墙，已解锁高亮、未解锁灰显。

⚙️ 设置面板

• 看板娘设置集成在 DSH 设置页中；
• 折叠分组：陪伴表现 / 天气 / 日常与养成 / 成就墙 / 数据与重置，总览卡与分组卡等宽对齐；
• 胶囊开关：看板娘 / 台词气泡 / 粒子效果 / 小游戏 / 关键词感知 / 摸鱼提醒 / 深夜模式 / 天气特效；
• 日常与养成用标签页收纳：今日任务 / 本周签到 / 称号，与成就墙同区管理；
• 养成数据使用横排小卡片展示，信息密度合理。

🧩 工程特性

• 纯前端注入，不修改 DSH 业务 DOM；
• 所有改动可备份、可回滚；
• 资源文件带版本号，升级后强制刷新缓存；
• 核心状态机与表现层分离，便于二次开发。

---

效果预览

仓库中的预览图位于 docs/images/，均为插件在 DSH 测试副本中运行时的真实截图。

---

安装要求

安装脚本会修改 DSH 安装目录中的前端资源文件。虽然脚本自带备份，仍建议安装前关闭 DSH 页面，并记录当前 DSH 版本号。

---

安装教程

第 1 步：获取插件

方式 A：下载 Release（推荐）

1. 打开 Releases；
2. 下载最新版 dsh-whale-musume-plugin-vX.Y.Z.zip；
3. 解压到任意目录，例如 D:\dsh-whale-musume。

方式 B：克隆仓库

git clone https://github.com/Sutera-Diffusus/dsh-whale-musume.git
cd dsh-whale-musume

第 2 步：确认 DSH 安装目录

DSH 安装目录通常包含 DeepSeekHarness-Launcher.exe 和 node_modules。如果不确定，可以查看启动器配置：

Get-Content "<DSH_INSTALL_DIR>\DeepSeekHarness-Launcher.cfg"

其中 workDir 字段指向的就是安装目录。下文统一用 <DSH_INSTALL_DIR> 代替该路径。

第 3 步：执行安装脚本

在插件目录打开 PowerShell，执行：

node scripts/apply-theme.mjs --assets-only --target "<DSH_INSTALL_DIR>"
node scripts/apply-theme.mjs --mascot-settings --target "<DSH_INSTALL_DIR>"

示例（默认安装路径）：

node scripts/apply-theme.mjs --assets-only --target "<DSH_INSTALL_DIR>"
node scripts/apply-theme.mjs --mascot-settings --target "<DSH_INSTALL_DIR>"

也可以通过环境变量指定安装目录：

$env:DSH_INSTALL_DIR = "<DSH_INSTALL_DIR>"
node scripts/apply-theme.mjs --assets-only
node scripts/apply-theme.mjs --mascot-settings

脚本输出中的 Backup: 路径就是本次改动的备份目录，请保留到确认插件运行正常。

第 4 步：刷新 DSH 页面

1. 打开 DSH Web 页面（默认 http://127.0.0.1:3080）；
2. 强制刷新：Ctrl + F5；
3. 页面加载完成后，右下角应出现鲸鱼娘。

第 5 步：验证安装

• 点击鲸鱼娘：应出现脸红/爱心特效；
• 连续快速点击三次：应出现星星眼庆祝；
• 拖拽鲸鱼娘：应切换为「被拎起来」并跟随光标摇摆；
• 打开 DSH 设置 → 看板娘：应看到开关、养成数据和成就墙。

---

使用说明

拖拽

• 按住鲸鱼娘移动，松手后位置自动保存；
• 右键鲸鱼娘 → 回到原位，恢复默认右下角位置。

右键菜单

设置面板

路径：DSH 设置 → 看板娘。

---

更新 / 回滚 / 卸载

更新

1. 下载新版插件 zip，覆盖旧目录中的 assets/ 和 scripts/；
2. 重新执行第 3 步的两条安装命令；
3. 强制刷新页面。

回滚

安装脚本会在 DSH_WHALE_BACKUP（默认 <BACKUP_DIR>）目录生成备份：

node scripts/apply-theme.mjs --rollback "<backup dir>"

卸载看板娘

node scripts/apply-theme.mjs --mascot-settings --target "<DSH_INSTALL_DIR>" --rollback <设置备份目录>
node scripts/apply-theme.mjs --assets-only --target "<DSH_INSTALL_DIR>" --rollback <资源备份目录>

或直接在设置面板关闭「看板娘」开关（资源仍保留，可随时重新开启）。

---

数据与隐私

• 所有状态保存在浏览器 localStorage，键名以 whale-moe: 开头；
• 不包含任何 API Key、用户凭据；
• 不发送遥测、不上传数据、不访问外部网络；
• 安装脚本只读取 DSH 前端资源文件并写入备份，不读取 DSH 会话数据。

---

项目结构

dsh-whale-musume/
├─ assets/
│  ├─ dsh-whale-moe.css          # 看板娘样式与动效
│  ├─ dsh-whale-moe.js           # DOM 表现层、状态调度、交互
│  ├─ whale-moe-core.js          # 纯函数状态机（可单元测试）
│  ├─ peek-calibration.json      # 探头立绘校准数据
│  └─ generated/                 # 90+ 张立绘（状态/互动/成长/游戏/天气/节日/表情）
├─ scripts/
│  ├─ apply-theme.mjs            # 安装 / 回滚 / 设置注入
│  ├─ gen-assets.py              # 立绘生成管线（调用第三方图像接口，密钥走环境变量）
│  ├─ build-assets.py            # 立绘资产构建
│  ├─ build-review.py            # 生成立绘审阅页
│  └─ slice-batch.py             # 海报切图
├─ test/
│  ├─ whale-moe-core.test.mjs
│  ├─ whale-moe-growth.test.mjs
│  ├─ whale-moe-game.test.mjs
│  ├─ whale-moe-fx.test.mjs
│  ├─ whale-moe-quest.test.mjs
│  ├─ whale-moe-zones.test.mjs
│  ├─ apply-theme.test.mjs
│  ├─ cdp-whale-moe.mjs
│  ├─ motion-qa.mjs
│  ├─ soak-work.mjs
│  ├─ showcase-poses.mjs
│  └─ showcase-actions.mjs
├─ docs/
│  └─ images/                    # 预览截图
├─ LICENSE
├─ README.md
├─ CHANGELOG.md
├─ SECURITY.md
└─ CONTRIBUTING.md

---

开发与测试

# 单元测试（97 个）
npm test
# 或等价命令：
node --test test/whale-moe-core.test.mjs test/whale-moe-growth.test.mjs test/apply-theme.test.mjs test/whale-moe-game.test.mjs test/whale-moe-fx.test.mjs test/whale-moe-quest.test.mjs test/whale-moe-zones.test.mjs

# 动效质量检查（需要测试用 DSH 副本运行在 3181 端口）
node test/motion-qa.mjs

# 全量 CDP 验收（需要 DSH 副本 + Chrome/Edge CDP 9223）
node test/cdp-whale-moe.mjs

建议使用独立 DSH 副本进行开发验证，避免污染主安装。

---

故障排查

---

License

MIT

---

鲸鱼娘陪你写代码，也陪你摸鱼。 🐳

---

组合包安装(bundle,零侵入)

鲸鱼娘同时提供标准 DSH 组合包形态(声明 dsh.bundle.patch),可直接经 dsh plugin 或插件市场(如 mydsh.dev)安装,无需脚本改写任何内置包文件:

dsh plugin --profile web add github:Sutera-Diffusus/dsh-whale-musume

安装后重启 dsh web 并强制刷新页面(Ctrl+F5),鲸鱼娘会自动出现。此模式:

• 宿主插件只注册只读静态资源路由 /api/dsh-whale-musume/assets,向浏览器提供样式/脚本/立绘;
• 浏览器插件注入鲸鱼娘本体,资源全部来自本机,无外部请求、无遥测;
• 开关与模式偏好走鲸鱼娘自带齿轮菜单(localStorage,键名 whale-moe:*);看板娘自带设置面板(胶囊开关/养成数据/成就墙/天气)在 bundle 模式下同样可用——已通过 38 项 CDP 全量验收;
• --mascot-settings 脚本方式仍保留,供主题集成场景使用。两种安装方式二选一,不要混用。