Xidong-AI/dsh-rate-limiter

English | 中文

DeepSeek Harness（dsh）的主动限速插件：在模型请求发出之前按 provider 控制请求速率（令牌桶），超限时延迟排队而不是失败，从而避免触发上游 429。

与官方 dsh-llm-retry（失败后指数退避）互补：限速在前（预防），退避在后（兜底），互不干扰。

特性

• 按 provider 令牌桶限速，且在请求发出之前生效（主动预防）
• 超限请求延迟排队而非拒绝（不触发 429、不丢请求）
• 未配置的 provider 原样放行（零侵入）
• 排队等待响应取消信号，用户停止时立即中断
• 手写预约式令牌桶（并发安全），零第三方限速库依赖
• 挂载 agent/request，与 dsh-llm-retry 天然共存

安装

从 npm 安装：

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

npm registry 的 URL 区分大小写，请使用小写包名。

或直接从 GitHub 安装：

dsh plugin --profile web add github:Xidong-AI/dsh-rate-limiter

本地开发时直接添加当前目录：

dsh plugin --profile web add .

安装后 dsh --profile web --dump-config 应能看到插件行：

- id: rate-limiter
  name: @xidong-ai/dsh-rate-limiter
  config:
    enabled: true
    providers: {}

配置

在 profile 的 cordis.patch.yml（或本插件 cordis.patch.yml）中按 provider 配置令牌桶：

- id: rate-limiter
  config:
    enabled: true
    providers:
      nvidia:
        rate: 2          # token/秒（长期平均 QPS）
        burst: 5         # 桶容量（允许的突发请求数）
      oc-zen:
        rate: 1
        burst: 3

• rate：补充速率（token/秒），即长期平均请求速率。
• burst：桶容量，允许的突发请求数。
• 未列出的 provider 不限速，请求原样放行（零侵入）。
• enabled: false 可整体关闭插件。

工作原理

插件挂在 agent/request waterfall 上：先 await next() 拿到含 provider 的调用配置，再按 provider 做令牌桶检查，不足则延迟排队（等待期间响应取消信号，用户停止时立即中断），然后原样返回配置——不修改请求内容、不改路由、不吞错误，只控制"何时发出"。

限速算法为手写令牌桶（预约式，并发安全），零第三方限速库依赖。

与 dsh-llm-retry 的关系

插件	时机	行为
dsh-rate-limiter	请求发出前	超限延迟排队（预防 429）
dsh-llm-retry	请求失败后	指数退避重试（兜底）

两者挂载点不同（agent/request vs agent/request-error），天然共存。

卸载

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

开发

npm install
npm run typecheck   # tsc --noEmit
npm run test        # vitest run
npm run build       # esbuild 转译 lib/*.ts → lib/*.js

鸣谢

感谢 Linux.do 社区的支持。