前言¶
在 DeepSeek Harness（DSH）裏跑智能體，模型調用會分散在普通對話、重試、上下文壓縮和不同 provider 路由之間。provider 控制檯能看到賬單，但很難對照「哪次會話、哪條路由、壓縮佔了多少」；本地會話 projection 裏也可能混着舊版無法按日歸因的用量。若要在本機做預算預警、趨勢對比或單會話軌跡審計，通常得自己寫統計腳本，且很難與 DSH Web 設置頁集成。
dsh-token-usage 是社區維護者 LeemanCheung 發佈的 DSH 插件，在 Web profile 下被動觀察 Host 側事件，持久記錄四類 Token bucket，並提供儀表盤、預算、公開費率估算、聚合導出，以及按需觸發的 AI 用量分析與會話軌跡報告。插件當前在 GitHub 有 12 stars，SkillHub 分類爲「記憶」。
這是什麼¶
一句話定位：面向 DeepSeek Harness 的本地優先 Token 可觀測性、預算與軌跡審計插件。
它解決的核心問題是：在不攔截模型請求的前提下，把未緩存輸入、輸出、緩存讀取、緩存寫入四類 bucket 記賬到可恢復的會話 projection，並在 設置 → Token 用量 頁面集中展示趨勢、預算、效率指標與會話級下鑽。USD 數字按內置靜態公開費率估算，不冒充 provider 賬單；AI 分析與軌跡報告須用戶顯式啓動，且只發送有界聚合 DTO 或白名單軌跡元數據。
許可證爲 MIT。完整說明見 GitHub 倉庫 與 SkillHub 目錄頁。SkillHub 是獨立社區目錄，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
精確記賬與多維聚合¶
Host 側觀察普通模型請求、重試和壓縮事件，構建可恢復的會話統計 projection。reasoningTokens 已包含在輸出中，不重複計算。流式 usage 先記爲臨時值，同一 attempt 內最終消息會覆蓋它；重試與上下文壓縮獨立計數。可按 provider / model、會話與 UTC 日期聚合；舊用量無法歸因時單獨披露，不破壞總量守恆。
統計口徑（摘自 README）：
| 指標 | 計算方式 |
|---|---|
| 輸入 Token | uncachedInputTokens + cacheReadTokens + cacheWriteTokens |
| 總 Token | 輸入 Token + outputTokens |
| 緩存讀取佔輸入 | cacheReadTokens / 輸入 Token（Token 結構比例，非請求級緩存命中率） |
| 壓縮 Token | 所有 compaction/summary provider usage 的四個 bucket 之和 |
| 每次模型嘗試 Token | (總 Token - 壓縮 Token) / assistantRequests；重試算獨立嘗試 |
概覽、趨勢與活躍度¶
儀表盤提供八項概覽指標：總量、輸入、輸出、緩存結構、公開費用、緩存讀取避免費用、費率覆蓋和有用量會話數。最近 30 周 UTC 日熱力圖支持四類 bucket 懸停與按日會話下鑽。週期趨勢可切換 7 / 30 / 90 日窗口，查看總量、環比、活躍天數與峯值日。
運行率、預算預測與異常檢測僅在逐日 bucket 完整可靠時啓用，避免舊版合成日期造成低估。運行率取最近 7 個完整 UTC 日（不含今天）的日均，乘以 30 得到滾動預測；異常檢測將昨天與此前 28 日內至少 5 個活躍基線日的中位數 / MAD 比較，異常日可下鑽會話貢獻。
預算與 Agent 效率¶
滾動 30 日 Token 預算寫入本機 DSH settings（token-usage.rolling30DayBudget）。預算開啓且逐日覆蓋完整時，界面顯示消耗比例、按當前運行率的 30 日預測及可能超額提示；填 0 或清空可關閉。插件只展示證據，不會阻止模型調用。
Agent 效率區展示模型嘗試數、每次嘗試 Token、每 100 次嘗試壓縮數、壓縮 Token 佔比、緩存讀取佔輸入、Top 1 / Top 3 路由集中度及未歸因比例。
公開價格估算¶
成本按內置靜態公開費率（USD / 1M Token）計算，當前 README 列出的匹配範圍包括 OpenAI 側 gpt-5、gpt-5-mini、gpt-5-nano、gpt-4.1 系列及 gpt-4o 等標籤。界面標明費率基準日、Token / 路由覆蓋與未覆蓋項；未覆蓋路由顯示 —。
AI Token 用量分析（按需、opt-in）¶
用戶從儀表盤選擇目錄預選的默認 / 首個路由，或改選任一當前可列出的已接入 provider / model，點擊生成後纔會調用模型。報告覆蓋總量、壓縮、緩存、路由貢獻、可靠日趨勢、峯值、波動與 Token 優化建議；按 Markdown 渲染並可導出。生成過程顯示準備 / 生成 / 整理階段；provider usage 到達前標註估算值，到達後切換精確值。模型目錄可手動刷新；單個 provider 枚舉失敗不影響其他路由。聚合 AI 用量報告不會持久化。
會話軌跡分析¶
可從設置頁會話列表或對話頁標題操作區啓動同一 Host 流程，支持 live 與冷會話。分析調用節點、重試、壓縮、工具可靠性、速率、生命週期和 Token 對賬，並含合規控制審計（審批請求與決定配對統計）。報告強制區分觀測證據、風險假設與不可用證據。軌跡報告在當前瀏覽器 localStorage（鍵名 dsh-token-usage.trajectory-history.v1）中最多保存 24 條，界面按當前會話過濾並可刪除。
聚合導出¶
可導出不含會話正文和標題的 JSON v2、每日 CSV 與模型 CSV。CSV 單元格防公式注入；JSON 與模型 CSV 帶公開費率覆蓋和已覆蓋路由估算。
設計邊界¶
- 被動賬本：不攔截請求，不改寫路由。
- 按需 AI：提示詞、回覆、標題、路徑、工具參數和原始 provider / model 不會進入模型證據。
- 估算非賬單：USD 與審批統計均不替代 provider 賬單、策略執行或認證審計。
- 隱私：持久 projection 只保存統計數據；私有 RPC 僅允許 loopback 頁面。
安裝與啓用¶
插件需要掛載完整 Client 服務的 DSH Web profile，依賴 DSH 0.1.0-rc.6 系列的 session、LLM、settings、projection 和 Web UI 服務。CLI 或非 Web profile 不提供儀表盤。
官方安裝命令如下。安裝後重啓當前 dsh web 進程並刷新 http://127.0.0.1:3080，再打開 設置 → Token 用量。
dsh plugin --profile web add github:LeemanCheung/dsh-token-usage
本地源碼開發時，可在插件目錄上一級執行：
dsh plugin --profile web add ./dsh-token-usage
卸載命令：
dsh plugin --profile web remove dsh-token-usage
卸載後重啓 dsh web 並刷新頁面。卸載是移除插件掛載，不是數據重置；若要減少本地殘留，可先刪除軌跡歷史報告、將預算清零，再按 DSH 自身 session / cache 策略處理 projection 數據。
典型用法¶
查看全局用量與趨勢¶
- 完成安裝並重啓
dsh web。 - 打開 設置 → Token 用量。
- 在概覽卡片查看總量、輸入 / 輸出、緩存結構與公開 USD 估算。
- 在 30 周熱力圖上懸停查看四類 bucket，點擊方格下鑽當天會話。
- 切換 7 / 30 / 90 日週期趨勢，對照環比與峯值日。
設置預算並觀察運行率¶
在 30 日預算區填入 Token 上限（寫入 token-usage.rolling30DayBudget）。當全部納入統計的會話都有真實逐日 bucket 時，界面會顯示滾動消耗比例、按當前運行率的 30 日預測及超額提示。覆蓋不完整時會標明相關指標不可用。
生成 AI 用量優化報告¶
- 在 AI Token 用量分析 區確認或刷新模型目錄。
- 選擇要用於分析的已接入 provider / model（默認使用目錄預選路由）。
- 點擊生成，等待準備 / 生成 / 整理階段完成。
- 閱讀 Markdown 報告，必要時導出。
選擇的路由只在用戶點擊生成後調用；目錄失敗可重試，不會靜默改用默認模型。
單會話軌跡分析¶
- 在會話記錄表第一列點擊軌跡分析，或從對話頁標題操作區進入同一流程。
- 查看四組確定性摘要：調用節點、重試、壓縮、工具與 Token 對賬等。
- 導出報告或在瀏覽器本地歷史中按會話過濾、刪除舊報告（最多 24 條）。
導出聚合數據¶
在聚合導出入口選擇 JSON v2、每日 CSV 或模型 CSV。導出內容不含會話標題與正文，適合外部分析或存檔；注意 JSON / 模型 CSV 中的費用仍爲公開費率估算。
適用場景與注意¶
適合誰
- 在 DSH Web 中長期跑智能體，需要本機 Token 結構、路由集中度與壓縮開銷的可視化。
- 需要滾動預算與異常日提示，但接受「僅展示證據、不攔截調用」的設計。
- 要對單會話做軌跡與審批事件審計，且願意按需觸發 AI 分析、接受白名單元數據邊界。
使用前注意
- 插件以當前
dsh進程權限運行；安裝前應閱讀源碼與 MIT 許可證，確認符合本機安全與合規要求。 - 僅 Web profile 可用；無 Web UI 的環境無法使用儀表盤。
- 舊版 projection 缺少逐日數據時，歷史總量仍保留，但運行率 / 異常等口徑會排除不完整日期。
- 公開費率表覆蓋有限，未匹配路由的費用顯示爲
—；勿將界面數字當作 provider 賬單。 - AI 用量分析與軌跡分析會向所選模型發送聚合或白名單數據；雖不含會話正文，仍屬 opt-in 操作。
結尾¶
dsh-token-usage 把 DSH 本地的 Token 事件收成可恢復的 projection，並在 Web 設置頁提供儀表盤、預算、導出與兩類按需分析報告。若你已在 Web profile 下使用 DSH，且需要可下鑽的用量賬本而非事後查賬單，可按上文命令安裝並在 設置 → Token 用量 啓用。
