[统一能力平台] SDK/CLI 支持 API Key、OAuth Device Flow 与 Agent Delegation

[ax2]

背景

toolkit 需要在保留 API Key 兼容性的同时，为交互式用户、无浏览器终端和 Agent 提供统一的凭证抽象。这个 parent issue 只跟踪公开客户端能力；Authorization Server、Resource Server 和计费服务的实现不属于本仓库。

2026-07-18 状态审计

Phase 0 已由 #226 / #231 完成。Phase 1 已由 #227 / #250 完成，并已基于两个受支持测试部署的公开 Device Authorization、refresh rotation 与 revoke 契约完成验证。

Phase 2 仍缺少完整、可验证的公开 token exchange / Agent Delegation 契约，包括受众绑定、scope/resource/预算收窄规则、错误结构和测试 fixtures。因此 parent issue 继续保持 blocked，不实现猜测性的 delegation 客户端。正式部署的 Device Flow 上线和发布验收属于外部服务发布动作，不影响 toolkit Phase 1 客户端实现的完成状态。

分阶段目标

Phase 0：凭证抽象，已完成（#226 / #231）

• CLI、JavaScript SDK 和 Python SDK 的请求层从统一 provider 获取凭证。
• 现有 QVERIS_API_KEY、构造参数和配置文件优先级保持不变。
• provider contract 支持未来按 resource/scopes 请求 token，但不伪造 OAuth endpoint。
• 日志、异常、telemetry 和 repr 不显示完整 API Key 或 token。
• API Key 回归和 provider contract tests 完整。

Phase 1：Device Flow 与会话生命周期，已完成（#227 / #250）

• CLI auth login/status/logout。
• Device Authorization Grant 的 pending、slow_down、denied、expired 状态机。
• refresh rotation、并发刷新合并、revoke 和安全存储。
• 缺 scope/resource 时给出可执行的重新授权提示。

实现依据：受支持测试部署的 discovery 已声明 Device Authorization、refresh、revoke 能力，并提供已登记的 public CLI client 和稳定错误契约。客户端对未声明该契约的部署明确失败，不猜测 endpoint 或静默降级。

Phase 2：Agent Delegation，blocked（#228）

• 用户授权换取短期、不可刷新的 Agent token。
• scope/resource、run_id、预算以及 tool/model 限制只能收窄。
• 默认不将 delegation token 写入磁盘。
• 401 最多进行一次安全的凭证更新重试，业务 4xx 不重试。

开始条件：公开 token exchange/delegation 契约、受众绑定 Resource Server 和测试 fixtures 可用。

统一 Provider 方向

• ApiKeyCredentialProvider
• OAuthCredentialProvider（Phase 1）
• AgentDelegationProvider（Phase 2）
• 可选 WorkloadCredentialProvider（另行评估）

请求层只依赖类似 getCredential(resource, scopes) 的接口，不根据 API Key 前缀或 region 参数切换 endpoint，也不在 resource/audience 不匹配时静默回退到 API Key。

总体验收标准

• API Key 行为和 endpoint 选择无回退。
• Tool、Model、Usage 请求不各自维护认证逻辑。
• 无浏览器终端可通过标准 Device Flow 登录。
• refresh token 自动轮换、并发安全且可撤销。
• Agent 只获得短期最小权限 token。
• token/API Key 不出现在日志、异常、telemetry 或普通状态输出中。
• README、CLI help 和最小示例与受支持部署的公开 discovery 一致。

公开关联

• [Product/Roadmap] Triggers/webhooks + qveris listen #164 — triggers/webhooks 与 qveris listen
• [P1][Auth] Introduce API-key-compatible credential providers across CLI and SDKs #226 / Add API-key-compatible credential providers #231 — Phase 0：已完成
• [Auth] Add CLI Device Flow, refresh rotation, and revoke lifecycle #227 / feat(cli): add OAuth Device Flow authentication #250 — Phase 1：Device Flow、refresh rotation 与 revoke，已完成
• [Blocked][Auth] Add Agent Delegation credential exchange #228 — Phase 2：Agent Delegation，blocked

非目标

• 不在本仓库实现 Authorization Server、Resource Server、模型路由或 Billing。
• 不在公开契约就绪前硬编码 endpoint、issuer、client、resource 或错误码。

[ax2]

统一平台方案复审、跨仓依赖和全部实施 issue 总表：https://zxoriiwxds4.feishu.cn/wiki/D3g2wOGHRioj2hkYkxWcyVPxnDf

原始方案：https://zxoriiwxds4.feishu.cn/wiki/TkTCwkmH3iZgqSkLP1qcadPJnFN

[linfangw]

Current status after the latest public release:

• Phase 0 credential-provider abstraction remains complete.
• Phase 1 Device Flow remains complete in the toolkit; CLI 0.9.0 release preparation is in chore(release): prepare coordinated client releases #258, and its Node 18/20/22 plus Windows release matrix passed.
• Phase 2 remains blocked for the reasons recorded in [Blocked][Auth] Add Agent Delegation credential exchange #228; the current public contract still has no token-exchange/delegation surface.

Keeping this parent issue open and blocked is accurate until Phase 2 has a complete public contract. Phase 1 publication can proceed independently after its stacked client PRs merge.