鲸鱼娘小宠物（Whale Pet）🐋

一个常驻在 DeepSeek Harness（DSH）页面右下角的对话小宠物：一只透明的鲸鱼娘， 会随「当前会话累计 token」平滑变胖，hover 显示 token 统计与账号余额，可以拖动， 自带喷水与浮动动画。

功能特性

特性	说明
形象	whale_pet.svg 透明矢量图（无方框、无白边），带柔和投影
胖瘦驱动	按当前会话累计 token 平滑缩放体型（log10 曲线，约 100 → 100 万 token 从 0 胖到 1）
双 token 统计	tooltip 显示「上次问答」token 与「当前会话累计」token
账号余额	通过 DeepSeek /user/balance 接口实时获取（带错误码诊断，可经 /whale-pet-diag-v2 自检）
喷水 + 浮动	三粒水滴循环喷出 + 上下浮动动画
可拖动	Pointer 事件 + setPointerCapture，拖动时限制在视口内
tooltip 自适应	变胖后 tooltip 自动上移与放大的头部保持 12px 间距；贴近视口顶部时翻转到下方避免被裁切

文件结构

whale-pet-plugin/
├── host.js           # Host 半区（动态 Cordis 插件函数体）：SVG 托管、token 统计、余额、get-state RPC
├── client.js         # Client 半区（动态 Cordis 插件函数体）：shell.overlay 槽位里的宠物 UI
├── whale_pet.svg     # 宠物形象资源
├── package.json      # 包元数据
└── README.md         # 本说明

运行方式（DSH 动态插件）

本插件以 DSH 动态 Cordis 插件形式运行（定义于会话内、随进程存续，重启后需重新定义）：

1. 把 host.js 的内容作为 code.host、client.js 的内容作为 code.client， 通过 cordis_define 定义（idPrefix 可任意，如 whal）；
2. 用 cordis_run 激活（首次运行需在页面批准）；
3. 宠物出现在页面右下角；刷新页面若旧实例残留，可在刷新后消失。

依赖

• Host 服务（可选读取，缺失时相应功能降级）：credentials、subprocess、 sessions、sessionProjections、sessionQuery、sandboxPolicy、fs、webServer； 事件 session/event；builtin harness、TextDecoder。
• Client builtin：React、styles、host；服务 slots（可选）、timer、sessions（硬依赖）。
• 槽位：shell.overlay（root 级，list 协议，id 需唯一，示例用 whale-pet-v2）。

配置点

• host.js 顶部 PET_SVG_PATH：宠物形象绝对路径（默认 C:\Users\29643\Desktop\myWork\harness_todo\whale_pet.svg），失败回退 policy.workspaceRoot + '/whale_pet.svg'；按你的环境修改。
• 图片 URL /whale-pet-v2.svg 与诊断路由 /whale-pet-diag-v2 使用 -v2 后缀， 避免与旧实例残留路由冲突。
• 余额读取依赖 DEEPSEEK_API_KEY 凭据；未配置时 tooltip 余额显示「获取失败(E3-cred-empty)」。

工作原理简述

• 胖瘦：fatness(tokens) = clamp((log10(1+tokens) − 2) / 4, 0, 1)； 体型 transform: scale(1 + 0.38f, 1 + 0.30f)，锚点 50% 100%（底部中心）。
• tooltip 修复：由于缩放锚点在底部中心，变胖时头部会向上撑高 (sy−1)×图片高； tooltip 上方锚点改为 bottom: calc(100% + 12px + 上移量)（上移量由 img.offsetHeight 实测得出），并给 bottom/top 加 0.5s 过渡；顶部翻转阈值同样计入上移量 （pos.top − lift < 170 时翻转到下方）。
• token 统计：当前会话累计读 sessionProjections 快照中的 tokenUsage； 上次问答从 session/event 的 assistant/chunk / assistant/message usage 事件按 turn 归集。

已知限制

• 动态插件定义不持久化：DSH 重启后需按上述步骤重新定义（或改为静态挂载方案）。
• host.call('get-state') 依赖动态 runner 提供的包私有 RPC（harness.handle）； 若改为静态挂载，需要自行替换为对应的 RPC 通道。
• 余额接口按 DeepSeek 官方 /user/balance 响应结构解析（balance_infos[0].total_balance）。

License

MIT