鲸鲸桌宠 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；程序内见「设置 → 关于 → 版权与致谢」。 若权利人认为某处用得不对，请联系作者，核实后会立刻替换或移除。