nzl153 / dsh-pet-whale

pet-whale · 桌宠小鲸鱼 🐳

English | 中文

DeepSeek Harness（DSH）Web 界面的桌宠插件：右下角一只官方轮廓版小鲸鱼，随 agent 状态实时切换动画。纯 DOM 实现、零 React 依赖、零运行时第三方依赖，WebAudio 合成音效无音频文件。

_{空闲 → 思考·深潜 → 工作·敲代码 → 完成·冒泡 → 报错，对话气泡随状态变化}

在线预览

无需安装，点开即玩（全部状态与交互，官方轮廓版）：

👉 https://nzl153.github.io/dsh-pet-whale/preview.html

仓库内的 preview.html 即预览页源码，本地直接打开同样可以体验。

特性

能力	说明
状态机	idle / think（深潜）/ working（游动 + 敲键盘 + 代码粒子）/ celebrate（跃起冒泡）/ error（发抖 + 尴尬黑线）/ disappointed（报错后短暂失落）/ wait（等待你的输入）；优先级 error > celebrate > think > working > idle
回合语义	回合进行中永不发呆：有工具 = working，无工具（文字流或内部推理）= think 深潜；工具密集期键盘动画粘滞 2.5s
交互	单击戳戳、双击 360° 翻滚、拖拽时眼睛变成动漫勾勾眼（>_<）、右键菜单（投喂 / 摸摸头 / 换颜色 / 假装工作 / 思考链 / 隐藏 / 定时 / 关闭 / 音效）、鼠标追光、20s 无操作打瞌睡、拖拽移动并记忆位置
假装工作	右键菜单「💼 假装工作」开关：开启后始终显示敲代码动画，偏好持久化
思考流	真实状态为 think 时，模型最近 200 字思考内容悬在桌宠正上方缓慢滚动（可右键开关），同时鲸鱼保持深潜思考动画
智能避让	idle 时若光标在身侧停留 0.9s，鲸鱼会自己让开；抓取/拖拽/右键立即取消避让并冷却 8s，绝不抢交互
主题联动	跟随 DSH 亮/暗主题自动切换气泡、对话框和阴影的明暗样式
后台省电	页面切到后台自动暂停所有动画、音效和思考流，回来即恢复
idle 小动作	idle 久了会随机游动、左右张望、吐泡泡，不再只是打瞌睡
错误关怀	error 状态下点击鲸鱼或右键「📋 复制错误信息」，直接把错误文本复制到剪贴板
换肤	7 套预设色板（默认主题蓝）：主题蓝 / 陶土 / 深海蓝 / 抹茶绿 / 樱粉 / 墨灰 / 夜黑；夜黑为深色皮肤示例（眼睛自动反白）。扩展只需在 src/client/palettes.ts 加一行
隐藏/召回	右键菜单「🙈 隐藏到右下角」收起桌宠，右下角出现 🐳 小按钮，点击召回；隐藏状态跨刷新记忆，隐藏期间自动静音、不说话
小按钮状态	隐藏时小按钮随 agent 状态变色呼吸：idle 蓝 / think 深蓝 / working 橙 / celebrate 绿 / error 红
小按钮拖拽	小按钮可拖拽移动，位置用 localStorage 记忆
定时隐藏	右键菜单「🕐 定时隐藏 ▸」：1 小时后 / 每晚 22:00 自动隐藏，可取消
关闭	右键菜单「⏹ 关闭桌宠」完全退出，刷新页面后回来
自主游动	右键菜单「🏊 游泳」开关：鲸鱼沿三次贝塞尔曲线在页面里自主巡游，带俯仰角、水平自适应翻转、下潜、航迹水圈和破浪水花；忙碌时自动让位，偏好持久化
多语言	中文 / English 两套完整文案，接入 DSH 官方 locale 服务自动跟随；独立预览页按浏览器语言判定并可手动覆盖
二级菜单	右键「⋯ 更多设置」展开面板，分为外观 / 行为 / 统计三类；统计页显示累计完成、互动、报错次数和陪伴天数
连戳升级	戳 12 下照常撒娇，35 下开始不耐烦侧身躲开，6 下以上扭头吊眉闹脾气；停手 2.6s 计数衰减，agent 一开工立刻收脾气
失落安抚	报错后的失落状态下戳它算安慰：开心动画 + 暖心台词，并提前结束自愈
完成提醒	你切到别的标签页时回合完成，标签页标题变成「✅ 完成了 · 原标题」，回来自动还原；另有可选系统通知（默认关，开启时才申请权限）
久坐提醒	可设 45 / 60 / 90 分钟，坐满后鲸鱼浮上来喷个水提醒你歇会儿；默认关，离开页面超过 10 分钟视为已休息并重新计时
熟悉度	互动次数、完成回合、共处天数一起攒分，关系分三档：初识 / 熟络 / 形影不离。档位会改戳戳台词和回来时的问候，到形影不离还会偶尔主动冒泡搭话；升档时它自己会说出来，当前档位和进度在「陪伴记录」里看
甩晕	抓住它左右猛甩，一秒内掉头四次就会被甩晕：眼睛翻成 @@，喊你别甩了，松手后身体还要摇一会儿；手抖或慢慢来回挪不算。晕完还有后遗症——接下来十几秒游不直，航迹明显歪
贴边挤扁	拖到屏幕边缘按上去会被压扁，像贴在玻璃上；离开边缘自己弹回来
拖着不动	抓起来悬在半空超过 2 秒，它开始扭腰问你还在不在；你一动它就不问了
翻肚皮	双击的反应跟着关系走：平时翻个 360° 跟头，处到「形影不离」才肯翻肚皮给你看
自定义大小	右键 →「外观 → 大小」在小 / 标准 / 大 / 特大之间循环，0.8 ~ 1.6 倍。缩放会同步影响碰撞边界、水花位置和贴边判定，不只是看着变大
音效	WebAudio 合成六种音效，右键可关，偏好持久化
无障碍	prefers-reduced-motion 下自动降级为静态显示

安装

要求 DSH >=0.1.0-rc.6（web profile）。

# 本地目录安装（仓库已包含构建产物 lib/，无需先构建）
dsh plugin --profile web add link:/path/to/pet-whale

# 或 git 直装
dsh plugin --profile web add "github:<user>/pet-whale#main"

装完重启 dsh web（host 半在启动时合成）。之后 client 半的改动只需硬刷新（Ctrl+F5），无需重启。

构建与测试

pnpm install
pnpm typecheck   # tsc 类型检查
pnpm build       # tsdown → lib/index.mjs + lib/client.js
pnpm test        # jsdom 冒烟测试（状态机 / 交互 / 换肤 / 清理）

开发

• src/client/palettes.ts — 色板扩展点。加一行就是一个新皮肤；eye/pupil 字段用于深色皮肤的"眼睛反白"
• scripts/extract-whale.mjs — 从 preview.html 同步 V2 SVG（含 CSS 变量替换），改完模板重跑 pnpm extract
• scripts/verify-live.mjs — 重启后的一键线上验证（boot 清单 / bundle 下载 / 注册格式）
• 状态来源：ctx.sessions 服务的会话快照（running / runningCalls / partial / lastAgentError / turnEnds），详见 src/client/state.ts

附：自用 UI 美化补丁（仅供参考）

patches/ 目录包含个人自用的 DSH 界面定制补丁，随仓库开源供参考，不是本插件的组成部分：

• 暖色纸感主题：类 Claude 风格暖调配色（陶土 #A3502C + 米白 #F7F2E6 + 暖墨 #2E2A24），亮暗两套，正文对比度 ≥4.5（WCAG AA）
• 鲸鱼发送 / 取消键：发送键 = 蓝色小鲸鱼，取消键 = 黑色小鲸鱼（与 favicon 一致），按钮 48px
• 针对 DSH rc.6 的特定构建产物编写，升级 DSH 后若锚点失效需人工核对更新

node patches/apply-patches.cjs <dsh 安装根目录>

声明

• 鲸鱼轮廓使用 DeepSeek 官方 FishLogo 路径（品牌素材，使用请注明出处）
• 交互设计思路参考 whale-girl（MIT）
• 主题配色灵感来自 Anthropic Claude 的暖色纸感风格

License

MIT