whale-girl

252Star15Fork3Issue0Watching

在 DSH 网页右下角悬浮一只鲸鱼娘桌宠，陪伴任务/会话积累经验与回忆，可投喂、玩耍、拖拽。

分类🐾 趣味与陪伴
vllnvlln
·vlln/whale-girl.git
语言
JavaScript
License
MIT
分支
main
deepseek-harnessdshdsh-plugindsh-repository-pluginpet

安装

$ dsh plugin --profile web add github:vlln/whale-girl

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

在 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 重新归一化
返回插件目录