前言¶
用 DeepSeek Harness（DSH）跑智能體，路由往往不止一條：官方 API、New API 系中轉、Sub2API、各家 Coding Plan……會話一多，賬單就散在各家控制檯裏，很難回答兩個樸素的問題——這個月到底燒了多少 Token？又是哪條線路、哪個項目在花錢？
社區插件 TokenLedger（zh667/TokenLedger）就是衝着這個痛點來的：在 dsh web 的 Web GUI 裏掛一塊「用量賬本」，把每次請求的 Token 用量歸屬到實際服務請求的中轉站，並按工作目錄做項目分組。裝完就能看彙總，零配置、不需要額外填憑據；查餘額時才複用宿主裏已有的 API Key。項目在 GitHub 上約 138 stars（MIT 許可），維護者爲 zh667，在 SkillHub 插件庫 中歸類爲模型推理。
需要說明的是：DSH 的核心理念是「一切皆插件」，SkillHub 等社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係；TokenLedger 本身也是第三方社區項目。
這是什麼¶
一句話：TokenLedger 是面向 DSH Web GUI 的 Token 用量統計與歸屬插件（npm 包名 dsh-tokenledger）。
它從 Harness 的事件流裏摺疊用量數據，按 provider 的 baseURL 歸一化出的 origin（域名） 把流量歸到對應中轉站——同站多把 key 合併成一行，站名是域名而不是你起的路由別名。同時按會話啓動時的工作目錄做項目歸屬：工作區登記過的顯示標題，沒登記過的用目錄名，子目錄裏起的會話也不會漏掉。
用量統計、餘額查詢、費用估算、導出診斷，面板和命令行讀的是同一套查詢，不存在兩套口徑。
核心功能與亮點¶
- 中轉站歸屬：自動從宿主 provider 配置發現
baseURL，只讀地址、不碰憑據；同一 origin 下的多路由合併統計。 - 按項目歸屬：以 cwd 爲鍵分組，可選關聯 workspace 標題；無目錄的會話單獨標爲「未記錄目錄」，不會被靜默丟棄。
- 餘額與訂閱配額：支持 DeepSeek 官方、New API 系、Sub2API、Moonshot/Kimi、智譜 GLM、OpenRouter（需 Management Key）、OpenCode Go、Kimi For Coding、MiniMax / Z.ai Coding Plan 等；訂閱型按 5 小時 / 日 / 周 / 月滾動窗口展示進度條與重置時間。
- 用量分析：今日 / 本月 / 累計三窗口，可按站點、模型下鑽，含緩存命中率與一年活躍度熱力圖。
- 費用估算：支持分段費率表與峯谷計價；未定價模型顯示破折號，不猜價格。
- 導出與診斷：CSV / JSON 導出，
/tokenledger diagnostics查看路由歸屬與索引健康度；歸因不上的行數單獨列出。 - 隱私與安全：只記錄 token 數、模型名、路由名、站點域名，不讀取提示詞、工具參數或響應正文；HTTP 端點僅限本機迴環 GET，並校驗 peer socket 地址。
項目在用量摺疊上處理了若干容易算錯的邊界：請求失敗後仍可能從 assistant/chunk 流出 usage；同一 (turn, step) 的重複報告做替換而非累加；孤兒 usage chunk 回退到最近一次 request/header，歸不上的記爲 unknown 而不猜測。
安裝與啓用¶
需要 DSH 的 web profile，宿主版本 @deepseek-ai/dsh >= 0.1.0-rc.6。
在終端執行（命令以 GitHub README 與目錄頁爲準）：
dsh plugin --profile web add "github:zh667/TokenLedger"
安裝後重啓正在運行的 dsh web，瀏覽器硬刷新。側邊欄底部會出現「用量賬本」入口。
升級或卸載：
dsh plugin --profile web update dsh-tokenledger
dsh plugin --profile web remove dsh-tokenledger
若要釘死版本，須使用完整的 40 位 commit SHA，短 SHA 會解析失敗：
# 跟蹤 main 分支（默認）
dsh plugin --profile web add "github:zh667/TokenLedger#main"
# 釘版本示例（SHA 以倉庫當前提交爲準）
dsh plugin --profile web add "github:zh667/TokenLedger#87b3d1806ac4d204a9195fc04ae8af6d6ebdd3ee"
裝完後可用 /tokenledger diagnostics 排查「中轉站爲什麼不顯示」——無需猜配置。
典型用法示例¶
Web 面板：側邊欄進入「用量賬本」，查看三窗口合計、按天/模型/站點分佈、賬戶餘額與熱力圖。
命令行（與面板同源數據）：
/tokenledger # 全部時間
/tokenledger 7 # 最近 7 天
/tokenledger 30 api.example.com # 某中轉站最近 30 天
/tokenledger site # 列出發現到的中轉站
/tokenledger site add <路由名> <地址>
/tokenledger site rm <路由名>
/tokenledger export csv 30 # 導出最近 30 天 CSV
/tokenledger diagnostics # 索引與路由診斷
/tokenledger reindex # 丟棄索引後全量重建
可選配置（寫入 settings.yaml，改完熱更新）——多數場景不需要：
tokenledger:
relays:
my-route: https://relay.example.com/v1
rates: [] # 費用估算費率表，不配則顯示破折號
fingerprint: false # 中轉站程序指紋探測，默認首次查餘額時自動探一次
內置表覆蓋不到的供應商，還可通過 tokenledger.endpoints 聲明餘額接口路徑（須與已配置 provider 同源，只發 GET，密鑰仍只從該 provider 的 apiKeyEnv 讀取）。
包也可作爲庫被其他消費者引用：
import { foldUsage, bySite, byModel } from "dsh-tokenledger";
import { LedgerStore } from "dsh-tokenledger/store";
import { readBalance } from "dsh-tokenledger/balance";
適用場景與注意事項¶
適合誰用：
- 同時配置多條 API 路由 / 中轉站，需要看清「哪一站、哪一模型、哪一項目」在消耗 Token；
- 使用 New API、Sub2API 等中轉，想在一個面板裏對照額度與用量；
- 需要導出 CSV/JSON 做團隊對賬或月度覆盤。
注意事項：
- 僅面向 web profile：插件通過
dsh web注入側邊欄與迴環 API，TUI / CLI-only 場景不適用。 - 插件權限：TokenLedger 以當前
dsh進程權限運行，安裝前建議閱讀源碼與 MIT 許可證，確認可接受其行爲邊界。 - 「未知路由」：若歷史請求的路由已從 provider 配置中刪除或改名，用量會暫歸「未知路由」——數據未丟，把同名路由配回去並觸發索引重建即可歸位。
- 餘額查詢例外：用量統計零憑據即可；餘額接口會複用宿主已存的 key（OpenRouter 需 Management Key），瀏覽器側拿不到密鑰。
- 社區目錄星標：SkillHub 與 GitHub 的 stars 會隨時間變化，以你安裝時打開的頁面爲準。
結尾¶
如果你已經在 DSH 裏接了好幾條線路，卻還在爲 Token 去向發愁，TokenLedger 值得一試：裝一條命令、刷新頁面，就能把用量拉到中轉站和工作目錄兩個維度上。它是社區裏把「算清楚」這件事做得比較完整的一塊拼圖，和官方 Harness 無隸屬關係，但和「一切皆插件」的生態方向很合拍。
- 目錄頁：https://www.skillhub.cn/plugins/zh667/TokenLedger
- GitHub：https://github.com/zh667/TokenLedger
- npm：
dsh-tokenledger
