feat(electron): 主进程 AI 请求 429 配额耗尽事件推送（gatewayHttp/Stream/preload）

Author: Aparencia

client/electron/ai/gatewayHttp.ts

@@ -10,6 +10,7 @@
  * source 字段（'local'|'remote'）供渲染层展示推理来源，勿删。
  */
 import { randomUUID } from 'crypto';
+import { BrowserWindow } from 'electron';
 import { logger } from '../logger.js';
 import { gatewayUrl } from './gatewayConfig.js';
 import { isLocalInferenceEnabled } from './ollama/config.js';
@@ -34,6 +35,19 @@ function logNetworkHint(errDetail: string): void {
   }
 }
 
+/**
+ * 429 配额耗尽 → 推送渲染进程（主进程代理路径的统一感知点）。
+ *
+ * 仅配额类 429 触发（文案含「已达上限」）；上游服务商 429 为临时故障不打扰用户。
+ * 渲染进程 QuotaNotice 组件监听 ai:quota-exhausted 事件弹非阻断提示并刷新配额。
+ * gatewayStream 复用本函数（唯一语义点，避免两处漂移）。
+ */
+export function notifyQuotaExhaustedToRenderer(detail: string): void {
+  if (!/已达上限/.test(detail)) return;
+  const win = BrowserWindow.getAllWindows().find((w) => !w.isDestroyed());
+  win?.webContents.send('ai:quota-exhausted', detail);
+}
+
 /**
  * POST 公共骨架：超时控制 + 日志 + req-id + 错误诊断 + JSON 响应解析
  */
@@ -95,6 +109,8 @@ async function executePost<TRes>(
     // 截取响应体前 500 字符防止日志爆炸
     const detailPreview = detail.length > 500 ? `${detail.slice(0, 500)}...(+${detail.length - 500} chars)` : detail;
     logger.error(`[AI] ✖ HTTP ${resp.status} ${url} (${elapsed}ms) [req-id: ${requestId ?? clientRequestId}]: ${detailPreview}`);
+    // 配额类 429：通知渲染进程展示配额耗尽提示（不改变既有抛错行为）
+    if (resp.status === 429) notifyQuotaExhaustedToRenderer(detail);
     throw new Error(`HTTP ${resp.status}: ${detail}`);
   }
 

client/electron/ai/gatewayStream.ts

@@ -9,6 +9,7 @@
 import { randomUUID } from 'crypto';
 import { logger } from '../logger.js';
 import { gatewayUrl } from './gatewayConfig.js';
+import { notifyQuotaExhaustedToRenderer } from './gatewayHttp.js';
 
 /**
  * 流式 POST 请求：解析 SSE data: 行，逐 chunk yield 文本
@@ -73,6 +74,8 @@ export async function* postJsonStream<TReq>(
   if (!resp.ok) {
     const detail = await resp.text().catch(() => 'unknown error');
     logger.error(`[AI] ✖ Stream HTTP ${resp.status} ${url} [req-id: ${requestId ?? clientRequestId}]: ${detail.slice(0, 200)}`);
+    // 配额类 429：通知渲染进程展示配额耗尽提示（不改变既有抛错行为）
+    if (resp.status === 429) notifyQuotaExhaustedToRenderer(detail);
     throw new Error(`Stream HTTP ${resp.status}: ${detail}`);
   }
 

client/electron/preload.ts

@@ -198,6 +198,8 @@ const ALLOWED_EVENT_CHANNELS = [
   'shortcut:triggered',
   // 3.18 电子墨水学习板：主进程推送复习卡片到次窗口
   'eink:card',
+  // AI 配额耗尽（429）：主进程代理路径推送，渲染进程弹非阻断提示 + 刷新配额
+  'ai:quota-exhausted',
 ] as const;
 
 /** 允许渲染进程单向发送的 channel 白名单（渲染进程 → 主进程，fire-and-forget） */
@@ -370,4 +372,14 @@ contextBridge.exposeInMainWorld('electronAPI', {
       return () => ipcRenderer.removeListener('ollama:pull-progress', handler);
     },
   },
+  // ---- AI 配额耗尽（429）：主进程代理路径推送 ----
+  onAIQuotaExhausted: (callback: (detail: string) => void) => {
+    if (!(ALLOWED_EVENT_CHANNELS as readonly string[]).includes('ai:quota-exhausted')) {
+      console.warn('[preload] 不允许的事件 channel: ai:quota-exhausted');
+      return () => {};
+    }
+    const handler = (_event: unknown, detail: string) => callback(detail);
+    ipcRenderer.on('ai:quota-exhausted', handler);
+    return () => ipcRenderer.removeListener('ai:quota-exhausted', handler);
+  },
 });