DeepSeek Harness 主動限速插件：dsh-rate-limiter

在開發基於 DeepSeek Harness (DSH) 的應用時，上游 API 的速率限制是常見痛點。直接發起請求往往導致 429 錯誤或請求丟失。dsh-rate-limiter 是一個主動限速插件，由 Xidong-AI 維護，旨在從源頭控制請求頻率。

核心定位¶

這是一個預防性的限流插件。它掛載在 agent/request 水流中，在請求發出前執行按供應商的令牌桶限速。當達到速率限制時，它選擇將請求延遲排隊，而不是直接拒絕或報錯，從而避免觸發上游的 429 錯誤，確保請求不丟失。

核心能力¶

按供應商令牌桶限速：在請求發出前強制執行，屬於預防性限流，而非失敗後的補救。
超限排隊機制：令牌不足時，請求會進入延遲隊列，等待令牌釋放。這種方式避免了直接拒絕請求，也避免了產生 429 響應。
零侵入設計：未配置的供應商不受任何限制，請求直接放行。enabled: false 可以完全禁用插件。
信號中斷支持：排隊等待期間，如果用戶中斷操作，等待會立即停止。
無第三方依賴：使用手寫的基於預留的令牌桶算法，保證併發安全，不依賴其他限流庫。
與重試插件共存：掛載點與 dsh-llm-retry 不同，兩者互不干擾，配合使用效果更佳（限流在前，重試在後）。

安裝與配置¶

使用 npm 安裝插件：

dsh plugin --profile web add @xidong-ai/dsh-rate-limiter

安裝完成後，通過配置 cordis.patch.yml 來定義各供應商的限流策略。配置項僅支持在 providers 鍵下定義：

- id: rate-limiter
  config:
    enabled: true
    providers:
      nvidia:
        rate: 0.5        # 令牌填充速率（tokens/second），即長期平均 QPS
        burst: 1         # 令牌桶容量，允許的突發請求數

參數說明¶

rate: 每秒填充的令牌數，決定了長期平均請求速率。
burst: 令牌桶的容量，決定了在令牌耗盡前可以連續發送多少個請求。
注意：未在配置中列出的供應商將完全不受限速影響，請求會直接放行。

工作原理¶

插件掛載在 agent/request 鏈路中。執行流程如下：

先執行 await next() 獲取請求配置（包含目標供應商信息）。
根據供應商配置檢查令牌桶狀態。
若令牌充足，立即返回配置併發出請求。
若令牌不足，將請求加入延遲隊列。
如果用戶在等待期間中斷操作，隊列等待會被 AbortSignal 立即打斷。

與 dsh-llm-retry 的關係¶

兩者在請求生命週期的不同階段發揮作用，互不衝突：

插件	介入時機	行爲
`dsh-rate-limiter`	請求發出前	超限時排隊延遲，預防 429 錯誤
`dsh-llm-retry`	請求失敗後	指數退避重試，作爲兜底機制

卸載¶

dsh plugin --profile web remove @xidong-ai/dsh-rate-limiter

總結¶

dsh-rate-limiter 通過在請求發出前進行精細化的令牌桶控制，解決了上游 API 限流導致的請求丟失問題。其零侵入的設計和與重試插件的天然兼容性，使其成爲 DSH 開發者在處理高併發或受限 API 時的實用工具。