前言¶
如果你在 DeepSeek Harness（DSH）里长期跑同一个 LLM provider，大概率遇到过这种情况：任务跑到一半，请求返回 QUOTA 或 429，整条工作流被迫停下来，手动换 key、重启进程、恢复上下文。
社区里一个常见做法是写脚本监控日志再人工干预，但这类方案脱离了 Harness 本身的请求流程，处理不了「换 key 后立即重试」这件事。m1khal3v 写的 dsh-llm-key-rotation 插件把这一步做进了 Harness 的恢复链路里：请求失败时自动切换到配置链中的下一个 key 并立即重试，不需要重启，也不丢上下文。下面介绍它的功能、安装和配置方式。
这是什么¶
dsh-llm-key-rotation 是一个面向 DeepSeek Harness 的插件，README 里的定位是「Seamless API-key rotation for DeepSeek Harness」——为 LLM provider 提供无感的 API-key 轮换。作者是 m1khal3v，当前版本 1.1.0，许可证为 MIT，README badge 标明适配 DeepSeek Harness v0.1.1-rc.1。
它解决的场景很具体：当一个 provider 的某个 key 触发 QUOTA、RATE_LIMIT 或 AUTH 错误时，插件从你预先配置的 key 链中取下一个，热切换后立刻重试这次请求。对 Agent 和用户来说这个过程是透明的——本轮请求用新 key 重试成功，后续请求继续沿用当前可用的 key。
核心功能¶
按 README 的说明，插件提供以下能力：
1、错误触发的热切换：请求返回 QUOTA / RATE_LIMIT / AUTH 时，自动换到配置链中的下一个 key 并立即重试，无需重启、不丢失上下文。
2、对 Agent 与用户透明：请求重试无感知，工作流不会因为额度问题中断。
3、原生 Web UI：在 Settings 中查看 provider 可用的所有 keys，并切换轮换开关。
4、Smart Anti-Spin：内置冷却机制，防止所有 key 都耗尽时陷入无限循环。
5、Smart Rotation Window（300 秒）：连续失败时依次向前轮换 key；超过 5 分钟没有失败，链会重置回链首重新开始。
6、零核心补丁：插件干净地接入 Harness 的 recovery waterfall（恢复瀑布），安装和移除都不会改动核心。
7、密钥安全存储：keys 保存在 Harness credential store 中。
8、终端实时日志且不泄露密钥：轮换事件实时输出到 dsh 终端，日志只包含 provider 名称、索引和错误码，不记录密钥值。
安装¶
插件通过 web profile 安装，在终端执行：
dsh plugin --profile web add @m1khal3v/dsh-llm-key-rotation
环境方面，package.json 的 engines 要求 Node ^22.19 || >=24。
配置与使用¶
安装完成后，进入 Settings → Plugins → Key Rotation，按以下步骤配置：
1、为目标 provider 打开轮换开关。
2、选择触发码（默认为 QUOTA、AUTH）。
3、点击 Add key，把该 provider 要轮换的所有 keys 依次粘贴进去，然后点击 Save。
keys 会保存到 Harness credential store，不会出现在明文配置里。
配置完成后，轮换事件会在 dsh 终端实时输出，日志格式如下：
[llm-key-rotation] rotated provider="opencode-go" chain[0]→"OPENCODE_GO_API_KEY" (QUOTA)
可以看到 provider 名称、链中的索引位置、切换到的环境变量名和触发错误码，密钥值本身不会出现在日志里。
与 dsh-llm-retry 的协作及轮换行为¶
如果你同时使用 dsh-llm-retry 插件，两个插件的分工是：
QUOTA和AUTH：由 key-rotation 立即轮换。RATE_LIMIT：默认先交给dsh-llm-retry做退避重试。
如果你希望遇到 429 时也立即换 key 而不是退避等待，可以把 RATE_LIMIT 从该 provider 的 retryableCodes 中移除，之后 429 会直接触发轮换。
轮换本身遵循 Smart Rotation Window 机制：连续失败期间插件沿 key 链依次向前切换；一旦超过 5 分钟没有失败发生，链会重置，下次从头开始。这个窗口配合冷却机制，保证所有 key 都耗尽时不会陷入无意义的循环。
适用场景与注意事项¶
这个插件适合的情况很明确：你有同一个 provider 的多个 API key，希望额度耗尽或遇到限流、鉴权错误时工作流能自动续上，而不是停下来人工干预。尤其是长时间运行的 Agent 任务，中断恢复的成本越高，这个插件的价值越明显。
使用前有几点需要确认：
1、插件以当前 dsh 进程的权限运行，它需要读取你的 keys 并介入请求恢复流程。安装前建议先查看源码（仓库地址见文末）确认实现符合预期。
2、确认许可证。该项目采用 MIT，允许自由使用和修改。
3、安装命令使用的是 web profile，客户端 platform 为 web，确认这与你的部署方式一致。
4、如果你参与插件本身的开发，仓库提供了标准的验证流程：
pnpm install
pnpm run verify # typecheck + test
pnpm run build
结尾¶
dsh-llm-key-rotation 做的事情不复杂，但切中了一个真实痛点：多 key 场景下的额度与限流处理。它通过接入 Harness 的 recovery waterfall 实现热切换，不动核心代码，配合 Web UI 和 credential store，安装配置的成本都很低。
- 插件目录页：https://www.skillhub.cn/plugins/m1khal3v/dsh-llm-key-rotation
- GitHub 仓库：https://github.com/m1khal3v/dsh-llm-key-rotation
顺带说明：插件目录 skillhub.cn 是独立的社区站点，与 DeepSeek、幻方没有官方从属关系。
