shiyi312/DeepSeek-Whale-Desktop-Pet

🐳 DeepSeek 小鲸鱼桌宠（Whale Desktop Pet）

Python GUI Platform Version

作者：shiyi312（辻弌）　|　版本：v4.4.2　|　开发者信息

DSH 小鲸鱼桌宠

一个独立运行的 Windows 桌面宠物：DeepSeek 小鲸鱼娘。基于 PyQt5 单文件实现，
不依赖浏览器、不依赖 DSH，开箱即用。她住在你的桌面角落：会呼吸眨眼、Q 弹软乎乎，
帮你盯着 Token 余额，还能陪你摸鱼。

💡 本项目是从 DeepSeek-WindowsTable-game.io（鲸鱼娘） 的玩法、
DeepSeek-Balance-Whale-Widget（DSH 余额挂件） 的交互风格、
DeepSeek-Whale-widget-desktop（独立桌面版） 的桌面形态
改造整合而来，并在其基础上重写了窗口、交互、Token 系统、气泡系统与设置面板。
详见文末「来源与致谢」。

✨ 特性

- 🧸 Q 弹玩偶：按压压扁回弹（底部坐标固定），自带弹簧手感
- 🖱️ 拖拽 + 四边四分之一吸附：松手时中心落在屏幕某侧 25% 区域即贴边，角落可组合
- 🔄 左吸附翻转：贴左边缘自动水平镜像（面朝屏内），文字保持可读
- 🎯 右键橡皮筋弹射：拉得越远越「重」，松手弹射 + 屏幕边缘反弹角反射 + 音效
- 💰 趣味 Token 系统：点击消耗、拖文件/文件夹喂食（弹窗警告真实删除）、
一键 +520W、清空、总开关
- 🔢 数字滚动动画：Token 变化时 700ms 缓动滚动，增加亮蓝 / 消耗红色反馈
- 🧾 鲸鱼娘风格 HUD：白色圆角框 + 深藏蓝 Token 数字 + 秒级时间，
主题色随气泡联动，支持大数缩写（388.4W）
- 🫧 气泡台词系统：今日心情 / 随机 / 自定义 / 固定台词，
自动关泡、4 种配色、字号 / 框大小 / 触发频率全可调
- 🐟 互动玩法：鼠标跟随、躲避鼠标（被逼到角落会瞬移到对角）、
待机漫游（走走停停 + 边缘弱回正 + 交互即停）
- 🎨 表情系统：内置 v1~v4 表情包 + 默认表情 + Gif 摸头，
连点 N 次换表情（1~100 可调）、自动轮换（5~100 秒可调）、空闲眨眼动画
- 🔊 音效系统：播放器池（连点每一声都完整、不重叠不延迟）、
点击 / 松手 / 弹射 / 反弹音效、sounds/ 目录放入 mp3 即可新增音效选项、
支持自定义音效（覆盖全部音效）
- 📝 台词与规则可外部编辑：.dshw-pet-lines.txt（每行一句台词）与
.dshw-pet-rules.txt（匹配词 | 台词 | 触发概率 | 启用，带完整注释说明），
记事本改完点「重新加载」即生效
- ⚙️ 系统能力：单实例锁、开机自启（自动修正失效路径）、
独立运行日志（每次启动归档、保留 100 份）、应用打开监控 + 自定义规则与概率、
自定义点击音效、GitHub 更新检查、磁盘图标美化（大肥鱼）、托盘右键菜单
- 🖥️ 全屏智能隐藏（v4.4.1 重做判定）：玩全屏游戏 / 看全屏视频时自动隐藏桌宠与气泡，
退出全屏 0.25 秒内恢复（可在设置里开关）。判定只认真正的全屏：
桌面（Progman/WorkerW）、任务栏、最大化窗口、半屏窗口都不算全屏 ——
刷新桌面、打开/最大化浏览器都不会再把桌宠藏起来；副屏全屏也不会影响主屏的桌宠
- 🎚️ 卡片式设置面板：4 个标签页 × 多分区卡片（每张卡片带标题、说明与「?」提示），
深色玻璃风格，面板内可搜索设置项，记住位置与页签，
标题栏可拖动、离开面板自动关闭，低分辨率屏幕自动启用滚动
- 🪟 窗口三态层级：置顶 / 正常 / 置底（垫在所有窗口下面，当桌面挂件用），托盘菜单点一下循环切换
- 🪞 贴边翻转时立绘上的文字保持正向：有字的表情（如眼睛里的「加油」、金币上的「token」）登记文字区域，翻转时那部分不镜像，字依然正读
- 💳 真实余额与今日消耗：双击鲸鱼查 DeepSeek 官方接口，按「当日起始余额 − 当前余额」算今日消耗
- 🔒 单实例锁自愈：残留的脏锁会自动识别并清理，不会出现「明明没在跑却说已经运行了」
- 📏 大小 0.6~2.5 倍任意调节（档位 1~20）

🚀 快速开始

方式 A：直接下载运行（推荐）

1. 打开右侧 Releases 页面
2. 下载最新版 WhaleDesktopPet.zip（包含独立 exe）
3. 解压后双击 WhaleDesktopPet.exe，小鲸鱼就出现了 🐳

无需安装 Python、无需联网、无需 DSH。

方式 B：源码运行

1. 安装 Python 3.9+（勾选 Add to PATH）
2. 安装依赖
pip install PyQt5

3. 运行
python whale_pet.py

Windows 下也可直接双击 run.bat。

方式 C：自己打包 exe

双击 build.bat（或手动执行）：

python -m PyInstaller --noconfirm --onefile --windowed --name WhaleDesktopPet ^
--icon expressions\DSniang1.png --add-data "expressions;expressions" whale_pet.py

🕹️ 玩法说明

| 操作 | 效果 |
| --- | --- |
| 左键单击 | 消耗 Token（200~50000），弹出一句台词气泡 |
| 左键连点 | 连续点击 N 次后轮换到下一个表情（默认 30 次，可在设置调整 1~100） |
| 左键拖拽 | 移动小鲸鱼；靠近屏幕边缘松手自动贴边吸附 |
| 贴到左边缘 | 自动水平翻转（面朝屏内） |
| 右键短按 | 打开设置面板（鼠标移出面板自动关闭；顶部标题栏可拖动，✕ 为备用关闭） |
| 右键拖拽 | 橡皮筋弹射：把鲸鱼娘往后拉（拉得越远越重），松手向反方向弹出，撞到屏幕边缘反弹并播音符 |
| 拖文件到角色 | 喂食！弹窗明确警告「文件会被真实删除」，按 1KB = 1 Token 结算 |
| 鼠标靠近 | 开启「躲避鼠标」后她会逃跑（被逼到角落会挣扎贴边） |
| 离开一阵 | 开启「待机漫游」后她会在桌面走走停停散步 |
| 托盘菜单 | 显示/隐藏、Token +520W、清空、切换置顶、重新加载表情、检查更新、打开日志等 |

⚙️ 设置面板一览

互动
表情切换 · 连点换表情（1~100 下） · 大小（档位） · 音量 · 音效（小黄鸭/音效1）
鼠标跟随 · 躲避鼠标 · 待机漫游 · 贴边自动镜像（翻转） · 当前表情不翻转（立绘有字时用） · 固定位置 ·
拖拽吸附屏幕边缘 · 窗口层级（置顶/正常/置底）

Token
开启 Token 系统 · 显示 Token HUD · HUD 数字缩写（388.4W） ·
当前 Token 余额 · +520W · 清空

气泡
台词模式（今日心情/随机/自定义/固定） · 自定义台词库增删 · 显示气泡 ·
自动关闭时间（1~10s） · 气泡颜色（蓝/粉/深/绿，HUD 同步换主题） ·
显示当前时间 · 时间问候（早/中/晚） · 气泡字号（10~24px） ·
气泡框大小（70%~140%） · 对话频率（1%~100%）

系统
自动轮换表情 + 间隔 5~100 秒 · 空闲自动表情动画 · 空闲自动眨眼 + 间隔 ·
开机自启（自动修正失效路径） · 应用打开监控（匹配进程名/窗口标题 → 自定义台词与概率，
可增删/启停规则，也可直接编辑 .dshw-pet-rules.txt） ·
编辑台词文件 / 编辑规则文件 / 重新加载台词与规则 · 检查更新 ·
自定义音效（设置/清除） · 美化磁盘图标（大肥鱼） · 打开运行日志

📁 目录结构

DeepSeek-Whale-Desktop-Pet/
├── whale_pet.py            # 主程序（全部逻辑，单文件）
├── run.bat                 # 源码一键运行
├── build.bat               # 一键打包 exe
├── WhaleDesktopPet.spec    # PyInstaller 配置
├── README.md               # 本说明
├── assets/
│   └── DSH2.png            # README 封面图
├── expressions/            # 表情素材（v1~v4 + 默认表情 + Gif + 内置音效）
└── sounds/                 # 音效目录：放入 mp3/wav 即成为可选音效
├── 吐小泡泡.mp3  ├── 呀呼.mp3  ├── 啵.mp3   ├── 喵.mp3
└── 曼波.mp3      ├── 玛卡巴卡.mp3       └── 酱酱.MP3

📄 配置与日志

- 配置文件：C:\Users\\.dshw-desktop-pet.json（自动保存）
- 台词文件：C:\Users\\.dshw-pet-lines.txt（每行一句，# 为注释）
- 监测规则文件：C:\Users\\.dshw-pet-rules.txt
格式：匹配词 | 触发台词 | 触发概率(0-100) | 是否启用(1/0)
例：steam | 又在打游戏啦 | 30 | 1（30 = 30% 概率触发）；文件开头有完整注释说明
- 运行日志：%TEMP%\dshw-pet.log（每次启动归档，保留最近 100 份）
- 开机自启：写入注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Run
（每次启动自动校验路径，失效会自动修正为当前程序）

💳 真实余额与今日消耗

双击鲸鱼会通过气泡显示真实 DeepSeek 账户余额与今日消耗金额（后台异步查询，不卡界面）。
单击照旧只说话；连点换表情不会误触发余额查询（程序会等 0.75 秒确认「没有第三下」才算双击）。

配置（设置 → Token → 真实余额）

- API Key：在 platform.deepseek.com 创建，填进输入框后点「保存设置」。
密钥只保存在本机配置文件 ~/.dshw-desktop-pet.json，不上传任何第三方。
- 余额来源：DeepSeek 官方接口 GET https://api.deepseek.com/user/balance（返回真实 CNY/USD 余额）。
- 今日消耗来源：按「当日起始余额 − 当前余额」自动计算，无需任何额外记录脚本。

今日消耗是怎么算的

每天首次查询时，桌宠会把当时的余额记作「当日起始基准」（存到 ~/.dshw-balance.json）。
之后每次查询，用 当日起始余额 - 当前余额 得到当日真实消耗金额，跨关机重启也准。

几点说明：

- 当天第一次点会显示「今日消耗 ¥0.0000」（因为刚把当前余额记为基准，还没产生差值）。
- 如果当天充值过，余额比基准变多，消耗会按 ¥0 显示（不会出现负数）。
- 基准按「自然日」隔离，每天 0 点后自动重新起算。

🧩 自定义表情

把 png / jpg / jpeg / webp / gif 放进 expressions\ 后，托盘菜单
「重新加载表情」即可（或重启）。文件名会自动出现在设置面板的表情列表，
支持 v1_xxx / v2_xxx / v3_xxx / v4_xxx 前缀分组显示。

🔊 自定义音效

把 mp3 / wav / ogg / m4a 放进 sounds\ 目录，重启后在
设置 → 互动 → 音效 下拉框即可选到（文件名就是选项名）。
想让点击和松手用不同音效，命名 名字_click.mp3 + 名字_release.mp3 配对即可。
另外还支持 自定义音效（设置面板选择任意音频文件），它会覆盖点击 / 松手 /
弹射 / 反弹全部音效；不想用时点「清除自定义音效」。

🧪 开发者自测（改代码后必跑）

项目内置两条互补的检查路径，双击根目录 自测.bat 即可全部跑一遍，
报告输出到 tests\自测报告.txt：

| 路径 | 作用 |
|---|---|
| 静态分析 tests/check_static.py | 语法编译 + pyflakes（未定义变量 / 重复定义 / 未使用）+ AST 扫描（注释里被吞掉的赋值语句、函数内未定义变量、超长函数提示） |
| 动态遍历 tests/check_dynamic.py | 遍历面板每个按钮/复选框/滑块/下拉/输入框/列表项，并模拟日常操作：连点、长按、拖拽、右键、弹射（含边缘反弹）、喂食文件与目录、跟随/躲避/漫游/锁定/置顶 tick、表情与大小全量、台词与气泡全量、音效播放、应用监控、日志清理 —— 任何异常都会打印 |
| 启动检查 tests/check_startup.py | 分段启动耗时、启动到可见总时长、启动瞬间朝向（贴左边缘应立即镜像）、音效延迟预加载、耗时日志 |
| 音效检查 tests/check_sound.py | 音效目录扫描、播放器池每声完整、池满接管最早、预加载不重复、自定义音效覆盖、音量同步 |
| 全屏判定 tests/check_fullscreen.py | 纯函数用例（真全屏 / 桌面 / 任务栏 / 最大化浏览器 / 半屏 / 最小化 / 采集失败）+ 同屏判定（副屏全屏不藏主屏桌宠）+ 隐藏恢复时序（防抖、立即恢复、250ms 轮询） |
| 性能专项 tests/check_perf.py | 静止时移动节拍降频、开启跟随/漫游立刻回 60fps、全屏隐藏期间 HUD/移动/眨眼/轮换全停、进程名按 PID 缓存、镜像位图缓存、面板关闭后悬停轮询停止 |
| 余额·层级·翻转豁免 tests/check_balance_level.py | 单击只说话不查余额、双击查余额、连点换表情不误触发、两次慢点不算双击、窗口三态标志、带字表情翻转豁免、镜像时文字区保持正向、进程存活探测、单实例锁、余额基准原子写 |

两条路缺一不可：静态分析能发现"代码根本没跑到"的问题（如被注释吞掉的赋值），
动态遍历能发现"跑起来才炸"的问题（参数不匹配、空数据、状态组合）。
详见 tests/README.md。

🙏 来源与致谢

本项目由以下开源项目改造整合而来，在此向他们表示衷心感谢：

| 项目 | 借鉴内容 |
| --- | --- |
| comreade-123/DeepSeek-Whale-widget-desktop | 独立桌面版形态、HUD 窗口卡片样式、更新检查对齐、托盘交互思路 |
| MeteorNOX/DeepSeek-Balance-Whale-Widget | 原版交互规范：四边四分之一吸附、左吸附翻转、数字滚动动画（700ms easeOutCubic）、Q 弹参数（底部锚点、scaleY 0.88/scaleX 1.05、OutBack 回弹）、HUD 主题联动 |
| JiafishNB/DeepSeek-WindowsTable-game.io | 鲸鱼娘本体（表情/音效素材）、右键弹射物理（橡皮筋阻尼、角度反射反弹、B→A 方向发射）、躲避/跟随/待机漫游 tick 逻辑、鲸鱼娘风格 HUD（白框 + 深藏蓝数字）、喂食/连点互动玩法 |

如果你喜欢本项目，也请去给上面三个仓库点个 Star ⭐，感谢原作者的付出！

👨‍💻 开发者信息

| 项 | 内容 |
|---|---|
| 作者 | shiyi312 |
| 版本 | v4.4.2 |
| QQ 交流群 | 254668799（点击搜索加群） |

🐛 使用中遇到问题？欢迎加入 QQ 交流群 254668799 反馈 bug 或提出建议；
也可以找我们讨论互动玩法、表情素材或一起开发桌宠功能。

📄 License

MIT License，详见 LICENSE。
© 2026 DeepSeek-Whale-Desktop-Pet contributors