前言¶
在 DSH 里跑 DeepSeek 对话时，余额和「今天到底花了多少」往往要切到 platform.deepseek.com/usage 或自己记 token 估算。对话一多，轮末成本、峰谷时段定价也容易对不上感觉。下面介绍社区插件 dsh-ds-whale（维护者 Iceseas）：在 DSH Web UI 右下角常驻一只小鲸鱼，用本机凭据拉余额与官网口径用量，并在每轮结束后用拟人语气播报花费；数据只落在本机 JSON，不经过模型。
这是什么¶
dsh-ds-whale 是 DSH 的 Web 客户端插件（package.json 中 dsh.client.platform 为 web，分类对应「客户端」）。当前版本 0.9.6，许可证 MIT，运行环境要求 Node ≥ 20。
它解决的是：在 DSH 界面内持续看到 DeepSeek 可用余额、与官网一致的今日用量，以及按插件内置价表估算的每轮消耗；同时提供预警、用量账本、峰谷倒计时和可选的零 token 天气查询。界面与播报支持 中文 / English（language: auto / zh / en）。
核心功能¶
余额与刷新¶
- 调用
GET https://api.deepseek.com/user/balance（BearerDEEPSEEK_API_KEY），展示总额、充值、赠金等可用余额。 - 默认约 60s 自动刷新（可在设置里改
refreshMs，范围 15s–1h）。 - 左键点击鲸鱼立即刷新，默认 6s 冷却（
clickCooldownMs，2000–120000ms），刷新过程有进度与「刷新中…」提示。 - 宿主刚启动、凭据服务未就绪时会自动退避重试（4s→60s，最多 8 次）。
今日用量（官网口径）¶
- 通过 DeepSeek 官网用量接口
GET https://platform.deepseek.com/api/v0/usage/by_api_key/{amount,cost}（带 DSH 登录态的x-dsh-auth-token），金额、请求数、tokens 与platform.deepseek.com/usage页面同源。 - 接口不可用时退回「余额下降」观测，并在标签上标明口径差异。
每轮消耗拟人播报¶
- 每轮对话结束，按金额分档用小鲸鱼口吻播报本轮花费；副行显示模型与入/出 token。
- 需点击「知道啦~」才关闭；可在设置中关闭
turnPop。
峰谷定价与倒计时¶
- 工作日 9:00–12:00、14:00–18:00 为高峰，空闲价为高峰价一半；周末全天谷价。
- 面板可显示峰谷状态与实时倒计时（
showPeak）。
内置价表（元 / 百万 tokens，格式 [空闲, 高峰]）用于本机估算，例如：
| 模型族 | 缓存命中 | 未命中输入 | 输出 |
|---|---|---|---|
deepseek-flash（含 v4-flash 系列） |
0.02 / 0.04 | 1 / 2 | 4 / 8 |
deepseek-v4-pro（含 pro / reasoner / r1） |
0.15 / 0.30 | 4.5 / 9.0 | 13.5 / 27.0 |
金额公式：金额 = (缓存命中 × 命中价 + 未命中输入 × 输入价 + 输出 × 输出价) / 1e6。DeepSeek usage 中 inputTokens 不含缓存命中时，保持 cacheInInput 关闭。
立绘与交互¶
- 六种状态立绘：平静、气鼓鼓（点击受击）、脸红（说话中）、慌张（余额告警）、挥手打招呼（开机问候）、托腮思考（查天气）。
- 常驻气泡（
miniFields）：可选 1–3 项——余额、今日已用、本机估算、本轮消耗、峰谷倒计时。 - 右键菜单：立即刷新、余额详情、今日天气、打开设置；左键刷新、右键不触发受击抖动。
- 拖拽移动并记忆位置；可按页面中线左右吸附（
snap）；可调整scale（0.6–2）；拖到窗口顶部时播报与详情会自动翻到下方，避免被裁切。
开机问候与天气¶
greetOnStart开启时，每次打开 DSH 按昵称与时段问好，配挥手立绘与提示音。- 「今日天气」由宿主进程请求 Open-Meteo，不消耗 token；需在设置里填写
weatherCity。城市转经纬度有内置表 → photon → Open-Meteo 三路兜底。
告警与用量记录¶
warnBelow：余额低于预警线时慌张脸 + 拟人播报，可跳转充值/用量。dailyBudget：超出今日预算提醒一次（0 为不限）。- 用量页支持今日 / 近 7 天 / 全部、模型占比、搜索；可清空今日、清空全部、重置基线。
设置入口¶
- DSH 设置 → 左侧导航 独立页「小鲸鱼 / Whale」（在「喵记忆」下方）。
- DSH 设置 → 插件 → dsh-ds-whale 由宿主按 schema 生成表单。
- 右键「打开小鲸鱼设置」直达该页。
安装与启用¶
前置：DSH 桌面端或 dsh web，以及 Node ≥ 20。
推荐从 GitHub 安装到当前 profile：
# 把整个仓库装进当前 profile 的插件目录
dsh plugin add github:Iceseas/dsh-ds-whale
装完后重启 DSH 或重载插件，右下角应出现小鲸鱼。
安装即用前提：DSH 中已配置 DEEPSEEK_API_KEY，或已登录 DeepSeek 账号。两者都没有时挂件仍会出现，余额栏会提示需要凭据。
若 DSH 版本不支持 plugin add，README 说明可手动将仓库放到 <DSH_PROFILE_DIR>/node_modules/dsh-ds-whale（常见为 ~/.dsh/profiles/desktop），并在该 profile 的 package.json 的 dsh.profile.bundles 中加入 "dsh-ds-whale" 后重启。
典型用法¶
- 安装并重载后，确认右下角小鲸鱼与常驻气泡显示余额或今日用量（在设置里勾选
miniFields）。 - 左键点鲸鱼手动刷新余额；右键打开菜单查看详情或进入设置。
- 完成一轮对话后查看拟人播报的本轮花费；不需要时可关闭
turnPop。 - 需要天气时，先在设置填写
weatherCity（如上海），再通过右键「今日天气」查看（零 token）。 - 需要与官网对账时，对比面板「今日已用」与
platform.deepseek.com/usage；本机 token 估算与官网差值会标为「偏差」，便于发现价表漂移。
本地状态与账本保存在唯一数据文件：
$DSH_HOME/.dsh-ds-whale.json
（Windows 默认为 C:\Users\<你>\.dsh\.dsh-ds-whale.json。）插件不保存对话内容；记录页底部可清空或重置基线。
宿主侧 HTTP 路由前缀为 /api/dsh-ds-whale（同源 POST，仅本机浏览器），例如 /state 聚合状态、/refresh 强制刷新、/weather 查天气、/settings 写配置、/ledger 与 /history 管理账本。
适用场景与注意¶
适合：长期在 DSH Web UI 使用 DeepSeek、希望余额与官网今日用量同屏可见、并想在每轮结束后快速感知成本的开发者。
注意：
- 插件在 当前 DSH 进程权限 下运行，会代表本机发起余额、官网用量与（可选）天气相关 HTTP 请求；安装前建议浏览 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。
- 社区目录 SkillHub 插件页 与 GitHub 为独立生态入口，与 DeepSeek / 幻方无官方从属关系；README 亦标明为非官方项目。
- 外部请求说明：余额 API 用
DEEPSEEK_API_KEY；官网用量用 DSH 登录态；天气请求不带凭据，且不经过大模型。
结尾¶
dsh-ds-whale 把 DeepSeek 余额、官网口径今日用量、轮末成本播报和峰谷倒计时收进 DSH 右下角挂件，配置与账本留在本机。若要安装或查看变更记录，可访问：
- 目录页：https://www.skillhub.cn/plugins/Iceseas/dsh-ds-whale
- 源码与 README：https://github.com/Iceseas/dsh-ds-whale
