OmniRoute 令牌健康检查的过期重试预算边界GitHub access-token 连接为何必须被持续探测【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文以 changelog.d/fixes/11592-token-health-retry-budget-boundary.md 修复条目为主线剖析 OmniRoute 主动令牌健康检查proactive token health check中「过期 剩余重试预算」这一判定边界的由来、一次由 carve-out 引发的回归、以及修复后如何保证 GitHubCopilot连接能够自愈。读者将理解EXPIRED_RETRY_MAX重试预算的完整生命周期、终态跳过守卫与三类豁免recoverable exception的取舍并掌握该机制的可测试判定规则。一、修复条目速览发生了什么该修复条目属于 OmniRoute 的 resilience韧性方向内容只有一句话却精准地描述了一次回归与一次还原恢复令牌健康检查 sweep 中的「过期连接重试预算」探测——由 #11608 重新引入的!isGitHubAccessTokenOnlyConnection特例与 #11592 钉死的边界相矛盾导致一个停在expired且仍剩重试预算的 GitHub 连接永远不会被探测也就永远无法自愈。同目录的维护性条目 changelog.d/maintenance/11592-token-health-retry-budget.md 则把这个边界抽象成了两条可测试的规则expired且仍有重试预算的连接 →必须被探测account_deactivated的连接 →始终保持跳过。要真正理解这条修复需要先回到src/lib/tokenHealthCheck.ts的实现中看清「重试预算」「终态守卫」「GitHub access-token-only 连接」这三个概念。二、背景主动令牌健康检查调度器如何工作OmniRoute 的令牌健康检查是一个后台任务实现文件周期性在 OAuth 令牌过期前主动刷新它们。文件头部的注释给出了它的三个关键参数每个连接都可配置自己的healthCheckInterval分钟默认 60 分钟0表示禁用调度器每个TICK_MS60 秒跑一轮轻量 sweep对每个符合条件的连接调用 provider 专属的刷新函数更新数据库并记录日志。代码顶部的常量进一步定义了 sweep 与重试预算的基本盘src/lib/tokenHealthCheck.tsconst LOG_PREFIX [HealthCheck]; const TICK_MS 60 * 1000; // sweep 间隔每 60 秒一轮 const DEFAULT_BATCH_SIZE 20; // 每轮处理的连接上限 const DEFAULT_HEALTH_CHECK_INTERVAL_MIN 60; // 默认每连接检查间隔分钟 const EXPIRED_RETRY_MAX 3; // 过期连接的最大重试次数 const EXPIRED_RETRY_BACKOFF_MIN 5; // 过期重试之间的退避分钟三、核心机制先重试、耗尽预算再停用retry-before-deactivation修复条目中反复出现的「retry budget重试预算」来自一次较早的 P0 缺陷修复。测试文件 tests/unit/token-health-check-retry-deactivation.test.ts 的头部注释完整记录了那段历史P0 bug一个不可恢复的刷新错误invalid_grant、refresh_token_reused等会立即把isActive置为false并把testStatus置为expired。随后终态守卫把连接挡在门外导致EXPIRED_RETRY_MAX重试循环永远成为死代码。且#7719曾把EXPIRED_RETRY_MAX与EXPIRED_RETRY_BACKOFF_MIN两个常量删除即使放行也会抛ReferenceError。修复方案与本次条目的机制直接对应是恢复两个常量在调度入口守卫处放行「expired 但剩余重试预算」的连接不可恢复刷新错误路径改为条件性停用——只有预算耗尽后才isActive: false把expiredRetry状态存进providerSpecificData与既有的refreshCircuit模式保持一致。当前代码正是这样落地的。调度入口在连接!conn.isActive时的判断src/lib/tokenHealthCheck.tsif (!conn.isActive) { // #P0: allow expired connections with retry budget remaining to pass // through so transient OAuth failures can self-heal instead of being // permanently skipped. Exhausted retries stay terminal. if (!(conn.testStatus expired getExpiredRetryCount(conn) EXPIRED_RETRY_MAX)) { return; } }也就是说停用isActive: false不等同于终态——只要expired且重试计数还没到EXPIRED_RETRY_MAXsweep 仍会继续探测它给瞬态 OAuth 失败留出自愈机会只有预算真正耗尽才把它当作不可恢复的终态跳过。四、终态守卫与三类豁免边界是怎么钉死的#8182引入的终态守卫本意是credits_exhausted/banned/expired这类连接无法通过刷新令牌自愈反复探测只会浪费 CPU 和网络src/lib/tokenHealthCheck.ts。但守卫本身用三个 recoverable 豁免把边界划得更细const isRecoverableGithubCopilotNoRefresh conn.testStatus expired conn.errorCode no_refresh_token isGitHubAccessTokenOnlyConnection(conn); const isRecoverableCursorExpired conn.testStatus expired String(conn.provider || ).toLowerCase() cursor conn.lastErrorType ! account_deactivated; const isRecoverableExpiredWithRetryBudget conn.testStatus expired conn.lastErrorType ! account_deactivated getExpiredRetryCount(conn) EXPIRED_RETRY_MAX; const terminalStatuses new Set([credits_exhausted, banned, expired]); if ( typeof conn.testStatus string terminalStatuses.has(conn.testStatus.toLowerCase()) !isRecoverableGithubCopilotNoRefresh !isRecoverableCursorExpired !isRecoverableExpiredWithRetryBudget ) { return; }逐一拆解可以提炼出被#11592钉死的完整边界语义account_deactivated永远被跳过。Cursor 场景中代码注释明确说明account_deactivated被记录为「永久死亡」——对它重试只会反复 nudge cursor-agent 并对一个已死账号重复抓取。这一点同时体现在isRecoverableCursorExpired与isRecoverableExpiredWithRetryBudget两个豁免中是唯一一处连预算都救不回来的硬性跳过条件。credits_exhausted/banned始终保持终态没有豁免不会进入重试。expired 剩余预算 → 一律探测无论 provider 形态如何GitHub access-token-only、Cursor、普通 refresh_token 连接只要预算未耗尽都应继续探测耗尽后才真正停用。五、回归现场#11608 的 carve-out 为何破坏自愈问题出在expired连接分支里被#11608重新引入的一个条件——!isGitHubAccessTokenOnlyConnection。它把「GitHub 形态的 access-token-only 连接」从「expired 剩余预算必须探测」这一通用规则中单独剔除出去与#11592钉死的边界直接冲突。那么什么是 GitHub access-token-only 连接代码用一组常量和一个判断函数给出了精确定义src/lib/tokenHealthCheck.ts// Providers whose OAuth flow yields only a GitHub-style access token (no // refresh_token) plus a short-lived Copilot sub-token: github.com Copilot and // GHE Copilot (device-code flow against the enterprise host) both fit this shape. const GITHUB_ACCESS_TOKEN_ONLY_PROVIDERS new Set([github, ghe-copilot]); function isGitHubAccessTokenOnlyConnection(conn: any): boolean { return ( GITHUB_ACCESS_TOKEN_ONLY_PROVIDERS.has(String(conn?.provider || ).toLowerCase()) typeof conn?.accessToken string conn.accessToken.trim().length 0 ); }这类连接的 OAuth 流程只产出 GitHub 风格的 access token没有refresh_token外加一个短命的 Copilot sub-token覆盖github.comCopilot 与企业版 GHE Copilot 两种场景。注释还特别提醒今后新增任何 github-token-only 的 provider例如新的 GHE 变体必须同步登记进这个集合。关键矛盾由此产生。#5326异常src/lib/tokenHealthCheck.ts本已明确一个停在expired、errorCode为no_refresh_token的 GitHub access-token-only 连接并不是真正的终态——它正是自愈逻辑canClearGitHubNoRefreshTokenState的目标对象一旦 Copilot sub-token 被证明可用就把过期的no_refresh_token状态清回active。若按#11608的 carve-out 把这类连接从预算探测中排除自愈路径将永远不可达健康的 Copilot 连接会卡死在expired。因此本次修复#11592删掉该 carve-out恢复统一边界expired 剩余预算的 GitHub 连接必须继续被探测让「清除no_refresh_token状态 → 回到active」的闭环得以走通。六、预算耗尽时的落地条件停用与日志重试预算的每一次消耗与最终停用都发生在不可恢复刷新错误的处理路径上src/lib/tokenHealthCheck.tsconst expiredRetryCount getExpiredRetryCount(conn) 1; const isRetryBudgetExhausted expiredRetryCount EXPIRED_RETRY_MAX; ... await updateProviderConnection(conn.id, { ... testStatus: expired, ... providerSpecificData: withExpiredRetry(psd, expiredRetryCount, now), // #P0: only deactivate when the retry budget is exhausted. Before that, // keep the connection active so subsequent sweeps can retry the refresh. ...(isRetryBudgetExhausted ? { isActive: false } : {}), ... }); logError( ${LOG_PREFIX} ✗ ${conn.provider}/${getConnectionLogLabel(conn)} — Refresh token is permanently invalid (${errorLabel}). (isRetryBudgetExhausted ? Connection deactivated. Re-authenticate to restore. : Retry ${expiredRetryCount}/${EXPIRED_RETRY_MAX} used; keeping connection active for retry.) );几个值得注意的实现细节重试状态存于providerSpecificData.expiredRetry { count, at }而非顶层列。原因是provider_connections表结构没有对应字段顶层字段会被_buildUpdateConnectionRowParams静默丢弃这与refreshCircuit先例一致src/lib/tokenHealthCheck.ts。停用只在预算耗尽时发生isRetryBudgetExhausted为真才附带写isActive: false否则保留isActive让后续 sweep 继续重试。旋转型令牌rotating-tokenprovider 的区分只有 Codex/OpenAI 这类一次性refresh_token才会在失败后被清空而 Google 系antigravity/gemini的refresh_token是用户唯一的恢复凭证清空会导致#3679描述的永久不可恢复因此被保留。这条路径与入口守卫第三节共同构成完整的预算闭环入口按预算放行 → 刷新失败则计数 → 耗尽才停用 → 未耗尽继续探测。七、可测试的判定规则与验证边界#11592的修复不是一次性的打补丁而是刻意做成「钉死边界」的测试契约。维护条目将其浓缩为两条断言式的规则连接状态判定原因expired 剩余重试预算含 GitHub access-token-only探测瞬态 OAuth 失败可自愈GitHub 连接需让no_refresh_token自愈逻辑可达account_deactivated始终跳过账号被记录为永久死亡重试只会重复触发上游抓取副作用围绕这两条规则仓库内有成组的针对性测试可佐证tests/unit/token-health-check-retry-deactivation.test.ts —— TDD 钉死「先重试、预算耗尽才停用」的主线覆盖不可恢复错误不再立即停用、预算耗尽后的终态语义tests/unit/token-health-check-cursor.test.ts —— 覆盖 Cursor 形态的 recoverable 分支及account_deactivated保持跳过tests/unit/token-health-no-refresh-token-expired-5326.test.ts —— 覆盖#5326场景no_refresh_token的 GitHub 连接非终态、必须可达自愈。值得再次强调边界上的不对称性预算只对expired起效account_deactivated无论预算如何都不可重试。Cursor 代码注释src/lib/tokenHealthCheck.ts解释了原因——account_deactivated是文档化的永久死亡状态反复探测会不断扰动 cursor-agent 并对已死账号做无意义的重复抓取。这条不对称规则同时被维护条目、三处豁免代码与多个测试反复锁定正是「边界」一词的全部含义。八、关联机制GitHub 凭证健康检查的更大图景把视角拉远本次修复是 GitHub 凭证健康管理链路中的一环。#10352changelog.d/fixes/10352-github-access-token-health.md确立了主动健康检查对 GitHub 的处理基调通过既有的 Copilot token exchange 验证 GitHub access token只把确认的401 Unauthorized标记为 expired而速率限制、权限失败、上游失败与网络错误都保持可路由状态——避免把暂时的上游抖动误判成凭证死亡。本次#11592的修复则补上了这条链路的「复位」环节正因为#10352只对真正的401置 expiredexpired状态对 GitHub 而言更可能是可恢复信号而非终态所以 sweep 必须带着剩余预算继续探测它让自愈逻辑有机会把它清回active。两者合起来回答了本文的核心疑问GitHub access-token-only 连接之所以必须在expired且剩预算时被探测是因为这类连接的自愈依赖 sweep 的持续触达任何一刀切的终态跳过都会让健康连接永远卡死在过期状态。总结#11592修复条目虽短却浓缩了 OmniRoute 令牌健康检查在韧性设计上的一个关键决策点把「停用」从「终态」中分离出来用显式重试预算EXPIRED_RETRY_MAX 3、EXPIRED_RETRY_BACKOFF_MIN 5接管「过期但可能恢复」的连接同时为预算豁免保留account_deactivated这一不可逾越的硬边界。对github/ghe-copilot这类无refresh_token的连接只有持续探测才能触发no_refresh_token状态清理并回归active。该边界已通过 maintenance 条目 固化为契约并有 retry-deactivation、cursor、5326 三组测试持续守护防止未来任何类似 carve-out 再次让自愈路径失联。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考