前言¶
在 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
