前言¶

在 DeepSeek Harness（DSH）裏選模型，通常只能知道「接下來走哪條路由」，看不到 OpenCode Go、Grok、Command Code 等訂閱窗口還剩多少，也看不到這一輪對話到底消耗了多少 token。社區插件 dsh-quota（維護者 xuluoluo，GitHub 倉庫 xuluoluo/dsh-quota）把這兩塊補到客戶端：直接向各廠商自己的計費 / 用量接口拉快照，並在本地攔截 llm/stream 彙總 usage。實現思路參考 yetone/magpie 的 provider 層與 Usage 頁，但嵌入 DSH 的 composer、設置頁與憑據體系。

DSH 生態主張「一切皆插件」；SkillHub 目錄頁 是社區收錄站點，與 DeepSeek / 幻方無官方從屬關係。安裝前請自行閱讀源碼與許可證（倉庫 package.json 標明 MIT，當前版本 1.6.0）。

這是什麼¶

dsh-quota 是分類爲「客戶端」的 DSH 插件：在 Web 客戶端注入 composer 窄條、工作區信息、設置裏的「額度」頁，並在 Host 側註冊額度查詢、憑據寫入與用量統計。它不替你在 llm-pi-ai 裏接模型路由——加供應商只寫額度配置與 key（Grok 登錄除外），模型清單仍在 DSH 的 Models 頁維護。

沒有內置默認供應商：未配置時設置頁只有「還沒有供應商」和添加入口，避免界面出現模型選擇器裏並不存在的卡片。

核心功能¶

界面上的五塊¶

1. Composer 下方窄條（conversation.composer.dock）：常駐顯示各 provider 最緊窗口或餘額摘要，例如 OpenCode Go 35% · Grok ⚠100% · 今日 ≈$0.42；超閾值帶 ⚠，點擊可刷新。鼠標懸停用原生 title 展開各滾動窗口與重置時間。Composer 右側 chip 與窄條同源，默認關閉，需 showChip: true 才顯示。
2. Composer 左側兩格（conversation.input.left）：當前工作文件夾與 git 分支（非倉庫則提示「不在 git 倉庫裏」）；約 15 秒向 Host 同步，換會話會重查。
3. 設置 → 額度：三欄——額度（卡片、進度條、憑據保存 / 清除 / 測試）、用量（近 7 天 token、緩存命中、推理 token、按模型明細與估算花費）、輸入預測（開關、模型、提示詞）。
4. + 添加供應商：選預設、可選顯示名與 API key（Grok 需在卡片內設備碼登錄）；寫入 profile 的 cordis.patch.yml（插件 id dsh-quota），重啓仍保留。
5. 卡片頭路由狀態（只讀）：已接入模型 / 未接入模型 / 僅額度（Command Code 無可用聊天接口，只盯額度）。

額度數據來源¶

插件按 preset 調用廠商接口，例如：

告警默認：alertAt 90、alertCriticalAt 97 按最緊窗口；餘額卡用 balanceFloor（默認 5，同幣種單位）。

用量與花費¶

插件包裝 llm/stream waterfall：chunk 原樣下游傳遞，在成功結束前記錄最後一個 usage chunk 與 provider / model。數據寫入 $DSH_HOME/.quota-usage.json（默認 ~/.dsh/.quota-usage.json），保留 30 天，頁面展示近 7 天與今天。

花費由 build/prices.js 價目表按 USD / 百萬 token 估算，訂閱制 provider 的 dollar 數僅作橫向參考，不是賬單。可在配置裏用 prices 覆蓋單價。

憑據¶

祕密不落插件私有文件，走 DSH ctx.credentials：

• Grok：設備碼 OAuth，寫入 ~/.dsh/.credentials.yaml 的 llm-pi-ai/xai，與 dsh-llm-pi-ai 同形——在此登錄後 DSH 內可選 Grok 模型對話。
• OpenCode Go / Command Code：POST /quota/key 寫入憑據庫；Command Code 無 key 時可只讀 ~/.commandcode/auth.json。
• DeepSeek API：使用 DEEPSEEK_API_KEY，與 DSH 賬號餘額頁是兩套賬單。

七種預設：opencode-go、xai-billing、commandcode、deepseek-api、bailian、chatgpt、claude。

輸入預測（可選）¶

參考 dsh-prompt-suggestion 思路：在一輪迴答結束且輸入框爲空時，經 debounce 調用模型，在輸入框以灰字顯示下一行建議；Tab 或 → 填入，不自動發送。預測本身算一次真實模型調用，計入用量與花費。

安裝與啓用¶

從 GitHub 安裝（命令來自倉庫 README「六、安裝」；--profile 按你實際 profile 替換，文檔示例爲 desktop）：

dsh plugin --profile desktop add github:xuluoluo/dsh-quota

生效規則：客戶端 build/client.js 改動後刷新頁面即可；Host 側（index.js、providers.js 等）改動需重啓 DSH。

啓用後打開 設置 → 額度，用 + 添加供應商 按需添加 preset；無配置則保持空頁。

典型用法¶

1. 添加 OpenCode Go 或 DeepSeek API preset，在卡片憑據區粘貼 key 並保存，點「測試」確認 Host 能打到廠商接口。
2. 添加 Grok（xai-billing） 後，在卡片點「登錄 Grok」，在瀏覽器完成設備碼授權；窄條與額度頁會顯示訂閱窗口。
3. 使用 ChatGPT / Claude preset 時，確保本機已有 Codex / Claude Code 登錄文件；插件只讀額度，不寫 API key。
4. 在 用量 欄查看近 7 天 token 與 ≈$ 估算；composer 窄條看「今日」估算。
5. 需要 composer 右側 chip 時，在 cordis.patch.yml 的 dsh-quota 配置中加 showChip: true（完整可選字段見 README「七、配置」）。

可選配置片段（節選）：

- id: dsh-quota
  name: 'dsh-allowance'
  config:
    enabled: true
    refreshMs: 60000
    alertAt: 90
    alertCriticalAt: 97
    showChip: true
    predict:
      enabled: true
      debounceMs: 700

適用場景與注意¶

適合：同時在 DSH 裏混用多種訂閱或 API，希望在對話界面一眼看到額度餘量、本地 token 用量，並在接近上限時收到 ⚠ 提示；需要在 composer 旁看到當前目錄與 git 分支的開發者。

務必注意：

• 插件以當前 DSH Host 進程權限運行，會讀寫在憑據庫、調用外網計費接口、讀取 ~/.codex/auth.json 等本機文件。安裝前應審閱 源碼 與 README「八、HTTP 面」中的同源與安全說明：/quota/* 路由由 Host 直接註冊，本機其它進程理論上可讀額度數字（與「本機可讀 ~/.dsh/.credentials.yaml」同一威脅模型）。
• 添加供應商不會自動接入 Models 路由；卡片標「未接入模型」時需到 Models 頁自行配置。
• Grok 登錄會寫入 llm-pi-ai/xai 憑據；「退出登錄」會刪除該記錄。
• 阿里雲百鍊僅存儲 DASHSCOPE_API_KEY；要在該網關調模型需自己在 Models 頁加 OpenAI 兼容路由。

結尾¶

dsh-quota 把「還剩多少額度」和「已經用了多少 token」從廠商控制台和日誌裏搬到 DSH 界面，並與本地憑據、patch 配置對齊，避免模型選擇器與額度視圖各說各話。進一步細節（HTTP 路由表、測試命令、test/live-probe.mjs）見倉庫 README。

• 目錄頁：https://www.skillhub.cn/plugins/xuluoluo/dsh-quota
• GitHub：https://github.com/xuluoluo/dsh-quota