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 适配器始终未被修改，卸载后系统恢复官方原样。