前言¶
用 DeepSeek Harness（DSH）跑 web profile 時，賬戶餘額和官方文檔裏的峯谷計價規則往往不在同一屏裏；會話多了之後，也很難從界面直接看出「這一 workspace 大概花了多少」。社區插件 dsh-balance（維護者 zz0-0）把餘額查詢、當前計價窗口和按會話/工作區的費用估算接到 DSH 頁面上，數據走本地 DSH 服務，API Key 不注入瀏覽器。
這是什麼¶
dsh-balance 是面向 DeepSeek Harness web profile 的聯網類插件：在窗口右下角展示實時賬戶餘額與當前高峯/谷價窗口，並從 session 日誌彙總每條對話、每個 workspace 的費用估算。插件通過 GitHub 倉庫 zz0-0/dsh-balance 分發；社區目錄頁見 skillhub.cn/plugins/zz0-0/dsh-balance（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。當前 package 版本爲 0.1.0，許可證 MIT。
核心功能¶
餘額卡片與詳情面板¶
卡片固定在窗口右下角，與 composer 獨立：顯示總餘額、當前窗口（谷價 / 高峯）、距下次切換的剩餘時間，以及本地時區的切換時刻。在無對話的 hero 屏也會留在窗口底部；當 composer 或單會話狀態行佔到底角時，卡片會上移，避免擋住其他信息。
點擊卡片打開菜單式詳情面板，內容包括：賬戶餘額 / 充值 / 贈送額度、本地與北京時間的下次切換、當前本地/北京時間、高峯時段說明、價目表來源與更新時間、賬本路徑、刷新按鈕。贈送額度行始終顯示（無贈送時爲 0）；若仍有贈送餘額，該行鏈到 DeepSeek Billing 查看過期信息。面板支持點擊外部或 Esc 關閉。
側邊欄費用估算¶
側邊欄在每條對話行顯示 ≈¥…（或 USD 賬戶下的 $）估算，workspace 行顯示其下對話合計。懸停 badge 可看 token 與已記錄估算。composer 狀態行刻意不再放置費用標籤，避免與對話行重複擠佔空間。
動態價目與峯谷規則¶
價目與高峯窗口不是寫死在插件裏：啓動時以及緩存超過六小時時，會從官方文檔頁拉取 CNY / USD 價表並解析模型列、緩存命中/未命中/輸出單價，以及中文頁腳註中的高峯時段。解析失敗時保留舊緩存，詳情裏標記爲 緩存/默認。
高峯默認爲北京工作日 09:00–12:00、14:00–18:00；週末恆爲谷價（自 2026-08-23 起文檔所述規則）。工作日若爲中國法定節假日則按谷價；調休形成的「週末」仍按週末處理。節假日數據來自 https://api.apihubs.cn/holiday/get?year=YYYY&size=500（當年與次年），緩存 30 天。
賬本與計價原則¶
本地賬本路徑爲 ~/.dsh/.dsh-balance-costs.json（或 $DSH_HOME 下同名文件）。每條 session 記錄 costs.CNY / costs.USD、tokens、lastSeq、當時使用的 pricingVersions 與 calendarVersions。再次掃描 session 時，只對 seq > lastSeq 的事件計價；已入賬事件不會因調價或重啓而重算，新價隻影響新事件。
餘額 API 可能返回多幣種 balance_infos；展示以非零餘額最大的幣種爲主（CNY 並列時優先 CNY）。雙幣種均有正餘額時卡片可疊顯兩種餘額，估算仍以較大余額對應幣種爲準。
主題、語言與可選通知¶
UI 使用 DSH menu-surface 設計 token（明暗、圓角、字號），跟隨 DSH 界面語言（zh-* / English）。若用戶此前已對 DSH 站點授予瀏覽器通知權限，峯谷窗口切換時可在標籤頁打開狀態下推送通知；瀏覽器完全關閉則無法收到。
環境與依賴¶
安裝前請確認：
- DSH 0.2.1.x 且啓用 web profile；README 在
0.2.1-rc.3上測試，package.json聲明engines.dsh = ">=0.2.1-0 <0.2.2-0"，其他 DSH 線版本不會掛載該插件。 - Node.js
^22.19.0 || >=24.0.0（與 DSH 要求一致）。 - 在 DSH credentials 中配置
DEEPSEEK_API_KEY。
安裝與啓用¶
從 GitHub 安裝（勿與 npm 上無關的 dsh-balance 包混淆）：
dsh plugin --profile web add github:zz0-0/dsh-balance
systemctl --user restart dsh-web
或使用顯式 git URL：
dsh plugin --profile web add git+https://github.com/zz0-0/dsh-balance.git
systemctl --user restart dsh-web
首次安裝後請對 DSH 頁面硬刷新（Ctrl/Cmd + Shift + R），以便注入瀏覽器腳本。systemctl 行假設 Linux 用戶級 dsh-web 服務；若手動運行 dsh web，需自行重啓該進程。
更新與卸載：
# 更新
dsh plugin --profile web add github:zz0-0/dsh-balance
systemctl --user restart dsh-web
# 移除
dsh plugin --profile web remove dsh-balance
systemctl --user restart dsh-web
典型用法¶
- 打開 DSH web 界面，看右下角卡片上的總餘額、當前
谷價/高峯與下次切換倒計時。 - 點擊卡片打開詳情，覈對價表來源時間、賬本路徑，必要時點刷新。
- 在側邊欄瀏覽各對話與 workspace 的
≈費用 badge；需要明細時懸停查看 token 與記錄值。
若卡片顯示 餘額? / Balance?，多爲 DEEPSEEK_API_KEY 缺失或無效，需在 DSH credentials 中檢查。
架構與隱私（簡要）¶
插件爲 DSH bundle：cordis.patch.yml 把條目寫入 web profile。Host（lib/index.js）解析 API Key、請求 api.deepseek.com/user/balance、讀 session、維護賬本、拉取價目/節假日，並提供 GET /dsh-balance/data 與 GET /dsh-balance/client.js。Browser（client.js）只訪問本地 DSH 服務，繪製卡片、面板與側邊欄 badge。
出站請求限於：餘額 API、兩個官方 pricing 文檔頁、api.apihubs.cn 節假日接口；無額外遙測。價目與節假日緩存位於 ~/.dsh/（如 .dsh-balance-pricing.json、.dsh-balance-holidays.json 等）。
適用場景與注意¶
適合長期在 DSH web 上開發智能體、需要對照官方峯谷規則控成本、並希望按對話/workspace 復盤 API 消耗的開發者。
插件以當前運行 DSH 的進程權限執行 host 邏輯並持有對 credentials 的訪問；安裝前請自行審閱 倉庫源碼 與 MIT 許可證，確認可接受其網絡與本地文件行爲。
結尾¶
dsh-balance 把 DeepSeek 賬戶餘額、峯谷窗口與會話級費用估算收進 DSH 同一界面，價目跟隨官方文檔更新，賬本只增不重算曆史。目錄與文檔：
