这是一个 Pi 扩展包,新增 gemini-cli-oauth provider,用于通过 Gemini CLI 风格 OAuth 登录访问 Gemini Code Assist,并支持配置 Google Cloud projectId,让企业用户使用指定 Google project 的额度。
风险提示:Gemini CLI OAuth 接入第三方工具可能受 Google 政策和风控影响。企业或组织账号请优先确认内部合规要求,并显式配置
projectId。
从 npm 安装(推荐):
pi install npm:pi-geminicli-oauth或直接从 GitHub 安装:
pi install https://github.com/Heelc/pi-geminicli-oauth两种方式都可以加 -l 只装到当前项目(写入 .pi/settings.json)而不是用户级:
pi install -l npm:pi-geminicli-oauthPi 会自动加载 package.json 中 pi.extensions 指向的 ./src/index.ts。无需额外 npm install:运行时只依赖 Node 内置模块和 Pi 自身提供的 @earendil-works/pi-ai(已声明为 optional peer dependency,不会被重复安装),typescript / vitest 仅开发时需要。
安装后可以确认 provider 已注册:
pi --list-models gemini-cliprovider model context max-out thinking images
gemini-cli-oauth gemini-3-flash 1M 65.5K yes yes
gemini-cli-oauth gemini-3.1-pro-preview 1M 65.5K yes yes
gemini-cli-oauth gemini-3.8-flash 1.0M 65.5K yes yes
更新与卸载(把来源替换成你安装时用的写法):
pi update npm:pi-geminicli-oauth
pi remove npm:pi-geminicli-oauth也支持 pi install git:github.com/Heelc/pi-geminicli-oauth 等其他来源写法。
要求 Node >= 20。
git clone https://github.com/Heelc/pi-geminicli-oauth
cd pi-geminicli-oauth
npm install # 仅开发/测试需要
pi -e ./src/index.ts # 单次加载,不写入 settings或用 pi install ./pi-geminicli-oauth 安装本地路径。
启动 Pi 后执行:
/login gemini-cli-oauth
流程:
- Pi 启动本地回调监听器
http://localhost:8085/oauth2callback,并打开 Google OAuth 授权 URL。 - 完成授权后,浏览器会跳回 localhost,插件自动读取
code并校验state。 - 如果本地监听器不可用(例如端口被占用、SSH/headless 环境),会回退到手动粘贴回调 URL 或授权码。
- 可选输入 Google Cloud
projectId;非空时会自动保存到用户级配置~/.pi/agent/gemini-cli-oauth.json。 - Pi 保存 OAuth refresh/access token,后续自动刷新 access token。
当前版本仅支持 Pi 为 gemini-cli-oauth 保存的一组 OAuth 凭据;再次执行 /login gemini-cli-oauth 会按 Pi 的单 provider 登录语义覆盖/更新当前凭据,不提供多账号池、账号切换或账号轮换。
企业、学校、Workspace 或 Gemini Code Assist Standard/Enterprise 用户应显式配置 projectId,以使用对应 Google Cloud project 的额度。
推荐方式是在 /login gemini-cli-oauth 流程中按提示输入 projectId,插件会自动写入用户级配置:
~/.pi/agent/gemini-cli-oauth.json
如果登录时留空,插件会在请求前先尝试通过 Code Assist loadCodeAssist 自动发现 managed project;若账号允许 free-tier,会继续调用 onboardUser 获取 managed project。自动发现或引导成功后,插件会将该 managed project 写入用户级配置 ~/.pi/agent/gemini-cli-oauth.json,后续 Pi 重启后可直接复用,减少首次请求探测延迟。企业/组织配额仍建议显式配置 projectId,显式配置始终优先。
解析优先级:
PI_GEMINI_CLI_PROJECT_ID- 项目配置:
.pi/gemini-cli-oauth.json - 全局配置:
~/.pi/agent/gemini-cli-oauth.json GOOGLE_CLOUD_PROJECTGOOGLE_CLOUD_PROJECT_ID
配置文件示例:
{
"projectId": "your-google-cloud-project-id"
}环境变量示例:
export PI_GEMINI_CLI_PROJECT_ID=your-google-cloud-project-id插件会注册 /gemini-quota 命令,用当前 gemini-cli-oauth 登录凭据和已解析的 projectId 调用 Code Assist retrieveUserQuota。access token 过期时会先用 refresh token 刷新并写回本地 auth,再展示按 Flash / Pro / Other 分组的 quota buckets;重置时间默认以 UTC+8 易读格式展示。
/gemini-quota
示例输出:
Gemini quota:项目 codeassist-preview
时区:UTC+8
Flash
gemini-3-flash 56.0% REQUESTS 2026-07-02 12:45:17
Pro
gemini-3.1-pro-preview 98.4% REQUESTS 2026-07-03 10:34:55
如果未登录或缺少 projectId,命令会给出对应提示。
当前版本 /gemini-quota 只查询当前登录账号和当前解析到的 projectId,不展示多账号聚合 quota。
如需排查真实请求、限流、project 或 token 刷新问题,可在启动 Pi 前开启:
export PI_GEMINI_CLI_OAUTH_DEBUG=1插件会在当前工作目录写入 gemini-cli-oauth-debug-*.log,记录脱敏后的请求 URL、project、model、headers、body preview、响应状态、trace id、retry 延迟等信息;Authorization 和 API key 类 header 会被隐藏。
Provider ID:gemini-cli-oauth
初始注册模型与常用别名:
gemini-3.8-flash:最新 Flash,无别名,用完整 ID 选择gemini-3-flash:preview、flash-preview、gemini-preview(别名保持指向它,已有配置不受影响)gemini-3.1-pro-preview:pro、pro-preview、gemini-pro-preview
模型元数据已提供非零成本估算,避免 usage cost 被误报为 0。
- system prompt 会作为 Gemini
systemInstruction发送。 - Gemini 3 模型使用
thinkingLevel,Gemini 2.5 模型使用thinkingBudget。 - 默认
includeThoughts: true,与 Pi 中 GPT provider 的 thinking 展示习惯保持一致;调用方可显式传入includeThoughts: false或thinking.enabled: false关闭输出。启用 reasoning 时,Gemini thought part 会输出为 Pithinking_start/thinking_delta/thinking_end事件并保留thinkingSignature。 - SSE 响应会按
data:到达顺序增量输出text_delta,并在最终消息中保留完整正文。 - 插件会过滤历史中的 thought-only model turn,归一化
cached_content/cachedContent,并把 Code AssisttraceId映射为responseId。 - 工具调用已支持完整 Pi ↔ Gemini 闭环:Pi
tools会发送为 GeminifunctionDeclarations,GeminifunctionCall会转成 Pitoolcall_*事件,后续 PitoolResult会回放为 GeminifunctionResponse;图片 toolResult 会按模型能力处理,Gemini 3 放入functionResponse.parts,Gemini 2.5 拆成单独 user image turn。 - 支持
toolChoice→ GeminitoolConfig.functionCallingConfig,并保留 GeminithoughtSignature到后续工具调用上下文。 - 稳定性恢复:请求前会在 access token 临近过期时主动 refresh 并持久化;Code Assist 返回 401 时也会 refresh access token 并重试一次;429/5xx/网络错误会按
RetryInfo、Retry-After或带 jitter 的指数退避重试,同一 project/model/endpoint 会记录短期 cooldown,永久QUOTA_EXHAUSTED不会盲目重试。 - Pi 原生行为对齐:
usageMetadata会补齐cacheRead、reasoning、totalTokens与成本统计;SAFETY/MALFORMED_FUNCTION_CALL/UNEXPECTED_TOOL_CALL会作为错误停止;请求前会清洗非法 Unicode surrogate。 - 高级请求选项:支持
temperature、maxTokens写入 GeminigenerationConfig,支持自定义 headers 合并(保留 OAuthAuthorization不被覆盖),并支持onPayload/onResponse调试钩子;显式thinking配置优先于reasoning派生配置。 - project 体验:显式
projectId优先;未配置时会尝试loadCodeAssist自动发现 managed project,并在free-tier可用时通过onboardUser引导 managed project;同一账号/模型的 project context 会缓存并发去重,onboardUser长操作会轮询至完成;自动发现/引导出的 managed project 会持久化到用户级配置,便于下次启动直接复用。 - 账号边界:当前版本保持单账号 OAuth 语义,不支持多个 Gemini OAuth 账号同时登录、账号池、429 自动切换账号或多账号 quota 聚合。
npm install
npm test
npm run typecheck当前测试覆盖:
- projectId 配置解析优先级
- OAuth 授权 URL、授权码交换、refresh token
- Code Assist 请求包装与响应/SSE 解包
- provider 注册与关键错误提示
/login gemini-cli-oauth后可选保存用户级projectId配置- OAuth 本地 callback listener 自动捕获授权
code,并覆盖 listener 不可用时的手动粘贴兜底 - 真正 SSE 增量输出、thought-only 历史清洗、cachedContent 归一化
traceId→responseId、Google error details 增强、/gemini-quota分组 quota 查询与过期 token 刷新- Pi toolCall/toolResult 与 Gemini functionCall/functionResponse 双向转换、toolChoice/toolConfig、thoughtSignature 保留
- 401 refresh retry、429/5xx/network retry、RetryInfo 解析、quota/capacity/rate-limit 分类
- usage/cacheRead/reasoning/cost、错误 finishReason、responseId 写回、Unicode surrogate 清洗
- 默认 thinking 事件流、显式关闭开关、Gemini 3/2.5 toolResult 图片转换、thinkingSignature 保留
- temperature/maxTokens、headers 合并、onPayload/onResponse、显式 thinking 配置优先级
- managed project 自动发现、free-tier onboarding、模型 aliases 与非零 cost 元数据、managedProjectId 长期持久化
- User-Agent 版本/surface 覆盖、project context 缓存与 onboard 轮询、debug 日志脱敏、Retry-After/cooldown、请求前主动 refresh 与凭据持久化
本项目通过 npm Trusted Publishing(GitHub Actions OIDC)发版,仓库里不存任何 npm token,发布时也不需要 2FA 一次性码。
发一个新版本:
npm version patch # 或 minor / major,会自动改 package.json 并打 tag
git push --follow-tags推送 v* tag 会触发 .github/workflows/publish.yml:先校验 tag 与 package.json 版本一致,再跑 npm ci、typecheck、测试,最后 npm publish。任一步失败都不会发布。也可以在 Actions 页面手动触发(workflow_dispatch)。
发布产物会自动带上 provenance 证明,使用者可以验证包确实由本仓库的这条工作流构建。
src/constants.ts 中的 GEMINI_CLIENT_ID / GEMINI_CLIENT_SECRET 与官方开源 google-gemini/gemini-cli 使用的是同一组公开 installed-app 凭据。按 OAuth 2.0 规范,原生/CLI 客户端的 client secret 不具备机密性,因此它们随源码公开不构成凭据泄漏。
你自己的 OAuth token 不在仓库内:access/refresh token 由 Pi 保存在本地 ~/.pi 下,projectId 保存在 ~/.pi/agent/gemini-cli-oauth.json 或项目级 .pi/gemini-cli-oauth.json,这些路径均已被 .gitignore 排除。
本项目为非官方的第三方实现,与 Google 无关联。通过 Gemini CLI OAuth 接入第三方工具可能受 Google 服务条款、政策变更和风控影响,请自行评估风险。企业或组织账号请先确认内部合规要求,并显式配置 projectId。