dsh-llm-pi-ai-headers：按提供商配置請求頭與多 Key 輪詢

DSH 作爲 Headless 工具，在調用某些模型時需要處理請求頭過濾、多 Key 輪詢等場景。舊版插件會替換官方適配器，導致流式傳輸、工具調用等功能失效。本插件採用標準安裝方式，保留官方 llm-pi-ai 適配器，僅注入請求頭和輪詢 Key。DSH 的設計理念是“一切皆插件”，社區維護的插件與 DeepSeek 官方無官方從屬關係。

核心功能¶

該插件主要解決以下問題：

按提供商配置請求頭：支持在設置側邊欄「模型擴展」分節編輯請求頭。
Key 輪詢：爲同一提供商配置多個 API Key，插件按 Round-Robin 順序自動輪詢注入。
按提供商配置重試策略：支持調整重試模式、次數、可重試錯誤碼及退避參數。
User-Agent 自動補回：官方適配器會過濾 user-agent，本插件在底層將其補回最終請求。
官方適配器能力保留：reasoning 回傳、SSE 解析、工具調用等核心功能與未裝插件時完全一致。

安裝與啓用¶

推薦使用標準安裝方式，無需手動修改官方代碼，升級 dsh 時無需重裝。

使用 npm 安裝：

dsh plugin --profile web add dsh-llm-pi-ai-headers

或從 GitHub 安裝：

dsh plugin --profile web add "git+https://github.com/xsluck/dsh-llm-pi-ai-headers.git"

安裝完成後，重啓 dsh web 進程並瀏覽器硬刷新（Ctrl+F5），配置入口即會出現。

使用方法¶

進入 設置 → 模型擴展。
選擇提供商，在「請求頭」區域添加自定義頭。
- 例如爲 OpenCode Zen 免費層添加：Key 爲 User-Agent，Value 爲 opencode/1.18.18，以避免 403 錯誤。
配置 Key 輪詢：
- 在「模型」頁爲該提供商保存的主 Key 會自動作爲輪詢池的 1 號位。
- 在擴展頁追加的 Key 會依次排在主 Key 之後。
- 插件默認將 Key 注入 Authorization 請求頭。
調整重試策略（可選）：
- 在「重試策略」區修改模式（限次數/無限重試）、最大重試次數。
- 通過中文標籤勾選可重試錯誤碼，或添加自定義碼。
保存配置。

Key 輪詢機制¶

插件啓用後，Key 輪詢自動生效。請求順序爲：第 1 次使用主 Key，第 2 次使用追加的第一個 Key，依此類推。

配置示例（等價於 UI 編輯）：

llm-pi-ai:
  providers:
    my-provider:
      apiKeyEnv: MY_PROVIDER_API_KEY   # 主 Key，來自憑據庫
      keyPool:
        headerName: Authorization      # 注入的請求頭名
        keys:                          # 追加的備用 Key
          - "sk-key-bbb-second"
          - "sk-key-ccc-third"

注意事項：
* 主 Key 不落盤，始終保留在憑據庫中，插件僅在輪詢時讀取。
* 追加的 Key 以明文存儲在 ~/.dsh/settings.yaml 中，請確保文件訪問權限受控。

額度耗盡與自動回池¶

當服務端返回額度耗盡錯誤（如 429，消息包含“使用上限”、“額度”、“餘額”等關鍵詞）時：

插件會將該 Key 歸類爲 QUOTA 錯誤，而非臨時限流。
該 Key 立即從輪詢池中移除。
插件會嘗試解析消息中的重置時間。到達時間後自動回池，無需重啓。
若消息中無重置時間，默認按 1 小時冷卻。
若全部 Key 均在冷卻，仍會嘗試發送最早解凍的那把 Key。

注意事項¶

舊版 vs 新版：舊版安裝腳本會禁用並替換官方適配器，存在參數截斷和契約風險。新用戶請優先使用上述標準安裝方式。舊版安裝僅建議現有用戶保留。
兼容性：安裝後，官方 llm-pi-ai 適配器始終未被修改，卸載後系統恢復官方原樣。