前言¶

长时间盯着 DeepSeek Harness（DSH）的 Web 界面写代码、跑 Agent，界面再专业也容易显得冷清：任务在后台推进，进度条在走，但屏幕上缺少一个能回应你操作的「在场感」。早年 QQ 宠物靠右下角的小精灵陪伴桌面，whale-girl 把类似体验搬进了 DSH Web GUI——一只可拖拽、可投喂、可玩耍的鲸鱼娘，悬浮在页面右下角，还会根据任务成败、会话状态和你是否空闲切换表情与动作。

whale-girl 由社区开发者 vlln 维护，在 SkillHub 插件库归类为「趣味换装」，GitHub 仓库截至核实日约有 281 stars。本文依据 SkillHub 目录页、deepseek-harness-plugin.com 详情页 与 GitHub README.zh.md 交叉核实后整理：它是什么、核心能力、如何安装，以及使用时需要注意什么。

这是什么¶

whale-girl 是一款面向 DSH Web GUI 的桌面宠物（桌宠）插件，形态参考 QQ 宠物：角色常驻页面右下角，可拖动位置，点击弹出菜单进行喂食（🍗）或玩耍（🎾）。它不是换肤插件，而是带交互与成长逻辑的「积累型伙伴」——完成任务、开启会话、陪伴时长会累积成资历等级、称号与共同回忆，hover 状态条可查看等级、任务数与近期记忆摘要。

技术上，whale-girl 采用官方 bundle 插件格式（根目录 package.json 声明 dsh.bundle + dsh.client，配合 cordis.patch.yml），仓库 README 将其定位为 bundle 机制的完整参考实现。许可证为 MIT；角色形象来自 B 站 UP 主 ZipZipPipe 的「鲸鱼娘」贴纸设计。

需要说明的是：DeepSeek Harness 的核心理念是「一切皆插件」，社区目录（如 SkillHub、deepseek-harness-plugin.com）由社区独立维护，与 DeepSeek / 幻方无官方从属关系。whale-girl 是社区精选插件，安装前仍建议自行审阅源码。

核心功能与亮点¶

十五态状态机，跟工作台脉搏联动¶

宠物内置完整状态机，共 15 种状态，覆盖待机、工作、庆祝、惊吓、投喂、玩耍、散步、睡眠等场景。部分典型映射如下：

完整优先级、转换语义与触发源见仓库 docs/state-machine.md；成长体系（XP、称号阈值）见 docs/growth-system.md。README 明确：XP / 称号等语义层不可通过配置修改，以免破坏积累账本一致性。

积累型陪伴：等级、称号与回忆¶

与纯装饰 GIF 不同，whale-girl 把「一起干活」写进数据：任务完成、会话活跃、陪伴时长会推动资历升级并解锁称号，状态条展示等级、任务计数与最近共同回忆。长时间使用 DSH 的开发者，会明显感知到「这只宠物记得你做过什么」——而不是每次刷新都回到同一张静态图。

可选桌面伴侣：跳出浏览器窗口¶

除网页内宠物外，仓库 desktop/ 提供独立桌面伴侣应用（Node 引擎 + Tauri 渲染壳，体积约 12MB）。它不通过 dsh plugin 安装，需自行执行 npm install -g whale-girl-desktop 并从 Tauri 源码编译壳层。桌面端通过公开端点（/state、/events、/presence 等）与 DSH 通信，运行期间网页端宠物按 presence 契约自动隐藏，退出或崩溃（TTL 45 秒）后恢复。适合希望宠物常驻操作系统桌面、而非仅嵌在浏览器里的用户。

bundle 插件范本¶

对打算开发 DSH 插件的读者，whale-girl 的价值不止于「好玩」：lib/（入口 / 逻辑 / client / 素材）与 docs、decisions、scripts 分层清晰，配套门禁脚本 scripts/gates/run.mjs 与素材全量契约（docs/sprites-spec.md）。vlln 的 plugin-registry 还提供 make-dsh-plugin skill 与 cookbook，可与本仓库对照学习。

安装与启用¶

whale-girl 面向 web profile。社区目录页给出的通用安装命令为：

dsh plugin add github:vlln/whale-girl

仓库 README 针对 web 场景的写法更明确（git 源一行，构建产物已入库）：

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

也可使用 npm 源或本地目录：

# npm 源
dsh plugin --profile web add whale-girl@0.1.0

# 本地目录
dsh plugin --profile web add <whale-girl 本地路径>

如需可复现安装，可固定 commit 哈希，例如目录页建议的 dsh plugin add github:vlln/whale-girl#commit。

装完后必须重启 web（bundle 层在启动时合成）。重启后右下角出现宠物：点击弹出菜单，拖拽可移动；鼠标悬停显示状态条。初始配置页 / onboarding 场景下宠物会隐藏，避免干扰首次引导。

更新插件：

dsh plugin --profile web update whale-girl

或更换 git ref 后再次重启 web。

典型用法示例¶

网页内日常交互¶

1. 打开 DSH Web GUI，确认 whale-girl 已安装且 web 已重启。
2. 右下角点击宠物，选择 🍗 喂食或 🎾 玩耍，观察 eat/play → joy 动画链。
3. 拖拽宠物到不挡代码的位置；空闲一分钟后它会 sleep，再点击即可 wake。
4. 正常跑 Agent：新会话触发 welcome，思考期陪伴 think，任务成功 celebrate，失败则 error → disappointed。

热更新配置（无需重启）¶

在 <dshHome>/settings.yaml 的 whale-girl: 段或设置 UI 中调整，修改后即时生效：

whale-girl:
  enabled: true      # 网页端开关；与桌面伴侣并存时可设 false 避免双宠物
  size: 110          # 尺寸 px，范围 64–160
  opacity: 1         # 透明度 0.2–1
  walk:
    enabled: true    # 是否允许周期游走
  sleepAfterMs: 60000

换角色（多角色 manifest 时）¶

菜单「🎭 换角色」可循环切换；也可设置 localStorage 键 whale-girl:character。若 manifest 仅含一个角色，按钮会置灰并提示「暂无其他角色」。贡献新角色需按 docs/adding-a-character.md 产出 15 张状态 sheet 并通过 verify-assets 验收。

适用场景与注意事项¶

适合谁：

• 长期在 DSH Web GUI 里写代码、审 diff、盯 Agent 的开发者，希望界面多一点轻松陪伴感。
• 想学习官方 bundle 插件结构、client 注入与状态机设计的插件作者。
• 喜欢 QQ 宠物 / 桌面宠物文化，又不愿离开 DSH 工作流的用户。

注意事项：

1. 权限与安全：插件以当前 dsh 进程权限运行，安装过程可能执行代码。安装前请阅读 GitHub 仓库 源码与 MIT 许可证；生产环境建议固定 commit。
2. 仅 Web GUI：核心体验绑定 web profile；TUI 或纯 CLI 场景不会自动出现这只宠物。
3. 重启 web：bundle 插件装完必须重启 web，否则看不到右下角角色。
4. 桌面伴侣是可选分支：whale-girl-desktop 需 Node ≥18 与 Rust（cargo），首次 Tauri 编译可能耗时 5–15 分钟，与 dsh plugin 安装路径无关。
5. 星标与分类：GitHub 星标会变动（核实日约 281）；SkillHub 归类「趣味换装」，deepseek-harness-plugin.com 目录页标注「主题与外观」——二者均为社区目录标签，以功能描述为准即可。

结尾¶

whale-girl 把 QQ 宠物式的右下角陪伴感带进了 DeepSeek Harness Web 界面：能拖、能喂、能玩，还能跟任务与会话状态同频呼吸。对日常泡在前端的 DSH 用户，它是一剂轻量但持久的「界面温度调节器」；对插件开发者，它更是 bundle 格式与 client 状态机的一份活教材。

• SkillHub 目录页：https://www.skillhub.cn/plugins/vlln/whale-girl
• 社区目录详情：https://deepseek-harness-plugin.com/zh-CN/plugins/whale-girl/
• GitHub 仓库：https://github.com/vlln/whale-girl