用途:为 quota-axi 新增配额提供商或修改现有适配器,定义要求、共享机制与安全不变量。
实现与依赖:适配器须净室实现,仅依据厂商自身 HTTP/OAuth 行为;不内置第三方适配器代码,Z.AI 适配器是唯一署名例外(源自 opencode-glm-quota,MIT,见 src/providers/zai.ts)。远程 HTTP 必须走 src/lib/http.ts 的 providerFetch,以统一应用 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 且不泄漏代理凭据,不得直接用全局 fetch。Node 26 下该文件将已安装 undici 的 ProxyAgent 与同一构建的 fetch 配对。进程表检查须经 src/lib/process.ts 的 currentUserProcessListArgs。
接入清单:按所有权稳定性枚举每个来源,用命名常量声明优先级;在类型化本地解析边界区分 absent、structurally_invalid、unsupported、read_error、resolved;Pi 条目走 classifyPiAuthEntry;credentialPresent 从本地解析推导一次。本地解析与有界只读存活探测分离:纳入已过期凭据、不得仅凭存在推断存活,探测结果分为 usable、live_no_quota、definitively_rejected、transient;只有第一方 HTTP 401/403 才算认证判定,服务器错误、限流、超时、模式不匹配均属请求失败。仅在确定性凭据失败后交接;缺失来源不标降级;有可用同源时,仅在最新读数上把已存在但损坏的来源标为 degraded。陈旧仅指最后已知缓存。绝不交换刷新令牌,不保留、记录、渲染、缓存或发送其值。
凭据选择:共享于 src/providers/credential-selection.ts。存储的 expiresAt/expired 仅为建议,不构成判定或重排来源理由;已过期凭据在其来源固定优先级位置先经经验测试,经验上存活的凭据优先;瞬时失败不得在同一来源内切换候选,也不得作为认证判定。Grok、Codex、Kimi、Command Code、Copilot、OpenCode Go、Devin、Muse 使用 selectCredential。--profile-only 为 Claude 与 Codex 的失败关闭单账户探测,需 CLAUDE_CONFIG_DIR 或 CODEX_HOME,仅读该档案原生凭据文件,绕过其他来源、委托刷新与配额缓存。
多源交接与降级:损坏存储不得代表仍有可用同源存储的提供商;交接仅因凭据问题,不因传输、解码或服务器失败;来源尝试由 src/lib/source-attempts.ts 分类,降级仅在最新读数经 src/interpretation.ts 发布,src/render.ts 输出 degraded_source 行。
委托刷新:位于 src/providers/delegated-refresh.ts,是只读边界的唯一例外。仅当同一存储访问令牌过期、带刷新令牌且被厂商端点以 401/403 确定性拒绝时,才执行厂商 CLI 最小非交互轮换命令(Claude: claude doctor;Grok: grok models;Codex: app-server JSON-RPC 探测)并重读其更新文件。绝不自行做 OAuth 刷新交换,仅检查刷新令牌是否存在。信号方面不向子进程发信号或强杀,超预算按 unconfirmed/refresh_timed_out 解析。委托 Claude 前须确认无 Claude Code 进程运行,否则保持只读。其他提供商严格只读。该功能由 ProviderOptions.refreshCredentials 控制,--no-credential-refresh 禁用,auth 命令始终传 false。
测试纪律:全部使用 test/fixtures/ 的合成凭据,模拟 Keychain、Windows 凭据管理器、进程表与远程 HTTP,测试与验证期间不得访问真实端点或执行真实刷新命令。