1.0.2

dsh-cooldown-retry 1.0.2

文档修正版。 1.0.1 发布后做了一次用户端安装实测，发现两处文档与发布包实际情况不符，本版修正。插件行为与 1.0.1 完全一致，无代码改动。

修正

• 开发章节的 npm test 跑不起来：package.json 的 files 白名单不含 test/，所以 dsh plugin add 装进 profile 的包里没有测试文件，用户照 README 在 node_modules 里跑 npm test 必然失败。已改为先 git clone 再跑，并明确说明 test/ 不属于安装包。

• 安装验证方法无法复现：原文写「插件清单里应出现 cooldown-retry 且 phase=active」，但这个说法没有可复现的获取途径。已改为实测可用的方法：

  dsh --profile web --dump-config | grep -A2 'cooldown-retry'

  并补充说明该行必须位于内置 llm-retry 之后 —— agent/request-error 是 waterfall，后注册的监听者绑定为内层监听者，这个位置决定了本插件能否对每次失败拥有优先接管权，而不是被内置快速重试短路。

用户端安装实测结论（全部通过）

在隔离的 DSH_HOME 下完整验证了第三方用户按 README 安装的路径：

检查	结果
仓库匿名可 clone（不带凭据）	✅
dsh plugin --profile <p> add github:dboycht/dsh-cooldown-retry	✅ pnpm 4.7s 装成，exit 0
自动登记 bundle 层（dsh.profile.bundles）	✅
--dump-config 确认行已插入	✅ 且位于 llm-retry 之后
从用户 profile import 该包	✅ 解析到 profiles/<p>/node_modules/dsh-cooldown-retry/index.js
真实 Cordis 上下文挂载	✅ fiber state = 2 (ACTIVE)
不提供 commands 服务也能挂载	✅ 仍 ACTIVE 并正常接管重试

最后一项印证了设计意图：inject 只声明 timer，commands / logger 全部走 ctx.get 优雅降级，因此残缺 profile（headless / ACP）不会因为一条装饰性命令而把插件卡在 waiting。

功能（自 1.0.1 起不变）

上游网关返回容量类 429 并附带重试提示时（例如 "All upstream providers are cooling down. Please retry after 28 seconds."），按上游给出的延时长等待后重试，而不是让内置 llm-retry 在冷却窗口里用两次快速重试撞死。

• 预算按 turn + provider 计，多步 turn 共享（acrossSteps: false 可恢复旧行为）
• 每次等待与放弃走 ctx.logger（名为 cooldown-retry），/cooldown-retry 可查计数器
• 可选 hintlessBackoff：对无提示的容量冷却也做指数退避

前置条件

github: 写法需要 PATH 上有 git（底层 pnpm 走 git 克隆）。插件本身零依赖、无需 API key。

安装

dsh plugin --profile web add github:dboycht/dsh-cooldown-retry

附件

• dsh-cooldown-retry-1.0.2.zip — 源码包（12 条目、扁平结构、package.json 在根）
• SHA256：C6074DC403508AF47B508F8913F3D627FF2E9DD0D1586743D59329A77A34A54E

注：1.0.1 的 tag 与 Release 保持原样不动（未改写已发布历史），其 README 含上述两处瑕疵；请优先使用 1.0.2。