nzl153/dsh-pet-whale

pet-whale · 桌宠小鲸鱼 🐳

DeepSeek Harness（DSH）Web 界面的桌宠插件：右下角一只官方轮廓版小鲸鱼，随 agent 状态实时切换动画。纯 DOM 实现、零 React 依赖、零运行时第三方依赖，WebAudio 合成音效无音频文件。

空闲 → 思考·深潜 → 工作·敲代码 → 完成·冒泡 → 报错，对话气泡随状态变化

在线预览

无需安装，点开即玩（全部状态与交互，官方轮廓版）：

👉 ****

仓库内的 preview.html 即预览页源码，本地直接打开同样可以体验。

特性

| 能力 | 说明 |
|---|---|
| 状态机 | idle / think（深潜）/ working（游动 + 敲键盘 + 代码粒子）/ celebrate（跃起冒泡）/ error（发抖 + 尴尬黑线）/ disappointed（报错后短暂失落）/ wait（等待你的输入）；优先级 error > celebrate > think > working > idle |
| 回合语义 | 回合进行中永不发呆：有工具 = working，无工具（文字流或内部推理）= think 深潜；工具密集期键盘动画粘滞 2.5s |
| 交互 | 单击戳戳、双击 360° 翻滚、拖拽时眼睛变成动漫勾勾眼（>_=0.1.5-alpha.2 =24.0.0。

| DSH 版本 | 状态 | 依据 |
|---|---|---|
| 0.1.5-rc.2 | compatible | 真机跑过：新建会话 / 工具调用 / 纯文字回合，控制台 0 报错，鲸鱼 idle→think→working→celebrate→idle 全部触发，且 celebrate 2.5 秒后自己回落到 idle（不需要下一条消息来顶） |
| 0.1.5-rc.1 | compatible | 未实跑。npm 包逐文件比对：本插件用到的 dsh-api-session-controller / dsh-client-ui-conversation / dsh-client-locale / dsh-client-modules / dsh-cordis-client-runner 与 rc.2 逐字节相同；dsh-client-ui-chat 只差一段 15 字符的 CSS（与本插件读的 legacy 投影无关） |
| 0.1.5-alpha.2 | compatible | 未实跑。同上，唯一差异是 dsh-cordis-client-runner 里一个文档字符串的行号（contract.ts:23 → :24） |

这台机器上原本跑的 1.1.0 在 0.1.5 下会在会话快照更新时抛
TypeError: Cannot read properties of undefined (reading 'length')，成因与改法见 src/client/state.ts 开头的字段对照。

本地目录安装（仓库已包含构建产物 lib/，无需先构建）
dsh plugin --profile web add link:/path/to/pet-whale

或 git 直装
dsh plugin --profile web add "github:/pet-whale#main"

装完重启 dsh web（host 半在启动时合成；只有 host 半的改动需要重启）。
Client 半的开发改动不需要重启、不需要硬刷新：见下方「开发 / Hot Reload」。

构建与测试

pnpm install
pnpm typecheck   # tsc 类型检查
pnpm dev           # 开发态 watch：改 src/client 自动重建 lib/client.js，DSH HMR 自动生效
pnpm build       # tsdown → lib/index.mjs + lib/client.js
pnpm test        # jsdom 冒烟测试（状态机 / 交互 / 换肤 / 清理）
pnpm verify:hmr    # 校验当前仓库 ↔ 运行中 DSH 的 HMR 链路一致

开发

- src/client/palettes.ts — 色板扩展点。加一行就是一个新皮肤；eye/pupil 字段用于深色皮肤的"眼睛反白"
- scripts/extract-whale.mjs — 从 preview.html 同步 V2 SVG（含 CSS 变量替换），改完模板重跑 pnpm extract
- scripts/verify-live.mjs — 重启后的一键线上验证（boot 清单 / bundle 下载 / 注册格式）
- 状态来源（dsh 0.1.5）：会话生命周期取自 ctx.sessions 的会话快照（running / lastAgentError / openError）；
partial / runningCalls / turnEnds 取自 ctx.uiConversation 的 chat 投影（ChatSnapshot.legacy）。
两处的字段对照和 0.1.5 的变更说明写在 src/client/state.ts 文件头。

Hot Reload

前提：DSH web profile 用 link: 方式安装本仓库（不是 GitHub/npm 的静态副本），且 DSH >=0.1.5-alpha.2。

pnpm dev

pnpm dev 会 watch 整个 src/ 并自动重建 lib/client.js（以及 host 半 lib/index.mjs）。
DSH 内置的 @deepseek-ai/dsh-client-hmr 会轮询到重建结果，通过 /plugins/events 广播，
浏览器自动 invalide 并 reload 该插件——client-only 改动不需要重启 DSH，也不需要刷新页面。

- 可热更新的范围：src/client/** 的 UI、样式、状态机、交互等 client 实现。
- 仍然必须重启 DSH 的范围：
- package.json 的 dsh.client / dsh.bundle / exports 结构变化
- cordis.patch.yml 或 host 半 src/index.mjs 的插件组合变化
- 安装 / 卸载依赖、升级 DSH、改动 profile bundles 列表
- 验证链路是否就绪：先确保 DSH 在跑，然后执行 pnpm verify:hmr。
- 常用脚本：
- pnpm dev / pnpm dev:client — 开发 watch（两者当前等价，dev:client 语义上只指 client 热更新目标）
- pnpm build — 提交前的一次性完整构建
- pnpm typecheck / pnpm test — 类型检查与冒烟测试

附：自用 UI 美化补丁（仅供参考）

patches/ 目录包含个人自用的 DSH 界面定制补丁，随仓库开源供参考，不是本插件的组成部分：

- 暖色纸感主题：类 Claude 风格暖调配色（陶土 #A3502C + 米白 #F7F2E6 + 暖墨 #2E2A24），亮暗两套，正文对比度 ≥4.5（WCAG AA）
- 鲸鱼发送 / 取消键：发送键 = 蓝色小鲸鱼，取消键 = 黑色小鲸鱼（与 favicon 一致），按钮 48px
- 针对 DSH rc.6 的特定构建产物编写，升级 DSH 后若锚点失效需人工核对更新

node patches/apply-patches.cjs

社区 fork

小鲸鱼本体以维护为主（见 CONTRIBUTING.md），想要更多玩法可以看看这些 fork：

- wzwei1990/dsh-pet-whale —— 多宠物架构（可在鲸鱼 / 小猫 / 灵儿之间切换，每只有独立的 SVG、动画与台词），附带 pnpm pet:doctor 体检脚本

这些 fork 独立维护，与本仓库无关，使用前请阅读各自仓库的说明。

声明
- 鲸鱼轮廓使用 DeepSeek 官方 FishLogo 路径（品牌素材，使用请注明出处）
- 交互设计思路参考 whale-girl（MIT）
- 主题配色灵感来自 Anthropic Claude 的暖色纸感风格

License

MIT