vlln/whale-girl
1738Last commit Aug 15, 2026
whale-girl DSH plugin
whale-girl is a companion pet for the DSH Web GUI. It can be dragged, fed, and played with, and it reacts to task completions, session events, and idle periods. The pet accumulates experience and titles based on your activity, fostering a sense of companionship.
How to install the whale-girl DSH plugin
dsh plugin --profile web add "github:vlln/whale-girl#main" # 推荐：git 源一行（构建产物已入库Copying does not run this command. Review the repository and version before installing the whale-girl DSH plugin.
whale-girl DSH plugin data source
whale-girl DSH plugin snapshot date: Aug 16, 2026
discovered
What the whale-girl DSH plugin can do
- Drag the pet to move it around the screen
- Feed and play with the pet via a context menu, triggering eating and play animations
- Responds to task completion, errors, new sessions, approval waiting, and idle time with over 15 animations
- Accumulates experience levels, titles, and memories based on task completions, sessions, and active companionship duration
- Supports multiple characters that can be switched via menu or localStorage
- Configuration options for size, opacity, roaming, and sleep timeout, hot-reloadable without restart
Where the whale-girl DSH plugin fits
- Interact with the pet during breaks to relax and enjoy cute animations
- Receive visual feedback when tasks complete or fail, making progress more tangible
- Have a persistent companion that stays in the corner of the web interface, responding to your activity
- Use the pet as a motivation tool by watching it celebrate achievements and level up
Who the whale-girl DSH plugin is for
- DSH users who want a fun, interactive desktop pet within the web interface
- Developers or power users who appreciate a companion that responds to their workflow events
whale-girl DSH plugin limitations
- Only works in the DSH Web GUI (requires `dsh plugin --profile web` and a restart after installation)
- Depends on the DSH host environment and its settings configuration (whale-girl section in settings.yaml)
- The semantic layer (XP thresholds, title conditions) is not configurable; changing it would break achievement consistency
- The pet is hidden on initial onboarding; must be explicitly enabled via settings
whale-girl DSH plugin: from the repository README
Quoted from the vlln/whale-girl README, the upstream source of the whale-girl DSH plugin. Copyright remains with the original authors.
右下角悬浮的积累型伙伴：可拖拽、可投喂/玩耍，陪伴你的工作台脉搏—— 完成任务/会话/活跃陪伴时长积累成资历等级、称号与回忆。 </p> <p align="center"> <img src="https://badgen.net/badge/license/MIT/green" alt="license" /> <img src="https://badgen.net/badge/format/official%20bundle/8257D0" alt="official bundle" /> </p> --- ## 安装 官方 **bundle 插件** 格式（仓库根 `package.json` 的 `dsh.bundle` + `dsh.client`）。经官方 profile 管理： ```sh dsh plugin --profile web add "github:vlln/whale-girl#main" # 推荐：git 源一行（构建产物已入库） # 或本地目录：dsh plugin --profile web add <whale-girl 本地路径> ``` 装完 **重启 web**（bundle 层在启动时合成），右下角出现宠物：点击弹出菜单（🍗 喂食 / 🎾 玩耍），拖拽可移动；hover 显示状态条（资历等级/任务数/最近共同回忆）。初始配置/欢迎页（onboarding）宠物隐藏。 更新插件时 `dsh plugin --profile web update whale-girl`（或换 git 源 ref），重启生效。 ## 使用 | 你做什么 / 发生什么 | 宠物表现 | |---|---| | 拖拽宠物 | 被斜向拉扯（`drag`） | | 点击菜单 🍗 喂食 / 🎾 玩耍 | 啃咬/抛接球（`eat`/`play`）→ 开心（`joy`） | | 空闲 ≥60s | 打盹（`sleep`）；互动时醒过来（`wake`） | | 任务完成 / 升级 / 称号 / 回合完成 | 举手欢呼（`celebrate`） | | 任务失败 / 请求出错 | 惊吓（`error`）→ 失落（`disappointed`） | | 新会话开始 | 挥手欢迎（`welcome`） | | 任一会话运行/思考中 | 沉思陪伴（`think`，偶尔 `working` 工作姿态） | | 等待批准 | 期待等待（`wait`） | | 周期游走 | 散步（`walk`） | | 常态 | 待机（`idle`，随机眨眼/转身） | 完整状态机（优先级/转换语义/触发源）见 [docs/state-machine.md](docs/state-machine.md)。 ## 状态预览 | 状
Read the full READMERepository license: MIT
whale-girl DSH plugin questions
How do I install whale-girl as a DSH plugin?
Run `dsh plugin --profile web add "github:vlln/whale-girl#main"` in your terminal, then restart the web interface. Alternatively, you can clone the repo locally and use `dsh plugin --profile web add <local-path>`. After a restart, the pet will appear in the bottom-right corner.
How do I update whale-girl to a newer version?
Use `dsh plugin --profile web update whale-girl` to pull the latest version. If you're using a git source ref, you can change the ref in the command. After the update, restart the web interface for changes to take effect.
Can I change the pet's appearance?
Yes, you can switch between different characters using the menu button '🎭 换角色' or by setting localStorage key `whale-girl:character` to the desired character name. Each character provides all 15 state animations. You can also contribute new characters by following the guide in docs/adding-a-character.md.
How do I configure whale-girl settings?
Settings are managed through the DSH host's settings.yaml file under the `whale-girl:` section. For example, you can set `enabled: true`, `size: 110`, `opacity: 1`, and `walk.enabled: true`. Changes are hot-reloaded without restarting the web interface. You can also configure via the settings UI if available.
What should I do if the pet doesn't appear after installation?
First, ensure you have restarted the web interface after installation. Check that the plugin is enabled: in settings.yaml, set `whale-girl.enabled: true`. The pet is hidden on initial onboarding, so you must explicitly enable it. Also verify that the installation command was successful and that the plugin is listed with `dsh plugin --profile web list`.