alexcarterio/deepseek-whale-pet

deepseek-whale-pet

CI

鲸鱼宠物的三个视图
行走动画

一个适用于 Windows 的透明、始终置顶的桌面宠物——一只可爱的鲸鱼伙伴，
它生活在你的桌面上，四处走动、说话，并关注你的
DeepSeek Harness (DSH)
会话。当一个 DSH 工作回合结束时，它会弹出一个对话气泡，并用可爱的声音
播报；当 DSH 正在等待你的批准或提问时，它会提醒你采取行动。它还可以
查询你的 DeepSeek API 余额，并为你启动 DSH。

该宠物以只读方式读取 DSH 的会话数据，绝不会修改或
重启 DSH。

功能特性

桌面宠物

- 三视图行走：侧面（自动镜像）、背面（向上行走）、正面（向下行走）。
- 三种移动模式：自由漫游 / 跟随光标 / 原地不动。
- 交互：拖拽（带语音台词）、单击弹跳 + 俏皮话 + 聊天入口、
双击喂食（小鱼干、蛋糕、棒棒糖、饺子、钻石）。
- 对话气泡系统：随机台词、反应台词，以及显示在灰色斜体气泡中的
内心“思维链”声音。
- 细节动画：呼吸、摇摆、跳跃、进食、方向交叉淡入淡出、
加速/减速惯性，以及随机休息。
- AI 聊天：点击 💬 入口，通过 DeepSeek deepseek-chat 模型聊天，
最多保留 40 条消息的上下文。
- 天气查询（右键菜单，数据来自 wttr.in）。
- 系统监控：当 CPU > 90%、RAM > 95% 或 NVIDIA GPU > 80 °C 时弹出气泡。
- 托盘图标、始终置顶、点击穿透（鼠标穿透）、开机自启，
以及记住位置/设置。

DSH 集成

- DSH 会话完成通知：当一个 DSH 工作回合结束时，宠物
显示气泡并大声播报。
- DSH 等待用户通知：当 DSH 正在等待批准或
提问时，宠物会提示你采取行动。
- DeepSeek 余额查询：右键菜单中的“查看 DeepSeek 余额”，
带气泡 + 语音播报，以及自动低余额提醒（静默
每小时巡检）。
- 自动启动 DSH：启动几秒后，宠物会探测
127.0.0.1:，如果 DSH Web 未运行，则启动它。它只会
启动 DSH——绝不会停止或重启它。

系统要求

- Windows 10 或 11
- Python 3.11+（已在 3.13 上测试）
- DSH (DeepSeek Harness)——可选，仅在需要 DSH 集成
功能时必需
- 用于 DeepSeek API、edge-tts 语音和天气的网络连接

安装

方式 A——一键安装

双击 install.bat。它会：

1. 安装 Python 依赖（pip install -r requirements.txt），
2. 启用开机自启（这也会启用自动启动 DSH 的行为），
3. 启动宠物。
选项 B — 手动

py -3 -m pip install -r requirements.txt
py -3 desktop_pet.py

日常使用时，只需双击 start_pet.bat。

开机启动 也可以通过右键菜单（“Start on Boot”）切换。
要从命令行中移除它，请运行：
py -3 desktop_pet.py --uninstall-autostart（或双击 uninstall.bat）。

配置

默认配置模板是
config.example.json。首次运行时，宠物会在脚本旁边创建实际的 config.json（在源码模式下），或在 %APPDATA%\WhalePet\config.json 下创建（在冻结的 .exe 构建中）。

| 键 | 默认值 | 描述 |
|---|---|---|
| mode | "wander" | 移动模式：wander / follow / still。 |
| size | 0.7 | 宠物缩放：0.55（小）/ 0.7（中）/ 0.9（大）。 |
| topmost | true | 保持宠物始终置顶。 |
| passthrough | false | 点击穿透（宠物变得不可点击）。 |
| autostart | false | 开机启动（安装程序会将其设为 true）。 |
| x, y | 0 | 保存的窗口位置（退出时覆盖）。 |
| ds_api_key | "" | 用于聊天和余额查询的 DeepSeek API 密钥。留空则回退到 DSH 凭据文件（~/.dsh/.credentials.yaml）。 |
| city | "" | 用于天气查询的城市名称（wttr.in）。 |
| voice_enabled | true | 语音播报开/关。 |
| voice_name | "" | SAPI 语音名称（空 = 系统默认）。 |
| voice_engine | "edge" | 语音引擎：edge（在线）或 sapi（离线）。 |
| say_voice | true | 语音播报日常台词（仅完整语音模式）。 |
| voice_mode | "full" | full（语音宠物）或 notify（仅任务通知）。 |
| voice_preset | "Xiaoyi - Sweet (recommended)" | edge-tts 语音预设（参见“Voice Preset”菜单）。 |
| dsh_launch | true | 启动后自动启动 DSH。 |
| dsh_dir | "" | DSH 安装目录（空 = 自动检测）。 |
| dsh_port | 3080 | DSH Web 端口。 |
| dsh_startup_delay | 10 | 启动后探测 DSH 前的秒数。 |
| dsh_notify_done | true | 当 DSH 会话回合完成时通知。 |
| dsh_notify_waiting | true | 当 DSH 等待用户操作时通知。 |
| dsh_notify_balance_low | true | 余额低时自动提醒。 |
| balance_low_threshold | 5.0 | 低余额阈值（单位：人民币）。 |

隐私与安全

这是一个纯客户端桌面应用：它不打开任何监听端口，也没有入站攻击面。出站数据仅限于以下内容，全部通过 HTTPS 发送：

| 数据 | 目的地 | 备注 |
|---|---|---|
| 聊天内容 + 上下文（最多 40 条消息，仅存于内存） | DeepSeek API | 仅在你使用聊天时发送。 |
| 城市名称 | wttr.in | 天气查询所必需。 |
| 语音播报文本 | Microsoft Edge TTS | 仅固定短语和台词 — 绝不包含 DSH 会话标题。 |
| DSH 会话数据 | 无 | 对本地状态文件的只读访问；不写入或传输任何内容。 |
API 密钥存储： 你的 API 密钥以明文形式存储在 config.json 中
（默认情况下仅你自己的 Windows 账户可读）。为避免这种情况，请将
ds_api_key 留空，改为将密钥保存在 DSH 凭据文件中；更
高级的设置可以使用 Windows 凭据管理器（DPAPI）。

DSH 访问： 桌宠只读取 DSH 的本地会话数据。它绝不会修改、
停止或重启 DSH。

使用方法

启动

- start_pet.bat — 正常启动桌宠。
- install.bat — 安装依赖 + 启用开机自启 + 首次启动。
- py -3 desktop_pet.py — 直接从终端启动。

交互

| 操作 | 效果 |
|---|---|
| 左键拖动 | 拖动桌宠（它会转向拖动方向，并在松开时说话）。 |
| 单击 | 弹跳 + 一句反应台词 + 💬 聊天入口。 |
| 双击 | 打开喂食面板。 |
| 右键单击（桌宠或托盘图标） | 完整菜单。 |

菜单亮点

- 查看 DeepSeek 余额 — 以气泡 + 语音播报你的剩余余额。
- DSH 状态 — 列出最近 DSH 会话的工作状态。
- 打开 DSH Web — 在 http://127.0.0.1: 打开 DSH Web UI。
- 语音播报 / 语音模式 / 语音预设 — 控制语音输出。
- 自动启动 DSH — 切换启动时是否自动启动 DSH。

语音播报

桌宠可以通过两种引擎说话：

- edge — 微软 Edge 在线 TTS（免费，无需密钥）。结果缓存在
%APPDATA%\WhalePet\voice_cache\ 下。
- sapi — Windows 内置离线语音，当 edge-tts 无法访问时
自动作为后备使用。

在仅通知语音模式下，桌宠在正常使用期间保持安静，
仅在任务事件（完成 / 等待 / 余额提醒）时说话。

DSH 集成

桌宠每 2 秒轮询一次 DSH 的会话数据（只读）：

- ~/.dsh/storages/session_projcache.json — 会话标题。
- ~/.dsh/sessions///session.jsonl.zstd — 事件日志，
用于精确检测一轮对话何时结束（turn/end）以及模型何时
在等待你（调用 ask_user_question 或有待处理的审批）。

设置 DSH_HOME 可覆盖 ~/.dsh 位置。dsh_dir（或自动检测）
告诉桌宠 DSH 的安装位置，以便在 DSH Web 尚未运行时
启动它。

开发者工具

tools/ 目录包含开发期间使用的辅助脚本，用于
试听语音、重做精灵图和打包发布版本。它们不是运行桌宠所必需的 —
普通用户可以忽略它们。

| 脚本 | 用途 | 依赖 | 示例 |
|---|---|---|---|
| tools/synth_candidates.py | 生成多个 edge-tts“萌化”试听变体。 | edge-tts（在 requirements.txt 中） | py tools/synth_candidates.py |
| tools/synth_kids.py | 使用 edge-tts 生成柔和的童声音调变体。 | edge-tts（在 requirements.txt 中） | py tools/synth_kids.py |
| tools/synth_chattts.py | 使用不同的语音种子合成 ChatTTS 试听候选音频。 | torch、torchaudio、ChatTTS | py tools/synth_chattts.py [out_dir] |
| tools/synth_chattts_loli.py | 将 F0 最高的 ChatTTS 种子进行变调，生成“萝莉”变体。 | torch、torchaudio、ChatTTS | py tools/synth_chattts_loli.py [out_dir] |
| tools/synth_chattts_scan.py | 扫描 50 个 ChatTTS 种子，并根据 F0 自动挑选少女音色。 | torch、torchaudio、ChatTTS | py tools/synth_chattts_scan.py [out_dir] |
| tools/preprocess.py | 从正面/侧面/背面源图像重建三视图精灵图。 | Pillow (PIL) | py tools/preprocess.py [src_dir] [out_dir] |
| tools/preprocess2.py | 边缘去污 + 预乘 Alpha 精灵图缩放。 | Pillow (PIL) | py tools/preprocess2.py [src_dir] [out_dir] |
| tools/make_zip.py | 将运行时源代码打包为可分享的 zip 文件。 | 无 | py tools/make_zip.py |

ChatTTS 脚本需要安装 torch、torchaudio 和
2noise/ChatTTS（通过 pip 或按照其
仓库说明安装）；它们体积较大且为可选组件。

语音样本

samples/ 目录存放候选语音的试听录音：edge-tts
变体（Xiaoyi / Xiaoxiao 等）以及 ChatTTS 多种子试听。宠物
的默认语音是内置的，因此无需 samples/ 也能正常运行。若要
重新生成候选语音，请运行相应的 tools/ 脚本——edge-tts
脚本无需额外依赖，而 ChatTTS 脚本需要先安装 torch
和 ChatTTS。

运行测试

py tests/test_watch.py

该测试需要 zstandard（pip install zstandard）。它使用伪造的（zstd 压缩）会话日志
驱动 DSH 事件状态机，并验证
普通工具活动不会被误报为“等待中”，只有问题和
审批才会报告“等待中”，并且只有回合结束才会报告“完成”。

常见问题 / 故障排除

1. 宠物不说话。

- 确保 config.json 中的 voice_enabled 为 true（或检查
“语音播报”菜单项）。
- edge 引擎需要互联网访问；如果离线，它会回退到
Windows SAPI 语音。请检查 Windows 是否已安装语音
（设置 → 时间和语言 → 语音）。你可以通过
菜单强制使用离线语音：语音预设 → “系统离线语音（无网络）”。

2. DSH 集成不显示通知。

- 确认 DSH 已安装并正在运行（或 dsh_dir 指向它，并且
dsh_launch 已启用）。
- 宠物会读取 ~/.dsh；如果你的 DSH 主目录在其他位置，请在启动宠物前
将 DSH_HOME 环境变量设置为该位置。
- 会话必须是最近的（在过去 24 小时内写入）才会被跟踪。

3. 如何移除开机自启动？

- 右键单击宠物或托盘图标 → 取消勾选“开机自启动”，或
- 双击 uninstall.bat，或
- 运行 py -3 desktop_pet.py --uninstall-autostart。

4. 余额查询失败。
- 在 config.json 中设置 ds_api_key（或在
~/.dsh/.credentials.yaml 中设置 DEEPSEEK_API_KEY）。该密钥必须是有效的 DeepSeek 开放平台
密钥。余额接口需要可用的互联网连接。

许可证

基于 MIT 许可证 发布。

致谢与参考

本项目基于以下项目的工作构建：

- dafeiyu-pet — 宠物行为、精灵图及基础应用程序源自
1190fasheqi/dafeiyu-pet
（MIT 许可证）。详情请见 NOTICE。
- edge-tts — 通过
rany2/edge-tts 实现在线语音合成。
- ChatTTS — 试听脚本使用
2noise/ChatTTS。
- wttr.in — 天气数据来自 wttr.in。
- DeepSeek Harness — 此宠物所监视的 DSH 会话状态由
deepseek-ai/deepseek-harness 生成。