在使用 DeepSeek Harness (DSH) 進行開發時，如果智能體或後臺任務並行調用，很容易觸發提供商的 429 錯誤或限流。dsh-llm-rate-limit 是一個插件，旨在請求到達提供商前介入，提供限流、併發控制和隊列管理。
插件定位¶
這是 DeepSeek Harness 的一個插件，由 Asong6824 維護。它使用令牌桶算法和 FIFO 隊列來控制 LLM 請求的頻率、併發數和代幣消耗，並處理提供商返回的 429 錯誤。
核心功能¶
該插件主要提供以下能力：
- 請求與併發控制
提供商範圍的請求控制。支持基於令牌桶的請求每分鐘（RPM）限制和可配置的突發容量。同時提供併發限制和有界 FIFO 隊列，支持超時和取消機制。 - 代幣預算管理
支持可選的每分鐘代幣預算。系統會估算代幣使用量，並在響應成功後進行實際使用量對賬。 - 自適應冷卻
針對提供商錯誤代碼、HTTP 狀態碼以及Retry-After響應頭，提供自適應的冷卻機制，避免在提供商限流時持續發送請求。 - 流量管理
支持顯式的輔助請求分流，防止後臺流量阻塞主要工作。 - 生命週期與診斷
提供持久化的准入等待和開始事件，便於 DSH 會話診斷。插件在銷燬時會清理生命週期，不會遺留隊列或活動請求。 - 重試感知
每次重試嘗試都是獨立的准入，插件本身不負責重試。
安裝與啓用¶
安裝命令如下：
dsh plugin --profile web add dsh-llm-rate-limit
安裝後，需要通過配置文件啓用。該插件默認保護 deepseek-official 提供商。
典型用法¶
在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 中覆蓋 llm-rate-limit 配置。
配置提供商限制¶
- id: llm-rate-limit
config:
providers:
deepseek-official:
requests: { perMinute: 30, burst: 1 }
maxConcurrentRequests: 2
queue: { maxSize: 100, maxWaitMs: 300000, auxiliary: reject }
cooldown:
codes: [RATE_LIMIT, SERVER]
statuses: [429, 529]
initialDelayMs: 500
maxDelayMs: 60000
maxProviderDelayMs: 3600000
jitterRatio: 0.1
配置代幣預算¶
如果需要限制代幣消耗，可以添加 tokens 配置：
tokens:
perMinute: 1000000
burst: 200000
estimatedOutputTokens: 8192
imageTokens: 1024
注意：tokens.burst 必須足夠大，以容納一個完整請求的估算值。如果不需要代幣限制，可以省略 tokens 配置。
適用場景與注意¶
適用場景：
當並行智能體、子智能體、重試機制或後臺請求導致 HTTP 429 錯誤或提供商限流時使用。
注意事項：
* 版本要求：需要 DeepSeek Harness 0.1.0-rc.8 或更新版本，以及 Node.js 22.19 或更新版本。
* 狀態持久化：插件的狀態是進程本地的，DSH 重啓後會重置。
* 功能邊界：插件不提供分佈式配額、自動重試或提供商故障轉移功能。
* 許可證：插件基於 MIT 許可證發佈，使用前請檢查源代碼。
總結¶
dsh-llm-rate-limit 爲 DSH 提供了基礎的流控能力，通過配置文件即可實現對不同提供商的精細化控制，適合需要在單進程內管理請求頻率和併發量的場景。
