宠物鲸鱼插件 ericzzhou/dsh-deep-whale

🐳 深潜小鲸 · Deep Whale

English: README.en.md

一只住在 DeepSeek Harness 里的宠物鲸鱼插件：在 Web GUI 里满屏巡游、会困倦/兴奋、吃工具调用为生、随机释放炫酷技能、偶尔来一发「鲸跃砸浪」，还能潜水捞珍珠占卜——模型也能通过动态工具 whale_talk 跟它互动。

本项目由 DeepSeek Harness 的动态 Cordis 插件能力驱动：Host 半部分跑在 Node 进程，Client 半部分跑在浏览器，通过 package-private RPC 通信。

✨ 功能一览

| 能力 | 说明 |
| 🌊 双向巡游 | 屏幕内波浪路径（三频正弦 ±22% 屏高）+ 平滑俯仰 + 边缘可见翻身，永不倒游 |
| 🎭 心情系统 | napping（打盹，5min 无活动）→ swimming（巡航）→ excited（30s 内有工具调用）→ happy（被投喂/摸摸） |
| 🦠 浮游生物 | 每次工具调用 = 喂它一口，按会话隔离计数 |
| ⚔️ 技能系统 | 刀光剑影 / 冲击波环 / 落雷 / 星芒散射 / 王霸之气光环——清醒 8~17s 一发，打盹也会放"梦游魔法" |
| 💥 鲸跃砸浪 | 终极技：下潜蓄力 → 冲天跃起 → 俯冲砸下 → 14 颗水珠 + 巨浪环 |
| 🌀 杂技 | 360° 筋斗、喷水柱、翻身掉头 |
| 🦪 珍珠占卜 | 根据最近工具类型（命令/文件/网络/子任务/导入）吐出对应的鲸语预言；带问题则走"神谕"池 |
| 🫧 实时反馈 | 状态 1s 轮询 + 客户端本地推演心情 + 组件总线；dock 条实时显示 💦喷水 / 🌀打滚 / 💥鲸跃 / ↪️翻身 |
| 🛡️ 不挡操作 | 全屏动画层 pointer-events: none，z-index 交给插槽（不盖住左侧面板），可正常点击任何 UI |

🧩 架构

┌─────────────────────────── 浏览器 (Client) ───────────────────────────┐ │ conversation.composer.dock ← 状态药丸（投喂/摸摸/鲸跃按钮） │ │ shell.overlay ← 全屏巡游鲸鱼动画层（点击穿透） │ │ │ host.call('whale/state' | 'feed' | 'pet' | 'dive' | 'leap') │ └────────┼──────────────────────────────────────────────────────────────┘ ▼ package-private JSON RPC ┌──────────────────────────── Node (Host) ─────────────────────────────┐ │ ctx.on('tools/result') ← 工具调用 → 浮游生物 + 活动窗口 │ │ harness.handle ×5 ← state / feed / pet / dive / leap │ │ harness.defineTool + registerTool ← 动态模型工具 whale_talk │ └───────────────────────────────────────────────────────────────────────┘

插槽（Slots）
- conversation.composer.dock（id whale-band）：输入栏底部的小鲸状态药丸
- shell.overlay（id whale-swimmer）：全屏巡游层，新增 id 不顶替任何现有层

动态工具 whale_talk 模型可调用的工具，动作：chat / feed / pet / dive（可附 question 占卜）/ leap（客户端 1 秒内表演鲸跃砸浪）。

🚀 安装 / 运行

方式一：动态定义（推荐体验）在 DSH 会话里使用 cordis_define 工具：

- code.host → 粘贴 src/host.js 中 return { apply(ctx) {...} } 的整段主体
- code.client → 粘贴 src/client.js 中 return { inject: ['timer'], apply(ctx) {...} } 的整段主体

然后 cordis_run 激活，浏览器侧授权即可。每次 DSH 进程重启后需重新定义（动态插件的正常生命周期）。

方式二：作为常规包挂载把本仓库克隆到你的部署环境，按 DSH 的 host 组合（cordis.yml）挂载该插件行；Host 入口 src/host.js，Client 入口 src/client.js。

⚙️ 可调参数（均在 src/client.js）

| 常量 | 默认 | 说明 |
| DURATIONS | excited 11s / happy 18s / swimming 32s / napping 80s | 每种心情横向游完全程的耗时（泳速） |
| 技能间隔 | 清醒 8.5~17.5s，兴奋 6~13s，打盹 16~30s | 首次技能在挂载后 3.5~8.5s 内必发 |
| 鲸跃间隔 | 巡航 22~38s，兴奋 15~28s，打盹 30~45s | 屏幕中段才触发，保证可见 |
| LEFT_EDGE / rightEdge | 50px / vw-60px | 掉头点（屏幕内，翻身全程可见） |
| 心情阈值 | 30s / 5min | 活动窗口 → excited / napping |

📜 版本故事

一路从"输入栏贴纸"迭代到"满屏巡游的战斗鲸"（16 个动态包版本）：

1. pkg-1~3：动态工具 schema 的两条硬规则（值 schema DSL 不支持 required、object 必须显式 additionalProperties）
2. pkg-4：修复 render 吞掉珍珠字段
3. pkg-5：全屏巡游（shell.overlay）
4. pkg-6：光标避让（后被移除——手感像"粘鼠标"）
5. pkg-7：偶发喷水 + 实时状态
6. pkg-8：双向游动 + 朝向跟随 + 平滑俯仰（修倒游/生硬）
7. pkg-9：移除光标避让，恢复自由巡游
8. pkg-10：更浪的泳姿（三频大波浪 + 360° 筋斗）
9. pkg-11：技能系统（刀光/冲击波/落雷/星芒/光环）
10. pkg-12：终极技「鲸跃砸浪」
11. pkg-13：按需鲸跃指令（whale_talk leap + dock 按钮）
12. pkg-14：修「麻瓜鱼」——打盹也能施法，频率翻倍
13. pkg-15：掉头点移回屏幕内（修"在屏幕外掉头"）
14. pkg-16：修 z-index 9999 盖住左侧插件面板

🧪 技术要点

- Client 运动循环用 ref 直改 DOM style（25fps），不触发 React 重渲染
- 心情切换时按当前位置重锚定时间轴，位置不跳变
- 翻身用半滚转动画（保持镜像旋转 180°，切换瞬间无跳变）
- 技能/水花用 React key 重挂载 + CSS 一次性动画（forwards 淡出）
- 状态轮询 1s + 客户端本地推演心情 + 组件内轻量 live bus（只 diff mood/phase）

📄 License

MIT © 2025 ericzzhou