pi-ccswitch-auto-switch 0.3.14 → 0.3.16

package/README.md

@@ -1,5 +1,7 @@
 # Pi CCSwitch Auto Switch
 
+> **Recommended project:** [Magpie](https://github.com/yetone/magpie) for managing models, accounts, and routing across multiple AI agents.
+
 > 中文说明：[README.zh-CN.md](README.zh-CN.md)
 
 Resilient model failover for [Pi](https://github.com/badlogic/pi-mono) when its providers are managed by [CC Switch](https://ccswitch.io/).
@@ -13,6 +15,7 @@ The extension observes real Pi requests, records sanitized health signals, and
 - Endpoint circuit breakers for DNS, connection, server, and streaming failures.
 - Endpoint platform isolation: when several models on the same endpoint (same BaseURL/provider) fail within one round, the whole endpoint is isolated so sibling models from the same platform are not tried one by one.
 - Model-only isolation for missing models and incompatible parameters.
+- Stops on missing Pi bundle chunks with a full-restart hint, without penalizing model/provider/endpoint health or isolating a platform.
 - Learns model-family content-policy constraints from real failures (`glm-4.5` and `GLM-4.6`, for example, are both `glm`) and avoids the entire family during the current content-policy failover chain. Evidence lives only in the owning extension instance, is never written to shared health state, and is cleared at that instance’s `session_start`, because a new session may handle tasks that are not content-sensitive, so the family becomes eligible again until this session observes its own content-policy rejection.
 - Applies hard health, failure-domain, policy-family, input-modality, and context filters before ranking candidates by provider diversity, model equivalence, capability compatibility, and historical reliability.
   - Independent-provider semantics: a copied vendor (e.g. `my-provider-copy`) shares the BaseURL but is a distinct provider with its own endpoint key, so isolating one never blocks the other.
@@ -57,7 +60,9 @@ This works on macOS, Linux, and Windows when Git is available. After the npm rel
 pi install npm:pi-ccswitch-auto-switch
 ```
 
-Restart Pi or run `/reload` after installing or updating. To update the Git installation later, run `pi update --extensions`.
+Restart Pi or run `/reload` after installing or updating this extension. To update the Git installation later, run `pi update --extensions`.
+
+After updating **Pi itself**, fully exit and restart Pi, then resume your session. `/reload` reloads extensions and resources within the existing process. If that process still references replaced Pi bundle chunks and reports `Cannot find module .../pi-coding-agent/dist/bundle/chunks/...`, CCSwitch stops the current round and asks you to restart Pi. This local loading failure does not count toward model/provider/endpoint cooldowns or the three-failure platform isolation threshold.
 
 CC Switch should be configured normally. This extension deliberately does not write Pi model settings or CC Switch data.
 
@@ -144,7 +149,7 @@ The state machine waits for Pi's native retry cycle to settle before switching.
 | Failure | Scope | Initial cooldown |
 | --- | --- | --- |
 | `401`, `403`, quota, billing | Provider | 30 minutes |
-| `429` | Provider | `Retry-After` when present; otherwise 5 minutes |
+| `429` | Provider | quota/billing body (e.g. `AccountQuotaExceeded`) → 30 minutes; otherwise `Retry-After` when present, else 5 minutes |
 | DNS, network, `408`, `5xx`, interrupted stream | Endpoint | 2 minutes |
 | `404`, invalid model, incompatible parameters | Model | 15 minutes |
 | Content-policy or sensitive-content rejection | Current model + learned model-family constraint | 2-minute model cooldown; family evidence is session-scoped (cleared at `session_start`) |

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # Pi CCSwitch 自动故障转移
 
+> **推荐项目：** [Magpie](https://github.com/yetone/magpie)，适合统一管理多个 AI Agent 的模型、账号和路由。
+
 > English: [README.md](README.md)
 
 当 [CC Switch](https://ccswitch.io/) 管理 [Pi](https://github.com/badlogic/pi-mono) 的 Provider 时，为 Pi 提供更稳健的模型自动故障转移。
@@ -12,6 +14,7 @@
 - 对认证、额度、账单和限流实施 Provider 优先熔断。
 - 对 DNS、连接、服务端和流中断实施端点熔断。
 - 模型不存在或参数不兼容时仅隔离该模型。
+- Pi 本地程序分块文件缺失时停止本轮切换并提示完整重启，不计入模型、Provider 或端点健康，也不触发平台隔离。
 - 内容审查失败会学习模型系列约束（例如 `glm-4.5`、`GLM-4.6` 同属 `glm`），在本轮内容审查故障转移中避开整个受限系列。该约束仅保存在当前扩展实例的内存中，不写入共享健康状态；当前实例的 `session_start` 只清除自身约束，因为新 session 处理的任务不一定涉及审查内容，模型系列恢复可用，直到本 session 再次观察到内容审查拒绝。
 - 候选模型先经过健康、故障域、审查系列、输入模态和上下文窗口硬过滤，再按跨 Provider、模型等价性、能力兼容和历史稳定性排序。
 - 首响应 90 秒、流式停滞 120 秒看门狗。
@@ -55,7 +58,9 @@ pi install git:github.com/JunyWuuuu91/pi-ccswitch-auto-switch
 pi install npm:pi-ccswitch-auto-switch
 ```
 
-安装或更新后重启 Pi，或执行 `/reload`。后续更新 Git 版本可执行 `pi update --extensions`。
+安装或更新本扩展后重启 Pi，或执行 `/reload`。后续更新 Git 版本可执行 `pi update --extensions`。
+
+更新 **Pi 本体**后，应完整退出并重新启动 Pi，再恢复原会话。`/reload` 只在现有进程中重载扩展和资源。如果旧进程仍引用已被替换的 Pi 程序分块文件，报出 `Cannot find module .../pi-coding-agent/dist/bundle/chunks/...`，CCSwitch 会停止本轮切换并提示重启 Pi。这类本地加载错误不计入模型、Provider 或端点冷却，也不累计到“失败 3 次隔离平台”的阈值。
 
 ### 无头自动化调用
 
@@ -132,7 +137,7 @@ CCS v0.3.5 ✓70/131 · ⏳61 · ⛔0 · 🔄3 · provider/model-id
 | 失败类型 | 熔断范围 | 初始冷却 |
 | --- | --- | --- |
 | `401`、`403`、额度或账单问题 | Provider | 30 分钟 |
-| `429` | Provider | 优先使用 `Retry-After`，否则 5 分钟 |
+| `429` | Provider | 配额/余额正文（如 `AccountQuotaExceeded`）→ 30 分钟；否则优先使用 `Retry-After`，无则 5 分钟 |
 | DNS、网络、`408`、`5xx`、流中断 | 端点 | 2 分钟 |
 | `404`、模型不存在、参数不兼容 | 模型 | 15 分钟 |
 | 内容审查/敏感拦截 | 当前模型 + 模型系列约束 | 模型冷却 2 分钟；系列约束按 session 隔离（`session_start` 时清除） |

package/classify.ts

@@ -14,18 +14,27 @@ const quota = /quota|billing|insufficient.?balance|out of budget|usage.?limit|cr
 const context = /context.?window|context.?length|too many tokens|prompt is too long|input is too long|token limit/i
 const transport = /dns|enotfound|eai_again|econn(?:reset|refused|aborted)|epipe|socket|connection|network|fetch failed|tls|certificate|timed? ?out|timeout|stream ended|terminated|websocket|und_err/i
 const overloaded = /overload|server busy|service unavailable|temporarily unavailable|capacity|upstream|bad gateway/i
+// 只匹配缺失的 Pi 分块文件本身，不能把 imported from 中的 Pi 路径当成缺失目标。
+const localRuntime = /cannot find (?:module|package) ['"][^'"\r\n]*[\\/]pi-coding-agent[\\/]dist[\\/]bundle[\\/]chunks[\\/][^'"\r\n]+['"]/i
 
 export function classifyFailure(observation: FailureObservation): Classification {
   const text = `${observation.rawStopReason ?? ''} ${observation.message ?? ''}`
   const status = observation.status
   if (observation.aborted && !observation.watchdog) return { kind: 'unknown', roundOnly: true }
+  if (localRuntime.test(text)) return { kind: 'local_runtime', roundOnly: true }
   if (observation.watchdog) return { kind: 'timeout', scope: 'endpoint', roundOnly: false }
   // 内容审查/敏感拦截属于该模型的失败：按 model 级记录并与冷却（2min×2ⁿ 上限 30min），
   // chooseCandidate 会排除后自动切换到其他模型，而不是同一内容原样重试到本轮上限。
   if (content.test(text)) return { kind: 'content_policy', scope: 'model', roundOnly: false }
   if (context.test(text)) return { kind: 'context_overflow', roundOnly: true }
   if (status === 413) return { kind: 'context_overflow', roundOnly: true }
-  if (status === 429) return { kind: 'rate_limit', scope: 'provider', roundOnly: false, retryAfterMs: observation.retryAfterMs }
+  // 账户级配额耗尽常以 429 上报（如 AccountQuotaExceeded + "exceeded the 5-hour usage quota"）。
+  // quota 文本必须优先于瞬时 rate_limit：否则死 provider 只按 5min 冷却停放，
+  // 在数小时后才重置的配额窗口内被放回健康池重试。
+  if (status === 429) {
+    if (quota.test(text)) return { kind: 'quota', scope: 'provider', roundOnly: false }
+    return { kind: 'rate_limit', scope: 'provider', roundOnly: false, retryAfterMs: observation.retryAfterMs }
+  }
   if (status === 402) return { kind: 'quota', scope: 'provider', roundOnly: false }
   if (status === 403 && quota.test(text)) return { kind: 'quota', scope: 'provider', roundOnly: false }
   if (status === 401 || status === 403) return { kind: 'auth', scope: 'provider', roundOnly: false }

package/index.ts

@@ -17,7 +17,7 @@ const roundLimitMs = (): number => {
   return Number.isFinite(override) && override > 0 ? override : ROUND_LIMIT_DEFAULT
 }
 const RPC_PROTOCOL_VERSION = 1
-const EXTENSION_VERSION = '0.3.14'
+const EXTENSION_VERSION = '0.3.16'
 // 同端点（BaseURL 相同）连续失败达到该次数即隔离该端点，避免同一个平台的多个模型逐个试错耗尽本轮切换
 const ENDPOINT_FAIL_THRESHOLD = 3
 
@@ -197,15 +197,16 @@ export default function (pi: ExtensionAPI) {
     round.phase = 'exhausted'
     clearWatchdog()
     ctx.ui.setWorkingMessage()
+    const lastFailure = round.observation ? classifyFailure(round.observation).kind : undefined
+    const recovery = lastFailure === 'local_runtime' ? '' : '\n\n可使用 /ccswitch status 查看状态，/ccswitch reactivate <provider/model|all> 重新激活。'
     // 报告列出本轮每个已试模型及其最后错误，便于直接定位是哪个 provider/模型、什么原因
     const triedLines = [...round.tried].map(item => {
       const error = round!.errors.get(item)
       return error ? `- ${item} — ${error}` : `- ${item}`
     })
-    await health.report(`# CCSwitch 自动故障转移失败\n\n时间：${new Date().toISOString()}\n原因：${reason}\n\n已尝试：\n${triedLines.join('\n')}\n\n可使用 /ccswitch status 查看状态，/ccswitch reactivate <provider/model|all> 重新激活。`)
+    await health.report(`# CCSwitch 自动故障转移失败\n\n时间：${new Date().toISOString()}\n原因：${reason}\n\n已尝试：\n${triedLines.join('\n')}${recovery}`)
     await health.log(`round exhausted: ${reason}; tried=${[...round.tried].join(',')}`)
     if (ctx.mode === 'rpc') {
-      const lastFailure = round.observation ? classifyFailure(round.observation).kind : undefined
       try {
         pi.appendEntry?.('ccswitch-exhausted', {
           protocolVersion: RPC_PROTOCOL_VERSION,
@@ -222,7 +223,7 @@ export default function (pi: ExtensionAPI) {
     }
     const currentKey = key(round.model)
     const currentError = currentKey ? round.errors.get(currentKey) : undefined
-    notify(ctx, `CCSwitch：自动切换停止（${reason}）${currentError ? `；当前 ${currentKey}：${currentError}` : ''}，请用 /ccswitch 查看详情`, 'error')
+    notify(ctx, `CCSwitch：自动切换停止（${reason}）${currentError ? `；当前 ${currentKey}：${currentError}` : ''}${lastFailure === 'local_runtime' ? '' : '，请用 /ccswitch 查看详情'}`, 'error')
     status(ctx)
   }
   /**
@@ -309,9 +310,11 @@ export default function (pi: ExtensionAPI) {
     // 下一轮还会重试同一个刚失败的模型/provider
     if (!classification.roundOnly && classification.scope) health.recordFailure(classification.scope, classification.scope === 'model' ? failedKey : classification.scope === 'provider' ? round.model.provider : endpointKey(round.model), classification.kind, round.observation.message, classification.retryAfterMs)
     await health.flush()
-    // 窗口从上一次成功切换（或本轮开始）起算：供应商内部重试耗时不应消耗整轮限额
+    // 窗口从上一次成功切换（或本轮开始）起算：供应商内部重试耗时不应消耗整轮限额。
+    // 仅在本轮已成功切换过（attempts > 0）后才生效：窗口的本意是限制连续切换 churn，
+    // 长健康轮末尾的第一次失败也必须拿到兜底切换，否则轮时限会拦掉唯一一次 fallback。
     const windowStart = Math.max(round.startedAt, round.lastSwitchAt ?? 0)
-    if (Date.now() - windowStart >= roundLimitMs()) return exhaust(ctx, '超过本轮时间限制')
+    if (round.attempts > 0 && Date.now() - windowStart >= roundLimitMs()) return exhaust(ctx, '超过本轮时间限制')
     await refresh(ctx)
     const candidates = effectiveCandidates(ctx.scopedModels, ctx.modelRegistry.getAvailable())
     const candidateOptions = () => ({
@@ -464,10 +467,20 @@ export default function (pi: ExtensionAPI) {
     }
   })
   pi.on('agent_settled', async (_event, ctx) => {
-    if (!round || round.phase !== 'settled-error') return
+    if (!round || round.phase !== 'settled-error' || !round.observation) return
     if (!ctx.isIdle()) return
-    if (!canRetry(ctx) && round.observation && round.model) {
-      const classification = classifyFailure(round.observation)
+    const classification = classifyFailure(round.observation)
+    // 本机 Pi 加载失败时，换任何模型都无益；必须在计入健康或平台失败次数前终止。
+    if (classification.kind === 'local_runtime') {
+      const failedKey = key(round.model)
+      if (failedKey) {
+        round.tried.add(failedKey)
+        round.errors.set(failedKey, round.observation.message ?? classification.kind)
+      }
+      await exhaust(ctx, 'Pi 本地程序文件加载失败，请完整退出并重新启动 Pi 后恢复会话；/reload 无法重新加载 Pi 本体')
+      return
+    }
+    if (!canRetry(ctx) && round.model) {
       if (classification.kind === 'content_policy') health.recordContentPolicyConstraint(modelFamily(round.model), round.model, round.observation.message)
       if (!classification.roundOnly && classification.scope) {
         const domain = classification.scope === 'model' ? modelKey(round.model) : classification.scope === 'provider' ? round.model.provider : endpointKey(round.model)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ccswitch-auto-switch",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "Provider-first automatic model failover extension for Pi and CC Switch",
   "license": "MIT",
   "keywords": [

package/types.ts

@@ -63,6 +63,7 @@ export type FailureClass =
   | 'model_config'
   | 'content_policy'
   | 'context_overflow'
+  | 'local_runtime'
   | 'unknown'
 
 export type HealthScope = 'model' | 'provider' | 'endpoint'