前言¶
在 DeepSeek Harness（DSH）裏跑智能體，會話一多，很難從服務商賬單或粗略的 input/output 數字還原「本機實際花了多少 token」。緩存讀寫在真實日誌裏往往遠大於新鮮輸入；seed、fork、子智能體還會讓同一條 message.id 出現在多個日誌文件裏，簡單相加會重複計數。下面介紹社區插件 花費（xiaobaga281/dsh-token-spend）：在本機設置頁增加一頁「花費」，直接讀已提交的會話日誌做日彙總與可視化，不聯網、不讀賬單、不另建業務數據庫。
這是什麼¶
花費 是 DSH 的 admin-security 類設置頁插件，維護者爲 xiaobaga281。npm 包名爲 @local/dsh-token-spend，當前發佈版本 1.0.0（MIT © 2026）。它在宿主側註冊聚合接口，在 Web 客戶端注入設置頁 UI，解決的是：按服務商意義上的全部 token（輸入 + 緩存讀 + 緩存寫 + 輸出）統計用量，按消息 ID 去重，並在會話被永久刪除後仍保留已記錄的花費。
核心功能¶
插件讀本機已提交的會話日誌，在設置頁展示以下內容（均來自本地派生，無外部請求）：
- 全部用量：四類 token 合計，對齊服務商
totalTokens，而非僅 input + output。 - 今日 / 昨日：頂部展示今日用量及與昨日環比。
- 用量構成：輸入、緩存讀、緩存寫、輸出四類佔比條。
- 14 天趨勢與每日熱力圖：按本地日曆日分桶；點色塊可查看當天明細。
- 當天明細：按會話、按模型列出花費，並展示緩存命中率。
- 預算條：日預算參照。未配置
budgetTokens時，按歷史最忙一天的用量 ×1.25 取整推算。 - 已刪除會話：永久刪除會移除會話目錄，純日誌總量會「改寫歷史」；插件用日賬本保留已見過的用量，並在頁面上單列這部分佔比。
兩條計數規則¶
- 一次調用只記一次。 同一
message.id可能因 seed / fork / 子智能體繼承事件前綴而出現在多個文件；用量按該 id 只計一次。 - 緩存讀不算輸入。 服務商的
inputTokens不含緩存讀取；若只用 input + output，相對真實全部用量可能嚴重低估。本插件按日誌中的完整字段統計。
摺疊結果按會話的 snapshot.revision 緩存，刷新時只重讀有變化的日誌。內存側默認緩存約 30 秒（見配置 cacheTtlMs）。
已刪除會話的賬本¶
賬本僅保存計數器，不含標題、路徑或消息正文，默認路徑爲：
<DSH_HOME>/storages/token-spend/ledger.json
寫入採用「臨時文件 + rename」的原子替換，避免寫壞時抹掉已有記錄。若不需要保留已刪會話的花費，可將 retainDeleted 設爲 false。
HTTP 接口¶
| 方法 | 路徑 | 說明 |
|---|---|---|
GET |
/token-spend/summary |
返回聚合結果；查詢參數 ?refresh=1 可跳過約 30 秒的內存緩存 |
返回字段包括 totals、days、sessions、models、today、budget、cacheHitRate、retainedDeleted 等（以倉庫 README 爲準）。
安裝與啓用¶
DSH 生態裏插件通常通過 Plugin Manager 的 install_bundle 安裝包目錄或發佈包，或將其加入 profile 的 bundle 列表。不要憑插件名自行拼接未在文檔中出現的 CLI 安裝命令。
發佈包可在插件倉庫根目錄打包：
npm pack
產物示例爲 dsh-token-spend-1.0.0.tgz（以 package/ 爲包根）。包內包含 index.js、client.js、cordis.patch.yml、locale、icon.svg 等（見 package.json 的 files 字段）。
說明：宿主側（index.js）改動後需重啓 DSH 應用；客戶端（client.js）隨設置頁重新加載即可。運行環境要求 Node.js >= 20。
cordis.patch.yml 會向 Loader 插入 token-spend 相關行，由 bundle 機制掛載到現有 DSH 宿主。
配置項¶
在插件配置中可調整以下鍵（默認值以 README 爲準）：
| 鍵 | 默認 | 說明 |
|---|---|---|
budgetTokens |
0 |
日預算 token 數；0 表示按歷史峯值自動推算 |
cacheTtlMs |
30000 |
聚合結果的內存緩存時長（毫秒） |
retainDeleted |
true |
是否在賬本中保留已刪除會話的用量 |
ledgerPath |
<DSH_HOME>/storages/token-spend/ledger.json |
日賬本文件路徑 |
典型用法¶
- 按上文方式通過 Plugin Manager 或 profile bundle 安裝並啓用插件，必要時重啓宿主。
- 打開 DSH 設置，進入插件提供的 「花費」 頁（顯示名來自
displayName與 locale）。 - 查看今日用量、構成、14 天熱力圖與當天明細；需要強制重算時，可調用
GET /token-spend/summary?refresh=1（例如自行腳本或調試工具，需具備訪問本機 DSH 宿主的權限）。 - 若需固定日預算參照線，將
budgetTokens設爲大於 0 的整數；若不希望保留已刪會話歷史，設retainDeleted: false。
插件不替代服務商賬單，只反映本機日誌與賬本中的統計結果。
適用場景與注意¶
適合：在本機 DSH 中長期開發、調試智能體，需要看清緩存讀寫佔比、避免重複計數、並在刪會話後仍能對齊歷史花費的開發者。
注意：
- 插件以當前 DSH 進程權限讀取會話日誌並寫入
ledgerPath；安裝前應閱讀 GitHub 源碼 與 MIT 許可證，確認符合你的安全策略。 - 社區目錄 SkillHub 插件頁 與 GitHub 倉庫由維護者發佈，與 DeepSeek / 幻方無官方從屬關係；DSH 理念是「一切皆插件」，本文介紹的是社區插件而非內置功能。
- 統計依賴本地已提交日誌的完整性與字段；若日誌格式或 DSH 版本與插件假設不一致，展示結果可能不完整，應以倉庫 Issue 與版本說明爲準。
結尾¶
花費 把「全部 token、按 message.id 去重、刪會話不丟賬」三件事收進一頁設置 UI 和一個可選的 ledger.json，適合作爲 admin-security 類本地用量面板。進一步瞭解可訪問目錄頁與倉庫：
- 目錄頁：https://www.skillhub.cn/plugins/xiaobaga281/dsh-token-spend
- GitHub：https://github.com/xiaobaga281/dsh-token-spend
