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

在开发基于 DeepSeek Harness (DSH) 的应用时，上游 API 的速率限制是常见痛点。直接发起请求往往导致 429 错误或请求丢失。dsh-rate-limiter 是一个主动限速插件，由 Xidong-AI 维护，旨在从源头控制请求频率。

核心定位¶

这是一个预防性的限流插件。它挂载在 agent/request 水流中，在请求发出前执行按供应商的令牌桶限速。当达到速率限制时，它选择将请求延迟排队，而不是直接拒绝或报错，从而避免触发上游的 429 错误，确保请求不丢失。

核心能力¶

1. 按供应商令牌桶限速：在请求发出前强制执行，属于预防性限流，而非失败后的补救。
2. 超限排队机制：令牌不足时，请求会进入延迟队列，等待令牌释放。这种方式避免了直接拒绝请求，也避免了产生 429 响应。
3. 零侵入设计：未配置的供应商不受任何限制，请求直接放行。enabled: false 可以完全禁用插件。
4. 信号中断支持：排队等待期间，如果用户中断操作，等待会立即停止。
5. 无第三方依赖：使用手写的基于预留的令牌桶算法，保证并发安全，不依赖其他限流库。
6. 与重试插件共存：挂载点与 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 链路中。执行流程如下：

1. 先执行 await next() 获取请求配置（包含目标供应商信息）。
2. 根据供应商配置检查令牌桶状态。
3. 若令牌充足，立即返回配置并发出请求。
4. 若令牌不足，将请求加入延迟队列。
5. 如果用户在等待期间中断操作，队列等待会被 AbortSignal 立即打断。

与 dsh-llm-retry 的关系¶

两者在请求生命周期的不同阶段发挥作用，互不冲突：

卸载¶

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

总结¶

dsh-rate-limiter 通过在请求发出前进行精细化的令牌桶控制，解决了上游 API 限流导致的请求丢失问题。其零侵入的设计和与重试插件的天然兼容性，使其成为 DSH 开发者在处理高并发或受限 API 时的实用工具。

• 插件目录
• GitHub 仓库