鲸鲸桌宠 Chuzhj/whale-pet

鲸鲸桌宠 v1.1.0

一只住在桌面上的蓝色鲸鱼娘。透明、无边框、会眨眼、会摆呆毛、会甩尾巴，饿了自己偷吃白饭，闲了冒两句台词，想说话就双击她。

程序用纯 Python + PySide6 写成，在 Windows 上跑；不用安装、不要管理员权限，双击就出来，右键就能设置。

这一版新增了什么 → RELEASE_NOTES.md　·完整改动史 → CHANGELOG.md

一、怎么跑起来

方式一：exe 压缩包（推荐给不想装 Python 的人）

解压 鲸鲸桌宠_分享版_v1.1.0_exe.zip，得到 WhalePet\ 文件夹，双击里面的 WhalePet.exe。

- 整个文件夹要一起留着：WhalePet.exe 旁边的 _internal\ 是运行时，删了就起不来。
- 第一次运行会被 Windows 防火墙/SmartScreen 问一句（没有代码签名，属正常），选"仍要运行"。
- 想开机自启：把 WhalePet.exe 的快捷方式丢进 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup。

方式二：直接跑源码

pip install -r requirements.txt
python whale_pet.py

需要 Python 3.10 以上（开发与打包用的是 3.13）。

命令行参数（都能不带，用默认值就很好看）：

python whale_pet.py --height 420 :: 角色高度（像素）
python whale_pet.py --fps 30 :: 降帧率省电
python whale_pet.py --pos 1200,600 :: 固定初始位置
python whale_pet.py --no-ai :: 不读配置、不联网，纯桌面宠物
python whale_pet.py --version :: 打印版本号
python whale_pet.py --selftest :: 离屏自检（不弹窗口）
python whale_pet.py --doctor :: 对外通道体检（飞书 / 派活逐项真测）

二、她都会什么

| 操作 | 效果 |
| 左键单击 | 换个表情（切过去就保持住，不会自己收回去） |
| 拖拽 | 换位置（位置会记住） |
| 双击 | 打开聊天窗口（接大模型聊天，需要配 API key） |
| 右键 | 菜单：说句话 / 显示时钟 / 做个表情 / 叫醒去睡觉 / 回到待机 / 派活给 Harness / 切换形态 / 设置 / 隐藏 |
| 点饭碗 | 喂她白饭（吃完自动添） |

- 精力 / 饱食度：聊天会消耗精力，耗尽了会自己趴下睡；睡够了自己醒。
- 记账：右键「小鲸鱼记账…」，按 DeepSeek 余额观测推算"今日已用"，含峰谷价。
- 提醒：跟她说"25 分钟后叫我"，或"十月二十号早上提醒我跑步"，两种都支持，后者存文件、关掉程序也不丢。
- 音效：按键、喂饭、任务结束、提醒都有声，音量和逐事件开关在「设置 → 音效」。
- 隐藏：右键 → 隐藏，程序缩进系统托盘；托盘图标右键「打开」请回来，「退出」才是真退出。

三、设置（右键 →「设置…」）

六页，改完即生效，都落在 exe 旁边的 whale_pet_config.json：

| 页 | 内容 |
| 聊天与钥匙 | 选模型厂商（DeepSeek / 通义 / 智谱 / Moonshot / OpenAI / 本地 Ollama）、填 API key、联网搜索开关 |
| 飞书接入 | App ID / Secret、域名（feishu / lark）、白名单、允许派活 |
| 音效 | 总开关、音量、逐事件开关、试听 |
| 桌宠 | 大小、是否始终置顶 |
| 界面 | 各窗口统一字号 |
| 关于 | 版本、数据目录、配置文件路径 |

不想用界面也行，直接改 whale_pet_config.json（明文 JSON，密钥会用 Windows DPAPI 加密存储）。

四、飞书接入（可选）

接上飞书以后，可以在手机或飞书里给她发消息、派活、让她发截图和结果文档。

1. 去 飞书开放平台 建一个「企业自建应用」。
2. 拿到 App ID / App Secret，填进「设置 → 飞书接入」。
3. 开放平台里打开长连接方式的事件订阅（本程序自己实现协议，只依赖 websockets，不需要公网 IP、不需要内网穿透、不开任何端口）。
4. 权限至少给：接收消息、发消息、上传图片、上传文件（发图片/文档要用）。
5. 建议填上「只认这个人的消息」（自己的 open_id）：不填的话私聊照常，但群消息一律忽略。
6. 勾「启用飞书接入」保存。桌宠控制台会打一行 [飞书] 已连接。

常用命令（直接发给她）：/status /shot（截屏发给你）/task（派活） /sessions（列出任务对话）。完整清单发 /help。

「允许飞书派活」等于允许能给她发消息的人在这台电脑上执行代码，默认关闭，自己掂量着开。

五、派活给 Harness（可选）

「派活给 Harness」走 DeepSeek Harness 的 ACP 通道，让桌宠把一件事交给本机的 Harness 去做（写代码、查资料、跑命令），结果回到桌宠的气泡里。

- 前提：本机装了 DeepSeek Harness。
- 程序会自动在 %LOCALAPPDATA%\Programs\DeepSeek Harness\、 %PROGRAMFILES%\DeepSeek Harness\ 下找主程序；装在别处就在 whale_pet_config.json 里把 dsh_exe 指过去。
- 没装的话这个菜单项点了会说一句"没找到"，不影响其它功能。

六、三种形态

| 形态 | 说明 |
| 鲸鲸娘（默认） | 全身女仆装，有 16 种表情、眨眼、睡姿、呆毛和尾巴两层独立摆动 |
| 哦鲸鲸 | 立绘特写，一张静态图，点了会尖叫一声并弹余额 |
| DS鲸鱼娘（Live2D） | 第三形态，眼珠会跟着鼠标转，表情可以叠加。exe 包里已经带了；跑源码要额外 pip install live2d-py PyOpenGL，没装就自动藏起这个形态 |

三个形态各自记住自己的显示高度，互不影响。切到第三形态要等一两秒（它得先建 GL 上下文）。

⚠ 第三形态不是原创素材。 Live2D「DS鲸鱼娘」是第三方作品：模型制作 B站 @氵六青（UID 11272072），形象版权 @上善无形 与 @ZipZipPin，采用 CC BY-NC-SA 4.0。
禁止出售、禁止以商业利益为主要目的使用；再分发须保留署名并以相同许可共享。
完整署名与改动说明见 CREDITS.md，程序内见「设置 → 关于 → 版权与致谢」。

七、数据都存在哪

全部放在 exe（或 whale_pet.py）旁边，搬家时整个文件夹一起搬就行：

| 文件 | 内容 |
| whale_pet_config.json | 配置（第一次保存设置时才生成；密钥 DPAPI 加密） |
| whale_pet_state.json | 精力 / 饱食度 / 是否睡着 |
| chat_log.jsonl | 最近三天的对话（更早的自动清） |
| memory.jsonl | 长期记忆 |
| alarm.jsonl | 长期提醒 |
| ledger.jsonl | 余额观测账本 |
| feishu_log.txt | 飞书连接日志（最近几十行） |

想恢复出厂：退出程序，把这些文件删掉即可（whale_pet_config.json 删掉就只有默认配置）。

八、重新打包

pip install -r requirements.txt
pyinstaller --noconfirm --clean WhalePet_onedir.spec

产物在 dist\WhalePet\，整个文件夹压缩后分发。
不要把源码（.py）放进分发包：onedir 包里只有 .pyc 与资源文件。

--selftest / --doctor 在打包后同样可用，GUI 版没有控制台，用 --selftest-log <文件> / --doctor-log <文件> 把结果写出来：

WhalePet.exe --selftest --selftest-log 自检.log WhalePet.exe --doctor --doctor-log 体检.log

退出码 0 = 全通过。

九、常见问题

双击没反应？ 先看有没有已经在跑（同一台机器只允许一只鲸鲸，再双击一次等于把她请回前台）。
还不行就命令行跑 WhalePet.exe --doctor --doctor-log 体检.log 看缺什么。

她不理我？ 没填 API key 时她只会冒台词、不会聊天，这是设计如此（不留半死不活的中间态）。

画面糊了？ 在「设置 → 桌宠」里拖一下大小滑块即可：重新读原图重采样，比放大旧图清楚。

杀毒软件报毒？ PyInstaller 打的未签名 exe 常被误报，源码可查、可自行重打包。

关掉之后弹「已停止工作」？ 这是安装路径含中文时的已知问题：功能全部正常、日志与配置都已落盘，只是进程退出那一刻会在两个 C/C++ 扩展（Cubism Native / PyOpenGL）的静态析构里崩掉。解压到纯英文路径（如 D:\WhalePet\）即可完全避免。
v1.0.1 也有同样表现，不是这一版引入的；细节见 RELEASE_NOTES.md。

十、许可与素材

10.1 程序代码

本项目自己写的 Python 代码可自由使用、修改、再分发。

10.2 美术素材分两类

| 类别 | 文件范围 | 权利状态 |
| 自绘 / AI 生成 | assets/ 下除 forms/l2d/ 以外的立绘、表情帧、白饭碗、音效 | 由作者提供，随本程序 as-is 附带，不单独授予再许可 |
| 第三方作品 | assets/forms/l2d/（第三形态「DS鲸鱼娘」） | 不是本项目原创，单独遵循下节的许可 |

早先的版本把这两类写成一句"美术素材由作者提供或使用 AI 工具生成"，对 Live2D 那部分是错的（它既不是自绘也不是 AI 生成），已更正。

10.3 第三形态「DS鲸鱼娘」—— CC BY-NC-SA 4.0

| 项目 | 内容 |
| 作品 | 「DS鲸鱼娘」Live2D 模型 |
| 模型制作 | B站 @氵六青（UID 11272072） |
| 形象版权 | @上善无形 与 @ZipZipPin |
| 来源 | 作者无偿分享的 Live2D 素材包（DS鲸鱼娘 / DS鼠控版） |
| 许可 | CC BY-NC-SA 4.0（署名 — 非商业性使用 — 相同方式共享）https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh |
| 改动说明 | 仅重建 model3.json 里的 Motions / Expressions 注册表（原包这两个字段是空的，绑定信息在 VTube Studio / 直播姬的配置里）。moc3、两张纹理、physics3.json、动作与表情文件逐字节未改。 |
| 使用限制 | 禁止出售；NC 条款禁止「以商业利益为主要目的」的使用；再分发须保留本署名并以相同许可共享 |

原包自带的《使用须知》原文：允许「商用直播」「自印物料」，同时明确 「禁止任何形式的盗用以及出售」，并说明 CC 官方 FAQ 认可"收取制作/运营成本等合理费用不必然构成商业性使用"。

完整署名另见 CREDITS.md；程序内见「设置 → 关于 → 版权与致谢」。
若权利人认为某处用得不对，请联系作者，核实后会立刻替换或移除。