前言¶

在 DeepSeek Harness（DSH）裏跑智能體會話，token 會按輪次、按模型持續累加。宿主可能提供用量摘要，但若你想在本地長期對照「安裝前累計」與「安裝後逐輪記錄」、按周/月/天篩出明細，並堅持四桶口徑與逐位精確數字，往往還需要單獨記賬或導出後再處理。

下面介紹的 dsh-token-ledger（維護者 6600788，社區分類 admin-security）是 DSH 側邊欄插件：在左側欄增加「Token 賬本」入口，打開完整統計頁。數據只寫在當前機器，不上報、不聯網。當前版本 1.2.0（MIT），倉庫地址：github.com/6600788/dsh-token-ledger；插件目錄頁：skillhub.cn/plugins/6600788/dsh-token-ledger。

插件定位¶

dsh-token-ledger 訂閱 DSH 會話側的 token 事件，落盤爲本地賬本，並通過迴環 HTTP 接口供統計頁查詢。它與 DSH 官方無綁定關係；社區插件目錄爲獨立站點，啓用方式遵循 profile 裏的 bundle 註冊，而非「官方應用商店」一鍵安裝。

前置條件（摘自 README 與 package.json）：

• Node >= 18
• DSH >= 0.1.5-rc.1
• 一個已配置、可正常啓動的 DSH profile

核心功能¶

兩個獨立賬本（之前 / 現在）¶

頂部兩張卡片對應彼此獨立的賬本，點擊可只查看其中一本：

baselineAt 默認是插件首次啓動時刻，寫在 ~/.dsh/token-ledger/ledger.json（DSH_HOME 可覆蓋路徑）。分界在讀取時計算，不改寫、不刪除事件，可隨時移動或恢復默認；兩本相加始終等於合計。

頁面頂部按鈕支持：刷新、暫停刷新、補導歷史、導出賬本；還可通過接口移動分界或清空實時記錄（見下文 HTTP 路由）。

四桶口徑與精確數值¶

合計按 DSH 官方 tokenUsage 四桶相加：

total = inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens

• inputTokens 與 uncachedInputTokens 爲別名，只取其一。
• reasoningTokens 屬於 outputTokens 子集，單獨展示、不重複累加。
• 安裝前 whale 歷史往往只有總量、無四桶拆分，故「之前」賬本書的四桶顯示可能爲 0 而總量有值；「現在」從第一條實時記錄起四桶齊全。頁面構成條會註明「四桶之和可能小於合計」。

頁面上 token 數一律使用賬本原始整數，僅加千分位分隔符，不用 K/M/B 縮寫，不做四捨五入或估算。

全局篩選與頁面區塊¶

篩選對 KPI、構成條、趨勢圖、按會話/模型/周月表、消耗明細同步生效：

• 快捷：全部時間、今天、本週、上週、本月、上月、近 7 天、近 30 天
• 自定義日期區間、任選 ISO 周或自然月
• 「清除篩選」回到全部

統計頁還包含兩本賬卡片、消耗構成與趨勢、按會話/按模型/按周月彙總、可搜索的消耗明細，以及「統計口徑」說明區。明暗主題跟隨宿主，樣式使用 --dsw-alias-* 變量。

輪詢、ETag 與本地回退（v1.2.0）¶

頁面默認每 5 秒輪詢，可暫停。宿主對 data.json / query.json 按 revision 緩存並生成強 ETag；客戶端帶 If-None-Match 時，數據未變可返回 304 且無 body，避免重複下載大 JSON。標籤頁不可見時跳過定時請求，重新可見時立即刷新一次。

若宿主版本較舊、/query.json 返回 404，client.js 會改拉 /export.json 在瀏覽器本地做與宿主相同的聚合，並在篩選欄標註「頁面本地統計」。宿主重啓後自動切回服務端聚合。

數據與隱私¶

• 賬本：~/.dsh/token-ledger/ledger.json（原子寫：先 .tmp 再 rename）
• 事件超過 20000 條時，前半歸檔到 events.archive.json
• 會話數上限 4000，超出按最久未活躍淘汰
• 全部本地保存；HTTP 路由僅迴環 + 同源放行，並受 DSH_TOKEN_LEDGER_HOSTS 等信任柵欄約束

安裝與啓用¶

官方 README 給出的步驟如下：先把倉庫放到 profile 的 plugins 目錄，再在 package.json 裏以 link: 註冊 bundle。

# 1) 把倉庫放到 profile 的 plugins 目錄
git clone https://github.com/6600788/dsh-token-ledger.git \
  ~/.dsh/plugins/dsh-token-ledger

# 2) 在 profile 的 package.json 裏註冊（路徑按實際位置調整）
#    dependencies:
#      "dsh-token-ledger": "link:../plugins/dsh-token-ledger"
#    dsh.profile.bundles:
#      - "dsh-token-ledger"

也可通過 DSH 插件管理命令啓用已安裝的 bundle；啓用後 profile 的 dsh.profile.bundles 會追加 dsh-token-ledger，依賴以 link: 指向插件目錄。

啓動行爲：

• 僅 client 變更：刷新 GUI 即可看到新界面。
• host（lib/index.js）變更：完全退出 DSH（含托盤）再重啓，使 /query.json、/baseline 等路由生效。

典型用法¶

打開統計頁¶

啓用 bundle 並啓動 DSH 後，在左側欄點擊「Token 賬本」進入統計頁。可用頂部快捷篩選查看「本週」或「近 30 天」消耗，或在「消耗明細」中按會話、模型搜索。

從現在重新起賬¶

需要把「現在」賬單獨清零分界、又保留歷史總量時，可在頁面操作中移動分界（等價於 POST /dsh-token-ledger/baseline）。恢復默認分界則回到首次啓動時刻。

補導安裝前 whale 歷史¶

若首次導入不完整，可點「補導歷史」，或調用：

# 需通過 GUI 同源或迴環訪問，具體 Origin 以宿主打印的 GUI 地址爲準
curl -X POST "${GUI_ORIGIN}/dsh-token-ledger/import-history"

導出與自檢接口¶

curl "${GUI_ORIGIN}/dsh-token-ledger/health.json"
# 示例字段：ok、plugin、version、revision、baselineAt

curl "${GUI_ORIGIN}/dsh-token-ledger/query.json?group=all"
# 含 groups / weeks / months / facets 的聚合 JSON

條件請求輪詢示例（摘自 README）：

curl -i "${GUI_ORIGIN}/dsh-token-ledger/health.json"

curl -i -H 'If-None-Match: "<etag>"' \
  "${GUI_ORIGIN}/dsh-token-ledger/query.json?group=all"

開發者在倉庫根目錄可運行 npm test 做語法檢查與 exact / mock-host / parity 等套件迴歸。

適用場景與注意¶

適合誰： 需要在 DSH 內長期覈對 token、區分安裝前後兩段用量、按周月復盤模型與會話消耗，且希望數字與官方四桶口徑一致、不做縮寫的開發者或團隊。

安全與權限： 插件以當前 DSH 進程權限運行，能讀寫 ~/.dsh 下賬本與會話相關數據。安裝前應閱讀 lib/index.js、lib/client.js 與 LICENSE，確認路由信任柵欄與數據來源（僅 whale 賬本導入路徑等）符合你的環境策略。POST /dsh-token-ledger/reset 清空實時記錄需 {"confirm":true}，操作前建議先 export.json 備份。

生態說明： DSH 倡導「一切皆插件」；本插件爲社區貢獻，星標與活躍度以倉庫現況爲準，本文不引用未在資料中出現的用戶案例或反饋數據。

結尾¶

dsh-token-ledger 把 token 用量做成可篩選、可導出、雙賬本劃分的本機賬本，並強調四桶精確計數與 304 條件輪詢。若你在用 DSH 做智能體開發，可從目錄頁與 GitHub 獲取源碼與更新說明：

• 目錄頁：https://www.skillhub.cn/plugins/6600788/dsh-token-ledger
• 倉庫：https://github.com/6600788/dsh-token-ledger