English | 中文

@zhourenke/dsh-agent-rate-limit

为 DSH 自动加上 TPM/RPM 速率限制：在触发供应商限速之前，先按滑动窗口余量把请求排好队。

DSH 的 Agent 循环能在几十秒内连续发出多个请求，很容易撞上供应商的每分钟令牌数（TPM）或每分钟请求数（RPM）上限，导致整轮对话被 429 打断。本插件在 LLM 流式管线前插一层自适应延迟：窗口还有余量就直接放行，接近上限才等待——只延迟，不拒绝。装好即用，无需改动 DSH 源码。

它解决什么问题

• 撞限速导致对话中断：多个 Agent 并发时令牌消耗远超单次请求的量，插件按滑动窗口提前排队
• 免人工调参：默认值匹配常见配额，不配置也能工作
• 账单口径准确：从 API 的 usage 数据块读取真实令牌消耗，含缓存命中，与账单一致
• 随时可卸：作为 profile 层插入，不修改 DSH 本体

安装

dsh plugin --profile web add "github:zhourenke/dsh-agent-rate-limit"

必须重启 DSH 才会生效——新增的 bundle 在进程启动时才载入，刷新页面无效。（装好之后再调整它的配置则不需要重启，见下文「快速上手」。）

装好后，DSH 的插件列表里会显示本插件的中文/英文名称、说明与图标，随界面语言切换。

卸载：

dsh plugin --profile web remove @zhourenke/dsh-agent-rate-limit

快速上手

默认配置即可工作，装上就完事。确认生效：在聊天输入框输入

/agent-rate-limit

看到 Status: loaded 就是已经加载并在工作。

要调整限额，编辑 ~/.dsh/profiles/web/cordis.patch.yml：

# ~/.dsh/profiles/web/cordis.patch.yml
- id: agent-rate-limit
  name: '@zhourenke/dsh-agent-rate-limit'
  config:
    tpmLimit: 1200000
    rpmLimit: 15000
    verbose: true

id 与 name 两行请照抄，不要改名。

保存即生效，不需要重启。 web profile 的补丁层是热重载的（patchReload: live，由 Cordis HMR 监视文件变更后重新应用）。注意区分：安装或卸载插件本身仍然必须重启，因为 bundle 列表在进程启动时就已经确定。

配置

四项数值配置必须是正数：写成 0、负数或 NaN 时插件会拒绝加载并报出具体字段，而不是静默不再限速。

查看状态

/agent-rate-limit 会打印当前配置与窗口占用：

Status: loaded
Config:
  TPM limit:     1,200,000 (effective: 960,000)
  RPM limit:     15,000
  Safety factor: 0.8
  Window:        60s
  Verbose:       false
  Count failed:  true
Current:
  Window entries:  12
  Current TPM:     14,765

Window entries 是当前 60 秒窗口内的请求数，Current TPM 是窗口内累计令牌数。两者都远低于限额时，插件不会产生任何延迟。

它会怎么干预你的请求

• 只延迟，不拒绝：插件永远不会让请求失败，也不会返回错误，只在必要时等待
• 有余量就放行：窗口内累计令牌加上本次预估输入仍低于生效上限时，延迟为 0
• 接近上限才排队：等待到足够的旧记录滑出窗口、腾出空间为止
• 并发时自动延长：多个 Agent 同时请求时，你的等待期间其他 Agent 仍在消耗配额，插件按超限比例放大延迟
• 失败的尝试照实记账：以 error / aborted 结束、但上游已回报用量的尝试默认计入窗口（上游已经处理并计费了那一次 prompt），可用 countFailedAttempts: false 关掉。这个开关只改记账、不改报告：verbose: true 时两种设置都会打日志，不会静默吞掉用量
• 延迟发生在下发之前：等待加在流开始之前，不会打断已经开始输出的响应

已知限制（实测确认）

• 按进程独立计数：窗口状态存在 DSH 进程内，多个 DSH 实例互不共享——同时跑多个 profile 时，每个实例都按完整配额独立计算，合计仍可能超限。
• 配置对 provider 是全局的：一份配置作用于该插件实例下的所有 provider，无法给不同 provider 设不同限额。
• 首次请求只能估算：窗口为空时没有历史数据，输入令牌数交给 DSH 自己的估算器计价（固定 4 字符/令牌，中文会偏低）；之后改用最近 3 次 API 实际值的平均。
• 旁路调用照样占窗口：上下文压缩、会话标题这类调用也计入窗口，只是不参与输入长度的估算。
• 单次超大请求无法拆分：如果一次请求本身就接近配额，插件只能等它滑出窗口，不能把它切开。
• 不保证不撞限速：插件的目标是大幅降低概率，而不是数学保证。配额被其它程序同时消耗时仍可能触发 429——那部分由 DSH 内置的重试机制接管。

给 Agent 的要点

• 本插件没有工具、没有模型可见的接口，对模型完全透明，无需也无法主动调用
• 速率限制是自动生效的：撞到限额时表现为响应变慢，而不是报错
• 判断是否生效：请用户输入 /agent-rate-limit，出现 Status: loaded 即为已加载
• 配置文件是 ~/.dsh/profiles/web/cordis.patch.yml；改它保存即生效，不需要重启（补丁层热重载）。只有安装/卸载插件本身才需要重启
• verbose: true 的日志可以直接和 DSH 的轮次用量对账：每行是 Recorded N tokens (uncached: …, cached: …, output: …)，失败尝试会多一个 [<原因>] 尾巴（[error] 或 [aborted]）。若两者对不上，先确认失败尝试是否出现在日志里（默认会记），再看上游是否改了 usage 字段——插件遇到 totalTokens 与分项不一致会打印告警

兼容性

在 v0.2.0-rc.2（2026-09）下测试通过。

许可证

MIT