whale-girl 是什么？DSH Web GUI 的 QQ 宠物风格桌面伙伴

whale-girl 是 DeepSeek Harness（DSH）Web GUI 的桌面宠物插件：一只 QQ 宠物风格的小鲸鱼悬浮在界面右下角，会随着你的任务完成、会话时长与陪伴时间积累等级、称号和记忆，还能拖拽、投喂、玩耍。 本文基于官方 README，介绍 whale-girl 是什么、核心功能、安装启用、典型用法与常见排错。

whale-girl 是什么？

whale-girl 解决「长时间用 DSH 缺少趣味反馈」的问题：把完成任务、积累陪伴变成看得见的等级、称号和记忆，让工具使用过程更像养一只小宠物。 以下定位与事实均来自官方 README（来源）：

whale-girl（GitHub 仓库 vlln/whale-girl）由 vlln 维护，用 JavaScript 开发，MIT 协议开源，是 DSH Plugin 生态中的界面插件（kind 为 ui，以 bundle 组合包形式发行：dsh.bundle 负责插件逻辑，dsh.client 负责浏览器端渲染）。它像过去的 QQ 宠物一样悬浮在 Web GUI 右下角，一只小鲸鱼会跟随你的使用节奏做出反应：任务完成时庆祝、出错时吓一跳、空闲久了打瞌睡。与普通装饰挂件不同，它把「养宠物的感觉」做进数据里——完成任务、会话时长、陪伴时间会积累为等级与称号，并沉淀为记忆（来源）。

whale-girl 的核心功能有哪些？

whale-girl 的核心能力围绕「悬浮陪伴 + 积累成长 + 状态机动画」展开：一只可拖拽、可投喂、可玩耍的小鲸鱼，把使用 DSH 的时间变成看得见的反馈。 功能事实来自官方 README（来源）：

• 悬浮桌面宠物：以 QQ 宠物风格悬浮在 Web GUI 右下角，随 DSH Web 界面打开自动出现，可拖拽到任意位置。
• 拖拽、投喂与玩耍：拖拽触发 drag 动画，投喂触发 eat，玩耍触发 play，按压还有 Q 弹交互，让宠物与操作实时联动。
• 等级、称号与记忆：完成任务、积累会话时长与陪伴时间会转化为经验，升级获得称号，陪伴细节沉淀为记忆，长使用周期也有成长感。
• 状态机驱动的 15 种动画状态：idle、working、celebrate、error、disappointed、joy、eat、play、drag、walk、sleep、wake、welcome、think、wait——任务完成或升级触发 celebrate，任务失败先 error 再 disappointed，空闲超过 sleepAfterMs 进入 sleep。
• 可选桌面伴侣应用：独立的桌面应用（whale-girl-desktop）让宠物常驻操作系统桌面，与网页版通过公开接口协作。

怎么安装与启用 whale-girl？

whale-girl 以 bundle 组合包形式通过 DSH Plugin 命令安装，装完重启 Web 客户端即可在右下角看到小鲸鱼。 安装过程与 DSH 其他插件一致，官方 README 提供了标准命令（来源）：

1. 确认环境与目标 profile。 whale-girl 是 DSH 界面插件，安装到运行 Web GUI 的 profile。下面的示例以 web 为 profile 名，换成你自己的 profile 名即可。

2. 执行官方安装命令。 在 DSH 环境里运行以下命令安装 whale-girl：

dsh plugin --profile web add whale-girl

也可以从 GitHub 源码安装：

dsh plugin --profile web add github:vlln/whale-girl

或用带版本号的 npm 包安装（当前为 0.1.0）：

dsh plugin --profile web add whale-girl@0.1.0

3. 重启 Web 客户端。 安装完成后重启 Web，让 bundle 组合包（dsh.bundle + dsh.client）加载生效。宠物悬浮在 Web GUI 右下角即安装成功。

4. 校验并管理插件。 查看已安装插件确认 whale-girl 在列：

dsh plugin list

更新时重新执行 add 即可覆盖安装；移除时使用 remove：

dsh plugin remove whale-girl

关于 whale-girl 的增删与更新，都通过 DSH Plugin 标准的 add/update/remove 命令完成，不需要手动改配置文件。

whale-girl 典型用法

装上 whale-girl 后，日常使用就是「陪它玩 + 看它成长」：拖拽、投喂、玩耍触发即时反馈，配置在设置文件里改完立即生效。 以下用法基于官方 README（来源）：

1. 调整宠物大小与开关。 在 DSH 设置文件（settings.yaml）的 whale-girl: 节点下修改配置，比如把 size 改成 120：

whale-girl:
  enabled: true
  size: 120

size 单位为像素，范围 64–160，默认 110；enabled 控制网页宠物是否显示。改动即时生效，无需重启。

2. 拖拽、投喂与玩耍。 直接用鼠标把右下角的小鲸鱼拖到任意位置（drag 动画）；在设置或伴侣面板里给它「投喂」（eat 动画）或「玩耍」（play 动画），按压还有 Q 弹反馈，每次交互都能看到状态机切换动画。

3. 观察事件驱动的状态反馈。 任务完成、升级或回合结束触发 celebrate（庆祝）；任务失败或请求错误先 error 再 disappointed；空闲超过 sleepAfterMs（默认 60000ms）进入 sleep（打瞌睡）。连续使用一段时间后，经验会累积成等级与称号，陪伴细节沉淀为记忆。

4. 启用桌面伴侣应用。 想让宠物常驻操作系统桌面，可全局安装独立应用：

npm install -g whale-girl-desktop

要求 Node ≥18，渲染外壳需要 Rust（cargo）环境；也可以 --headless 无头运行，或从源码构建 Tauri 外壳（首次构建约 5–15 分钟，产物约 12MB）。运行时网页宠物会隐藏，退出或崩溃后约 45 秒内自动恢复显示（presence 契约）。

whale-girl 常见问题与排错

whale-girl 的常见问题集中在「宠物不显示」「大小与配置」「桌面伴侣」三类，多数情况按下面的步骤即可解决。 排错要点来自官方 README 与 FAQ（来源）：

1. 症状：安装后宠物不显示。 解决：安装或更新后先重启 Web 客户端使 bundle 组合包生效；然后确认设置中 whale-girl 的 enabled 为 true（为 false 通常是因为桌面伴侣正在运行）；最后确认当前不在引导页面上——引导页会隐藏宠物。

2. 症状：size 改了半天没反应或显示异常。 解决：size 只认 64–160 范围内的值，超出范围可能被忽略或异常；改完确认写入的是 settings.yaml 的 whale-girl: 节点。注意配置改动是热更新的，但插件安装/更新仍需要重启 Web。

3. 症状：桌面伴侣启动不了或网页宠物消失。 解决：先确认 Node ≥18，需要渲染外壳时确认 Rust（cargo）可用；若只想保留网页宠物，把 enabled 设为 true 并关闭桌面伴侣。桌面伴侣是独立应用，不通过 dsh plugin 安装，装完也不要在插件列表里找它。

适用场景与注意

whale-girl 适合想给长时间 DSH 工作流加一点趣味和陪伴感的用户，但它本质是界面装饰型插件，不承担任何核心业务。 以下几点来自官方 README（来源）：

• 适合：长时间在 DSH Web GUI 里写提示词、跑任务、调 Agent 的用户；喜欢桌面宠物、想获得正向反馈的用户；想用等级/称号激励持续使用的团队或个人。
• 不适合：追求极致简洁、容不下任何界面装饰的环境；对低内存/低性能有硬性要求的部署（桌面伴侣需 Node ≥18，可选 Rust 构建外壳）。
• 注意：桌面伴侣运行时网页宠物会隐藏，退出后约 45 秒恢复；XP 与称号阈值不可配置；「Switch Character」在 manifest 仅单角色时置灰；桌面伴侣是独立应用，与 dsh plugin 安装通道无关。

项目链接

whale-girl 是 vlln 维护的 MIT 开源项目。 插件详情页：whale-girl 插件详情。

本页是基于该插件官方 README 独立重写的导读——权威文档和最新变更请以源头为准：vlln/whale-girl。插件是安装时就在你机器上运行的第三方代码；收录不代表背书——安装前请自行审阅源码。