鲸鱼娘桌宠 DMM-331/dsh-rice-pet

鲸鱼娘吃白饭 · DeepSeek 桌宠插件（dsh-rice-pet）

DeepSeek 的桌宠插件：一只 chibi 鲸鱼娘住进 DeepSeek Harness（DSH）。模型生成时她一口一口吃白饭，工具调用时放下碗记笔记，等你审批时朝你挥手；在 macOS 和 Windows 上她还能走出 DSH 窗口，待在桌面任意角落。
每完成一轮对话她攒一颗饵，右键就能下海捞宝。

一个 DeepSeek 桌宠插件，面向 DeepSeek Harness（DSH）：模型生成时，chibi 鲸鱼女仆一直吃白饭，模型停下时她放下碗。在 macOS 和 Windows 上，她住在你的桌面上，可以待在任何屏幕的任何位置；在其他平台上，她留在 DSH 窗口里。

DeepSeek 桌宠插件：鲸鱼娘在桌面上吃白饭

dsh plugin --profile web add github:DMM-331/dsh-rice-pet

目录 · Contents

- 这是什么
- 功能特性
- 安装
- 常见问题
- 开发
- 许可

这是什么 · What it is

一个开源的 DeepSeek 桌宠（desktop pet）插件：她不是独立程序，而是 DeepSeek Harness 的一个插件，装进 DSH 后同时出现在两处——DSH 窗口里的浮层，以及（macOS / Windows）桌面上的透明置顶窗口。
桌宠状态跟着智能体的真实进度走：step/start 到 assistant/message 之间她在吃，工具在跑时她记笔记， approval/asked 时她挥手等你点确认，出错时她会噎住。她有自己的情绪模型，会闹别扭、会犯困，也会自己溜达。

功能特性

- token 流动时她就吃：从 step/start 到模型的 assistant/message，她循环播放吃东西动画；步骤之间间隔不到 1.5 秒不会打断她。生成停止后，她吃完这一口，放下碗。
- 悬停显示余额：配置了 API key 后，宿主读取 GET https://api.deepseek.com/user/balance，提示框显示当前余额。读不到时不显示任何内容（例如用 DeepSeek 账号登录的情况），并且刻意不显示单次回复的花费 / 充值：余额变化无法可靠地归因到某一次回复。
- 桌面模式（macOS、Windows）：她离开 DSH 窗口。双击她 → 所有屏幕变暗 → 在任意屏幕上拖出一个矩形，设定她的活动区域（Esc / 右键取消）。保存在 ~/.dsh/whale-rice/overlay.json。
- 互动：点一下戳她，拖动可以把她拎起来（她会弹回活动区域内），她也会自己在活动区域里蹦跶。
- 下海捞宝：每完成一轮对话她攒一颗饵（长对话两颗，最多 5 颗）。右键她 → 下海捞宝：她在屏幕上砸出一个洞，潜进洞后的海里，再带着随机宝物浮上来（36 件物品、5 种稀有度，10 抽保底史诗，50 抽保底传说）。捞到什么由宿主在演出潜水之前抽好并保存，存在 ~/.dsh/whale-rice/bag.json。右键 → 背包 显示背包和收藏；挑一件，她拿出来给你看。她偶尔也会自己拿一件出来欣赏。屏幕上什么都不截取：玻璃是画出来的，所以不需要任何权限。

安装

dsh plugin --profile web add github:DMM-331/dsh-rice-pet

key 从 DSH 凭据服务读取，名字是 DEEPSEEK_API_KEY（DSH 自己用的也是这个），读不到时回退到环境变量。
key 只在宿主侧使用，绝不会发到浏览器。

可选配置（cordis.patch.yml）：

config:
apiKeyRef: DEEPSEEK_API_KEY # credential / env var name
pollSeconds: 60 # polling interval, minimum 15
desktop: true # false keeps her inside the DSH window

桌面模式会运行一个小型原生辅助程序 lib/whale-overlay / lib/whale-overlay.exe（源码在 native/，构建时编译）：每块屏幕一个透明置顶窗口，除鲸鱼外全部点击穿透。它只与插件打开的私有 127.0.0.1 端口通信（每次启动随机 token），DSH 退出时它也随之退出。

- macOS：Swift + WKWebView，用 swiftc 编译。无需额外运行时。
- Windows：.NET Framework 4.8 + WebView2（组合托管，因此页面的透明背景是真正的透明），位于 native/windows/。构建需要 .NET SDK（dotnet build）；WebView2 运行时随 Windows 10/11 的 Edge 一起提供。没有 SDK 时直接跳过辅助程序，她就待在 DSH 窗口里。命中测试、DPI 缩放和区域选择器的 Esc 键都由辅助程序处理；~/.dsh/whale-rice/overlay.log 记录它做了什么。

开发

pnpm install
pnpm dev # build + start the local harness at http://127.0.0.1:8770 (DESKTOP=1 to also run the desktop overlay)

harness（dev/）运行真实的主机侧代码，配一个模拟的 DeepSeek 余额 API，因此不安装 DSH 也能模拟扣费、充值和卸载。

导演模式（默认关闭；harness 中开启）会触发那些平时只能碰巧或等待才会出现的行为，用于演示和调试。在插件配置里设 director: true 开启，然后：

curl 'http://127.0.0.1:8771/?act=run&arg=left' # run|walk|roll left/right, sleep, oops, full, cheer
curl 'http://127.0.0.1:8771/?act=grab&arg=5,-650,-450' # hold 5 s (she struggles), then throw
curl 'http://127.0.0.1:8771/?act=feel&arg=praise' # nudge her mood; calm resets it
curl 'http://127.0.0.1:8771/?act=dive&arg=legendary' # dive now, no bait spent; arg: a rarity, an item id, or nothing
curl 'http://127.0.0.1:8771/?act=admire' # take a treasure out of the bag to look at

它只监听 127.0.0.1，播放真实的动画和状态机；只有触发是手动的。

src/
host/ Node half: agent activity (activity.ts), balance, SSE hub, desktop overlay host
shared/ The whale itself: behaviour state machine, sprite playback, regions, styles
client/ In-app entry (inside the DSH window)
overlay/ Desktop overlay page (one per screen, inside the native helper)
native/macos/ Swift helper: transparent click-through windows
native/windows/ C# helper: the same, on .NET Framework 4.8 + composition-hosted WebView2
assets/ Shipped runtime assets: sprites/whale.webp + whale.json, artwork license
art/ Source artwork (not shipped): generated grids, reference, prompts, sprites.json manifest
scripts/ 目录：build.mjs（把所有产物输出到 lib/）、sprites/build_sprites.py（把美术资源打成图集） dev/ 目录：本地调试环境，带模拟事件和模拟余额 API

精灵图：编辑 art/sprites.json（源文件、帧 id、动画、时长），然后运行 pnpm sprites （需要 Python 3，并装好 Pillow 和 NumPy）。脚本会切分网格、去掉白底、把每一帧对齐到脚部 / 面部轴线，输出 assets/sprites/whale.{webp,json}、一张带标注的拼版预览图（art/previews/atlas.png），以及按播放顺序排好的每个行为，并标出实测头部尺寸（art/previews/flows.png）。

尺寸规则：同一张图集内，站立帧统一归一到相同身高；跨图集时，每张图集取一个系数，让它的头部高度中位数（发顶到下巴）与其他图集一致，这样在不同图集里画的行为之间切换，她的头大小始终不变（faceMatch：1 = 头部等大，0 = 身高等高）。逐帧的 frameScale 只用于图像模型在同一网格内画得大小不一的那些分格。

| 智能体状态（会话事件） | 她会做什么 |
| 生成中（step/start → assistant/message） | 一口一口地吃 |
| 工具运行中（assistant/message → step/end） | 记笔记，碗放在地上 |
| 等待审批（approval/asked → approval/decided） | 朝你挥手；8 秒后开始哀求，敲她的碗 |
| 回合以 error / max-tokens 结束 | 噎住 / 捧着吃撑的肚子 |
| 一个回合跑满 20s 以上才完成 | 跳起来比个赞 |
| 空闲 | 走来走去，开心时端着饭碗小跑（多半是心情好的时候），或者在她的地盘里翻跟头（像轮子一样滚：距离 = 角度 × 半径），做点小手势，5 分钟后打盹 |
| 被拎起（拖拽） | 被捏住后颈悬在光标下，像钟摆一样晃；2.5 秒后开始挣扎，然后瘫软 |
| 之后（心情） | 一个情绪模型（src/shared/emotion.ts）：每个事件给 valence（不开心…开心）、arousal（疲惫…亢奋）和 need（想被关注）加一个固定冲量，三者各自衰减；心情就是她所处的区域——赌气、警惕、低落、得意、期待（夸夸我）、犯困。重复事件会叠加，好事只能缓和坏心情，如果她最后闹起别扭，开心的收尾（体操姿势、欢呼）就跳过。加新行为 = 在事件表里加一行 |
| 被扔出去（移动中松手） | 在重力下飞出，撞到屏幕边缘弹开并翻滚；落地时如果身子是正的就像体操运动员一样站稳，否则脸着地；落到地盘外会自己走回来 |

常见问题 · FAQ

这是 DeepSeek 官方出的桌宠吗？
不是。这是一个社区开源的 DeepSeek 桌宠插件，通过 DeepSeek Harness（DSH）的插件机制加载；代码 MIT、美术 CC BY-NC-SA，和 DeepSeek 官方没有关系。

怎么安装这个 DeepSeek 桌宠插件？
一条命令：dsh plugin --profile web add github:DMM-331/dsh-rice-pet，然后重启 DeepSeek Harness。
装好后她就待在 DSH 窗口里；桌面模式默认开启（desktop: true），她会走到桌面上，想要只留在窗口里就设成 false。

支持 Windows 吗？支持 macOS 吗？
两个平台都支持，包括多屏和高 DPI。macOS 用 Swift + WKWebView，Windows 用 .NET Framework 4.8 + WebView2（组合宿主，页面背景真透明）。Windows 构建 helper 需要 .NET SDK，缺了会自动退回「只在窗口里」的模式。

她会挡住鼠标、影响我点桌面图标吗？
不会。她的窗口只覆盖自己身边那一小块，其余区域的点击原样透传；按住左键拖动时窗口才临时扩大到她经过的地方。

需要 DeepSeek API Key 吗？
只有想看「余额气泡」才需要（读 DEEPSEEK_API_KEY）。吃白饭、下海捞宝、情绪和行为都只依赖 DSH 的会话事件，不联网也不需要 Key。

会收集数据吗？
不会。唯一的网络请求是余额查询，Key 只在主进程使用，从不下发到浏览器端。

License

- Code: MIT (LICENSE)
- Artwork: CC BY-NC-SA 4.0 (assets/LICENSE-ARTWORK), no commercial use; see NOTICE for sources

Unofficial fan work, not affiliated with DeepSeek.

关键词 · Keywords

DeepSeek 桌宠、DeepSeek 桌宠插件、DeepSeek 桌面宠物、DSH 插件、DeepSeek Harness 插件、鲸鱼娘、二次元桌宠、Windows 桌宠、macOS 桌宠、开源桌宠； DeepSeek desktop pet、DeepSeek desktop pet plugin、DeepSeek Harness plugin、DSH plugin、 whale maid desktop mascot、virtual pet、anime desktop pet、open source desktop pet.