前言¶
如果你在 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、幻方沒有官方從屬關係。
