前言¶

在 DeepSeek Harness（DSH）里跑智能体或长会话时，账户余额往往要另开页面或手动刷新才能看到。社区里已有类似「余额鲸鱼挂件」的思路；dsh-balance-whale 是维护者 CLxingxi 的独立实现：同一个 npm 包同时提供 Host 半（读余额、跟踪工作状态、记账、供图）与 Browser 半（挂件本体），通过 bundle 一行挂起，不必手写组件配置。

下面介绍它是什么、能做什么，以及如何装进 profile 并启用。

这是什么¶

插件包名 dsh-balance-whale，GitHub 仓库 CLxingxi/dsh-balance-whale，当前版本 1.0.0，MIT 许可证。要求 DSH >=0.2.0-rc.1。

挂件常驻 Web 界面右下角，实时展示 DeepSeek 账户余额；余额只由 Host 通过 ctx.deepseekAccount.getBalance() 读取，凭据不会进入页面。参考了 MeteorNOX/DeepSeek-Balance-Whale-Widget 的思路，本仓库是完整重写而非 fork。

核心功能¶

余额与状态¶

Host 暴露同源、仅回环的 HTTP 接口（10 秒短缓存，refresh=1 可绕过）：

Browser 半注册 shell.overlay 槽位，用里程表式数字滚动显示金额；空闲时按配置轮询，工作时 Host 会把轮询间隔缩短到不超过 8 秒。

表情与气泡¶

表情随工作状态自动切换：idle、working、happy、worried、excited、sleep、error 等。状态来自 Host 事件（如 api-session/status、tools/execute、agent/error）以及余额涨跌、拖动与点击。

气泡对开工、本轮消耗、余额变化、未登录、换皮肤等事件排队展示（最多 3 条）；安静时每 4–9 分钟可随机闲聊一句。

皮肤与音效¶

自带手绘 SVG 皮肤「深海经典鲸」，不依赖外部图片。立绘类皮肤需自行放入 assets/<id>/（skin.json + 各心情图），可用 tools/prepare-skins.py 裁切、居中并生成配置；选择结果存在 localStorage。

音效由 WebAudio 现场合成，无音频文件依赖；首次用户手势后解锁 AudioContext，卡片内可开关并记住偏好。

记账¶

每次 Host 真实读余额时与上次比较：减少记为消费，增加记为充值。消费计入「今天」「本轮启动」及刚结束的一轮（含 60 秒延迟窗口）。卡片展示今日已用、上一轮消耗、本次启动累计、近 7 天柱状图与最近几笔变化（可带工具名）。账本持久化在 $DSH_HOME/balance-whale/ledger.json，保留 60 天。

交互手感¶

支持拖拽吸附左右边缘（靠近底部贴底）、左吸附时水平镜像、QQ 弹式的呼吸与点击反馈、主题跟随 --dsw-alias-* token。键盘：Enter/空格 刷新，←/→ 换边吸附。

安装与启用¶

本包是 DSH bundle：cordis.patch.yml 插入一行 balance-whale，同时挂起 Host 与 Browser，无需手写组件列表。

1. 让 profile 依赖它。 编辑 ~/.dsh/profiles/<profile>/package.json（桌面端 profile 名一般为 desktop），在原有 dependencies 与 dsh.profile.bundles 中追加 dsh-balance-whale：

{
  "dependencies": {
    "dsh-balance-whale": "github:CLxingxi/dsh-balance-whale"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-balance-whale"]
    }
  }
}

2. 在 profile 目录安装依赖：

cd ~/.dsh/profiles/desktop
pnpm install

3. 重启 DSH，右下角会出现小鲸鱼。

本地开发时，可把依赖改为 "link:/绝对路径/dsh-balance-whale"，bundles 保持不变，改完重启生效。

可选配置¶

在 profile 的 bundle 条目上为 balance-whale 增加 config（省略则用默认值）：

- id: balance-whale
  name: 'dsh-balance-whale'
  config:
    size: 96            # 鲸鱼尺寸 px，64..160
    refreshSeconds: 30  # 空闲轮询秒数，10..600（工作时自动缩短到 ≤8 秒）

典型用法与自检¶

换皮肤： 点击挂件卡片中的「皮肤」展开选择器；自带「深海经典鲸」即可用。自定义立绘：将资源放进 assets/<skin-id>/ 后重启，或用：

python tools/prepare-skins.py --list
python tools/prepare-skins.py --check
python tools/prepare-skins.py --skin my-skin --name "我的皮肤" --accent "#FF8800" \
    --frame idle=raw/idle.png --frame happy=raw/happy.png

心情名包括 idle / happy / work / excited / worried / sleep / error，缺失帧回落到 idle。

不启动浏览器做冒烟测试（Node ≥ 18）：

node tools/balance-whale-smoke.mjs

脚本验证 Host 路由、账本数学、皮肤发现与交互模拟等；包目录不在默认位置时设置 BALANCE_WHALE_DIR=<包目录>。

适用场景与注意¶

适合长期在 DSH Web 界面工作、希望余额、消耗与 Agent 状态一眼可见的开发者。插件以当前 DSH 进程权限运行，安装前应阅读源码与 MIT 许可证；assets/ 下自行添加的立绘授权由你或原作者负责，不在 MIT 覆盖范围内。

DSH 生态强调「一切皆插件」；社区目录 skillhub 上的 dsh-balance-whale 页 为独立站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-balance-whale 把余额读取、记账与可拖拽挂件收进一个 bundle，装依赖、写 bundles、重启即可使用。详情与 Issue 见 GitHub 仓库，目录页见 skillhub.cn/plugins/CLxingxi/dsh-balance-whale。