whale-girl

dsh plugin --profile web add whale-girl

<p align="center">中文 | <a href="README.md">English</a></p>

<h1 align="center">whale-girl</h1>

<p align="center">

<strong>DSH Web GUI 内的桌面宠物（QQ 宠物形态）</strong><br/>

右下角悬浮的积累型伙伴：可拖拽、可投喂/玩耍，陪伴你的工作台脉搏——

完成任务/会话/活跃陪伴时长积累成资历等级、称号与回忆。

</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 管理：

dsh plugin --profile web add whale-girl                        # npm 源（构建产物随包发布）
# 想跟最新提交而不是发布版：dsh plugin --profile web add "github:vlln/whale-girl#main"
# 或本地目录：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)。

桌面伴侣（可选）

desktop/ 是独立桌面伴侣应用（Node 引擎 + Tauri 渲染壳，零运行时依赖），把鲸鱼娘渲染到操作系统桌面常驻。不随 dsh plugin 安装——想要桌宠的用户自行启用：

# 前置：Node ≥18；桌面渲染壳需 Rust 工具链（cargo）
npm install -g whale-girl-desktop   # npm 源安装（引擎 + Tauri 渲染壳源码随包分发）
whale-girl-desktop --headless       # 无窗模式可用：presence 心跳 + 状态轮询 + SSE
cd "$(npm root -g)/whale-girl-desktop/src-tauri" && cargo build --release  # 首次编译约 5-15 分钟；产物 target/release/whale-girl-desktop（约 12MB）
./target/release/whale-girl-desktop   # 启动透明置顶桌宠（默认连本机 DSH 3080）
# WHALE_GIRL_BASE_URL=http://IP:PORT 指向非本机 DSH
# 或从源码：cd desktop && npm install && cd src-tauri && cargo build --release

• 消费 whale-girl 既有公开端点（/state、/events、/presence、/interact、/config、/assets），不改动插件本体；运行期间网页端宠物自动隐藏（presence 契约），退出或崩溃（TTL 45s 过期）后恢复。
• 渲染壳：Tauri v2（推荐，体积 ~12MB）；Electron 遗留壳保留（npm i -D electron 后可用）。
• 设计与契约见 desktop/DESIGN.md、desktop/BUILD-RUN.md。

状态预览

状态 · 触发 · 预览

idle · 常态待机 · 

working · 会话思考期随机工作插曲 · 

celebrate · 任务完成/升级/称号/回合完成 · 

error · 任务失败/请求出错 · 

disappointed · 失败后短时失落 · 

joy · 投喂/玩耍后开心 · 

eat · 点击投喂 · 

play · 点击玩耍 · 

drag · 拖拽中 · 

walk · 周期游走 · 

sleep · 空闲 ≥60s · 

wake · 睡醒过渡 · 

welcome · 新会话 · 

think · 会话思考陪伴 · 

wait · 等待批准 · 

配置

插件 → 已安装 → whale-girl 包页（配置卡片）：高频子集——网页端显示、会话记忆、尺寸、透明度、游走、睡眠等待，以及投喂/玩耍回话文案池（每行一条）。会话记忆默认关闭：开启后宠物把任务完成等里程碑写进本机 data/whale-girl/sessions.json（几字节/条），会话恢复或分支（fork）时沿会话血缘读回、重逢时说一句上次完成了什么——只写本机文件，不进模型上下文、不上传网络；关闭即停止读写（文件保留，可自行删除）。改动即时生效、免重启（开关点击即写；数字与文案池失焦或回车即写）。

卡片首行是更新行：挂载时自动查一次上游（git 安装按提交、registry 安装按版本），状态行给出结论与当前短提交，有新版时按钮变成「更新到 <版本/提交>…」；更新经 DSH 的 profile 包管理服务重装，不碰你的设置。完整契约（端点、载荷、两步重装、失败原因、宿主版本要求）见 [docs/update-row.md](docs/update-row.md)。

全量与高级项（如各窗口时长）在 profile patch 的条目 config:（<dshHome>/profiles/<profile>/cordis.patch.yml）；<dshHome>/settings.yaml 的 whale-girl: section 会被一次性导入该条目：

whale-girl:
  enabled: true      # 网页端渲染开关（与桌面伴侣并存时设 false 关闭网页端宠物，避免双宠物）
  sessionMemory: false # 会话记忆（本机 sessions.json 记录 + 血缘回读；默认关，见配置卡片说明）
  size: 110          # 宠物尺寸 px（64–160）
  opacity: 1         # 常态透明度（0.2–1）
  walk:
    enabled: true    # 游走开关
  sleepAfterMs: 60000

完整配置项清单与语义层（XP/称号）封闭说明见 lib/src/config.mjs。语义层不可配（改 XP/称号阈值会破坏积累账本一致性）。

角色

菜单「🎭 换角色」循环切换角色（或设置 localStorage whale-girl:character）；manifest 仅 1 个角色时按钮置灰（悬停提示「暂无其他角色」）。每个角色提供全部 15 状态素材（素材全量契约，见 [docs/sprites-spec.md](docs/sprites-spec.md)）；贡献新角色指南见 [docs/adding-a-character.md](docs/adding-a-character.md)。

作为参考实现

whale-girl 是官方 bundle 插件格式的完整范本（dsh.bundle + cordis.patch.yml + lib/ 布局，随官方机制演进）——开发新插件可对照：

• 结构：lib/（入口/纯逻辑/client/素材）与 docs/decisions/scripts 分离，见根 [AGENTS.md](AGENTS.md)
• 规范：门禁（scripts/gates/run.mjs）+ 决策记录 + 素材全量契约；开发引导见 plugin-registry 的 make-dsh-plugin skill 与 cookbook，踩过的坑见 gotchas

贡献

欢迎提交 issue 和建议——你的反馈直接决定宠物的下一步：

• 🐛 遇到问题：提交 issue，附复现步骤、浏览器与 dsh 版本；客户端问题附控制台报错更佳
• 💡 功能建议：参考 [docs/state-machine.md](docs/state-machine.md) 与 [docs/growth-system.md](docs/growth-system.md) 了解现状，说明期待效果
• 🎨 新角色：见 [docs/adding-a-character.md](docs/adding-a-character.md) §贡献角色速览——只读契约，产出 15 张 sheet + manifest 条目，本地 verify-assets 验收
• 🔧 代码贡献：每个非平凡改动带决策记录（decisions/）、门禁自证、单一性质提交（见 [docs/AGENTS.md](docs/AGENTS.md) 与根 [AGENTS.md](AGENTS.md)）

致谢

角色形象由 ZipZipPipe 创作（《鲸鱼娘》表情包角色），sprites 基于其角色设定生成。

License

MIT License