DeepSeek Harness 插件：側邊欄實時餘額 + 每輪對話花費

前言¶

DeepSeek Harness (DSH) 採用模塊化設計，鼓勵通過插件擴展功能。在開發或調試過程中，實時掌握賬戶餘額與單次對話的成本非常重要。dsh-deepseek-usage 插件旨在解決這一問題，它直接在 DeepSeek Harness 的側邊欄和對話底部展示相關數據。

插件簡介¶

名稱：@blackthunder2191026/dsh-deepseek-usage

維護者：BlackThunder2191026

定位：側邊欄實時餘額顯示 + 每輪對話花費（人民幣，含 token 明細）。

核心功能：
* 側邊欄餘額：在左下角顯示 DeepSeek 賬戶餘額，默認每 60 秒刷新一次。點擊可展開充值餘額 / 贈送餘額並手動刷新；側欄收窄成圖標欄時顯示爲彩色狀態點。
* 每輪對話花費：在每一輪對話底部的信息欄裏額外顯示這一輪花費的人民幣金額，點擊可展開三列明細（項目 / tokens / 單價）。

安裝¶

插件已發佈至 npm，包名爲 @blackthunder2191026/dsh-deepseek-usage。

方式一：命令行安裝（推薦）¶

npx @deepseek-ai/dsh plugin --profile desktop add @blackthunder2191026/dsh-deepseek-usage

安裝完成後需重啓 dsh 進程。

方式二：圖形市場安裝¶

在市場的搜索框查找 dsh-deepseek-usage。

方式三：從 GitHub 源碼安裝¶

npx @deepseek-ai/dsh plugin --profile desktop add github:BlackThunder2191026/dsh-deepseek-usage

注意：若使用 pnpm，可能需要在 pnpm-workspace.yaml 中配置 allowBuilds，因爲插件包含 prepare 鉤子（僅做文件完整性檢查）。

⚠️ 升級注意事項¶

如果之前安裝的是不帶 scope 的舊包 dsh-deepseek-usage，安裝新包後會出現兩套餘額欄。升級前需先移除舊包：

npx @deepseek-ai/dsh plugin --profile desktop remove dsh-deepseek-usage
npx @deepseek-ai/dsh plugin --profile desktop add @blackthunder2191026/dsh-deepseek-usage

配置與計費¶

配置項¶

配置文件位於 profile 的 cordis.patch.yml，行 id 爲 deepseek-usage。需整段替換而非深合併。

- id: deepseek-usage
  name: dsh-deepseek-usage
  config:
    apiKeyEnv: DEEPSEEK_API_KEY
    currency: CNY
    balanceTtlMs: 30000
    defaultModel: deepseek-flash
    maxTurns: 300
    models:
      deepseek-flash:
        hit: { peak: 0.04, offPeak: 0.02 }
        miss: { peak: 2, offPeak: 1 }
        output: { peak: 8, offPeak: 4 }
      deepseek-v4-pro:
        hit: { peak: 0.3, offPeak: 0.15 }
        miss: { peak: 9, offPeak: 4.5 }
        output: { peak: 27, offPeak: 13.5 }

計費邏輯¶

計價依據：來自官方 DeepSeek 中文定價頁，單位爲元/百萬 tokens。
計算公式：

    花費(CNY) = 未命中輸入 × miss價 + (緩存命中輸入 + 緩存寫入) × hit價 + 輸出 × output價

高峯/低谷：週一至週五 09:00-12:00 與 14:00-18:00 爲高峯，其餘時段爲低谷，高峯費率是低谷的兩倍。
生效範圍：只有已結束的輪次纔會計價。

注意事項與環境要求¶

環境要求：
- dsh：必須使用帶 Web 界面的 profile（desktop 或 web），headless 或 SDK profile 無效。
- Node.js：宿主版本需 >= 22.19。
- 憑據：需要官方 DeepSeek provider 的 DEEPSEEK_API_KEY（環境變量或 ~/.dsh/.credentials.yaml）。
平臺支持：不含平臺相關代碼，支持 Windows / macOS / Linux。
運行時依賴：零運行時依賴，host 半不 import 任何包，client 半隻依賴 dsh 的 react。
調試：
- Host 半代碼變動需重啓 dsh。
- Client 半代碼變動需刷新頁面（Ctrl+F5）。

常見問題¶

出現兩套餘額欄：舊版 dsh-deepseek-usage 與新版 @blackthunder2191026/dsh-deepseek-usage 同時安裝。請按上述升級步驟操作。
側邊欄沒有餘額行：檢查 profile 是否帶 Web 界面；或查看 curl "http://127.0.0.1:<端口>/deepseek-usage/summary?debug=1" 的響應。
餘額顯示不可用：未配置 DEEPSEEK_API_KEY 或未使用官方 DeepSeek provider。
安裝失敗提示只能安裝 npm 包：某些客戶端只接受 包名@精確版本，請使用方式一或方式四。

結語¶

該插件提供了 DeepSeek Harness 開發者所需的成本監控能力，直接在官方客戶端界面展示餘額與明細。更多細節與源碼可參考項目主頁。