前言¶
在 DeepSeek Harness（DSH）裏做多輪會話時，token 往往分散在一條條會話事件裏：今天多少、這個月累計多少、某個模型是否特別費，只能靠翻日誌或憑印象猜。官方 Web GUI 側重對話與工具鏈，並不自帶按日、按提供商、按模型彙總的用量視圖。
dsh-token-board 是社區維護的客戶端插件，在側邊欄增加「使用統計」入口，把本機會話日誌折成可讀看板。數據只在本機讀取與緩存，不聯網、不上報。下面介紹它的能力邊界、安裝方式與使用時的口徑約定。
這是什麼¶
- 名稱：
dsh-token-board - 維護者：HTempt
- 分類：客戶端（瀏覽器半，
dsh.client.platform爲web） - 許可證：MIT（© 2026 HTempt）
- 當前 npm 版本：
0.1.5 - 依賴宿主：
@deepseek-ai/dsh>=0.2.1-rc.2；Node^22.19.0 || >=24.0.0
插件隨 DSH 宿主加載，不能單獨用 node 當獨立服務跑起來。它注入 webServer、sessionPersistence、sessions，通過持久層與會話內存讀 usage 相關事件，並在 Web 側註冊只讀路由與側邊欄入口。
適用運行方式：
| 運行方式 | profile | 說明 |
|---|---|---|
dsh web |
web |
標準用法 |
| DSH Desktop（Dataelem 第三方客戶端） | web |
內部同樣是 web profile，安裝命令一致 |
核心功能¶
看板主要回答「花了多少 token、調了多少次、花在哪」——模塊與入口如下。
頂部指標卡¶
五張卡片：今日消耗、本月消耗、所選範圍消耗、累計消耗、調用次數。腳註寫清每張卡覆蓋的時段與調用數；範圍卡會標明區間名（如「近 3 月」「近 1 年」或自選起止）。
約定：
- 本月：當前自然月 1 號到月末，由宿主單獨計算，不隨頁面所選時間範圍變化。
- 累計：始終爲全量
allTime，與熱力日曆畫了多久無關。
熱力日曆與區間¶
可按 近 3 月 / 近 6 月 / 近 1 年 / 全部 / 自選起止 切換（自選最長 1 年，超出會截斷）。日曆按 token 單色深淺編碼；「全部」從最早有數據的月份畫到最新，不畫空白月（繪製上限 24 個月，統計與卡片仍按全量算）。
點擊某一天彈出當日明細：token 與調用、緩存命中率、失敗/嘗試與重試；按提供商列出模型；底部有當日工作區分佈（按項目，最多展示 6 條）。
分佈、趨勢與時段¶
- 概覽 / 時段 / 分佈 三個頂部頁籤。
- 按提供商：環形圖與佔比條；按模型：按 token 排名。
- 雙指標趨勢：token 與調用次數各一條縱軸，圖例可點選隱藏曲線。
- 時段：24 個鐘點柱狀圖，可切「按 Token / 按調用」；小時按瀏覽器本地時區切分，與日曆日界一致。
數據從哪來¶
| 你想知道 | 頁面在哪 |
|---|---|
| 今天花了多少 token、跑了幾次 | 頂部「今日消耗」卡 |
| 這個月累計多少 | 「本月消耗」卡 |
| 這段時間每天都用了多少 | 熱力日曆 |
| 某一天具體花在哪個提供商/模型 | 點日曆某天 → 當日明細 |
| 哪個提供商/模型最費 | 「按提供商」/「按模型」頁籤 |
| 趨勢怎麼走 | 底部雙指標趨勢圖 |
| 一天裏哪個時段最費 | 「時段」頁籤 |
插件會寫自己的統計與緩存文件；讀寫範圍見倉庫 ORIGINALITY.md。
關鍵統計口徑¶
與用戶側約定保持一致的幾點：
- 調用次數 = 帶 usage 樣本的實際請求數，不是消息數。
- 成功/失敗來自持久事件：
assistant/message（帶usage）計成功；assistant/attempt計失敗；llm/retry只計重試、不重複計調用。 - 全零 usage 的預熱請求不計入。
- 熱力圖只編碼 token 消耗。
- 時段圖只統計帶時間戳的會話記錄；按天歸檔的
statistics.json歷史不計入時段圖，頁底會註明覆蓋窗口內消耗的百分比。
安裝與啓用¶
從 npm 安裝（推薦）¶
dsh plugin 會把參數轉發給 pnpm，並自動登記 bundle：
dsh plugin --profile web add "dsh-token-board"
升級到最新發布版本：
dsh plugin --profile web add "dsh-token-board@latest"
若 pnpm 元數據緩存導致仍裝舊版，可指定精確版本或清理緩存後再裝。README 示例：
dsh plugin --profile web add "dsh-token-board@0.1.5"
安裝後建議用下面命令確認實際版本，不要只看命令輸出：
node -e "console.log(require('./node_modules/dsh-token-board/package.json').version)"
卸載：
dsh plugin --profile web remove "dsh-token-board"
裝完必做¶
- 重啓對應的 DSH Host（僅刷新瀏覽器不會加載新的服務端插件），然後 Ctrl+F5。
- 用配置 dump 確認插件已登記（
dsh-token-board在dsh.profile.bundles中應出現一次）：
dsh --dump-config --profile web | grep -A1 dsh-token-board
不要手工在 profile 的 cordis.patch.yml 裏重複 insert 註冊點；add 已會寫入 package.json 的 bundles 與 dependencies。
DSH Desktop 用戶¶
Desktop 走應用內插件市場（推薦），或用命令行時先把 DSH_HOME 指到 Desktop 實際使用的 profiles 目錄，並確認：
dsh --dump-config --profile web | head -5
裝完後應完全退出應用再打開，等效於重啓 Host。
其他安裝途徑（按需）¶
- npm 未發包時：
dsh plugin --profile web add "github:HTempt/dsh-token-board"或帶 commit SHA。 - 離線：從 GitHub Releases 下載
.tgz後add "/path/to/dsh-token-board-0.1.5.tgz"。
典型用法¶
- 在
webprofile 完成安裝並重啓 Host。 - 打開 DSH Web GUI（瀏覽器或 Desktop），在側邊欄進入「使用統計」。
- 頂部切換時間範圍（近 3/6/12 月、全部或自選日期），查看五張指標卡與熱力日曆。
- 點日曆某一天，查看提供商、模型、工作區與逐小時分佈（對話框底部）。
- 在「時段」頁籤查看 0–23 點分佈；在「分佈」頁籤切換提供商與模型排行，並對照底部雙軸趨勢。
插件路由爲只讀 HTTP 接口，由宿主 webServer 註冊；前端依賴 dsh-client-locale、dsh-client-ui-layout、dsh-client-ui-sidebar 注入。
適用場景與注意¶
適合誰：長期在本地用 dsh web 或 DSH Desktop、希望用統一口徑回看 token 與調用次數、又不希望用量數據離開本機的開發者。
權限與安全：插件以當前 DSH 進程的權限讀取會話持久化路徑並寫入自身緩存；安裝前應閱讀源碼與 ORIGINALITY.md、LICENSE，確認可接受讀寫範圍。社區目錄與 GitHub 倉庫由維護者發佈，與 DeepSeek / 幻方無官方從屬關係，生態上 DSH 理念是「一切皆插件」，本包是其中一項客戶端擴展。
可移植性：lib/ 未 import @deepseek-ai/*，純 Node 內置模塊；lib/usage.js 可在無宿主環境下單獨做函數級測試，但完整看板仍需 Web GUI 宿主。
結尾¶
dsh-token-board 把本機會話日誌收成日、提供商、模型三個維度的用量視圖，並配上熱力日曆、明細彈窗、排行與雙軸趨勢，且默認不聯網。若你已在用 web profile，一條 dsh plugin --profile web add "dsh-token-board" 即可掛上側邊欄入口。
- 目錄頁：https://www.skillhub.cn/plugins/HTempt/dsh-token-board
- 倉庫：https://github.com/HTempt/dsh-token-board
