前言¶

DeepSeek Harness (DSH) 的核心設計理念是「一切皆插件」。在通過 Web GUI 進行本地開發或調試時，實時掌握 DeepSeek 賬戶餘額、當前會話的 Token 消耗以及上下文佔用情況，是控制成本和調試模型行爲的基礎。

dsh-session-balance 插件專門解決這一問題。它不改變會話狀態，也不發起模型請求，而是在 DSH Web GUI 的會話標題欄右側掛載一個餘額徽標。點擊展開後，可以查看賬戶餘額明細、會話 Token 用量統計、上下文壓力（Context Pressure）以及基於當前模型單價的費用估算。

核心功能¶

該插件通過宿主與瀏覽器的協作實現數據展示：

1. 賬戶餘額：通過調用 DeepSeek GET /user/balance 接口，獲取賬戶總額、充值餘額、贈送餘額及可用狀態。
2. 會話用量：讀取會話投影（Projection）中的 tokenUsage（細分爲未緩存輸入、緩存讀取、緩存寫入、輸出）與 sessionStats（輪次、步驟、模型耗時）。
3. 上下文壓力：讀取 contextPressure 數據，顯示已用 Token 與窗口限制的佔比。
4. 費用估算：在瀏覽器本地，根據當前選中的模型單價（modelSelection 投影）將 Token 數量換算爲 CNY（元）。
5. 安全設計：全程只讀。API Key 僅在宿主進程內使用，不會寫入前端響應；路由僅接受同源 GET/HEAD 請求，防止跨域調用。

安裝與啓用¶

插件由「宿主插件」和「瀏覽器插件」兩部分組成，需要安裝到當前使用的 web profile 中。

1. 添加插件包¶

將插件目錄以軟鏈方式加入 profile：

dsh plugin --profile web add link:/path/to/dsh-session-balance

注：link: 表示軟鏈，修改代碼後重啓 dsh web 即可生效。若需固定副本，可使用 file:/path/to/dsh-session-balance。

2. 掛載插件行¶

編輯 profile 配置文件 ~/.dsh/profiles/web/cordis.patch.yml，添加插件行。該文件默認爲空列表，直接追加即可：

- insert:
    - id: session-balance
      name: 'dsh-session-balance'

3. 重啓服務¶

重啓 DSH Web 服務以加載插件：

dsh web

刷新 Web GUI（通常是 http://127.0.0.1:3080）後，會話標題欄右側應出現餘額徽標。

配置參考¶

所有配置項均爲可選，通過 config 字段覆蓋默認值。

基礎配置¶

顯示開關¶

模型單價覆蓋（Pricing）¶

插件內置了 DeepSeek 官方定價的默認值，但單價可能隨時間調整，建議根據實際模型配置覆蓋。

默認單價（元 / 1M tokens，空閒時段）：

配置示例：

config:
  rate: peak
  currency: CNY
  pricing:
    deepseek-v4-pro:
      cacheHitInput: 0.3
      cacheMissInput: 9
      cacheWriteInput: 9
      output: 27

注意：pricing 表中的數值按空閒時段基準填寫，rate: peak 時程序會統一乘以 2。

工作原理¶

插件利用 DSH 的投影機制獲取數據，不修改宿主狀態。

1. 數據源：會話用量和上下文壓力來自宿主已有的投影（如 dsh-token-meter 提供的 tokenUsage 和 contextPressure）。
2. 前端計算：費用估算完全在瀏覽器端完成，使用投影中的累計 Token 數和宿主下發的單價表。
3. 餘額獲取：前端通過路由 fetch /dsh-session-balance/api/overview 請求宿主，宿主讀取憑據後調用 DeepSeek API。餘額請求帶有 TTL 緩存和併發合併機制，避免頻繁請求打爆上游。
4. 安全路由：後端路由只接受同源的 GET/HEAD 請求，檢查 Origin 與 Host 一致性，否則返回 403。

兼容性與要求¶

• DSH 版本：需 DSH 0.1.5-rc.1 及以上，且 Web composition 中已啓用 dsh-token-meter、dsh-session-stats、dsh-api-session-controller。
• Node.js：宿主環境需 Node.js >=20。
• 瀏覽器：需支持 Intl.NumberFormat 和可選鏈操作符的現代瀏覽器。

排查¶

如果功能未正常顯示，可參考以下現象與原因：

License¶

MIT