前言¶

在 DeepSeek Harness（DSH）裏跑 OpenCode Go 或 DeepSeek 官方 API 時，常見用量面板只能回答「已經花了多少」。訂閱窗口還剩多少百分比、按當前速度月底會到多少、DeepSeek 餘額還能撐幾天——這類問題要靠自己翻日誌或心算。下面介紹社區插件 用量羅盤（dsh-usage-compass），它在 DSH 設置頁聚合本機會話統計，並接上餘額與趨勢預測；統計來自 ~/.dsh/sessions，Key 與餘額查詢只在 DSH 宿主進程裏完成，不進入瀏覽器。

這是什麼¶

用量羅盤 是 DSH 設置頁插件，維護者爲 CHengShan-deep。支持 OpenCode Go 訂閱與 DeepSeek 官方 API，並提供可選的自定義來源接入，把其它插件或腳本推送的用量併入同一看板。分類上可歸入 模型推理 相關工具；當前 GitHub 星標爲 0，許可證爲 MIT，package.json 版本爲 0.5.0，要求 Node >= 22.19、DSH >= 0.2.1-rc.5。

和「只顯示已用額度」面板的區別¶

用量羅盤在總覽之外，側重回答：

1. 按當前速度，本窗口/月底大約到多少百分比？
2. 訂閱預計何時撞到 100% 月額度？
3. DeepSeek 餘額按近 30 天日均，還能用大約幾天？
4. 當天按小時消耗分佈；近 24 小時跨天時，標籤是否帶日期以便區分「昨天」時段。

花費按內置價目表估算（OpenCode Go 美元、DeepSeek 官方人民幣峯谷），並非「訂閱不計費」的假設。

核心功能¶

餘額與總覽¶

• 餘額卡片：OpenCode Go 滾動 / 本週 / 本月；DeepSeek 官方贈送、充值、可用餘額。
• 用量總覽：請求數、輸入 / 緩存讀取 / 緩存寫入 / 輸出 Tokens、緩存命中率。

趨勢與預測¶

• 趨勢：Tokens / 請求 / 成本 / 預測 四視圖；當天按小時，7 / 14 / 30 天 / 全部按自然日；縱軸自動用億 / M / K 分檔。
• 預測（在 成本 右側）：
• 訂閱：按當前套餐窗口趨勢，預測到重置日的百分比，並給出預計達 100% 的日期。
• DeepSeek 官方：按最近 30 天日均預測未來 30 天花費；虛線表示當前餘額，餘額刷新會移動虛線。

明細、篩選與時間¶

• 明細排行：會話 / 工作區 / 模型，默認活躍優先，可切換用量優先，每頁 10 條。
• 篩選：會話、工作區、供應商、模型下拉與搜索。
• 時間範圍：當天 / 近 24 小時 / 近 7 / 14 / 30 天 / 全部 / 自定義月曆。
• 請求日誌：每頁 10 條，支持頁碼跳轉。

供應商卡片¶

默認展示 OpenCode Go、DeepSeek 官方及 DSH 已配置供應商；每頁 2 張卡，滾輪翻頁；點擊卡片切換當前供應商；「+」打開 DSH 模型設置新增第三方供應商。

自定義來源¶

默認只統計 DSH 會話。頂部「來源」裏其它項需勾選後才計入總請求、Tokens、成本、趨勢與日誌，便於把外部工具的用量併入同一羅盤，而不僞裝成全進程自動抓包（插件無全局網絡鉤子，也不讀取其它插件的 API 響應）。

安裝與啓用¶

插件以當前 DSH 進程權限運行，安裝前建議在 GitHub 查看源碼與 MIT 許可證。DSH 0.2.1-rc.5 起尚無官方公共插件市場，Discover 依賴用戶自行添加 market index。

方式 A：自定義市場索引（推薦）¶

1. 打開 Plugins → More（Experimental plugins），啓用 Custom plugin markets。
2. 在 Discover 索引中添加：

https://raw.githubusercontent.com/CHengShan-deep/dsh-usage-compass/main/market/index.json

3. 搜索 用量羅盤、Usage Compass、usage forecast 或 預測 並安裝。
4. 安裝後重啓 DSH，或按當前熱重載策略刷新頁面。

方式 B：從 Git 安裝¶

dsh plugin --profile desktop add git+https://github.com/CHengShan-deep/dsh-usage-compass.git

重啓後，設置左側會出現「用量統計」。若曾使用舊版 dsh-usage-statistics，需先移除 local-plugins 與 cordis.patch.yml 中的舊 usage-statistics 條目，避免同 id 重複註冊。

方式 C：本地插件目錄¶

將倉庫拷貝到 ~/.dsh/profiles/desktop/local-plugins/dsh-usage-compass，並在 ~/.dsh/profiles/desktop/cordis.patch.yml 末尾按 README 示例插入 usage-statistics 條目（含 refreshSeconds、balanceSeconds、requestsLimit 等可選配置）。

典型用法¶

在設置頁查看¶

安裝並重啓後，從 DSH 設置進入「用量統計」，切換供應商卡片、時間範圍與趨勢視圖即可。瀏覽器只請求插件路由 /plugins/dsh-usage-statistics/data，餘額由宿主拉取：

其它插件推送用量（推薦：宿主內 audit）¶

同一 DSH 進程內的插件可直接取服務，無需 HTTP：

const audit = ctx.get('usageAudit')
if (audit !== undefined) {
  await audit.ingest({
    source: { id: 'ai-review', label: 'AI 審覈插件', kind: 'plugin' },
    events: [{
      time: Date.now(),
      provider: 'deepseek-official',
      model: 'deepseek-v4.1-flash',
      input: 1200,
      cacheRead: 3000,
      cacheWrite: 0,
      output: 300,
      cost: 0.0021,
      currency: 'CNY',
      sessionId: 'review-2026-11-08',
      title: '命令審覈',
      workspace: 'L:/work/project',
    }],
  })
}

ctx.get('usageAudit') 無需寫入 inject；服務不可用時爲 undefined，可安全跳過。

本地 HTTP 推送（MCP、腳本等）¶

POST http://127.0.0.1:<DSH Web 端口>/plugins/dsh-usage-statistics/ingest
Content-Type: application/json
X-Usage-Token: <配置了 ingestToken 時必填>

單次最多 100 條事件；外部寫入持久化在 ~/.dsh/storages/dsh-usage-compass/events.jsonl。input 表示未命中緩存的輸入 Tokens，勿與緩存命中部分混傳。

可選配置¶

在 cordis.patch.yml 的 config 中可覆蓋：

OpenCode Go 與 DeepSeek 官方已內置價目表；其它供應商可用 pricing 補單價，否則可能不計入估算花費。

數據口徑與安全¶

• 會話數據來自 ~/.dsh/sessions 的 assistant/chunk、assistant/message usage，按 turn/step 去重；Tokens 合計含輸入、緩存讀/寫與輸出。
• 不把 API Key 發給瀏覽器；餘額僅宿主訪問；插件路由監聽迴環並校驗 Origin / Referer。
• 只統計本機會話，不彙總其它機器；預測爲線性趨勢估算，非賬單承諾；OpenCode Go /usage 未公開文檔化，字段變化時可能顯示讀取失敗但不致崩潰。

適用場景與注意¶

適合在本機長期用 DSH 調用 OpenCode Go 或 DeepSeek 官方、需要統一看板又希望 Key 留在宿主側的開發者。若還需把 CI、MCP 或其它插件的調用記入同一羅盤，用 ingest 主動推送即可。

社區目錄 SkillHub 插件頁 與 GitHub 倉庫並列收錄，與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，本文安裝與配置均以倉庫 README 爲準。

源碼與問題反饋：https://github.com/CHengShan-deep/dsh-usage-compass