dsh-llm-rate-limiter

English | 中文

DeepSeek Harness 的按模型 LLM 调用限速插件，支持排队/拒绝两种节流策略，并带交互式图形配置界面。

---

功能

• 按模型限速 —— 每个 provider/model 独立的并发数、RPM 与突发容量限制
• 两种算法 —— 令牌桶（允许突发）或滑动窗口（平滑、严格 RPM）
• 排队模式 —— 被限流的请求排队等待，有槽位空出时放行
• 拒绝模式 —— 被限流的请求立即失败（可与 dsh-llm-retry 配合自动退避重试）
• 交互式界面 —— DSH 设置 → 插件页内的可展开配置卡片
• 实时状态面板 —— 实时计数器、按模型的进度条与事件日志（v0.2.0 起）
• 热更新 —— 配置改动立即生效，无需重启
• 全量检查 —— 拦截 llm/stream waterfall，覆盖每个 agent 轮次里的每一次 LLM 调用

---

状态面板（v0.2.0）

打开卡片后，其正文顶部会显示实时面板：

📊 实时状态                          ● 实时   [清零]
 请求 42 · 通过 38 · 拒绝 2 · 超时 1 · 中止 1 · 平均等待 214ms
 deepseek/deepseek-chat   [令牌桶]  ▓▓▓▓▓▓▓░░░ 7.5/10   并发 2/5   排队 1
 openai/gpt-4o            [滑动窗口] ▓▓▓▓▓▓▓▓▓▓ 3/3 rpm  并发 1/5
 12:00:03  timeout   openai/gpt-4o              等待 1m
 12:00:01  rejected  openai/gpt-4o
 12:00:00  granted   deepseek/deepseek-chat     等待 4.2s

方面	行为
数据通道	通道 /llm-rate-limiter —— 带认证（401/403 栅栏），POST+JSON，随插件 fiber 自动清理
载体	优先用框架的 connection.rpc.handle()；框架路径失效时，退回到插件自注册的前缀路由并复用 connection.requestRejection()（见下文）
轮询节奏	卡片展开时 1 秒轮询；连续失败后退避 2 秒 → 4 秒 → 8 秒
折叠状态	面板卸载，因此完全不轮询
端点	snapshot（实时计数）与 reset（清零统计）
通道不可用时	显示「状态通道不可用」，卡片其余部分功能不受影响
计数器	requests / granted / rejected / timeouts / aborted / totalWaitMs，外加最近 8 条事件（环形缓冲为 64）
进度条	令牌桶显示 tokens/burstSize；滑动窗口显示 countInWindow/maxRpm；接近上限时变琥珀色

载体兜底（DSH 0.1.5-rc.3 起）

DSH 0.1.5-rc.3 把 @deepseek-ai/dsh-client-connection 这个框架插件自身的 inject 从 ["webServer", "credentials"] 改成了 ["credentials"]，但其 HostConnectionService.register() 仍然解引用 owner.webServer。 Cordis 会把跨 fiber 读取的 service 的 ctx 重绑定到读取者的 fiber，因此 connection.rpc.handle() 会抛错：在 0.1.7-rc.1 中依然存在 —— 见下文。

cannot get property "webServer" without inject

插件会检测到该错误，并自行挂载同一条通道：

路径	触发条件	做法
1（首选）	connection.rpc.handle() 正常	由框架持有路由、请求校验与 fiber 级撤销
2（兜底）	路径 1 抛错	插件在自己的 fiber（能看到 webServer）注册 kind: "prefix" 路由，并复用 connection.requestRejection() 作为 403/401 栅栏

两条载体使用逐字相同的 wire 协议，因此浏览器端无需改动 —— 面板也分辨不出 当前是哪一条。若 connection.requestRejection() 不可用，插件会拒绝挂载， 而不是发布一条未鉴权的路由。

---

安装

方式 1：npm（推荐）

dsh plugin add <your-profile> @leaf233/dsh-llm-rate-limiter
# 或在该 profile 目录内：
pnpm add @leaf233/dsh-llm-rate-limiter

方式 2：本地路径（开发）

dsh plugin add <your-profile> ./path/to/dsh-llm-rate-limiter
# 或
dsh plugin add ./path/to/dsh-llm-rate-limiter   # 默认 profile

插件必须被加入该 profile 的 package.json 依赖中。 bundle 入口（cordis.patch.yml）由 reconcilePlugins 自动识别。

0.3.0 要求 DSH 0.1.7-rc.1 或更新版本。 若使用 DSH 0.1.5，请锁定 @leaf233/[email protected]。见兼容性表。

方式 3：从 GitHub 安装

dsh plugin add <your-profile> github:Leafyezi233/dsh-llm-rate-limiter

⚠️ 重要：从 Git 安装的插件在首次安装时会被 pnpm 的 allowBuilds 限制拦下。 若安装失败，请查看报错信息中 pnpm 给出的确切键名，然后加入该 profile 的 pnpm-workspace.yaml：

pnpm:
  allowBuilds:
    - '@leaf233/dsh-llm-rate-limiter'

然后重新执行安装命令。

---

配置

通过图形界面

1. 打开 DSH Web UI（dsh web）
2. 进入设置 → 插件，展开 Official 分组
3. 找到 LLM 调用限速 卡片（data-plugin-item="llm-rate-limiter"）并打开
4. 配置全局默认值、按模型覆盖与节流行为 —— 改动经页面自带的表单保存， 实时状态面板就在同一页

卡片出现在 Official 分组里，是因为 DSH 把所有 plugins.item 的注册者 都列在那里；本插件的 order 为 900，因此排在五个官方设置页之后。

通过配置文件

改动会被持久化到该 profile 的 Cordis patch 中该条目的 config 里 （0.1.7 起，插件以自己的 Config 作为配置来源；旧版 settings.yaml 由 DSH 在首次启动时导入一次并改名）。形状如下：

llm-rate-limiter:
  enabled: true
  strategy: token-bucket       # "token-bucket" | "sliding-window"
  defaults:
    maxConcurrent: 5
    maxRpm: 60
    burstSize: 10               # 仅令牌桶
    refillRate: 1               # 仅令牌桶（每秒补充的令牌数）
  models:
    "deepseek/deepseek-chat":
      maxConcurrent: 8
      maxRpm: 120
    "openai/gpt-4o":
      maxConcurrent: 2
      maxRpm: 10
      burstSize: 3
    "anthropic/claude-3-5-sonnet":
      enabled: false            # 对该模型跳过限速
  onThrottled: queue            # "queue" | "reject"
  maxQueueWaitMs: 60000

---

设置项参考

字段	默认值	说明
enabled	true	全局总开关。关闭时零开销直接放行。
strategy	"token-bucket"	"token-bucket"（允许突发）或 "sliding-window"（平滑、严格 RPM）
defaults.maxConcurrent	5	每个模型的最大同时请求数
defaults.maxRpm	60	每个模型每分钟最大请求数
defaults.burstSize	10	令牌桶容量 —— 一次最多可突发多少个请求
defaults.refillRate	1	每秒补充的令牌数（令牌桶）。未设置时由 maxRpm / 60 自动推导。
models.<key>.maxConcurrent	—	该模型的并发数覆盖
models.<key>.maxRpm	—	该模型的 RPM 覆盖
models.<key>.burstSize	—	该模型的突发容量覆盖
models.<key>.refillRate	—	该模型的补充速率覆盖
models.<key>.enabled	—	设为 false 可对该模型跳过限速
onThrottled	"queue"	请求触限时的行为："queue"（等待）或 "reject"（立即失败）
maxQueueWaitMs	60000	请求在队列中等待多久（毫秒）后放弃并被拒绝

注意：当模型覆盖了 maxRpm 但未显式设置 refillRate 时，补充速率会 自动按 maxRpm / 60（每秒令牌数）推导。这样才能保证「设 maxRpm=3」真的限制到 每分钟 3 个请求。

---

算法对比

	令牌桶	滑动窗口
突发	允许（由 burstSize 控制）	不允许 —— 严格平滑
恢复	令牌按 refillRate/秒补充	窗口持续滑动
最适合	容忍请求尖峰	有硬性每分钟上限的 API
界面名称	令牌桶 (Token Bucket)	滑动窗口 (Sliding Window)

---

工作原理

Agent 轮次
  → LLM 调用（例如 deepseek/deepseek-chat）
    → ctx.on("llm/stream") 拦截器
      → 为该 provider/model 解析对应的限速器
      → 令牌桶：还有令牌且并发未满？
      → 是：消耗令牌、占用槽位、转发到 API
      → 否（拒绝模式）：立即返回 RATE_LIMIT 错误
      → 否（排队模式）：进入 waiters[] 等待令牌补充
    → 请求完成 → 释放槽位 → 唤醒等待中的请求
  → dsh-llm-retry 捕获 RATE_LIMIT → 指数退避 → 重试

---

开发

# 克隆
git clone https://github.com/Leafyezi233/dsh-llm-rate-limiter.git
cd dsh-llm-rate-limiter

# 安装依赖
pnpm install

# 跑完整测试套件（6 个文件，375 条断言）
pnpm test

# 单独运行各套件
node test-strategies.mjs       # 19 —— 限速算法
node test-status-rpc.mjs       # 61 —— 通道处理器与计数器
node test-client-bundle.mjs    # 106 —— 真实客户端 bundle 跑在迷你 React 运行时上
node test-host-integration.mjs # 80 —— 真实 apply(ctx, config) 接线与 volatile 引用
node test-status-route.mjs     # 73 —— 自注册路由与 0.1.5 回归
node test-config-schema.mjs    # 36 —— 设置页所依赖的 Config volatile 契约

# 针对真实 DSH 安装的实机 HTTP 验证（真实 socket、真实 webserver）
pnpm run verify:live           # 19 —— 无 DSH 时以退出码 2 跳过

# 运行端到端限速测试
node test-3rpm.mjs

# 安装到某个 DSH profile 里测试
dsh plugin add <your-profile> .

通过 link: 安装时，插件走实时符号链接 —— 对 lib/ 的改动在浏览器硬刷新 （Ctrl+Shift+R）后即生效，无需重新安装。

---

兼容性

DSH 版本	插件版本	状态	说明
0.1.2-rc.1	0.2.x	✅ 已测	最初目标；connection.rpc 载体
0.1.5-rc.3	0.2.x	✅ 已测	需要载体兜底；已通过实机 HTTP 验证
0.1.7-rc.1+	0.3.x	✅ 已测	settingsScope → configForms；settings.plugin.item → plugins.item；基于 Config 的设置
0.2.x（DSH）	—	⚠️ 未测	可能需要调整 API
Cordis 5+	—	⚠️ 未测	大版本升级多半需要重写

0.3.0 的破坏性变更

DSH 0.1.7 移除了本插件设置界面所用的两个客户端服务：

0.1.5	0.1.7
settingsScope 服务	configForms 服务
settings.plugin.item 槽位	plugins.item 槽位
宿主 ctx.settings.register(ns, schema, { base })	条目自己导出的 Config schema
宿主 scope.get() / scope.watch()	.volatile() 引用，用 .get() 读取

0.3.0 只支持 DSH 0.1.7-rc.1+。使用 0.1.5 请安装 0.2.x。

本次迁移所依赖的四个断裂点，已就地写在 lib/index.js 与 lib/types/config.js 的注释里；完整推理记录在 CHANGELOG.md 的 [0.3.0] 段落。

---

许可证

MIT