Balance Whale Widget

它是什么

DSH Web 界面右下角的一个常驻挂件：一只小鲸鱼娘，气泡里显示你的 DeepSeek 账户余额、今日已用，以及刚刚结束那一轮对话的花费。它自己维护一本本地账本，余额或当日预算跌破你设的阈值时给提醒，一轮回复结束时还能播放音效。

最容易误读的地方在于它不是什么：它不是会话功能。它往服务端渲染的页面里注入一个 <script defer src="/dsh-whale/widget.js"> 标签，并订阅 session/event 读取 token 数。它不注册任何工具、斜杠命令、Cordis 服务，也不碰记忆；来源里没有任何一处会改动模型、提示词或对话本身。README 把记账称作「小鲸鱼记账」——那是它自己的一本账，不是对 DSH 运行方式或计费方式的改动。

余额到底从哪来

它直接调官方接口，你的密钥不会流向别处。 宿主侧声明了 BALANCE_URL = 'https://api.deepseek.com/user/balance'，只对这个地址发一次 fetch，带 Authorization: 'Bearer ' + cred.value 和 AbortSignal.timeout(20000)。中间没有中转服务，也没有作者自建的代理；README 写的是同一个接口，并列出它唯一需要的那个凭据。

密钥从 DSH 自己的凭据服务读取，即 ctx.credentials.resolve('DEEPSEEK_API_KEY')，再作为 bearer token 发出去。没有配置凭据时，路由返回 { ok: false, code: 'NO_KEY' } 和「未配置 DEEPSEEK_API_KEY」，而不是静默失败。你自己添加其他厂商的密钥走 ctx.credentials.set(...)，注册表上方的注释明确写着该文件不存明文密钥——只存凭据名（例如 OPENROUTER_API_KEY）。

出网流量有两点可核对。前端那一半从不调用 api.deepseek.com，它请求本地的 /dsh-whale/balance.json，由宿主发出那唯一一次外部请求。另外，在两个随包发布的源码文件里搜 telemetry、analytics、sentry、posthog、mixpanel、umami、gtag、matomo 这类分析域名，结果为空——文件里出现的每一个 URL 要么是本地路由前缀，要么是模型厂商的 API 地址，要么是厂商的文档或充值页。来源中没有隐私声明，所以请把代码当作证据，而不是把「没有声明」当作安全承诺。

两条数字管道，只有一条是远端的

• 余额是唯一真正的远端读取。服务端缓存 25 秒（BALANCE_TTL_MS = 25000），前端每 60 秒刷新一次（REFRESH_MS = 60000），点一下鲸鱼也能手动刷新。README 说，遇到瞬时网络抖动时会沿用最近一次余额，而不是报错。
• 今日已用是推算出来的。README 明确写它不需要任何令牌：插件拿观测到的余额与当天基准做差，把下降额记入账本；一轮的花费则按 harness 为该轮真实上报的 token 用量（inputTokens / cacheReadTokens / outputTokens / reasoningTokens）换算。价目表在 lib/index.js 顶部（PRICING / BASE_PRICE / PRO_PRICE），分峰谷两列，注释里标了官方定价页，还有带日期的复核记录。README 说内置的 DeepSeek 一项不能自定义单价，始终用这张表。

所以气泡里的余额是一次接口读取，而「今日已用」和「本轮花费」是对观测差值与上报 token 的本地算术。这就是测量与估算的分界，来源本身也让两者保持分开。

自定义厂商，以及 Codex 作为数据源

后续版本远远超出了内置的那一次余额读取：README 记录了 33 个厂商模板。其中一部分确实能查到余额或额度——OpenRouter、Kimi / Moonshot（大陆站与国际站）、阶跃星辰 StepFun、Novita、智谱 GLM Coding Plan、Kimi Coding、MiniMax Coding，以及 OneAPI / New API 中转站。其余那些，包括 OpenAI、Anthropic、Gemini、xAI、Groq、硅基流动、火山方舟、阿里云百炼和本地模型，被标为「（无余额接口）」，因为这些厂商没有公开的、用 API key 查余额的接口。这些模板会改用 probeUrl 探活验证 key，余额显示「—」，今日已用按会话事件估算。README 还引用了厂商的更新公告，记录硅基流动的余额接口已于 2026-08-14 下线。

Codex 模式自带一条警告：它只读本机 Codex 会话日志 $CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl，不联网也不需要密钥；README 明确这是部分接口适配，并且这个挂件不能安装进 Codex 里。

它往磁盘写什么

README 以表格列出运行时数据文件，都放在 $DSH_HOME（默认 ~/.dsh）；源码用 path.join(DSH_HOME, ...) 拼出同样的文件名：外观与开关在 .dshw-size.json，账本与用量设置在 .dshw-usage.json，自定义泡泡在 .dshw-bubble.json，厂商注册表在 .dshw-api.json，账本归档在 .dshw-usage-archive.json，Codex 缓存在 .dshw-codex.json，还有一个单调递增的 seq 放在 .dshw-turn.json，避免热重载后前端把新轮次当成旧轮次。上传的角色图、音频片段和泡泡图分别进 whale-roles/、whale-audio/ 和 whale-bubble-imgs/。纯外观状态——位置、当前角色、吸附区——存在浏览器 localStorage 的 dshw-pos、dshw-role、dshw-snap。这些文件里没有一个存密钥。

宿主侧通过 ctx.webServer 注册了 21 条 /dsh-whale/* 路由，每条都套了同一个 registerRoute 包装：先调用 connection.requestRejection(req)，对未认证或疑似 DNS 重绑定的请求按返回码拒绝（伪造 Host 头得到 403）。README 把后果说得很直白：不带会话凭据的裸 curl 会返回 401，而那个 401 是栅栏在工作，不是路由坏了。源码注释里也写明一个例外：如果 connection 服务缺失，栅栏会放行并打一条警告。

运行要求

• harness 目标：来源未声明。 README 没有点名任何 harness 版本，whale-widget-prompt.md 也没有，package.json 既无 engines 字段也无 peerDependencies，其 dsh 字段里也没有 compatibility 条目。既然来源中没有任何一处说明它支持哪些 harness 版本，本条不记录 dshTarget，验证等级止于 L2，而不是替来源断言一个本站无从核实的兼容性。
• 仅 Web。 包里的 dsh 字段只有 { bundle: { patch: './cordis.patch.yml' } }，该 patch 插入 id: dsh-whale-widget。没有 client 平台声明：挂件能进浏览器，是因为宿主往页面里注入了 script 标签，而不是因为 DSH 挂载了客户端包。
• 依赖。 发布到 npm 的包里没有 dependencies，也没有 peerDependencies；宿主只 import node:fs、node:os、node:path、node:dns、node:url。它真正的硬依赖是 inject 里声明的三个 DSH 服务：webServer、credentials、connection。
• 安装期脚本：没有。 package.json 里根本没有 scripts 段，所以不存在 preinstall / install / postinstall / prepare 步骤。
• 网络访问有文档，遥测未提及。 README 写明了余额接口，也列出了模板可能调用的各厂商接口，源码里能找到对应 URL。来源中没有任何隐私或数据保留声明，也没有披露任何遥测。
• 凭据。 内置余额需要 DEEPSEEK_API_KEY。README 说明早期「实时·令牌」模式用到的 DEEPSEEK_PLATFORM_TOKEN 已不再需要，因为该模式已下线。

已知限制

• 余额是按厂商的，不是通用的。 内置读取只对官方接口有效。厂商没有余额接口时，插件显示「—」并给出估算，不会凭空编一个数字。
• 「今日已用」是记账，不是账单。 它以当天第一次余额观测为基准；README 承认这个数字可能与官网有差异：主口径是余额差，会话事件只在余额差不可用时兜底——充值、退款，或者当天还没有基准。
• 仅限 Web 界面。 没有 headless 或纯 CLI 入口；没有浏览器页面就没有气泡、菜单和设置。
• 账本有保留期：逐轮明细 90 天或 2 万条、逐日汇总 365 天，超期记录移入归档文件。README 没有记录卸载时会清理这些文件，只给了 remove 命令。
• connection 服务缺失时信任栅栏会放行，这一点写在源码注释里。
• Codex 支持被 README 自己标注为部分适配，订阅窗口的部分也被说明为没有真实订阅样本可验证。
• 没有公开的安全扫描。 这里的 security: unverified 就是这个意思：来源描述了凭据处理与路由栅栏，但本条目没有任何审计记录。

什么时候用它、什么时候不要用

如果你想在 DSH Web 界面里随时瞄一眼余额和消耗速度，并且更希望这个数字来自官方余额接口而不是平台会话令牌，它合适；如果你手上有多家厂商的密钥，想找个地方统一验证和统计额度，它也合适。每轮消耗气泡是最没有替代品的部分，因为它读的是 harness 自己上报的 token 用量，而不是靠文本长度猜。

不要把它当成计费真相来装。「今日已用」由余额差推算，可能与官网不一致；每轮花费是按插件内置的价目表算的，所以两次发版之间官方若调价，金额会一直错到包更新为止。也不要装在 headless 或纯 CLI 的 DSH 上——它提供的每一个界面都是浏览器 UI。

FAQ

这个挂件会把我的 DeepSeek API 密钥发到 DeepSeek 以外的地方吗？

来源说不会，而且具体到可以核对。宿主为内置余额只发一次外部 fetch——https://api.deepseek.com/user/balance，带 Authorization: Bearer <key>——README 写的是同一个接口。密钥从 DSH 凭据服务读取，从不写进插件自己的配置文件。前端那一半完全不调用 api.deepseek.com，它只请求本地的 /dsh-whale/balance.json，外部请求由宿主发出。你为自定义厂商填的密钥进入同一个 DSH 凭据服务，注册表文件里只存凭据名。

它会改变我的会话行为吗？

不会。它不注册工具、不注册斜杠命令、也不注册 Cordis 服务。它只是往页面注入一个 script 标签，并订阅 session/event 读取 token 用量、订阅 session/disposed 清掉残留的按会话缓冲。来源里没有任何一处会改写提示词、改动模型路由或截短对话。

安装它会执行代码吗？

不会。发布到 npm 的 package.json 里没有 scripts 段，因此没有 install、preinstall、postinstall 或 prepare 钩子可执行。插件是在 DSH 把它加载进 web profile 之后才开始工作的。

那个余额数字权威吗？

余额是对 GET https://api.deepseek.com/user/balance 的直接读取，服务端缓存 25 秒、前端每 60 秒刷新一次，所以请把它当成可能有一分钟延迟的接口读取，而不是实时流。「今日已用」和每轮花费不是读取值：前者是与当天首次观测余额的差值，后者是按 harness 上报的 token 用量对 lib/index.js 里那张价目表做算术。README 自己也提到今日数字可能与官网有差异。

它和其他鲸鱼类或余额类插件比怎么样？

本条目不做这种对比，也请不要从中读出对比。生态里存在不止一个鲸鱼主题或余额展示类的 DSH 插件，其中一些出自别的作者；它们的数据来源恰好可能在这个最关键的点上不同——数字是从官方余额接口读来的、从本地日志推算的，还是按会话事件估算的。选定之前，请自己核对你选的那个插件的数据来源与凭据处理方式。