在使用 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 提供了基础的流控能力，通过配置文件即可实现对不同提供商的精细化控制，适合需要在单进程内管理请求频率和并发量的场景。
