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 列表在进程启动时就已经确定。
配置
| 键 | 类型 | 默认 | 说明 |
|---|
windowMs | number | 60000 | 滑动窗口大小（毫秒）。默认 60 秒，与供应商的 TPM/RPM 统计周期一致，一般不用改 |
tpmLimit | number | 1200000 | 每分钟令牌上限。默认值适配常见的高吞吐配额档位 |
rpmLimit | number | 15000 | 每分钟请求数上限 |
safetyFactor | number | 0.8 | 安全系数。实际生效上限 = tpmLimit × safetyFactor，默认只用 80% 配额，留 20% 缓冲 |
countFailedAttempts | boolean | true | 以 error / aborted 结束、但上游已回报用量的尝试是否计入窗口。上游确实处理并计费了那一次 prompt，不计会低估窗口压力；关掉可恢复"失败不占额度"。无论开关如何，失败尝试都会打印日志 |
verbose | boolean | false | 输出每次请求的延迟与令牌记录日志，排查问题时打开 |
四项数值配置必须是正数：写成 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）下测试通过。
在 v0.2.1-rc.2（2026-10）下测试通过。
许可证
MIT
