前言¶
在 DSH 裏跑 QQ 橋接時，模型每回合都會留下 token 用量，但默認往往只能看到單次對話或全局日誌，很難回答「哪個羣、哪段私聊最費 token」「緩存命中率如何」「最近一週趨勢怎樣」。若只靠 grep 或手工彙總 token-usage.jsonl，成本高且不利於對比佔比與時段分佈。dsh-token-flow 是社區維護的 DSH 插件，只讀橋接寫入的用量文件，在 Harness 內提供表格、圖表與導出，把消耗按會話和時間去向可視化。
這是什麼¶
dsh-token-flow（維護者 xiaole3349，社區目錄分類爲「記憶」）定位是：統計各羣 / 私聊的 token 消耗與流向。數據來源是 QQ 橋接寫下的 token-usage.jsonl（每個回合一行，字段含 cacheHit、cacheMiss、output、reasoning）。插件只讀磁盤，不寫任何文件，也不修改會話狀態。
核心功能¶
裝好後通過 Harness 提供的 Web 頁面與 HTTP 接口查看聚合結果（具體路徑見下文「典型用法」）。
概覽頁（README 描述）包括：
- 按會話排序的表格：回合數、未命中、命中、輸出、總 token、命中率、均值、佔比
- 兩張餅圖：總 token 佔比、實付（未命中 + 輸出）佔比
- 各羣按天的多線圖、每日總量折線、未命中按天
- 峯 / 谷拆分、按小時分佈、最貴的 10 個回合
- 點擊某行進入該會話詳情；右上角可導出 CSV
HTTP 接口（與頁面同源，可用 days 篩選時間範圍）：
/dsh-token-flow/api?days=7（days=0表示全部歷史）/dsh-token-flow/csv?days=7/dsh-token-flow/detail?days=7&key=group:<羣號>
輔助邏輯（README 說明）：羣名優先從 SnowLuma 的羣列表讀取（緩存 10 分鐘），取不到時退回磁盤緩存。「峯 / 谷」按工作日 09:00–12:00、14:00–18:00 粗分，不查節假日表。
安裝與啓用¶
插件隨 DSH 生態以 bundle 形式安裝，官方 README 給出兩種方式，不要自行拼接未在文檔出現的安裝命令。
先在本地取得插件目錄（例如從 GitHub 倉庫 下載 release 或拷貝已解壓目錄），在該目錄下執行：
plugin_manager install_bundle <本目錄>
或將 patch 寫入 profile 的 cordis.patch.yml：
- insert:
- id: token-flow
name: dsh-token-flow
package.json 中聲明版本爲 0.1.0，許可證 MIT；入口爲 lib/index.js，bundle 補丁文件爲 cordis.patch.yml。
安裝完成後重啓或按你當前 DSH 流程加載插件，再訪問頁面與接口。
典型用法¶
- 確認 QQ 橋接已在運行，且持續向
token-usage.jsonl追加每回合記錄。 - 在瀏覽器打開
<DSH 地址>/dsh-token-flow，默認可按 README 使用最近 7 天等視圖（頁面內篩選與 API 的days參數一致）。 - 需要離線分析時，使用導出或 CSV 接口，例如：
<DSH 地址>/dsh-token-flow/csv?days=7
- 查看單個羣會話明細時，使用 detail 接口，
key形如group:<羣號>：
<DSH 地址>/dsh-token-flow/detail?days=7&key=group:<羣號>
- 程序化拉取 JSON 聚合：
<DSH 地址>/dsh-token-flow/api?days=7
將 <DSH 地址> 替換爲你實際部署的 Harness 基址。
適用場景與注意¶
適合：已在 DSH 中使用 QQ 橋接、並希望按羣 / 私聊對比 token、命中率與時間分佈的開發者或運維；需要 CSV 或 API 做二次統計的場景。
注意：
- 無
token-usage.jsonl或橋接未寫盤時，頁面無有效數據；插件不會代寫該文件。 - 羣名依賴 SnowLuma 羣列表與本地緩存，名稱可能短暫與 QQ 客戶端不一致。
- 峯 / 谷劃分是工作時段 heuristic，不適合作爲計費或 SLA 的唯一依據。
- 插件以當前 DSH 進程權限讀盤並提供 Web 路由；安裝前應閱讀 源碼與 MIT 許可，確認路徑與數據範圍符合你的部署策略。DSH 社區插件目錄（SkillHub 條目）爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-token-flow 把橋接已有的 token-usage.jsonl 轉成會話維度的表格、圖表與導出，只讀、不碰會話，適合在 Harness 內快速看清 token 流向。進一步瞭解可訪問社區目錄頁與 GitHub 倉庫：
- https://www.skillhub.cn/plugins/xiaole3349/dsh-token-flow
- https://github.com/xiaole3349/dsh-token-flow
