ExtensionProvider@piex-dev/xai-oauth

xai-oauth — 用订阅登录 Grok，而不是绑死 API Key

导语

若你已为 Grok 订阅付费，@piex-dev/xai-oauth 让 pi 走同一套配额；API Key 通道仍留给自动化与按量场景。

简介

pi 内置 xai 走 API Key（按量计费、模型固定、适合 CI）。但很多用户手里是 SuperGrok 订阅或 X Premium+ 额度——已为订阅付过钱却还要再开 API Key 走另一套账本。`@piex-dev/xai-oauth` 在 /login 增加 xAI Grok，用标准设备码 OAuth 授权，登录后后台发现模型（订阅 vs 公开 API 分流），与内置 xai 并存互不抢戏。

技术原理

Device Authorization Grant（RFC 8628）：扩展作为 public client（不持有 secret）请求 device_code，用户在官方页面认证，扩展只拿 token；access_token 过期前用 refresh_token 续期。登录后对两边 /v1/models 拉取（公开 API api.x.ai + 订阅代理 cli-chat-proxy.grok.com），合并进 provider 模型表——新模型出现后 /reload 即可，不必升级 npm 包。

内置 xai	xai-oauth
API Key 认证	OAuth 订阅
按量计费	订阅配额
固定公开集	fallback + 实时发现
内置	扩展

使用说明

安装

bash

pi install npm:@piex-dev/xai-oauth

仓库源码：extensions/xai-oauth

用法

flow

/login → 选 xAI Grok（SuperGrok / X Premium+）
→ 浏览器打开验证页确认
→ /model grok-4.5（或列表里出现的 id）

配置

模型白名单/排序：PI_XAI_OAUTH_MODELS=grok-build,grok-4.5。订阅 token 存 pi 标准存储，扩展层不落盘。`/reload` 即可拿到新模型。

验证

bash

bun test extensions/xai-oauth/test/xai-oauth.test.ts extensions/xai-oauth/test/models.test.ts

实现方案

xai-oauth.ts OAuth 流程 + registerProvider；models.ts 目录/发现/合并/路由。piex 少数带单测的包。安全姿态：错误信息截断（只提取 error/error_description 限长，避免整包响应进日志）；端点校验（仅 *.x.ai）；token skew（提前数分钟过期 + 最小 TTL 地板）；slow_down（加大轮询间隔）。模型层：fallback 目录（离线可用）+ triggerDiscovery（登录后后台拉取）+ rebuildModelsForOAuth（合并标记路由）+ 环境变量过滤。

设计参考

项目	机制	piex 取舍
oh-my-pi xai-oauth	RFC 8628 完整流程；双 endpoint 发现；标准 OAuth provider 注册	采纳：流程链路、client_id（同源）、端点校验、错误截断/skew。不采纳：Bun 运行时
stnly/pi-grok	拉取 /v1/models 合并进 provider	借鉴：实时发现理念，实现独立重写
pi 内置 xai	API Key + 固定模型集	并存：Key/CI + 订阅/交互不冲突

核心取舍：订阅 token 存 pi 标准存储（扩展层不落盘），模型发现 best-effort（失败回退 fallback），安全姿态「宁可少报不错报」。

迭代记录

路线图

方向	打算
强依赖 xAI 侧变更	薄封装 + 快速跟版；OIDC/device code 契约测试（快照 mock）防回归
模型发现 best-effort	/models 或 status 标明来源（discovered/fallback）与路由；PI_XAI_OAUTH_MODELS 写成一等配置说明
错误与配额语义偏生	分错误类给出下一步（重新 /login、换模型、检查订阅）
与内置 xai 易混淆	UI/status 明确当前 provider 与计费路径
企业场景未覆盖	个人订阅路径做稳；企业需求单独评估

版本记录

版本	日期	变更
0.1.1	2026-07-19	初始版本：RFC 8628 OAuth 流程；双 endpoint 模型发现（公开 API + 订阅代理）；fallback 目录 + triggerDiscovery + rebuildModelsForOAuth 路由合并；PI_XAI_OAUTH_MODELS 白名单；安全姿态（错误截断、端点校验 *.x.ai、token skew、slow_down）；订阅 token 走 pi 标准存储不落盘；单测覆盖

源稿 Markdown：docs/packages/xai-oauth.md