dsh-codex-usage：DeepSeek Harness 的 Codex 配額與餘額聚合插件

前言¶

DeepSeek Harness (DSH) 用戶若將 Codex 作爲子代理使用，需關注 ChatGPT Plus 的滾動配額（5h/7d/month）。本插件爲 DSH host 插件，通過聚合接口將 Codex 配額與 DeepSeek 餘額展示在同一 JSON 下，方便統一監控。

核心功能¶

• 讀取 Codex 訂閱配額 (5h/7d/month)
• 查詢 DeepSeek 賬戶餘額
• 提供迴環-only 聚合接口 GET /api/dsh-usage/overview
• 通過 DSH 憑據服務管理 DeepSeek API Key

安裝¶

依賴 DSH >= 0.1.1-rc.x 和 Node >= 22。安裝命令如下：

dsh plugin --profile web add dsh-codex-usage

安裝後，dsh web 會自動通過 cordis.patch.yml 註冊插件。插件依賴的 @openai/codex@0.147.0 由 npm 自動安裝，使用前需確保 Codex 側已登錄（執行 codex login status 檢查）。

接口說明¶

插件提供迴環-only 聚合接口 GET /api/dsh-usage/overview。

查詢參數：
- 無：命中 5 分鐘內存緩存
- ?refresh=1：強制穿透緩存，刷新數據

響應結構：
- ok: 是否成功
- updatedAt: 數據更新時間戳
- codex: Codex 配額信息
- configured: Codex 是否配置正確
- windows: 滾動窗口數組，包含 label (5h/7d/month)、usedPercent (已用百分比)、resetIn (重置倒計時)、resetsAt (重置時間戳)
- error: 錯誤信息
- deepseek: DeepSeek 餘額信息
- balance: 包含 currency (幣種)、total (總餘額)、granted (贈金)、toppedUp (充值)
- links: 官方用量頁鏈接

配置¶

可在 cordis.patch.yml 中添加 config 參數以調整行爲：

- insert:
    - id: codex-usage
      name: dsh-codex-usage
      config:
        apiKeyRef: DEEPSEEK_API_KEY        # 餘額接口 API Key ref
        codexUsageUrl: https://codex.app/account/usage     # 官方用量頁鏈接
        deepseekUsageUrl: https://platform.deepseek.com/usage
        refreshMs: 300000                  # 緩存 TTL (默認 5 分鐘)
        timeoutMs: 30000                   # 超時時間 (默認 30s)

注意事項¶

• 僅接受迴環地址請求 (127.x / ::1 / localhost)，外部請求一律 403。
• 僅支持 GET 請求，不接收請求體，不寫入狀態。
• 數據緩存時間爲 5 分鐘 (默認 refreshMs: 300000)。
• Codex 側需已登錄，否則 codex.configured 爲 false。

與 Codex 子代理的關係¶

• 官方子代理（@deepseek-ai/dsh-subagent-codex）：負責把任務委派給 Codex 執行。
• 本插件：負責讀取配額數據，不參與任務調度。

建議組合使用：先安裝官方子代理幹活，再安裝本插件監控配額，避免額度刷爆。