前言¶
在 DeepSeek Harness（DSH）裏跑長會話、多模型切換時，官方控制台能看賬戶餘額，但本地很難把「這一條 assistant 消息」對應到人民幣：峯谷單價不同、緩存命中與未命中通道分開計價，節假日規則還要跟時間戳對齊。常見做法是看 Token 估算或標題欄彙總，和賬單對不上時只能事後手算。
dsh-precise-billing（包名 dsh-precise-billing，當前版本 0.2.2）面向桌面 Profile 的 DSH 用戶：以每條響應自帶的 usage 爲計價單位，按 DeepSeek 官方人民幣價目（含峯谷與 2025–2026 中國法定節假日）逐請求計費，並在界面提供費用條、側欄卡片、用量看板與三段式熱重啓。維護者爲 Sheldon Jinn，許可證爲 MIT；插件類型爲 DSH 本地插件（Host + Client），在 SkillHub 目錄中歸類爲 admin-security。
下面介紹插件定位、核心能力、安裝啓用方式與日常使用路徑。
這是什麼¶
一句話：dsh-precise-billing 在 DSH 進程內讀取會話與 usage 元數據，按請求時間戳判定峯谷後折算費用，不要求用戶手工填單價。
計價與展示拆成幾塊：
- 精確計費：輸入（未命中緩存）、緩存命中、緩存寫入、輸出分通道計價；峯時單價爲閒時 × 2；未定價模型單獨計數並標註「未計價」，不顯示爲 0 元。
- 費用條：可選出現在輸入框下方、會話標題欄或隱藏。
- 側欄卡片：常駐底部，彙總今日/累計消費、餘額與峯谷進度。
- 用量看板：趨勢、日曆（日/周/月/年）及年視圖柱狀圖。
- 熱重啓：側欄觸發，三段式確認後重啓 DSH，並做環境快照。
數據索引與設置寫在 $DSH_HOME/storages/precise-billing.json；會話源數據只讀 $DSH_HOME/sessions/**/session.v4.jsonl.zstd。重啓日誌爲系統臨時目錄下的 pb-restart-<時間戳>.log（README 中 Windows 示例爲 %TEMP%\pb-restart-*.log）。
精確計費規則（與官方價目對齊）¶
每條 assistant/message 的 usage 是一條計價記錄，不用 Token 總量粗估。
峯谷判定（北京時間）
- 週一至週五 09:00–12:00、14:00–18:00 爲峯時；其餘爲閒時。
- 內置 2025–2026 中國法定節假日，節假日全天按閒時。
- 以該請求自己的時間戳判定，而不是會話開始時間。
單價示例（人民幣 / 百萬 token，閒時 / 峯時）
| 模型 | 輸入（未命中） | 緩存命中 | 輸出 |
|---|---|---|---|
| deepseek-flash（含 v4-flash） | ¥1 / ¥2 | ¥0.02 / ¥0.04 | ¥4 / ¥8 |
README 未窮盡所有模型價目；未出現在價表中的模型走「未計價」計數邏輯。
界面與核心功能¶
費用條¶
位置三選一：輸入框下方、會話標題欄、隱藏（隱藏後相關設置項收起）。可勾選顯示峯時/閒時、本次、今日、累計、餘額；字體、字號、顏色可調，支持跟隨主題。點擊費用條可展開當前會話明細。
側欄卡片¶
顯示今日消費、累計消費、賬戶餘額與峯谷進度。風格：標準 / 簡約 / 緊湊 / 自定義（自定義可控制 16 個顯示項）。右上角三個入口：熱重啓（↻）、用量看板（▦）、設置（⚙）。
用量看板¶
趨勢：統計 Token、API 請求次數、消費金額、餘額；各模型消費與 Token 曲線；單日按小時、多日按天，超過 120 天按月聚合。
日曆：日 / 周 / 月 / 年視圖；格子展示 Token、消費、峯時/閒時金額；點擊格子彈出分模型明細（含輸入命中/未命中、緩存寫入、輸出等）。年視圖左側爲年度彙總，右側 12 個月峯/閒堆疊柱狀圖，當前年份行高亮。
熱重啓¶
由側欄卡片刷新圖標觸發，流程分三步：
- 檢查運行中對話：若有，橙色警示框列出標題，可選「取消」或「繼續重啓」。
- 紅色確認框：明確提示會中斷進行中的操作。
- 藍色執行中：進度條與日誌路徑，可「收起並複製日誌」。
重啓前對 DSH_* 與代理相關變量做環境快照；助手經 Explorer 派發，避免被 DSH job object 連帶結束；接口帶 15 秒冷卻。系統開啓「減少動態效果」時，警示框呼吸動畫會關閉。
設置¶
選項自動保存（600 ms 防抖），保存後設置頁中央有 ✓ 提示。「恢復默認」立即寫回默認值；默認刷新間隔爲 60 秒。側欄卡片「進度條」關閉時，刻度線/游標/懸浮提示一併禁用。設置頁底部「參考項目」提供 DeepSeek-Usage、dsh-hot-restart、dsh-meter 的地址與複製安裝命令（本插件對三者均爲獨立實現，詳見倉庫 CREDITS.md）。
安裝與啓用¶
插件以當前 DSH 進程權限運行；安裝前建議在 GitHub 查看源碼與 MIT 許可證全文。package.json 要求 Node >=22。
從 npm 安裝（README 推薦）：
dsh plugin --profile desktop add dsh-precise-billing
安裝後在 設置 → 插件 中啓用 dsh-precise-billing，並刷新頁面。本地開發可用 link: 指向插件目錄（README 給出 Windows 路徑示例，需按本機 _plugins 實際位置修改）。
典型用法¶
安裝啓用並刷新後，可按 README「快速上手」路徑操作：
- 看費用：輸入框下方費用條，或側欄底部計費卡片（點卡片展開本會話明細）。
- 開看板：側欄卡片右上角 ▦，或 設置 → 精確計費 → 用量面板。
- 改設置：側欄卡片右上角 ⚙，或 設置 → 插件 → 精確計費；修改後自動保存。
- 熱重啓：側欄卡片右上角 ↻；先處理運行中對話提示，再完成紅色確認與藍色執行步驟。
需要對照歷史消費時，用量看板日曆/年視圖適合按日或按月回看；需要與官方賬單核對時，應以逐條 usage 聚合結果爲準，並注意未計價模型的單獨計數。
適用場景與注意¶
適合誰
- 長期在 DSH Desktop 使用 DeepSeek API，希望本地界面直接看到人民幣費用、峯谷拆分與會話明細的用戶。
- 需要用量趨勢、日曆與年視圖，又不想單獨裝多個碎片化插件的用戶（本插件集成了計費展示、看板與熱重啓；設計思路參考了社區中的 DeepSeek-Usage、dsh-meter、dsh-hot-restart，代碼爲獨立實現）。
使用注意
- 計價依賴響應中的
usage與價表覆蓋的模型；未定價模型不會僞裝成零元。 - 峯谷與節假日規則以內置表爲準，模型單價隨 README 價表更新，升級插件後留意版本說明。
- 熱重啓會中斷進行中的對話與操作，務必走完三段式確認。
- DSH 生態奉行「一切皆插件」；SkillHub 目錄（https://www.skillhub.cn/plugins/SheldonJinn/dsh-precise-billing）爲社區站點，與 DeepSeek / 幻方無官方從屬關係，安裝來源以 npm 包名與 GitHub 倉庫爲準。
結尾¶
dsh-precise-billing 把官方人民幣價目、峯谷與節假日規則落到每一條請求的 usage 上，並在 DSH 內提供費用條、側欄卡片、用量看板與帶環境快照的三段式熱重啓。若你需要在本地開發環境裏可覈對、可回看、可配置的精確計費，可按上文命令安裝後在插件設置中啓用。
- 插件目錄頁：https://www.skillhub.cn/plugins/SheldonJinn/dsh-precise-billing
- GitHub：https://github.com/SheldonJinn/dsh-precise-billing
