feat(ai): AI hooks 流式化改造——苏格拉底追问/救援打字机渐进展示

- useAISocratic: 新增 askQuestionStream 流式追问，JSON 宽松解析，失败自动降级非流式
- useAIRescue: 新增 rescueStream 流式救援，打字机渐进展示，取消保护
- AIPluginLoader: 统一调用链，getAIPlugin 委托内部环境方法
- visionWorker: 收紧导出（接口/类型改为内部）
- RescuePanel: 接入流式救援（rescueStream）

Author: Aparencia

client/src/components/RescuePanel.tsx

@@ -42,20 +42,20 @@ const SUGGESTIONS = [
 export function RescuePanel({ isOpen, onClose, context, onSuggestion }: RescuePanelProps) {
   const [activeLevel, setActiveLevel] = useState<RescueLevel>(1);
   const [showIncubation, setShowIncubation] = useState(false);
-  const { loading, data, error, needsConfig, rescue } = useAIRescue();
+  const { loading, data, error, needsConfig, streamingText, rescueStream } = useAIRescue();
   const navigate = useNavigate();
 
-  // 面板打开时触发救援请求
+  // 面板打开时触发救援请求（P5 流式：打字机渐进展示，失败自动降级非流式）
   useEffect(() => {
     if (isOpen && context.topic) {
       const rescueCtx: RescueContext = {
         topic: context.topic,
         relatedContent: context.relatedContent,
         mode: (context.mode as RescueContext['mode']) ?? 'general',
       };
-      rescue(rescueCtx);
+      rescueStream(rescueCtx);
     }
-  }, [isOpen, context.topic, context.relatedContent, context.mode, rescue]);
+  }, [isOpen, context.topic, context.relatedContent, context.mode, rescueStream]);
 
   // 卡壳超10分钟显示孵化建议（由外部 useStuckTimer 触发）
   useEffect(() => {
@@ -146,8 +146,15 @@ export function RescuePanel({ isOpen, onClose, context, onSuggestion }: RescuePa
             <div className="flex-1 overflow-y-auto px-kb-md py-kb-md">
               {loading && (
                 <div className="flex items-center gap-2 text-b2 text-text-secondary py-8 justify-center">
-                  <AIThinkingIndicator size={4} gap={3} />
-                  AI 正在思考救援方案…
+                  {/* P5 流式：首 chunk 到达前显示思考动画，之后打字机渐进展示 */}
+                  {streamingText ? (
+                    <p className="text-b2 text-text-secondary leading-relaxed whitespace-pre-wrap">{streamingText}</p>
+                  ) : (
+                    <>
+                      <AIThinkingIndicator size={4} gap={3} />
+                      AI 正在思考救援方案…
+                    </>
+                  )}
                 </div>
               )}
 

client/src/lib/ai/AIPluginLoader.ts

@@ -13,8 +13,9 @@
 import { LocalDurationRecommender } from './LocalFallback';
 import { AIError } from './ai-errors';
 import { ensureOnline, ensureMinLength } from './aiGuards';
-import { getAIPlugin, getRemotePlugin, getElectronPlugin } from './aiPluginProvider';
+import { getRemotePlugin, getElectronPlugin } from './aiPluginProvider';
 import { offlineAIQueue } from './offlineAIQueue';
+import { isElectron } from '../utils/platform';
 import type { AIPlugin, DurationHistoryData, DurationOptions, DurationResult,
   SummarizeResult, FlashcardResult, EvaluateResult,
   SummarizeOptions, FlashcardOptions, EvaluateOptions,
@@ -38,8 +39,11 @@ class AIPluginLoader {
   /** 获取 Electron AI 插件实例（委托 aiPluginProvider，保留旧 API） */
   async getElectronPlugin() { return getElectronPlugin(); }
 
-  /** 根据运行环境获取 AI 插件实例 */
-  async getAIPlugin(): Promise<AIPlugin> { return getAIPlugin(); }
+  /** 根据运行环境获取 AI 插件实例（内部委托本类两个环境方法，统一调用链） */
+  async getAIPlugin(): Promise<AIPlugin> {
+    if (isElectron()) return await this.getElectronPlugin();
+    return this.getRemotePlugin();
+  }
 
   /**
    * 统一非流式调用包装：守卫 → 取插件 → 能力检查 → 调用
@@ -62,7 +66,7 @@ class AIPluginLoader {
       throw err;
     }
     ensureMinLength(opts.contentCheck, opts.minLength);
-    const plugin = await getAIPlugin();
+    const plugin = await this.getAIPlugin();
     const result = invoke(plugin);
     if (result === undefined) {
       throw new AIError(opts.unsupportedMsg, 'service_unavailable', false);
@@ -79,7 +83,7 @@ class AIPluginLoader {
   ): AsyncGenerator<string, void, unknown> {
     ensureOnline();
     ensureMinLength(opts.contentCheck, opts.minLength);
-    const plugin = await getAIPlugin();
+    const plugin = await this.getAIPlugin();
     const s = getStreamFn(plugin);
     if (!s) {
       throw new AIError(opts.unsupportedMsg, 'service_unavailable', true);
@@ -117,7 +121,7 @@ class AIPluginLoader {
    * 注意：刻意不做离线守卫（Electron 本地视觉可离线使用，历史行为）
    */
   async extractScreenContent(imageBase64: string, language = 'zh'): Promise<VisionExtractResult> {
-    const plugin = await getAIPlugin();
+    const plugin = await this.getAIPlugin();
     if (plugin.extractScreenContent) {
       return plugin.extractScreenContent(imageBase64, language);
     }
@@ -128,7 +132,7 @@ class AIPluginLoader {
   async recommendDuration(historyData: DurationHistoryData, options?: DurationOptions): Promise<DurationResult> {
     ensureOnline();
     try {
-      return await (await getAIPlugin()).recommendDuration(historyData, options);
+      return await (await this.getAIPlugin()).recommendDuration(historyData, options);
     } catch {
       return this.localRecommender.recommend(historyData, options);
     }

client/src/lib/ai/hooks/useAIRescue.ts

@@ -1,13 +1,56 @@
 /**
  * @ai-context: Rescue 功能的 React Hook 包装：仅做加载/错误状态编排，业务调用统一走 aiPluginLoader，禁止在 Hook 内写业务计算。
+ * @ai-context: P5 流式接入——rescueStream 经 aiPluginLoader.rescueStream 逐 chunk
+ * 累积 JSON（rescue_v1 模板强制 JSON），完成后宽松解析；失败自动降级非流式 rescue。
+ * cancelRef/streamIdRef 防竞态与卸载泄漏（与 useAISummarize 流式模式一致）。
  */
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useRef, useEffect } from 'react';
 import { aiPluginLoader } from '../AIPluginLoader';
 import { resolveAIFallback, setAICache, FallbackLevel } from '../aiServiceFallback';
 import { type AIState, INITIAL_STATE, resolveAIErrorState } from './types';
 import { withTimeout } from './withTimeout';
 import type { RescueContext, ResourceLink } from '../types';
 
+/** 救援结果结构（与 useAIRescue 状态一致） */
+export interface RescueResultData {
+  hints: string[];
+  resources: ResourceLink[];
+  alternativeApproach?: string;
+}
+
+/**
+ * 宽松解析流式累积的救援 JSON（rescue_v1 模板强制 JSON；AI 输出可能带前后缀）
+ */
+function parseRescueJson(text: string): RescueResultData | null {
+  const tryParse = (s: string): RescueResultData | null => {
+    try {
+      const parsed = JSON.parse(s) as {
+        hints?: string[]; resources?: Array<{ title?: string; url?: string; type?: string }>;
+        alternative_approach?: string; alternativeApproach?: string;
+      };
+      if (Array.isArray(parsed.hints) || parsed.alternative_approach || parsed.alternativeApproach) {
+        return {
+          hints: Array.isArray(parsed.hints) ? parsed.hints : [],
+          resources: Array.isArray(parsed.resources)
+            ? parsed.resources.map((r) => ({
+                title: r.title ?? '',
+                url: r.url ?? '',
+                type: (['article', 'video', 'exercise', 'documentation', 'other'] as const)
+                  .find((t) => t === r.type) ?? 'other',
+              }))
+            : [],
+          alternativeApproach: parsed.alternative_approach ?? parsed.alternativeApproach,
+        };
+      }
+    } catch { /* fallthrough */ }
+    return null;
+  };
+  const direct = tryParse(text);
+  if (direct) return direct;
+  const block = text.match(/\{[\s\S]*\}/);
+  return block ? tryParse(block[0]) : null;
+}
+
 /**
  * AI 学习救援 hook
  *
@@ -24,6 +67,12 @@ export function useAIRescue() {
   }>>({
     ...INITIAL_STATE,
   });
+  /** 流式渐进文本（逐 chunk 累积，打字机展示） */
+  const [streamingText, setStreamingText] = useState('');
+  /** 是否正在流式输出 */
+  const [isStreaming, setIsStreaming] = useState(false);
+  const cancelRef = useRef(false);
+  const streamIdRef = useRef(0);
 
   const rescue = useCallback(async (context: RescueContext) => {
     setState(prev => ({ ...prev, loading: true, error: null, needsConfig: false }));
@@ -47,5 +96,49 @@ export function useAIRescue() {
     }
   }, []);
 
-  return { ...state, rescue };
+  /**
+   * P5 流式学习救援：逐 chunk 累积 JSON，完成后解析结构化结果；失败降级非流式 rescue
+   */
+  const rescueStream = useCallback(async (context: RescueContext) => {
+    cancelRef.current = false;
+    const streamId = ++streamIdRef.current;
+    setState(prev => ({ ...prev, loading: true, error: null, needsConfig: false }));
+    setIsStreaming(true);
+    setStreamingText('');
+    let accumulated = '';
+    try {
+      const iterable = aiPluginLoader.rescueStream(context);
+      for await (const chunk of iterable) {
+        if (cancelRef.current || streamIdRef.current !== streamId) return null;
+        accumulated += chunk;
+        setStreamingText(accumulated);
+      }
+      if (cancelRef.current || streamIdRef.current !== streamId) return null;
+      const parsed = parseRescueJson(accumulated);
+      if (!parsed) {
+        throw new Error('AI 流式返回无法解析为救援 JSON');
+      }
+      const cacheKey = `rescue:${context.topic.slice(0, 100)}:${context.stuckPoint?.slice(0, 50) || 'default'}`;
+      setAICache(cacheKey, parsed);
+      setState({ data: parsed, loading: false, error: null, isFallback: false, needsConfig: false });
+      setIsStreaming(false);
+      return parsed;
+    } catch (error: unknown) {
+      if (cancelRef.current || streamIdRef.current !== streamId) return null;
+      // 流式失败 → 降级非流式（非流式内部自行处理错误态与降级链）
+      setIsStreaming(false);
+      return rescue(context);
+    }
+  }, [rescue]);
+
+  /** 取消当前流式输出 */
+  const cancelStream = useCallback(() => {
+    cancelRef.current = true;
+    setIsStreaming(false);
+  }, []);
+
+  // 组件卸载时自动取消，避免对已卸载组件 setState
+  useEffect(() => () => { cancelRef.current = true; }, []);
+
+  return { ...state, streamingText, isStreaming, rescue, rescueStream, cancelStream };
 }

client/src/lib/ai/hooks/useAISocratic.ts

@@ -1,7 +1,7 @@
 /**
  * @ai-context: Socratic 功能的 React Hook 包装：仅做加载/错误状态编排，业务调用统一走 aiPluginLoader，禁止在 Hook 内写业务计算。
  */
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useRef, useEffect } from 'react';
 import { aiPluginLoader } from '../AIPluginLoader';
 import { soundPlayer } from '@/lib/audio/SoundPlayer';
 import {
@@ -15,6 +15,26 @@ import {
 import { type AIState, INITIAL_STATE, resolveAIErrorState } from './types';
 import type { BrainstormIdea, ChatMessage, SocraticEvaluateResult, SocraticDeepeningResult, SocraticMirrorResult } from '../types';
 
+/**
+ * 宽松解析流式累积的苏格拉底追问 JSON（socratic_v1 模板强制 JSON：
+ * {"question": "...", "hints": [...]}；AI 输出可能带前后缀说明文字）
+ */
+function parseSocraticQuestionJson(text: string): { question: string; hints: string[] } | null {
+  const tryParse = (s: string): { question: string; hints: string[] } | null => {
+    try {
+      const parsed = JSON.parse(s) as { question?: string; hints?: string[] };
+      if (typeof parsed.question === 'string' && parsed.question.trim()) {
+        return { question: parsed.question, hints: Array.isArray(parsed.hints) ? parsed.hints : [] };
+      }
+    } catch { /* fallthrough */ }
+    return null;
+  };
+  const direct = tryParse(text);
+  if (direct) return direct;
+  const block = text.match(/\{[\s\S]*\}/);
+  return block ? tryParse(block[0]) : null;
+}
+
 /**
  * AI 苏格拉底式学习 hook
  *
@@ -47,6 +67,12 @@ export function useAISocratic() {
   const [mirrorState, setMirrorState] = useState<AIState<SocraticMirrorResult>>({
     ...INITIAL_STATE,
   });
+  /** 追问流式渐进文本（逐 chunk 累积，打字机展示） */
+  const [streamingQuestion, setStreamingQuestion] = useState('');
+  /** 是否正在流式追问输出 */
+  const [isQuestionStreaming, setIsQuestionStreaming] = useState(false);
+  const questionCancelRef = useRef(false);
+  const questionStreamIdRef = useRef(0);
 
   /** 苏格拉底式头脑风暴 — 带 300 秒缓存 + 请求去重 + 降级处理 */
   const brainstorm = useCallback(async (topic: string, context?: string) => {
@@ -106,7 +132,6 @@ export function useAISocratic() {
   const askQuestion = useCallback(async (conversationId: string, topic: string, history: ChatMessage[]) => {
     setQuestionState(prev => ({ ...prev, loading: true, error: null, needsConfig: false }));
     const cacheKey = `socratic_question:${conversationId}:${topic.slice(0, 100)}`;
-
     try {
       const result = await aiPluginLoader.socraticQuestion(conversationId, topic, history);
 
@@ -141,6 +166,57 @@ export function useAISocratic() {
     }
   }, []);
 
+  /**
+   * A 组流式接入：苏格拉底追问打字机（/socratic/stream SSE）
+   * 逐 chunk 累积 JSON（socratic_v1 模板强制 {"question","hints"}），完成后宽松解析；
+   * 流式失败自动降级非流式 askQuestion。onChunk 回调供 UI 渐进展示。
+   */
+  const askQuestionStream = useCallback(async (
+    conversationId: string,
+    topic: string,
+    history: ChatMessage[],
+    onChunk?: (partial: string) => void,
+  ) => {
+    questionCancelRef.current = false;
+    const streamId = ++questionStreamIdRef.current;
+    setQuestionState(prev => ({ ...prev, loading: true, error: null, needsConfig: false }));
+    setIsQuestionStreaming(true);
+    setStreamingQuestion('');
+    let accumulated = '';
+    try {
+      const iterable = aiPluginLoader.socraticQuestionStream(conversationId, topic, history);
+      for await (const chunk of iterable) {
+        if (questionCancelRef.current || questionStreamIdRef.current !== streamId) return null;
+        accumulated += chunk;
+        setStreamingQuestion(accumulated);
+        onChunk?.(accumulated);
+      }
+      if (questionCancelRef.current || questionStreamIdRef.current !== streamId) return null;
+      const parsed = parseSocraticQuestionJson(accumulated);
+      if (!parsed) {
+        throw new Error('AI 流式返回无法解析为苏格拉底追问 JSON');
+      }
+      soundPlayer.play('ai_analysis_done');
+      setQuestionState({ data: parsed, loading: false, error: null, isFallback: false, needsConfig: false });
+      setIsQuestionStreaming(false);
+      return parsed;
+    } catch (error: unknown) {
+      if (questionCancelRef.current || questionStreamIdRef.current !== streamId) return null;
+      // 流式失败 → 降级非流式（非流式内部自行处理错误态与降级链）
+      setIsQuestionStreaming(false);
+      return askQuestion(conversationId, topic, history);
+    }
+  }, [askQuestion]);
+
+  /** 取消当前流式追问 */
+  const cancelQuestionStream = useCallback(() => {
+    questionCancelRef.current = true;
+    setIsQuestionStreaming(false);
+  }, []);
+
+  // 组件卸载时自动取消，避免对已卸载组件 setState
+  useEffect(() => () => { questionCancelRef.current = true; }, []);
+
   /** FEAT-022: 苏格拉底回答评估 — 带 300 秒缓存 + 请求去重 + 降级处理 */
   const evaluateAnswer = useCallback(async (topic: string, question: string, answer: string, history: ChatMessage[]) => {
     // 评估缓存 key 包含 topic+question+answer 的摘要
@@ -304,7 +380,14 @@ export function useAISocratic() {
 
   return {
     brainstorm: { ...brainstormState, brainstorm },
-    question: { ...questionState, askQuestion },
+    question: {
+      ...questionState,
+      askQuestion,
+      askQuestionStream,
+      cancelQuestionStream,
+      streamingQuestion,
+      isQuestionStreaming,
+    },
     evaluate: { ...evaluateState, evaluateAnswer },
     deepening: { ...deepeningState, generateDeepeningAngles },
     mirror: { ...mirrorState, mirrorQuestion },

client/src/lib/ai/visionWorker.ts

@@ -20,16 +20,16 @@ import { supabase } from '@/lib/auth/supabaseClient';
 // ================================================================
 
 /** 视觉提取模式 */
-export type VisionExtractMode = 'auto' | 'text' | 'formula' | 'diagram' | 'code' | 'full';
+type VisionExtractMode = 'auto' | 'text' | 'formula' | 'diagram' | 'code' | 'full';
 
 /** 代码块结构 */
-export interface CodeBlock {
+interface CodeBlock {
   language: string;
   code: string;
 }
 
 /** 视觉提取选项 */
-export interface VisionExtractOptions {
+interface VisionExtractOptions {
   /** 提取模式，默认 'auto' */
   mode?: VisionExtractMode;
 }
@@ -196,7 +196,7 @@ export class VisionWorker implements PipelineWorker {
 // ================================================================
 
 /** 视觉提取错误类型 */
-export type VisionErrorType =
+type VisionErrorType =
   | 'network'        // 网络不可达 / fetch 失败
   | 'timeout'        // 请求超时
   | 'auth'           // 认证失败 401/403
@@ -205,7 +205,7 @@ export type VisionErrorType =
   | 'unknown';       // 未分类
 
 /** 分类后的错误信息 */
-export interface VisionErrorInfo {
+interface VisionErrorInfo {
   type: VisionErrorType;
   message: string;
   statusCode?: number;