它是什么
Whale Girl 是一只悬浮在 DSH Web GUI 右下角的 QQ 宠物式伙伴。你可以拖她、喂她（🍗）、陪她玩（🎾）；放着不管，她会自己走动、眨眼，最后趴着打盹。可爱表皮之下是真实的事件挂钩：一台由真实会话与任务事件驱动的 15 态精灵状态机，以及一本成长账——完成的任务、结束的会话与陪伴时长会累积成资历等级、头衔与回忆。
安装并重启 Web 应用后她就会出现在页面右下角（引导页按设计隐藏）。点开菜单可以喂食和玩耍，拖动移位，悬停能看到状态条：等级、任务计数和最近的共同回忆。
状态机
十五种状态及其触发条件，按 README 整理：
- 工作状态 ——
think（会话思考时安静陪伴，偶尔插入working工作模样）、wait（工具调用等待批准时期待地等待）。 - 结果状态 —— 任务完成、升级、获得新头衔或一轮结束时欢呼（
celebrate）；任务失败或请求出错时受惊（error），随后短暂低落（disappointed）。 - 会话状态 —— 新会话开启时挥手欢迎（
welcome）。 - 互动状态 —— 拖拽时的斜向拉伸（
drag）、菜单触发的吃（eat）与玩（play），之后接一段开心（joy）。 - 空闲循环 —— 周期性散步（
walk）、闲置 60 秒后入睡（sleep）、互动时醒来（wake），以及默认的待机（idle，随机眨眼与转身）。
完整的优先级与迁移表在仓库的 docs/state-machine.md 里。每个角色都配齐全部 15 种状态的精灵图——状态机是角色契约的一部分，不是单个皮肤自己的装饰。
成长系统，以及能配什么
成长层被刻意焊死：XP 与头衔阈值不可配置，README 说清了原因——改动它们会破坏累积账本的一致性。可调的部分在 设置 → 插件 → Whale Girl：是否在页面显示、大小（64–160 px，默认 110）、不透明度（0.2–1）、是否散步、入睡延时，以及喂食/玩耍的回复池（每行一条）。改动保存后即时生效，无需重启；更完整的选项在 settings.yaml 的 whale-girl: 一节。
「切换角色」按钮在多个角色间轮换（也可用 localStorage 的 whale-girl:character）；当清单里只有一个角色时，按钮会老实地变灰。README 还把这个仓库当作官方 bundle 插件格式（dsh.bundle + cordis.patch.yml + lib/）的参考实现来推荐——这里的「官方」指的是打包机制，不是官方背书。
可选的桌面伴侣
另外，desktop/ 目录是一个独立的 Tauri 应用——Node 引擎加 Tauri v2 外壳，构建产物约 12 MB——让鲸鱼女孩常驻操作系统桌面。它不通过 dsh plugin 安装：需要你自己从 npm 安装 whale-girl-desktop，且渲染外壳需要 Rust 工具链（首次 cargo build --release 约 5–15 分钟）。它通过插件的公开端点（/state、/events、/presence、/interact、/config、/assets）工作，不改动插件本身；presence 契约会在它运行时隐藏页内宠物，在它退出或崩溃后按 45 秒 TTL 恢复。默认连接本机 3080 端口的 DSH，WHALE_GIRL_BASE_URL 可指向其他地址。
运行要求
- 需要 DSH 的
webprofile；插件形态是 bundle 加web平台客户端，安装后必须重启 Web 应用——bundle 各层在启动时组装。 - 运行时依赖只有
schemastery一个；无安装期生命周期脚本。 - 任何地方都没有声明 harness 版本——连
engines字段都没有，也没有dsh.compatibility块，README 同样没给范围。这正是本条目验证等级为 L2 的原因：清单与 README 自洽，走的也是官方 profile 安装机制，但没有声明的范围可用来核对你的 harness 版本。请把兼容性当作未验证。 - 仅桌面伴侣需要：Node ≥ 18 与 Rust（cargo）用于构建外壳。
已知限制
- 美术素材的许可条款没有写明。 README 致谢了 B 站创作者 ZipZipPipe 的角色设计，并说明精灵图由其设计生成——但全部来源材料中都没有出现这些美术素材的许可条款。代码是 MIT；不要假定 MIT 授权覆盖角色美术，在取得创作者确认前不要再分发这些精灵图。
- 版本号是
0.1.0——文档再完整，这也是第一个发布版。 - 桌面伴侣是需要真实 Rust 构建成本的独立手动安装；它是一个伴生项目，不是插件功能。
- README 徽章行引用了第三方目录站（dshfind、dsh.so）。那是目录收录徽章，不是审计——本条目的评级仍是
security: unverified。 - 配置拆在两处（常用项在页内卡片，其余在
settings.yaml），而语义层被刻意焊死——想自己调 XP 曲线的话，这个插件按设计就是说「不」。
什么时候用它、什么时候不要用
喜欢 QQ 宠物那套陪伴感、又希望她的反应「有所指」时使用它：欢呼 / 出错 / 等待这些状态跟的是真实任务结果，成长账本让长期使用有了连续性。公开端点契约也是一条干净得难得的集成缝——想自己写个伴侣外壳的话可以直接用。
如果工作界面里常驻一只动画角色对你而言是干扰而非陪伴，如果未明确授权的角色美术在你的使用场景（比如公司电脑）里是个问题，或者你想要桌面常驻却不愿维护一个 Rust 构建的伴生应用，都请跳过它。
安装
从 npm 安装：
dsh plugin --profile web add whale-girl@0.1.0README 的首选路径是携带已提交构建产物的 git 源——dsh plugin --profile web add "github:vlln/whale-girl#main"。无论走哪条路，装完都要重启 Web 应用，页面刷新后她就会出现在右下角。