dsh-deepseek-usage：DeepSeek 平臺用量面板

在 DeepSeek Harness（DSH）的開發環境中，實時監控 API 調用次數、Token 消耗和賬戶餘額是必要的。手動在網頁端查看不僅效率低下，而且容易打斷工作流。dsh-deepseek-usage 插件將 DeepSeek 平臺的用量數據集成到 DSH 的 Web 界面側邊欄中，提供統一的監控入口。

該插件由社區開發者 scientisbo 維護，遵循 MIT 許可證。它通過讀取 DeepSeek 平臺的公開接口和私有 Dashboard 接口，在本地生成可視化的用量面板。

核心功能¶

賬戶餘額與用量展示：顯示賬戶餘額、今日/本月 Token 數量、花費、請求數、緩存命中/未命中情況、Top 模型排名。
可視化熱力圖：提供每日用量熱力圖，按月翻頁與單日明細。
側邊欄集成：在側邊欄底部提供入口，支持徽標顯示當前餘額；點擊打開浮動面板，收起側邊欄時變爲圓形圖標按鈕。

安裝與啓用¶

使用以下命令安裝插件。若通過文件安裝，請替換路徑爲實際的文件路徑。

dsh plugin --profile web add "file:/絕對路徑/dsh-deepseek-usage"
# 或者發佈到 npm 後：dsh plugin --profile web add dsh-deepseek-usage

安裝完成後，重啓 dsh web 並在瀏覽器中硬刷新（Ctrl+Shift+R），側邊欄底部會出現「DeepSeek 用量」入口。

配置憑據¶

插件依賴兩個憑據：API Key 用於獲取餘額，Platform Token 用於獲取平臺用量詳情。

數據類型	憑據名	說明
餘額	`DEEPSEEK_API_KEY`	默認讀取 ref，可在配置中指定 `apiKeyRef`
平臺用量	`DEEPSEEK_PLATFORM_TOKEN`	默認讀取 ref，可在配置中指定 `platformTokenRef`

獲取 userToken¶

瀏覽器登錄 https://platform.deepseek.com。
打開瀏覽器開發者工具（F12），進入 Application（應用）選項卡。
在 Local Storage 中找到 platform.deepseek.com 域名。
複製 userToken 的值。

配置方式¶

面板內粘貼：在插件面板的「配置會話 token」區域直接粘貼 userToken（推薦，即時生效）。
寫入配置文件：在 ~/.dsh/.credentials.yaml 中寫入：

    refs:
      DEEPSEEK_PLATFORM_TOKEN: <userToken>

未配置 userToken 時，面板仍顯示餘額，用量區會給出配置引導。

可選配置¶

通過 cordis.patch.yml 的 insert 條目，可以調整插件的運行參數。

- insert:
    - id: deepseek-usage
      name: dsh-deepseek-usage
      config:
        apiKeyRef: DEEPSEEK_API_KEY        # 默認
        platformTokenRef: DEEPSEEK_PLATFORM_TOKEN  # 默認
        refreshMs: 300000                  # 服務端緩存 TTL，默認 5 分鐘
        timeoutMs: 15000                   # 上游請求超時，默認 15s

接口與安全¶

插件內置了兩個服務端接口，用於獲取數據。

端點	說明
`GET /api/deepseek-usage/summary?month=&year=`	餘額 + 指定月份用量聚合（帶緩存）
`GET /api/deepseek-usage/refresh?month=&year=`	強制刷新上述數據

安全說明：
* 服務端接口僅接受本機迴環（localhost）的 GET 請求。
* userToken 僅存儲在瀏覽器的 localStorage 中，僅隨請求頭髮送給本機 dsh 服務，絕不會落盤保存。

生態背景¶

DeepSeek Harness 的核心理念是「一切皆插件」。該插件依賴 DeepSeek Harness Web 客戶端環境運行。作爲社區目錄中的獨立項目，它不隸屬於 DeepSeek 或幻方官方，由開源社區維護。