1.1 分层架构#

AionUi 采用经典的 Electron 多进程架构，将职责清晰地划分到不同的进程中：

┌────────────────────────────────────────────────────────────┐
│                     渲染进程 (Renderer)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ GeminiChat   │  │  CodexChat   │  │  AcpChat     │     │
│  │  (React UI)  │  │  (React UI)  │  │  (React UI)  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│         │                 │                 │              │
│  ┌──────▼─────────────────▼─────────────────▼────┐        │
│  │         IPC Bridge 层 (通用接口)              │        │
│  │  - ipcBridge.conversation.responseStream     │        │
│  │  - ipcBridge.conversation.sendMessage        │        │
│  └──────┬─────────────────┬─────────────────┬─────┘       │
└─────────┼─────────────────┼─────────────────┼─────────────┘
          │ IPC Channel     │ IPC Channel     │ IPC Channel
┌─────────▼─────────────────▼─────────────────▼─────────────┐
│                     主进程 (Main)                          │
│  ┌─────────────────────────────────────────────────────┐  │
│  │      IPC Bridge 提供者 (Bridge Providers)           │  │
│  │  - conversationBridge                              │  │
│  │  - geminiConversationBridge                        │  │
│  │  - acpConversationBridge                           │  │
│  │  - codexConversationBridge                         │  │
│  └─┬───────────────────────────────────────────────────┘  │
│    │                                                       │
│  ┌─▼────────────────────────────────────────────────────┐ │
│  │     WorkerManage (Agent 管理器)                      │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │ │
│  │  │ GeminiAgent  │  │  CodexAgent  │  │  AcpAgent  │ │ │
│  │  │  Manager     │  │  Manager     │  │  Manager   │ │ │
│  │  └──┬───────────┘  └──┬───────────┘  └──┬─────────┘ │ │
│  └─────┼─────────────────┼──────────────────┼───────────┘ │
│        │                 │                  │              │
│  ┌─────▼─────────────────▼──────────────────▼──────────┐  │
│  │         数据库层 (Database Layer)                   │  │
│  │  - StreamingMessageBuffer (流式消息缓冲)           │  │
│  │  - AionUIDatabase (SQLite 数据库)                 │  │
│  │  - Message/Conversation 持久化                     │  │
│  └─┬───────────────────────────────────────────────────┘  │
│    │                                                       │
│  ┌─▼────────────────────────────────────────────────────┐ │
│  │      Worker 进程 (Sub-processes)                     │ │
│  │  ┌────────────────────────────────────────┐          │ │
│  │  │  Worker (Fork):                        │          │ │
│  │  │  - GeminiAgent (from aioncli-core)    │          │ │
│  │  │  - CodexAgent                          │          │ │
│  │  │  - AcpAgent                            │          │ │
│  │  │  - AI 流式处理                         │          │ │
│  │  └────────────────────────────────────────┘          │ │
│  └───────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
          │ onStreamEvent         │ 消息事件
          └───────────────────────┘

1.2 职责划分#

阶段 0：架构全景#

用户输入文本
   ↓
[渲染进程] React SendBox 组件
   ↓ IPC: chat.send.message
[主进程] conversationBridge 接收
   ↓
[主进程] GeminiAgentManager 预处理
   ↓ 保存到数据库
[主进程] 数据库层存储用户消息
   ↓ IPC: send.message
[Worker 进程] GeminiAgent 处理
   ↓ HTTP Request
[Gemini API] 流式响应
   ↓ onStreamEvent
[Worker 进程] 事件回调
   ↓ IPC: gemini.message
[主进程] GeminiAgentManager 接收事件
   ↓ 流式缓冲优化
[主进程] StreamingMessageBuffer 批量写入
   ↓ IPC: chat.response.stream
[渲染进程] responseStream.on() 监听
   ↓ 消息索引合并
[渲染进程] useAddOrUpdateMessage Hook
   ↓ 批量更新
[渲染进程] requestAnimationFrame
   ↓ 虚拟化渲染
[渲染进程] Virtuoso MessageList
   ↓
💬 用户看到流式响应

阶段 1：渲染进程 - 用户输入处理#

文件位置: src/renderer/pages/conversation/gemini/GeminiSendBox.tsx:36-250

const useGeminiMessage = (conversation_id: string) => {
  const addOrUpdateMessage = useAddOrUpdateMessage();
  const [streamRunning, setStreamRunning] = useState(false);

  useEffect(() => {
    // 监听来自主进程的流式响应
    return ipcBridge.geminiConversation.responseStream.on((message) => {
      if (conversation_id !== message.conversation_id) return;

      switch (message.type) {
        case 'thought': // Gemini 思考过程
          throttledSetThought(message.data as ThoughtData);
          break;
        case 'start': // 开始响应
          setStreamRunning(true);
          break;
        case 'finish': // 响应完成
          setStreamRunning(false);
          break;
        case 'tool_group': // 工具调用
          addOrUpdateMessage(transformMessage(message));
          break;
      }
    });
  }, [conversation_id]);
};

// 用户点击发送按钮
const handleSend = async () => {
  const result = await ipcBridge.conversation.sendMessage.invoke({
    conversation_id,
    input: userInput,
    msg_id: uuid(), // 生成消息 ID
    files: attachedFiles,
  });
};

关键点：

• 监听 responseStream 事件流
• 根据消息类型分发处理
• 使用 addOrUpdateMessage Hook 更新 UI

阶段 2：主进程 - IPC Bridge 分发#

文件位置: src/process/bridge/conversationBridge.ts:372-399

// 统一的 sendMessage 提供者
ipcBridge.conversation.sendMessage.provider(async ({
  conversation_id,
  files,
  ...other
}) => {
  // 1. 获取对应的 Agent 管理器
  const task = await WorkerManage.getTaskByIdRollbackBuild(
    conversation_id
  ) as GeminiAgentManager | AcpAgentManager | CodexAgentManager;

  if (!task) {
    return { success: false, msg: 'conversation not found' };
  }

  // 2. 复制文件到工作空间
  await copyFilesToDirectory(task.workspace, files);

  try {
    // 3. 根据 task 类型调用对应的 sendMessage 方法
    if (task.type === 'gemini') {
      await (task as GeminiAgentManager).sendMessage({
        ...other,
        files
      });
      return { success: true };
    } else if (task.type === 'acp') {
      await (task as AcpAgentManager).sendMessage({
        content: other.input,
        files,
        msg_id: other.msg_id
      });
      return { success: true };
    } else if (task.type === 'codex') {
      await (task as CodexAgentManager).sendMessage({
        content: other.input,
        files,
        msg_id: other.msg_id
      });
      return { success: true };
    }
  } catch (err: unknown) {
    return {
      success: false,
      msg: err instanceof Error ? err.message : String(err)
    };
  }
});

关键点：

• 统一接口：无论哪种 Agent，都通过同一个 IPC 通道
• 自动分发：根据对话类型路由到不同的 Agent Manager
• 文件处理：自动复制文件到工作空间

阶段 3：Agent 管理器 - 消息预处理#

文件位置: src/process/task/GeminiAgentManager.ts:157-187

async sendMessage(data: {
  input: string;
  msg_id: string;
  files?: string[]
}) {
  // 1. 创建用户消息对象
  const message: TMessage = {
    id: data.msg_id,
    type: 'text',
    position: 'right',
    conversation_id: this.conversation_id,
    content: {
      content: data.input,
    },
  };

  // 2. 立即添加到数据库（本地快速响应）
  addMessage(this.conversation_id, message);
  this.status = 'pending';

  // 3. 等待 bootstrap 完成（Agent 初始化）
  const result = await this.bootstrap
    .catch((e) => {
      this.emit('gemini.message', {
        type: 'error',
        data: e.message || JSON.stringify(e),
        msg_id: data.msg_id,
      });
      return new Promise((_, reject) => {
        nextTickToLocalFinish(() => {
          reject(e);
        });
      });
    })
    // 4. 调用基类的 sendMessage 通过 IPC 发送到 Worker
    .then(() => super.sendMessage(data));

  return result;
}

关键点：

• 乐观更新：先保存到数据库，给用户即时反馈
• 错误处理：如果初始化失败，发送错误事件
• 异步流水线：bootstrap → 保存 → 发送 Worker

阶段 4：Worker 进程 - Agent 初始化#

文件位置: src/worker/gemini.ts:12-48

export default forkTask(({ data }, pipe) => {
  pipe.log('gemini.init', data);

  // 创建 GeminiAgent 实例
  const agent = new GeminiAgent({
    ...data,
    // 关键：设置流事件处理回调
    onStreamEvent(event) {
      if (event.type === 'tool_group') {
        // 处理工具调用确认回调
        event.data = (event.data as any[]).map((tool: any) => {
          const { confirmationDetails, ...other } = tool;
          if (confirmationDetails) {
            const { onConfirm, ...details } = confirmationDetails;
            // 当用户确认时调用 onConfirm
            pipe.once(tool.callId, (confirmKey: string) => {
              onConfirm(confirmKey);
            });
            return {
              ...other,
              confirmationDetails: details,
            };
          }
          return other;
        });
      }
      // 将事件通过 IPC 发送回主进程
      pipe.call('gemini.message', event);
    },
  });

  // IPC 消息处理
  pipe.on('stop.stream', (_, deferred) => {
    agent.stop();
    deferred.with(Promise.resolve());
  });

  pipe.on('send.message', (event, deferred) => {
    // 调用 Agent 的 send 方法处理消息
    deferred.with(agent.send(event.input, event.msg_id, event.files));
  });

  return agent.bootstrap;
});

关键点：

• forkTask：在子进程中运行，避免阻塞主进程
• onStreamEvent：所有流式事件通过这个回调发送回主进程
• 工具确认：处理需要用户确认的工具调用

阶段 5：GeminiAgent - 核心交互逻辑#

文件位置: src/agent/gemini/index.ts:607-729

async send(
  message: string | Array<{ text: string }>,
  msg_id = '',
  files?: string[]
) {
  await this.bootstrap;
  const abortController = this.createAbortController();

  // 1. 处理 @ 文件引用
  const { processedQuery, shouldProceed } = await handleAtCommand({
    query: Array.isArray(message) ? message[0].text : message,
    config: this.config,
    signal: abortController.signal,
  });

  if (!shouldProceed) {
    this.onStreamEvent({
      type: 'error',
      data: 'Failed to process @ file reference',
      msg_id,
    });
    return;
  }

  // 2. 调用 submitQuery 发送到 Gemini API
  const requestId = this.submitQuery(
    processedQuery,
    msg_id,
    abortController
  );
  return requestId;
}

submitQuery(
  query: unknown,
  msg_id: string,
  abortController: AbortController,
  options?: { prompt_id?: string; isContinuation?: boolean }
): string | undefined {
  try {
    this.activeMsgId = msg_id;
    let prompt_id = options?.prompt_id;

    if (!prompt_id) {
      prompt_id = this.config.getSessionId() + '########' + getPromptCount();
    }

    // 发送消息流请求到 Gemini API
    const stream = this.geminiClient.sendMessageStream(
      query,
      abortController.signal,
      prompt_id
    );

    // 立即发送 start 事件
    this.onStreamEvent({
      type: 'start',
      data: '',
      msg_id,
    });

    // 处理消息流（带自动重试）
    this.handleMessage(stream, msg_id, abortController, query)
      .catch((e: unknown) => {
        const errorMessage = e instanceof Error ?
          e.message : JSON.stringify(e);
        this.onStreamEvent({
          type: 'error',
          data: errorMessage,
          msg_id,
        });
      })
      .finally(() => {
        this.onStreamEvent({
          type: 'finish',
          data: '',
          msg_id,
        });
      });

    return '';
  } catch (e) {
    const errorMessage = e instanceof Error ?
      e.message : JSON.stringify(e);
    this.onStreamEvent({
      type: 'error',
      data: errorMessage,
      msg_id,
    });
  }
}

关键点：

• @ 命令处理：支持引用工作空间中的文件
• 流式请求：使用 sendMessageStream 获取流式响应
• 事件发送：start → chunk → finish，完整的生命周期

阶段 6：主进程 - 流式响应回传#

当 Worker 进程通过 pipe.call('gemini.message', event) 发送事件时：

文件位置: src/process/task/GeminiAgentManager.ts:100-120

// GeminiAgentManager 监听 Worker 事件
this.on('gemini.message', (event) => {
  // 1. 添加或更新消息到数据库
  addOrUpdateMessage(this.conversation_id, event);

  // 2. 通过 IPC 发射事件到渲染进程
  ipcBridge.geminiConversation.responseStream.emit({
    ...event,
    conversation_id: this.conversation_id,
  });
});

阶段 7：渲染进程 - UI 更新#

回到渲染进程，responseStream.on() 监听器接收事件并更新 UI：

ipcBridge.geminiConversation.responseStream.on((message) => {
  if (conversation_id !== message.conversation_id) return;

  switch (message.type) {
    case 'text':
      // 流式文本消息
      addOrUpdateMessage(transformMessage(message));
      break;
    case 'tool_group':
      // 工具调用
      addOrUpdateMessage(transformMessage(message));
      break;
    case 'start':
      setStreamRunning(true);
      break;
    case 'finish':
      setStreamRunning(false);
      break;
  }
});

3.1 Gemini 适配器#

核心文件: src/agent/gemini/index.ts:51-756

export class GeminiAgent {
  config: Config | null = null;
  private workspace: string | null = null;
  private geminiClient: GeminiClient | null = null;
  private scheduler: CoreToolScheduler | null = null;
  private onStreamEvent: (event: {
    type: string;
    data: unknown;
    msg_id: string
  }) => void;

  constructor(options: GeminiAgent2Options) {
    this.workspace = options.workspace;
    this.model = options.model;
    this.onStreamEvent = options.onStreamEvent;

    // 初始化环境变量
    this.initClientEnv();

    // 异步初始化
    this.bootstrap = this.initialize();
  }

  private async initialize(): Promise<void> {
    const path = this.workspace;
    const settings = loadSettings(path).merged;

    // 1. 加载扩展和配置
    const extensions = loadExtensions(path);
    this.config = await loadCliConfig({
      workspace: path,
      settings,
      extensions,
      sessionId,
      model: this.model.useModel,
      mcpServers: this.mcpServers,
    });

    // 2. 初始化 Gemini 客户端
    await this.config.initialize();
    this.geminiClient = this.config.getGeminiClient();

    // 3. 注入系统规则
    if (this.presetRules) {
      const currentMemory = this.config.getUserMemory();
      const rulesSection = `[Assistant System Rules]\n${this.presetRules}`;
      const combined = currentMemory ?
        `${rulesSection}\n\n${currentMemory}` : rulesSection;
      this.config.setUserMemory(combined);
    }

    // 4. 初始化工具调度器
    this.initToolScheduler(settings);
  }
}

private handleMessage(
  stream: AsyncGenerator<ServerGeminiStreamEvent, Turn, unknown>,
  msg_id: string,
  abortController: AbortController,
  query?: unknown,
  retryCount: number = 0
): Promise<void> {
  const MAX_INVALID_STREAM_RETRIES = 2;
  const RETRY_DELAY_MS = 1000;
  const toolCallRequests: ToolCallRequestInfo[] = [];
  let invalidStreamDetected = false;

  return processGeminiStreamEvents(
    stream,
    this.config,
    (data) => {
      if (data.type === 'tool_call_request') {
        // 保护工具调用
        globalToolCallGuard.protect(data.data.callId);
        toolCallRequests.push(data.data as ToolCallRequestInfo);
        return;
      }

      // 检测 invalid_stream 事件
      if (data.type === ('invalid_stream' as string)) {
        invalidStreamDetected = true;
        const eventData = data.data as {
          message: string;
          retryable: boolean
        };
        if (eventData.retryable &&
            retryCount < MAX_INVALID_STREAM_RETRIES &&
            query &&
            !abortController.signal.aborted) {
          console.warn('[GeminiAgent] Invalid stream detected, will retry');
          this.onStreamEvent({
            type: 'info',
            data: 'Stream interrupted, retrying...',
            msg_id,
          });
        }
        return;
      }

      // 发送事件到 Worker
      this.onStreamEvent({
        ...data,
        msg_id,
      });
    }
  )
  .then(async () => {
    // 如果检测到 invalid_stream 且可以重试
    if (invalidStreamDetected &&
        retryCount < MAX_INVALID_STREAM_RETRIES &&
        query &&
        !abortController.signal.aborted) {
      console.log('[GeminiAgent] Retrying after invalid stream');
      await new Promise((resolve) =>
        setTimeout(resolve, RETRY_DELAY_MS));

      if (abortController.signal.aborted) return;

      const prompt_id = this.config.getSessionId() +
        '########' + getPromptCount();
      const newStream = this.geminiClient.sendMessageStream(
        query,
        abortController.signal,
        prompt_id
      );
      return this.handleMessage(
        newStream,
        msg_id,
        abortController,
        query,
        retryCount + 1
      );
    }

    // 执行工具调用
    if (toolCallRequests.length > 0) {
      this.emitPreviewForNavigationTools(toolCallRequests, msg_id);
      await this.scheduler.schedule(
        toolCallRequests,
        abortController.signal
      );
    }
  });
}

3.2 Codex (Claude Code) 适配器#

核心文件: src/agent/codex/core/CodexAgent.ts

class CodexAgent {
  private connection: CodexConnection;
  private messageProcessor: CodexMessageProcessor;
  private eventHandler: CodexEventHandler;
  private sessionManager: CodexSessionManager;

  async start() {
    // 1. 建立连接
    await this.connection.connect();

    // 2. 开始监听事件
    this.startEventListening();

    // 3. 初始化会话
    await this.sessionManager.initializeSession();
  }

  async sendMessage(data: { content: string; msg_id: string }) {
    // 处理消息发送
    const response = await this.connection.send({
      type: 'message',
      content: data.content,
    });

    // 处理响应事件
    await this.messageProcessor.process(response);
  }
}

3.3 ACP (通用协议) 适配器#

核心文件: src/agent/acp/AcpAdapter.ts:14-80

export class AcpAdapter {
  private conversationId: string;
  private backend: AcpBackend;
  private activeToolCalls: Map<string, IMessageAcpToolCall> = new Map();
  private currentMessageId: string | null = uuid();

  constructor(conversationId: string, backend: AcpBackend) {
    this.conversationId = conversationId;
    this.backend = backend;
  }

  /**
   * 将 ACP 会话更新转换为 AionUI 消息
   */
  convertSessionUpdate(sessionUpdate: AcpSessionUpdate): TMessage[] {
    const messages: TMessage[] = [];
    const update = sessionUpdate.update;

    switch (update.sessionUpdate) {
      case 'agent_message_chunk': {
        // 转换 agent 消息块
        if (update.content) {
          const message = this.convertSessionUpdateChunk(update);
          if (message) {
            messages.push(message);
          }
        }
        break;
      }

      case 'agent_thought_chunk': {
        // 转换思考块
        if (update.content) {
          const message = this.convertThoughtChunk(update);
          if (message) {
            messages.push(message);
          }
        }
        this.resetMessageTracking();
        break;
      }

      case 'tool_call': {
        // 转换工具调用
        const toolCallMessage = this.createOrUpdateAcpToolCall(
          sessionUpdate
        );
        if (toolCallMessage) {
          messages.push(toolCallMessage);
        }
        this.resetMessageTracking();
        break;
      }
    }

    return messages;
  }
}

4.1 流式消息缓冲优化#

AionUi 的核心性能优化之一是 StreamingMessageBuffer，它将频繁的数据库写入优化为批量更新。

文件位置: src/process/database/StreamingMessageBuffer.ts:24-164

/**
 * 流式消息缓冲管理器
 */

interface StreamBuffer {
  messageId: string;
  conversationId: string;
  currentContent: string;
  chunkCount: number;
  lastDbUpdate: number;
  updateTimer?: NodeJS.Timeout;
  mode: 'accumulate' | 'replace'; // 累积或替换模式
}

export class StreamingMessageBuffer {
  private buffers = new Map<string, StreamBuffer>();
  private readonly UPDATE_INTERVAL = 300; // 300ms 更新一次
  private readonly CHUNK_BATCH_SIZE = 20; // 或累积 20 个 chunk

  /**
   * 追加流式 chunk
   */
  append(
    id: string,
    messageId: string,
    conversationId: string,
    chunk: string,
    mode: 'accumulate' | 'replace'
  ): void {
    let buffer = this.buffers.get(messageId);

    if (!buffer) {
      // 首次 chunk，初始化缓冲区
      buffer = {
        messageId,
        conversationId,
        currentContent: chunk,
        chunkCount: 1,
        lastDbUpdate: Date.now(),
        mode,
      };
      this.buffers.set(messageId, buffer);
    } else {
      // 根据模式累积或替换内容
      if (buffer.mode === 'accumulate') {
        buffer.currentContent += chunk;
      } else {
        buffer.currentContent = chunk; // 替换模式
      }
      buffer.chunkCount++;
    }

    // 判断是否需要更新数据库
    const shouldUpdate =
      buffer.chunkCount % this.CHUNK_BATCH_SIZE === 0 || // 累积足够
      Date.now() - buffer.lastDbUpdate > this.UPDATE_INTERVAL; // 超时

    if (shouldUpdate) {
      // 立即更新
      this.flushBuffer(id, messageId, false);
    } else {
      // 设置延迟更新
      if (buffer.updateTimer) {
        clearTimeout(buffer.updateTimer);
      }
      buffer.updateTimer = setTimeout(() => {
        this.flushBuffer(id, messageId, false);
      }, this.UPDATE_INTERVAL);
    }
  }

  /**
   * 刷新缓冲区到数据库
   */
  private flushBuffer(
    id: string,
    messageId: string,
    clearBuffer = false
  ): void {
    const buffer = this.buffers.get(messageId);
    if (!buffer) return;

    const db = getDatabase();

    try {
      const message: TMessage = {
        id: id,
        msg_id: messageId,
        conversation_id: buffer.conversationId,
        type: 'text',
        content: { content: buffer.currentContent },
        status: 'pending',
        position: 'left',
        createdAt: Date.now(),
      };

      const existing = db.getMessageByMsgId(
        buffer.conversationId,
        messageId
      );

      if (existing.success && existing.data) {
        // 消息已存在 - 更新
        db.updateMessage(existing.data.id, message);
      } else {
        // 消息不存在 - 插入
        db.insertMessage(message);
      }

      buffer.lastDbUpdate = Date.now();

      if (clearBuffer) {
        if (buffer.updateTimer) {
          clearTimeout(buffer.updateTimer);
        }
        this.buffers.delete(messageId);
      }
    } catch (error) {
      console.error(
        `[StreamingBuffer] Failed to flush buffer for ${messageId}:`,
        error
      );
    }
  }

  /**
   * 完成流式消息（强制刷新并清理）
   */
  finish(id: string, messageId: string): void {
    this.flushBuffer(id, messageId, true);
  }
}

// 在消息处理中使用流式缓冲
export const addOrUpdateMessage = (
  conversation_id: string,
  message: TMessage
): void => {
  // 对于文本消息：使用流式缓冲
  if (message.type === 'text' && message.msg_id) {
    const incomingMsg = message as IMessageText;
    const content = incomingMsg.content.content;
    const messageId = message.msg_id || '';

    // 使用流式缓冲优化数据库写入
    streamingBuffer.append(
      message.id,
      messageId,
      conversation_id,
      content,
      'replace' // 或 'accumulate'
    );
  }
};

4.2 自动重试机制#

Gemini API 可能返回 invalid_stream 错误，GeminiAgent 实现了自动重试：

// 检测 invalid_stream 事件
if (data.type === 'invalid_stream') {
  invalidStreamDetected = true;
  const eventData = data.data as {
    message: string;
    retryable: boolean
  };

  if (eventData.retryable &&
      retryCount < MAX_INVALID_STREAM_RETRIES) {
    console.warn('[GeminiAgent] Invalid stream, will retry');
    this.onStreamEvent({
      type: 'info',
      data: 'Stream interrupted, retrying...',
      msg_id,
    });
  }
  return;
}

// 流结束后重试
if (invalidStreamDetected &&
    retryCount < MAX_INVALID_STREAM_RETRIES) {
  await new Promise((resolve) =>
    setTimeout(resolve, RETRY_DELAY_MS));

  const newStream = this.geminiClient.sendMessageStream(
    query,
    abortController.signal,
    prompt_id
  );

  // 递归调用，retryCount + 1
  return this.handleMessage(
    newStream,
    msg_id,
    abortController,
    query,
    retryCount + 1
  );
}

5.1 数据库架构#

AionUi 使用 better-sqlite3 作为本地数据库，提供高性能的同步 API。

文件位置: src/process/database/index.ts:21-100

export class AionUIDatabase {
  private db: Database.Database;
  private readonly defaultUserId = 'system_default_user';

  constructor() {
    const finalPath = path.join(getDataPath(), 'aionui.db');
    console.log(`[Database] Initializing database at: ${finalPath}`);

    const dir = path.dirname(finalPath);
    ensureDirectory(dir);

    try {
      this.db = new BetterSqlite3(finalPath);
      this.initialize();
    } catch (error) {
      console.error(
        '[Database] Failed to initialize, attempting recovery...',
        error
      );
      // 自动恢复：备份并重建数据库
    }
  }

  private initialize(): void {
    try {
      // 1. 初始化数据库架构
      initSchema(this.db);

      // 2. 检查数据库版本
      const currentVersion = getDatabaseVersion(this.db);
      if (currentVersion < CURRENT_DB_VERSION) {
        // 3. 运行迁移脚本
        this.runMigrations(currentVersion, CURRENT_DB_VERSION);
        setDatabaseVersion(this.db, CURRENT_DB_VERSION);
      }

      // 4. 确保系统用户存在
      this.ensureSystemUser();
    } catch (error) {
      console.error('[Database] Initialization failed:', error);
      throw error;
    }
  }
}

5.2 数据库表结构#

-- 会话表
CREATE TABLE conversations (
  id TEXT PRIMARY KEY,
  title TEXT,
  agent_type TEXT,  -- 'gemini' | 'codex' | 'acp'
  workspace_id TEXT,
  created_at INTEGER,
  updated_at INTEGER
);

-- 消息表
CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  conversation_id TEXT,
  role TEXT,  -- 'user' | 'assistant' | 'system'
  content TEXT,
  metadata JSON,  -- 附加信息（图片、文件等）
  created_at INTEGER,
  FOREIGN KEY (conversation_id) REFERENCES conversations(id)
);

-- 工作空间表
CREATE TABLE workspaces (
  id TEXT PRIMARY KEY,
  name TEXT,
  root_path TEXT,
  file_tree JSON,  -- 缓存文件树结构
  created_at INTEGER
);

-- 全文搜索索引
CREATE VIRTUAL TABLE messages_fts USING fts5(
  content,
  content=messages,
  content_rowid=id
);

5.3 WAL 模式性能优化#

const db = new Database('aionui.db');

// 启用 WAL (Write-Ahead Logging) 模式
db.pragma('journal_mode = WAL');

// 平衡性能和安全性
db.pragma('synchronous = NORMAL');

WAL 模式优势：

• 并发性能：读操作不阻塞写操作
• 崩溃恢复：更好的数据完整性保证
• 写入性能：减少磁盘 I/O 操作

5.4 消息处理函数#

文件位置: src/process/message.ts:20-222

/**
 * 添加或更新单个消息
 */
export const addOrUpdateMessage = (
  conversation_id: string,
  message: TMessage,
  backend?: AcpBackend
): void => {
  if (!message || !message.id) {
    console.error('[Message] Cannot add or update undefined message');
    return;
  }

  void (async () => {
    try {
      const db = getDatabase();
      await ensureConversationExists(db, conversation_id);

      // 对于文本消息：使用流式缓冲
      if (message.type === 'text' && message.msg_id) {
        const incomingMsg = message as IMessageText;
        const content = incomingMsg.content.content;
        const messageId = message.msg_id || '';

        // 批量写入优化
        streamingBuffer.append(
          message.id,
          messageId,
          conversation_id,
          content,
          backend ? 'accumulate' : 'replace'
        );
      }
      // 对于工具调用：使用 composeMessage 合并
      else if (
        message.type === 'tool_group' ||
        message.type === 'tool_call' ||
        message.type === 'codex_tool_call' ||
        message.type === 'acp_tool_call'
      ) {
        const result = db.getConversationMessages(
          conversation_id,
          0,
          10000
        );
        const existingMessages = result.data || [];
        const sameTypeMessages = existingMessages.filter(
          (m) => m.type === message.type
        );

        // 合并逻辑
        const composedList = composeMessage(
          message,
          sameTypeMessages.slice()
        );

        // 检测并应用变化
        if (composedList.length > sameTypeMessages.length) {
          const newMessages = composedList.slice(
            sameTypeMessages.length
          );
          for (const newMsg of newMessages) {
            db.insertMessage(newMsg);
          }
        } else {
          for (let i = 0; i < composedList.length; i++) {
            const original = sameTypeMessages[i];
            const composed = composedList[i];
            if (JSON.stringify(original) !== JSON.stringify(composed)) {
              db.updateMessage(composed.id, composed);
            }
          }
        }
      }

      executePendingCallbacks();
    } catch (error) {
      console.error('[Message] Failed to add or update message:', error);
      executePendingCallbacks();
    }
  })();
};

6.1 React Context#

文件位置: src/renderer/context/ConversationContext.tsx:7-68

/**
 * 会话上下文接口
 */
export interface ConversationContextValue {
  /**
   * 会话 ID
   */
  conversationId: string;

  /**
   * 工作空间目录路径
   */
  workspace?: string;

  /**
   * 会话类型
   */
  type: 'gemini' | 'acp' | 'codex';
}

const ConversationContext = createContext<ConversationContextValue | null>(
  null
);

/**
 * 会话上下文提供者
 */
export const ConversationProvider: React.FC<{
  children: React.ReactNode;
  value: ConversationContextValue;
}> = ({ children, value }) => {
  return (
    <ConversationContext.Provider value={value}>
      {children}
    </ConversationContext.Provider>
  );
};

/**
 * 使用会话上下文 Hook
 */
export const useConversationContext = () => {
  const context = useContext(ConversationContext);
  if (!context) {
    throw new Error(
      'useConversationContext must be used within ConversationProvider'
    );
  }
  return context;
};

6.2 消息列表状态管理#

文件位置: src/renderer/messages/hooks.ts:13-143

/**
 * 消息索引缓存类型定义
 */
interface MessageIndex {
  msgIdIndex: Map<string, number>; // msg_id -> index
  callIdIndex: Map<string, number>; // tool_call.callId -> index
  toolCallIdIndex: Map<string, number>; // codex_tool_call.toolCallId -> index
}

// 使用 WeakMap 缓存索引，当列表被 GC 时自动清理
const indexCache = new WeakMap<TMessage[], MessageIndex>();

/**
 * 构建消息索引 - O(n) 时间复杂度
 */
function buildMessageIndex(list: TMessage[]): MessageIndex {
  const msgIdIndex = new Map<string, number>();
  const callIdIndex = new Map<string, number>();
  const toolCallIdIndex = new Map<string, number>();

  for (let i = 0; i < list.length; i++) {
    const msg = list[i];
    if (msg.msg_id) msgIdIndex.set(msg.msg_id, i);
    if (msg.type === 'tool_call' && msg.content?.callId) {
      callIdIndex.set(msg.content.callId, i);
    }
    if (msg.type === 'codex_tool_call' && msg.content?.toolCallId) {
      toolCallIdIndex.set(msg.content.toolCallId, i);
    }
    if (msg.type === 'acp_tool_call' && msg.content?.update?.toolCallId) {
      toolCallIdIndex.set(msg.content.update.toolCallId, i);
    }
  }

  return { msgIdIndex, callIdIndex, toolCallIdIndex };
}

/**
 * 获取或构建索引
 */
function getOrBuildIndex(list: TMessage[]): MessageIndex {
  let index = indexCache.get(list);
  if (!index) {
    index = buildMessageIndex(list);
    indexCache.set(list, index);
  }
  return index;
}

/**
 * 使用索引优化的消息合并 - O(1) 查找
 */
function composeMessageWithIndex(
  message: TMessage,
  list: TMessage[],
  index: MessageIndex
): TMessage[] {
  if (!message) return list || [];
  if (!list?.length) return [message];

  // tool_call: 使用 callIdIndex 快速查找
  if (message.type === 'tool_call' && message.content?.callId) {
    const existingIdx = index.callIdIndex.get(message.content.callId);
    if (existingIdx !== undefined && existingIdx < list.length) {
      const existingMsg = list[existingIdx];
      if (existingMsg.type === 'tool_call') {
        const newList = list.slice();
        const merged = { ...existingMsg.content, ...message.content };
        newList[existingIdx] = { ...existingMsg, content: merged };
        return newList;
      }
    }
    list.push(message);
    return list;
  }

  // text: 使用 msgIdIndex 快速查找
  if (message.type === 'text' && message.msg_id) {
    const existingIdx = index.msgIdIndex.get(message.msg_id);
    if (existingIdx !== undefined && existingIdx < list.length) {
      const newList = list.slice();
      newList[existingIdx] = message;
      return newList;
    }
  }

  return list.concat(message);
}

/**
 * useAddOrUpdateMessage Hook - 批量更新消息
 * 使用 requestAnimationFrame 合并多个微观更新为一个宏观更新
 */
export const useAddOrUpdateMessage = () => {
  const update = useUpdateMessageList();
  const pendingRef = useRef<Array<{ message: TMessage; add: boolean }>>([]);
  const rafRef = useRef<number | null>(null);

  const flush = useCallback(() => {
    rafRef.current = null;
    const pending = pendingRef.current;
    if (!pending.length) return;
    pendingRef.current = [];

    update((list) => {
      const index = getOrBuildIndex(list);
      let newList = list;

      for (const item of pending) {
        if (item.add) {
          // 新增消息，更新索引
          const msg = item.message;
          const newIdx = newList.length;
          if (msg.msg_id) index.msgIdIndex.set(msg.msg_id, newIdx);
          newList = newList.concat(msg);
        } else {
          // 使用索引优化的消息合并
          newList = composeMessageWithIndex(item.message, newList, index);
        }

        // 执行前置处理
        while (beforeUpdateMessageListStack.length) {
          newList = beforeUpdateMessageListStack.shift()!(newList);
        }
      }
      return newList;
    });
  }, [update]);

  return useCallback((message: TMessage, add = false) => {
    pendingRef.current.push({ message, add });
    if (rafRef.current === null) {
      // 使用 requestAnimationFrame 合并更新
      rafRef.current = requestAnimationFrame(flush);
    }
  }, [flush]);
};

6.3 对话状态追踪#

文件位置: src/renderer/pages/conversation/gemini/GeminiSendBox.tsx:36-250

const useGeminiMessage = (
  conversation_id: string,
  onError?: (message: IResponseMessage) => void
) => {
  const addOrUpdateMessage = useAddOrUpdateMessage();
  const [streamRunning, setStreamRunning] = useState(false);
  const [hasActiveTools, setHasActiveTools] = useState(false);
  const [thought, setThought] = useState<ThoughtData>({
    description: '',
    subject: '',
  });
  const [tokenUsage, setTokenUsage] = useState<TokenUsageData | null>(null);

  // 当前活跃的消息 ID，用于过滤旧请求的事件
  const activeMsgIdRef = useRef<string | null>(null);

  // 思考消息节流：50ms 更新一次
  const thoughtThrottleRef = useRef<{
    lastUpdate: number;
    pending: ThoughtData | null;
    timer: ReturnType<typeof setTimeout> | null;
  }>({ lastUpdate: 0, pending: null, timer: null });

  const throttledSetThought = (newThought: ThoughtData) => {
    const now = Date.now();
    const throttle = thoughtThrottleRef.current;

    throttle.pending = newThought;

    if (now - throttle.lastUpdate > 50) {
      // 超过 50ms，立即更新
      setThought(newThought);
      throttle.lastUpdate = now;
      throttle.pending = null;
    } else {
      // 设置延迟更新
      if (!throttle.timer) {
        throttle.timer = setTimeout(() => {
          if (throttle.pending) {
            setThought(throttle.pending);
            throttle.lastUpdate = Date.now();
            throttle.pending = null;
          }
          throttle.timer = null;
        }, 50);
      }
    }
  };

  // 综合运行状态
  const running = streamRunning || hasActiveTools;

  useEffect(() => {
    return ipcBridge.geminiConversation.responseStream.on((message) => {
      if (conversation_id !== message.conversation_id) return;

      // 过滤掉不属于当前活跃请求的事件
      if (activeMsgIdRef.current &&
          message.msg_id &&
          message.msg_id !== activeMsgIdRef.current) {
        if (message.type === 'thought') {
          return; // 只过滤掉 thought
        }
      }

      switch (message.type) {
        case 'thought':
          throttledSetThought(message.data as ThoughtData);
          break;

        case 'start':
          setStreamRunning(true);
          break;

        case 'finish':
          setStreamRunning(false);
          if (!hasActiveTools) {
            setThought({ subject: '', description: '' });
          }
          break;

        case 'tool_group':
          const tools = message.data as Array<{
            status: string;
            name?: string
          }>;
          const activeStatuses = ['Executing', 'Confirming', 'Pending'];
          const hasActive = tools.some((tool) =>
            activeStatuses.includes(tool.status)
          );
          setHasActiveTools(hasActive);
          addOrUpdateMessage(transformMessage(message));
          break;

        case 'finished':
          const finishedData = message.data as {
            reason?: string;
            usageMetadata?: {
              promptTokenCount?: number;
              candidatesTokenCount?: number;
              totalTokenCount?: number;
              cachedContentTokenCount?: number;
            };
          };
          if (finishedData?.usageMetadata) {
            const newTokenUsage: TokenUsageData = {
              totalTokens: finishedData.usageMetadata.totalTokenCount || 0,
            };
            setTokenUsage(newTokenUsage);
          }
          break;
      }
    });
  }, [conversation_id]);

  return {
    running,
    thought,
    tokenUsage,
    setActiveMsgId: (msgId: string) => {
      activeMsgIdRef.current = msgId;
    }
  };
};

7.1 虚拟化列表渲染#

文件位置: src/renderer/messages/MessageList.tsx:34-150

使用 react-virtuoso 实现虚拟化滚动，只渲染可见区域的消息。

const MessageList: React.FC<{ className?: string }> = () => {
  const list = useMessageList();
  const virtuosoRef = useRef<VirtuosoHandle>(null);
  const [showScrollButton, setShowScrollButton] = useState(false);

  return (
    <Virtuoso
      ref={virtuosoRef}
      data={list}
      className={classNames('flex-1 w-full overflow-y-auto', className)}
      itemContent={(index, message) => (
        <MessageItem key={message.id} message={message} />
      )}
      atBottomStateChange={(atBottom) => {
        setShowScrollButton(!atBottom);
      }}
      followOutput={true}
      style={{
        height: '100%',
        width: '100%',
      }}
    />
  );
};

性能优势：

• 常数级复杂度：无论有多少消息，只渲染可见的 ~20 条
• 自动滚动：新消息到达时自动滚动到底部
• 内存优化：未渲染的消息不占用 DOM 内存

7.2 消息项渲染#

const MessageItem: React.FC<{ message: TMessage }> = React.memo(
  HOC((props) => {
    const { message } = props as { message: TMessage };
    return (
      <div
        className={classNames(
          'flex items-start message-item max-w-full px-8px m-t-10px',
          message.type,
          {
            'justify-center': message.position === 'center',
            'justify-end': message.position === 'right',
            'justify-start': message.position === 'left',
          }
        )}
      >
        {props.children}
      </div>
    );
  })(({ message }) => {
    // 根据消息类型分发渲染
    switch (message.type) {
      case 'text':
        return <MessageText message={message} />;
      case 'tips':
        return <MessageTips message={message} />;
      case 'tool_call':
        return <MessageToolCall message={message} />;
      case 'tool_group':
        return <MessageToolGroup message={message} />;
      case 'agent_status':
        return <MessageAgentStatus message={message} />;
      case 'acp_permission':
        return <MessageAcpPermission message={message} />;
      case 'acp_tool_call':
        return <MessageAcpToolCall message={message} />;
      case 'codex_permission':
        return <MessageCodexPermission message={message} />;
      case 'codex_tool_call':
        return <MessageCodexToolCall message={message} />;
      default:
        return <div>Unknown message type: {(message as any).type}</div>;
    }
  }),
  // React.memo 比较函数
  (prev, next) =>
    prev.message.id === next.message.id &&
    prev.message.content === next.message.content &&
    prev.message.position === next.message.position &&
    prev.message.type === next.message.type
);

优化要点：

• React.memo：防止不必要的重新渲染
• 类型分发：每种消息类型有专门的渲染组件
• 浅比较：只比较关键属性，减少比较开销

7.3 Markdown 渲染#

使用 react-markdown + KaTeX 渲染富文本消息。

相关文件: src/renderer/pages/conversation/preview/components/viewers/MarkdownViewer.tsx

const MessageText: React.FC<{ message: IMessageText }> = ({ message }) => {
  const content = message.content.content;

  return (
    <div className="message-text">
      <ReactMarkdown
        remarkPlugins={[remarkGfm, remarkMath]}
        rehypePlugins={[rehypeKatex, rehypeHighlight]}
        components={{
          code({ node, inline, className, children, ...props }) {
            const match = /language-(\w+)/.exec(className || '');
            return !inline && match ? (
              <SyntaxHighlighter
                style={vscDarkPlus}
                language={match[1]}
                PreTag="div"
                {...props}
              >
                {String(children).replace(/\n$/, '')}
              </SyntaxHighlighter>
            ) : (
              <code className={className} {...props}>
                {children}
              </code>
            );
          },
        }}
      >
        {content}
      </ReactMarkdown>
    </div>
  );
};

功能支持：

• GFM：GitHub Flavored Markdown（表格、任务列表等）
• 数学公式：KaTeX 渲染 LaTeX 公式
• 代码高亮：Prism.js 语法高亮
• 自定义组件：可扩展的渲染器

8.1 优化措施对比#

8.2 性能指标#

9.1 AI Agent 层#

9.2 Agent 管理层#

9.3 IPC 通信层#

9.4 Worker 进程#

9.5 数据库层#

9.6 前端层#

核心优势#

1. 多 Agent 支持：统一接口，自动分发，易于扩展
2. 流式优化：批量缓冲、自动重试、弹性监控
3. 实时渲染：虚拟化列表、消息索引、批量更新
4. 数据持久化：SQLite WAL 模式、流式缓冲、100x 性能提升
5. 可扩展设计：清晰的模块划分，便于添加新的 Agent

架构特点#

• 职责分离：渲染进程（UI）、主进程（数据）、Worker（AI）
• 异步通信：IPC 桥接，非阻塞架构
• 性能优先：O(1) 索引、批量更新、虚拟化渲染
• 错误恢复：自动重试、降级处理、友好提示

适用场景#

• 学习参考：Electron 多进程架构的最佳实践
• 技术选型：了解 AI 应用的底层实现机制
• 性能优化：流式数据处理的优化策略
• 架构设计：多 Agent 系统的统一接口设计