前言¶
在 DeepSeek Harness（DSH）裏跑 Agent 或批量調用 API 時，費用往往按月彙總出現在官方控制台，很難一眼看出是哪個 API Key、哪類模型、或哪一天把用量拉上去的。把官方導出的 ZIP 或自家整理的 CSV / JSON 留在本機做統計，又不希望賬單字節流到第三方服務，就需要一套和會話界面綁定的本地分析能力。下面介紹社區插件 dsh-token-usage（維護者 Jimmy-20100728），它在 DSH 內完成導入、歸一化、分析與展示，分類屬於 admin-security，當前 npm 包版本爲 1.1.0。
這是什麼¶
dsh-token-usage 是 DeepSeek Harness 插件：導入 DeepSeek 官方導出 ZIP（amount-*.csv + cost-*.csv）、通用 CSV 或 JSON，在會話界面新增「Token 用量」標籤頁，查看費用趨勢、按模型 / API Key / 自定義分組對比、緩存命中與節省、輸入輸出構成、異常用量檢測；也可在對話裏讓 Agent 調用 token_analysis 工具。解析、統計、落盤均在 DSH 本機進程內完成，瀏覽器只訪問本機 /api/token-usage/*。
同一套 analyze() 邏輯同時供 Web UI 與對話工具使用，兩邊數字一致。
它解決什麼問題¶
官方控制台側重「當月花了多少」，本插件針對以下缺口做本地補充（README 中列出的能力）：
- 哪個 API Key / 項目 在消耗更多：賬單本身不按 Key 拆分時，按 token 與單價權重把月賬單分攤到 Key。
- 緩存命中率 與命中節省的費用。
- 輸入 / 輸出 Token 構成。
- 哪天 用量突增：採用中位數 + MAD 判定，相對均值更抗離羣點。
核心功能¶
數據導入與存儲¶
支持拖拽或「導入文件」上傳；同一數據集可多次追加（例如先 amount-*.csv 再 cost-*.csv，或 ZIP 內兩份一起）。默認數據目錄爲 $DSH_HOME/token-usage（一般爲 ~/.dsh/token-usage），可通過插件配置項 dataDir 覆蓋。目錄下保存數據集元信息、歸一化 rows.json、原始文件及 groups.json（自定義分組）。
界面儀表盤（1.1.0）¶
會話頂部視圖標籤出現「Token 用量」。可切換按日 / 按周 / 按月、Token / 費用、模型 / API Key / 分組；底部「自定義分組」可爲 Key 起業務名並按組聚合。
儀表盤包含：KPI 條（總 Token、總費用、緩存命中率、緩存節省、請求數、日均 Token）；趨勢區（堆疊柱狀或折線）；三欄分析（模型排行、Token 構成圖、統計參數）；異常用量檢測與中文解讀。圖表爲自繪 SVG，無 ECharts、無遠程字體。
對話工具 token_analysis¶
Agent 可調用 token_analysis，例如分析已導入的最新數據集、直接分析本機路徑（不落庫）、或 persist: true 分析併入庫。返回結構化數據並渲染爲中文 markdown。
HTTP API¶
路由經 Host 連接鑑權（connection.requestRejection），與 DSH 自身 /api 同一策略；無該能力時退回僅信任 loopback。主要路徑包括：GET /api/token-usage/state、POST /api/token-usage/import、POST /api/token-usage/import-path、GET /api/token-usage/analysis、GET /api/token-usage/export、POST /api/token-usage/groups、POST /api/token-usage/rename、POST /api/token-usage/delete。
費用口徑¶
優先級爲：billed（cost-*.csv）→ reported（通用數據自帶 cost）→ price（amount 的 price × amount）→ estimated（內置價目表）。缺 cost-*.csv 的月份會在界面標明費用爲推算，不冒充精確賬單。
安裝與啓用¶
插件爲純 JavaScript（ESM），無需構建，無第三方依賴，僅依賴 Node 自帶的 zlib。package.json 要求 Node ^22.19.0 || >=24.0.0。許可證爲 MIT。
README 給出的安裝方式如下，請按你本機 DSH 的插件管理習慣選擇其一：
# 方式 A：在本機 DSH 裏用插件管理器安裝包目錄
# plugin_manager install_bundle target = <本倉庫絕對路徑>
# 方式 B：打包成 tgz / 目錄後放進 profile 的 node_modules 再啓用
npm pack # 生成 dsh-token-usage-1.1.0.tgz
安裝後由 cordis.patch.yml（dsh.bundle.patch）向 bundle 注入 dsh-token-usage，並註冊 Web 客戶端（lib/client.js 注入會話視圖標籤）。
典型用法¶
在界面裏導入並查看¶
- 打開 DSH 會話，切換到「Token 用量」標籤。
- 拖入 DeepSeek 導出的 ZIP，或 CSV / JSON；需要時可對同一數據集多次追加文件。
- 切換時間桶與維度，按需配置「自定義分組」後保存，查看排行與趨勢。
在對話裏讓 Agent 分析¶
// 分析已導入的最新數據集
{ "name": "token_analysis", "arguments": { "bucket": "week", "group_by": "key", "top": 10 } }
// 直接分析本機文件（不落庫）
{ "name": "token_analysis", "arguments": { "path": "D:/賬單/export.zip", "bucket": "day" } }
// 分析併入庫，之後可在界面裏繼續看
{ "name": "token_analysis", "arguments": { "path": "D:/賬單/amount-2026-08.csv", "persist": true } }
腳本調用分析接口¶
對已入庫的數據集，可帶鑑權請求：
GET /api/token-usage/analysis?datasetId=&bucket=&from=&to=&top=
參數與 UI 側分析一致，便於與自有報表串聯。
適用場景與注意¶
適合誰：需要在 DSH 工作臺內做 Token / 費用復盤、按 Key 或項目分組對比、觀察緩存節省與突增日的團隊或個人；希望賬單文件不出本機的環境。
權限與安全：插件以當前 DSH 進程權限運行，可讀寫 dataDir、通過 import-path 讀取服務器本機路徑。安裝前應自行審閱 GitHub 倉庫 源碼與 MIT 許可證。README 說明不寫遙測、不向外部服務發送賬單數據。
已知邊界（來自 README）：ZIP 僅支持 store / deflate，ZIP64 會報錯；Key 級費用爲權重分攤，不是賬單原始拆分；界面文案目前爲中文，未做 i18n。
生態說明：DSH 社區插件目錄由獨立站點維護（SkillHub 目錄頁），與 DeepSeek / 幻方無官方從屬關係；「一切皆插件」是 DSH 的使用方式，本文介紹的是社區維護的 admin-security 類插件。
結尾¶
dsh-token-usage 把官方導出與通用賬單文件留在本機，用同一分析內核驅動「Token 用量」頁與 token_analysis 工具，補齊 Key 維度、緩存與突增等控制台不易展開的細節。若要安裝細節與適配器擴展，以倉庫 README 爲準。
