feat(ai,classroom): streaming ASR/TTS, gateway refactor, handler IPC consolidation

- Add streaming ASR service with Sherpa model streaming support

- Add speech normalizer/streamer and TTS handler for assistant

- Refactor all AI handlers to unified gateway HTTP/stream transport

- Simplify ai-gateway auth middleware and rate limiter

- Add AsrSettingsSection UI; remove legacy apiKeyManager

- Update CSP policy, preload bridge, classroom capture hooks

- Add server db-backup/db-restore scripts; update docs

Author: Aparencia

.github/workflows/pr-check.yml

@@ -70,7 +70,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          # Go 1.25 尚未发布，使用当前最新稳定版 1.24（截至 2026 年 8 月）
+          go-version: '1.24'
           cache-dependency-path: server/sync-service/go.sum
       - name: Lint (go vet)
         run: go vet ./...

client/.env.example

@@ -19,10 +19,11 @@ VITE_API_BASE_URL=https://entropydecrease.com
 VITE_API_HEALTH_URL=https://entropydecrease.com/health
 
 # ---- AI 网关 ----
-# AI Gateway 服务地址
-# 开发环境: http://127.0.0.1:8000
+# AI Gateway 服务地址（electron:dev 与前端渲染进程共用）
+# 本地开发时指向本地 AI 网关: http://localhost:8000
+# 连接远程测试/生产服务器时，请改为对应地址（注意：测试服务器 IP 应写在 .env.test，不要提交到仓库）
 # 生产环境: https://entropydecrease.com
-VITE_AI_GATEWAY_URL=https://entropydecrease.com
+VITE_AI_GATEWAY_URL=http://localhost:8000
 
 # ---- Ollama 本地推理（可选） ----
 # Ollama 服务地址，默认自动检测 localhost:11434

client/electron/ai/gatewayHttp.ts

@@ -16,11 +16,10 @@ import { isLocalInferenceEnabled } from './ollama/config.js';
 import { isOllamaAvailable } from './ollama/OllamaService.js';
 
 /** 构建公共请求头（JSON 模式含 Content-Type，multipart 由 fetch 自动生成） */
-function buildHeaders(clientRequestId: string, json: boolean, authToken?: string, userApiKey?: string): Record<string, string> {
+function buildHeaders(clientRequestId: string, json: boolean, authToken?: string): Record<string, string> {
   const headers: Record<string, string> = { 'X-Request-ID': clientRequestId };
   if (json) headers['Content-Type'] = 'application/json';
   if (authToken) headers['Authorization'] = `Bearer ${authToken}`;
-  if (userApiKey) headers['X-User-API-Key'] = userApiKey;
   return headers;
 }
 
@@ -44,7 +43,6 @@ async function executePost<TRes>(
   isJson: boolean,
   bodyDesc: string,
   authToken?: string,
-  userApiKey?: string,
   timeoutMs: number = 60000,
 ): Promise<{ data: TRes; requestId: string | undefined }> {
   const base = gatewayUrl();
@@ -57,9 +55,9 @@ async function executePost<TRes>(
 
   // ── 请求前日志 ──
   logger.info(`[AI] → POST ${url} [req-id: ${clientRequestId}]`);
-  logger.debug(`[AI] Request config: timeout=${timeoutMs}ms, hasAuth=${!!authToken}, hasUserKey=${!!userApiKey}, ${bodyDesc}`);
+  logger.debug(`[AI] Request config: timeout=${timeoutMs}ms, hasAuth=${!!authToken}, ${bodyDesc}`);
 
-  const headers = buildHeaders(clientRequestId, isJson, authToken, userApiKey);
+  const headers = buildHeaders(clientRequestId, isJson, authToken);
 
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
@@ -122,11 +120,10 @@ export async function postJson<TReq, TRes>(
   apiPath: string,
   body: TReq,
   authToken?: string,
-  userApiKey?: string,
   timeoutMs: number = 60000,
 ): Promise<{ data: TRes; requestId: string | undefined }> {
   const bodyDesc = `bodyKeys=${Object.keys(body as Record<string, unknown>).join(',')}`;
-  return executePost<TRes>(apiPath, JSON.stringify(body), true, bodyDesc, authToken, userApiKey, timeoutMs);
+  return executePost<TRes>(apiPath, JSON.stringify(body), true, bodyDesc, authToken, timeoutMs);
 }
 
 /**
@@ -139,10 +136,9 @@ export async function postMultipart<TRes>(
   apiPath: string,
   formData: FormData,
   authToken?: string,
-  userApiKey?: string,
   timeoutMs: number = 300000,
 ): Promise<{ data: TRes; requestId: string | undefined }> {
-  return executePost<TRes>(apiPath, formData, false, 'body=FormData', authToken, userApiKey, timeoutMs);
+  return executePost<TRes>(apiPath, formData, false, 'body=FormData', authToken, timeoutMs);
 }
 
 /**
@@ -158,7 +154,6 @@ export async function callWithLocalFallback<TReq, TRes>(
   body: TReq,
   localHandler: () => Promise<TRes>,
   authToken?: string,
-  userApiKey?: string,
   timeoutMs: number = 60000,
 ): Promise<{ data: TRes; source: 'local' | 'remote'; requestId?: string }> {
   // 检查本地 Ollama 是否可用
@@ -179,7 +174,6 @@ export async function callWithLocalFallback<TReq, TRes>(
     apiPath,
     body,
     authToken,
-    userApiKey,
     timeoutMs,
   );
   return { data, source: 'remote', requestId };

client/electron/ai/gatewayStream.ts

@@ -17,7 +17,6 @@ export async function* postJsonStream<TReq>(
   apiPath: string,
   body: TReq,
   authToken?: string,
-  userApiKey?: string,
   timeoutMs: number = 300000,
 ): AsyncGenerator<string, void, unknown> {
   const base = gatewayUrl();
@@ -36,9 +35,6 @@ export async function* postJsonStream<TReq>(
   if (authToken) {
     headers['Authorization'] = `Bearer ${authToken}`;
   }
-  if (userApiKey) {
-    headers['X-User-API-Key'] = userApiKey;
-  }
 
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
@@ -98,19 +94,24 @@ export async function* postJsonStream<TReq>(
             if (data === '[DONE]') {
               return;
             }
+            // 先单独解析 JSON：仅捕获解析失败（回退纯文本），
+            // 避免把下方 parsed.error 的主动 throw 一并吞掉——
+            // 那个 throw 必须传播出去才能触发上层「流式失败→降级非流式」。
+            let parsed: { error?: string; chunk?: string } | null = null;
             try {
-              const parsed = JSON.parse(data);
-              if (parsed.error) {
-                throw new Error(`Stream error: ${parsed.error}`);
-              }
-              if (parsed.chunk) {
-                yield parsed.chunk;
-              }
-            } catch (e) {
+              parsed = JSON.parse(data);
+            } catch {
               // JSON 解析失败，尝试作为纯文本
-              if (data && data !== '[DONE]') {
+              if (data) {
                 yield data;
               }
+              continue;
+            }
+            if (parsed?.error) {
+              throw new Error(`Stream error: ${parsed.error}`);
+            }
+            if (parsed?.chunk) {
+              yield parsed.chunk;
             }
           }
         }

client/electron/ai/handlers/anchorPointHandler.ts

@@ -27,7 +27,6 @@ function register(): void {
         content: string;
         title?: string;
         authToken?: string;
-        userApiKey?: string;
       },
     ) => {
       const startMs = Date.now();
@@ -68,7 +67,6 @@ function register(): void {
           reqBody,
           localHandler,
           args.authToken,
-          args.userApiKey,
           60000,
         );
 

client/electron/ai/handlers/chatHandler.ts

@@ -29,10 +29,9 @@ export function registerChatHandlers(): void {
         history: Array<{ role: string; content: string }>;
         scene: string;
         authToken?: string;
-        userApiKey?: string;
       },
     ) => {
-      const { requestId, sessionId, message, history, scene, authToken, userApiKey } = args;
+      const { requestId, sessionId, message, history, scene, authToken } = args;
       const sender = event.sender;
       const startMs = Date.now();
 
@@ -70,7 +69,7 @@ export function registerChatHandlers(): void {
       }
 
       try {
-        const stream = postJsonStream('/api/v1/ai/chat/stream', payload, authToken, userApiKey);
+        const stream = postJsonStream('/api/v1/ai/chat/stream', payload, authToken);
 
         for await (const chunk of stream) {
           fullResponse += chunk;

client/electron/ai/handlers/evaluateHandler.ts

@@ -27,7 +27,6 @@ function register(): void {
         concept: string;
         explanation: string;
         authToken?: string;
-        userApiKey?: string;
       },
     ) => {
       const startMs = Date.now();
@@ -83,7 +82,6 @@ function register(): void {
           reqBody,
           localHandler,
           args.authToken,
-          args.userApiKey,
           40000,
         );
 

client/electron/ai/handlers/feynmanHandler.ts

@@ -31,7 +31,6 @@ function register(): void {
         concept: string;
         explanation: string;
         authToken?: string;
-        userApiKey?: string;
       },
     ) => {
       const startMs = Date.now();
@@ -65,7 +64,6 @@ function register(): void {
           reqBody,
           localHandler,
           args.authToken,
-          args.userApiKey,
           40000,
         );
 
@@ -104,7 +102,6 @@ function register(): void {
         questions: string[];
         answers: string[];
         authToken?: string;
-        userApiKey?: string;
       },
     ) => {
       const startMs = Date.now();
@@ -142,7 +139,6 @@ function register(): void {
           reqBody,
           localHandler,
           args.authToken,
-          args.userApiKey,
           40000,
         );
 

client/electron/ai/handlers/flashcardHandler.ts

@@ -29,7 +29,6 @@ function register(): void {
         difficulty?: string;
         cardType?: string;
         authToken?: string;
-        userApiKey?: string;
       },
     ) => {
       const startMs = Date.now();
@@ -79,7 +78,6 @@ function register(): void {
           reqBody,
           localHandler,
           args.authToken,
-          args.userApiKey,
           90000,
         );
 

client/electron/ai/handlers/mergeNotesHandler.ts

@@ -30,7 +30,6 @@ function register(): void {
         duration?: number;   // 秒
         language?: string;
         authToken?: string;
-        userApiKey?: string;
       },
     ) => {
       const startMs = Date.now();
@@ -105,7 +104,6 @@ function register(): void {
           reqBody,
           localHandler,
           args.authToken,
-          args.userApiKey,
           30000, // 纯文本合并，30s 超时足够
         );