在 DSH 网页右下角悬浮一只鲸鱼娘桌宠，陪伴任务/会话积累经验与回忆，可投喂、玩耍、拖拽。
- 语言
- JavaScript
- License
- MIT
- 分支
- main
安装
$ dsh plugin --profile web add github:vlln/whale-girl在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
对话式安装
帮我安装 DeepSeek Harness 插件 vlln/whale-girl：先查看仓库 https://github.com/vlln/whale-girl.git 确认安全性，然后执行安装命令并验证插件加载成功。
把这段指令粘贴给 DSH Web GUI 里的助手，由它代你完成安装与验证。
一句话定位
在 DSH Web GUI 右下角悬浮一只鲸鱼娘桌宠，陪伴你完成任务、开会话、积累资历和共同回忆。属于"QQ 宠物"形态的轻量陪伴型插件，靠积累而非养成压力驱动。
核心能力
- 浮窗渲染：在 DSH 网页右下角显示一只可拖拽的角色，支持点击交互菜单（喂食/玩耍/换角色）
- 状态机驱动：根据任务/会话/空闲等事件自动切换待机、打盹、欢迎、庆祝、惊吓、失落、思考、等待、散步等 15 种状态动画
- 资历积累：完成任务 +10 XP、新会话 +5 XP、活跃陪伴时长累加，零负反馈（失败只计数不扣分）
- 称号与回忆：达到里程碑自动解锁称号，累计你和它的共同事件写进回忆录
- 体验层热配：宠物尺寸、透明度、游走间隔、闲置多久打盹、互动回话文案等通过 settings.yaml 修改后免重启生效
- 多角色切换：内置多个角色素材（每个角色必须提供全部 15 状态），菜单可循环切换或写入 localStorage 持久选择
技术实现
- 语言: JavaScript (Node half) + ES Modules；client bundle 由 esbuild 打包
- 关键依赖: schemastery（配置 schema）、esbuild（构建 client bundle）；无其它运行时第三方依赖
- 架构模式: 官方 bundle 插件格式——仓库根 package.json 声明
dsh.bundle.patch+dsh.client.platform=web；Node half 是完整 Cordis 插件（依赖jobs/agents/sessions/settings/webServer），client 经__ModuleLoader__内核挂载 - 入口文件:
lib/index.mjs（Node half）+lib/client/index.mjs（client 源；产物lib/client.js由scripts/build-client.mjs生成）
适用场景
长时间使用 DSH 跑任务或会话的人，希望工位上有个会动的"伙伴"缓解单调。宠物对任务/会话事件有真实反馈（完成时庆祝、思考时陪伴、空闲时打盹），相比纯装饰挂件更能体现"一起工作"的氛围。也适合想体验 QQ 宠物怀旧感的用户，以及作为官方 bundle 插件开发范本来参考。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 未声明 | 官方 bundle 插件，未在 package.json 中声明 engines；需使用支持 bundle 格式的 DSH（profile web 管理） |
| Node | 未声明 | 源码使用 ES Modules 与顶层 await；运行时由宿主提供 |
| 平台 | 跨平台 | Node half 跨平台；assets 路径净化已处理 Windows 反斜杠穿越 |
| 原生模块 | 无 | 仅 schemastery 纯 JS 依赖，不引入 native binding |
安装方式
dsh plugin --profile web add github:vlln/whale-girl
配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
enabled | 布尔 | 网页端宠物渲染总开关；桌面伴侣运行时建议设为 false 避免双宠物 | true |
size | 数字 (64–160) | 宠物显示尺寸（像素） | 110 |
opacity | 数字 (0.2–1) | 常态透明度（交互时另有 0.25 的临时低透明度，不在此配） | 1 |
walk.enabled | 布尔 | 是否允许宠物周期性自动游走 | true |
walk.minWaitMs / maxWaitMs | 数字 (0–300000) | 两次游走之间的随机等待上下限（毫秒） | 18000 / 40000 |
walk.minMs / maxMs | 数字 (0–60000) | 单次游走持续时间上下限（毫秒） | 3000 / 6000 |
walk.speedPxPerSec | 数字 (10–300) | 游走速度（像素/秒） | 45 |
sleepAfterMs | 数字 (5000–600000) | 空闲多久后进入打盹状态（毫秒） | 60000 |
pollMs | 数字 (1000–30000) | 状态轮询间隔（毫秒） | 3000 |
bubbleMs | 数字 (500–10000) | 互动时回话气泡显示时长（毫秒） | 2500 |
welcomeMs / celebrateMs | 数字 (0–30000) | 欢迎/庆祝状态窗口时长（毫秒） | 6000 / 6000 |
errorMs / disappointedMs | 数字 (0–15000) | 惊吓/失落状态窗口时长（毫秒） | 4000 / 6000 |
replies.feed / replies.play | 字符串数组 | 喂食/玩耍时回话文案池（可追加自定义） | 内置各 3 句 |
语义层（XP 阈值/等级曲线/称号集合/回忆上限）不在 schema 中，禁止在配置里覆盖。
常见问题
Q: 装完为什么没看到宠物？
A: bundle 插件是在 DSH 启动时合成的，所以装完需要重启 DSH Web；首次安装还会进入 onboarding 引导页，期间宠物默认隐藏，完成引导后才会出现。
Q: 能和桌面伴侣同时跑吗？
A: 可以。运行 desktop/ 下的桌面伴侣时，网页端宠物会通过 presence 心跳自动隐藏（伴侣退出或崩溃 45 秒 TTL 过期后恢复）。如果不想双端同显，在 settings.yaml 的 whale-girl.enabled 设为 false 关闭网页端即可。
Q: 资历/称号/等级曲线能自己调吗？
A: 不能。这些是代码级封闭的语义层常量（XP 公式 50·L·(L−1)/2、称号集合、回忆上限等），schema 故意不暴露，由门禁守护配置面不可引用——只允许调整上面那张体验层表格里的视觉/时序参数。
Q: 数据存哪里？卸载会丢吗？
A: 状态文件写在 <DSH_HOME>/data/whale-girl/state.json，不在插件目录里，所以卸载插件不会删除资历和回忆，重装后继续累计。
Q: 更新后没生效怎么办？
A: 多数改动（配置面、client 行为）需要刷新页面或重启 DSH Web 才生效；Node half 改源码后必须重启 web，因为 ESM 同 URL 二次 import 会返回旧模块。
Q: 怎么加自定义角色？
A: 按 docs/adding-a-character.md 与 docs/sprites-spec.md 的素材全量契约提供 15 个状态的 sprite sheet 和 manifest 条目；角色 id 限制 [a-z0-9-]（要进 URL 路径），本地跑 node scripts/gates/verify-assets.mjs 验收通过后随插件发布。
上手难度
入门 — 安装一条命令即可使用，所有体验层参数都有默认值；想自定义角色或参与开发再进入进阶层（需了解 schemastery、Cordis 插件结构与 sprite 素材规范）。
已知问题与限制
- bundle 格式首发后插件路径/导出名已不可重命名（公开 ref 被消费），改结构会破坏已安装环境
- 角色 id 仅允许
[a-z0-9-]字符（URL 路径注入防御），命名时需注意 - 桌面伴侣不在
dsh plugin安装范围内，需要在desktop/子目录自行npm install+ 启动 Tauri/headless 引擎 - Node half 改源码后 ESM 缓存导致 disable/enable 不生效，必须重启 DSH Web（
plugin tree failed to load是该问题的明显信号） - 配置修改虽支持热生效，但首次注入仍然依赖宿主启动时合成；改 schema 字段名/默认值后需重启才能让旧 settings 重新归一化
中文 | English
whale-girl
A desktop pet in the DSH Web GUI (QQ-pet style)
A persistent companion floating bottom-right: draggable, feedable, playable —
completed tasks, sessions, and companionship time accrue into seniority levels,
titles, and memories.
Installation
Official bundle plugin (dsh.bundle + dsh.client in root package.json), managed via the official profile:
dsh plugin --profile web add "github:vlln/whale-girl#main" # single-line git source (build artifacts committed)
# or npm source: dsh plugin --profile web add whale-girl@0.1.0
# or local directory: dsh plugin --profile web add <path-to-whale-girl>
Restart web after installing (bundle layers compose at startup); the pet appears bottom-right: click for its menu (🍗 feed / 🎾 play), drag to move, hover for the status bar (seniority level / task count / recent shared memories). Hidden on onboarding pages.
Update via dsh plugin --profile web update whale-girl (or switch the git ref), then restart.
Usage
| You / event | Pet behavior |
|---|---|
| Drag the pet | Stretched diagonally (drag) |
| Menu 🍗 feed / 🎾 play | Chomping / ball toss (eat/play) → joy (joy) |
| Idle ≥60s | Naps (sleep); wakes on interaction (wake) |
| Task done / level-up / title / round done | Cheers (celebrate) |
| Task failed / request error | Startled (error) → disappointed (disappointed) |
| New session | Waves welcome (welcome) |
| Session running / thinking | Pensive company (think, occasional working) |
| Awaiting approval | Expectant waiting (wait) |
| Periodic wandering | Walking (walk) |
| Default | Idle standby (idle, random blinks / turns) |
Full state machine (priorities / transitions / triggers): docs/state-machine.md.
Desktop Companion (Optional)
desktop/ is a standalone companion app (Node engine + Tauri shell, zero runtime deps) that keeps the whale girl resident on your OS desktop. Not installed via dsh plugin — enable it yourself:
# Prereqs: Node ≥18; the rendering shell needs Rust (cargo)
npm install -g whale-girl-desktop # npm install (engine + Tauri shell source included)
whale-girl-desktop --headless # headless: presence heartbeat + state polling + SSE
cd "$(npm root -g)/whale-girl-desktop/src-tauri" && cargo build --release # first build ~5-15 min; artifact target/release/whale-girl-desktop (~12MB)
./target/release/whale-girl-desktop # transparent always-on-top desktop pet (defaults to local DSH on 3080)
# WHALE_GIRL_BASE_URL=http://IP:PORT points at a non-local DSH
# or from source: cd desktop && npm install && cd src-tauri && cargo build --release
- Uses whale-girl's public endpoints (
/state,/events,/presence,/interact,/config,/assets) without touching the plugin; the in-page pet hides while it runs (presence contract) and returns after exit/crash (TTL 45s). - Shell: Tauri v2 (recommended, ~12MB); legacy Electron shell kept (
npm i -D electron). - Design & contracts:
desktop/DESIGN.md,desktop/BUILD-RUN.md.
State Preview
| State | Trigger | Preview |
|---|---|---|
idle | Default standby |  |
working | Random work spell while session thinks |  |
celebrate | Task done / level-up / title / round done |  |
error | Task failed / request error |  |
disappointed | Brief dejection after failure |  |
joy | Happy after feeding / playing |  |
eat | Click to feed |  |
play | Click to play |  |
drag | While dragging |  |
walk | Periodic wandering |  |
sleep | Idle ≥60s |  |
wake | Wake-up transition |  |
welcome | New session |  |
think | Company while session thinks |  |
wait | Awaiting approval |  |
Configuration
Edit the whale-girl: section in <dshHome>/settings.yaml (or the settings UI); changes apply live, no restart:
whale-girl:
enabled: true # web render toggle (false disables the in-page pet while a desktop companion runs)
size: 110 # pet size px (64–160)
opacity: 1 # default opacity (0.2–1)
walk:
enabled: true # wandering toggle
sleepAfterMs: 60000
Full option list and why the semantic layer (XP / titles) is sealed: lib/src/config.mjs. Not configurable (changing XP / title thresholds would break the accumulation ledger).
Characters
🎭 "Switch Character" cycles characters (or set whale-girl:character in localStorage); the button is greyed out when the manifest has a single character ("No other characters available"). Every character ships all 15 states (full contract: docs/sprites-spec.md); new characters: docs/adding-a-character.md.
Reference Implementation
whale-girl is a complete bundle plugin format exemplar (dsh.bundle + cordis.patch.yml + lib/, evolving with the official mechanism) — model new plugins on it:
- Structure:
lib/(entry / logic / client / assets) separate from docs, decisions, scripts — root AGENTS.md - Conventions: gates (
scripts/gates/run.mjs) + decision records + full asset contracts; guidance: plugin-registry's make-dsh-plugin skill, cookbook, gotchas
Contributing
Issues and suggestions welcome — your feedback shapes the pet's next steps:
- 🐛 Bug: file an issue with repro steps, browser & dsh versions; console errors for client issues
- 💡 Feature ideas: see docs/state-machine.md and docs/growth-system.md, describe the expected effect
- 🎨 New characters: docs/adding-a-character.md §quick guide — read-only contract, 15 sheets + manifest entries, validated by
verify-assets - 🔧 Code: every non-trivial change needs a decision record (
decisions/), gate self-checks, single-purpose commits (docs/AGENTS.md, root AGENTS.md)
Acknowledgements
Character by ZipZipPipe (the "Whale Girl" sticker character); sprites generated from their design.
License
MIT License
收录徽章
[](https://deepseek-plugin.org/plugins/vlln/whale-girl)把这段 markdown 粘贴到你的 GitHub README，链接回本插件详情页。徽章只声明已被本站收录，不代表安全认证。