第十三章：Electron 主进程架构

“Electron 应用的本质是：一个 Node.js 进程管理着一个 Chromium 浏览器，两者通过严格的桥接层进行通信。理解这个架构，就理解了为什么安全桥接是设计的核心。”

13.1 为什么选择 Electron？

Auto-Claude 是一个同时包含 Python 后端（AI 智能体）和 React 前端（可视化界面）的复杂系统。选择 Electron 作为桌面应用框架，有几个关键原因：

跨平台：一套代码在 Windows、macOS、Linux 上运行
原生能力：可以访问文件系统、运行子进程、使用系统密钥链
前端复用：Web 技术栈（React、TypeScript）直接用于桌面 UI
PTY 集成：通过 node-pty 实现真正的终端模拟

但 Electron 的架构也带来了特有的复杂性：主进程（Main Process）和渲染进程（Renderer Process）是完全隔离的两个进程，它们只能通过受限的 IPC 通道通信。

13.2 三进程架构

Auto-Claude 的 Electron 应用实际上运行着三类进程：

┌─────────────────────────────────────────────────────────┐
│                    Electron 应用                          │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │           主进程（Main Process）                    │  │
│  │   Node.js 运行环境，完全访问 Node.js API            │  │
│  │   - IPC 处理器（40+ 模块）                         │  │
│  │   - Python 子进程管理                              │  │
│  │   - 文件系统操作                                   │  │
│  │   - OS 密钥链（macOS Keychain / Windows Credential）│  │
│  └──────────────┬────────────────────────────────────┘  │
│                 │ IPC (ipcMain/ipcRenderer)              │
│                 │ 通过 preload 脚本安全桥接               │
│  ┌──────────────▼────────────────────────────────────┐  │
│  │           渲染进程（Renderer Process）               │  │
│  │   Chromium + React 运行环境                        │  │
│  │   - UI 组件（React + Tailwind）                    │  │
│  │   - 状态管理（Zustand）                            │  │
│  │   - 只能访问 window.electronAPI                    │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │           Python 子进程（多个）                     │  │
│  │   spawn('python', [...args])                      │  │
│  │   - 智能体运行器（run.py）                         │  │
│  │   - 规格创建器                                    │  │
│  │   - Roadmap/Ideation runner                      │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

主进程是整个应用的"服务器端"。它拥有完整的 Node.js 能力，负责：

生命周期管理（创建/销毁窗口）
所有危险操作（文件系统写入、进程启动、网络请求）
接收渲染进程的 IPC 调用并返回结果

渲染进程是"纯 UI 层"。出于安全考虑，它默认不能访问 Node.js API（contextIsolation: true），只能通过 preload 脚本暴露的 window.electronAPI 对象与主进程通信。

13.3 Preload 脚本：安全桥接层

apps/frontend/src/preload/ 中的 preload 脚本是主进程和渲染进程之间的"受信中间人"。它运行在渲染进程的 JavaScript 上下文中，但可以访问有限的 Node.js API：

// apps/frontend/src/preload/index.ts（概念化）
import { contextBridge, ipcRenderer } from 'electron';

contextBridge.exposeInMainWorld('electronAPI', {
  // 任务操作
  createTask: (data: TaskData) =>
    ipcRenderer.invoke('task:create', data),
  startTask: (taskId: string) =>
    ipcRenderer.invoke('task:start', taskId),

  // 监听主进程事件
  onAgentLog: (callback: (log: string) => void) => {
    ipcRenderer.on('agent:log', (_, log) => callback(log));
  },

  // 清理监听器
  removeAgentLogListener: () => {
    ipcRenderer.removeAllListeners('agent:log');
  },
});

渲染进程中的 React 代码通过 window.electronAPI.createTask(data) 调用，这个调用被安全地转发给主进程的 IPC 处理器。

★ Insight ───────────────────────────────────── contextIsolation + contextBridge 是 Electron 的安全核心。渲染进程中运行的 React 代码和用户加载的网页一样处于沙箱中，无法直接调用 require('fs') 或 require('child_process')。contextBridge 只暴露经过设计的白名单 API，使得即使渲染进程被 XSS 攻击，攻击者也无法获得 Node.js 的完整能力。 ─────────────────────────────────────────────────

13.4 IPC 处理器：40+ 模块的组织方式

apps/frontend/src/main/ipc-handlers/ 包含 40+ 个 IPC 处理器文件，按功能域组织：

ipc-handlers/
├── index.ts                  # 注册所有处理器的入口
├── task-handlers.ts          # 任务 CRUD + 执行 + Worktree
├── task/
│   ├── crud-handlers.ts      # 创建/读取/更新/删除
│   ├── execution-handlers.ts # 启动/停止/恢复
│   ├── worktree-handlers.ts  # Worktree 状态/合并/丢弃
│   └── logs-handlers.ts      # 日志获取/监听
├── github-handlers.ts        # GitHub 集成
├── gitlab-handlers.ts        # GitLab 集成
├── profile-handlers.ts       # Claude Profile 管理
├── terminal-handlers.ts      # PTY 终端
├── settings-handlers.ts      # 应用设置
├── ideation-handlers.ts      # Ideation 功能
├── roadmap-handlers.ts       # Roadmap 功能
└── ...（其他功能域）

每个处理器文件导出一个注册函数：

// apps/frontend/src/main/ipc-handlers/task/execution-handlers.ts（概念化）
import { ipcMain } from 'electron';
import { AgentProcessManager } from '../agent';

export function registerTaskExecutionHandlers(
  processManager: AgentProcessManager
) {
  // 启动任务：触发 Python 智能体进程
  ipcMain.handle('task:start', async (event, taskId: string) => {
    return await processManager.startTask(taskId);
  });

  // 停止任务：终止 Python 进程
  ipcMain.handle('task:stop', async (event, taskId: string) => {
    return processManager.stopTask(taskId);
  });

  // 获取任务状态
  ipcMain.handle('task:status', async (event, taskId: string) => {
    return processManager.getTaskStatus(taskId);
  });
}

index.ts 中统一调用所有注册函数：

// 集中注册所有 IPC 处理器
export function registerAllHandlers(managers: AppManagers) {
  registerTaskHandlers(managers.processManager);
  registerProfileHandlers(managers.profileManager);
  registerTerminalHandlers(managers.terminalManager);
  registerGitHubHandlers(managers.githubService);
  // ...
}

这种按域拆分、统一注册的设计使每个处理器模块保持单一职责，同时主进程入口保持简洁。

13.5 Python 子进程管理

apps/frontend/src/main/agent/agent-process.ts 是整个前端最核心的模块——它负责启动和管理 Python 子进程。

13.5.1 环境变量的六层叠加

启动 Python 进程时，环境变量的构建遵循严格的优先级顺序：

// apps/frontend/src/main/agent/agent-queue.ts（简化）

const finalEnv = {
  // 1. 系统环境变量（最低优先级）
  ...process.env,

  // 2. Python 捆绑包环境（site-packages 路径）
  ...pythonEnv,

  // 3. 项目 .env 文件（CLI 使用场景）
  ...combinedEnv,

  // 4. OAuth 模式清理变量（清除过期的 ANTHROPIC_* 变量）
  ...oauthModeClearVars,

  // 5. Electron App OAuth Token
  ...profileEnv,

  // 6. 激活的 API Profile 配置（最高优先级的 ANTHROPIC_* 变量）
  ...apiProfileEnv,

  // 强制覆盖项
  PYTHONPATH: combinedPythonPath,
  PYTHONUNBUFFERED: '1',  // 禁用 Python 输出缓冲，确保实时输出
  PYTHONUTF8: '1'         // 强制 UTF-8 编码
};

// 修复 Windows 的 PATH 键名大小写问题
normalizeEnvPathKey(finalEnv);

这六层叠加解决了一个复杂的权限问题：用户可能同时有系统级 API Key（在 .env 文件中）、Electron App 的 OAuth Token，以及通过 UI 配置的 API Profile。正确的优先级确保 UI 配置的 Profile 总是优先生效。

13.5.2 Windows PATH 规范化

// apps/frontend/src/main/agent/env-utils.ts（概念化）
export function normalizeEnvPathKey(
  env: Record<string, string | undefined>
): void {
  // Windows 的 process.env 包含 "Path"（注意大小写），
  // 而 Python 环境可能写入 "PATH"（全大写）
  // 两者并存时子进程可能找不到可执行文件
  const pathKeys = Object.keys(env).filter(k => k.toLowerCase() === 'path');

  if (pathKeys.length > 1) {
    // 合并所有 path 变量，统一使用 "PATH"
    const combinedPath = pathKeys
      .map(k => env[k])
      .filter(Boolean)
      .join(getPathDelimiter());  // ':' on Unix, ';' on Windows

    pathKeys.forEach(k => delete env[k]);
    env['PATH'] = combinedPath;
  }
}

这个问题（Windows PATH 大小写冲突）在实践中曾导致子进程找不到 git/python 等工具，是跨平台开发中典型的"低概率高影响"陷阱。

13.5.3 SpawnId 机制：防止幽灵进程

// apps/frontend/src/main/agent/agent-state.ts（简化）

class AgentState {
  private killedSpawnIds: Set<number> = new Set();
  private spawnCounter: number = 0;

  generateSpawnId(): number {
    return ++this.spawnCounter;
  }

  markSpawnAsKilled(spawnId: number): void {
    this.killedSpawnIds.add(spawnId);
  }

  wasSpawnKilled(spawnId: number): boolean {
    return this.killedSpawnIds.has(spawnId);
  }
}

在进程退出处理中：

childProcess.on('exit', (code) => {
  // 检查这个进程是否是被用户主动停止的
  const wasIntentionallyStopped = this.state.wasSpawnKilled(spawnId);
  if (wasIntentionallyStopped) {
    // 忽略此次退出——是主动停止，不是异常
    this.state.clearKilledSpawn(spawnId);
    this.emitter.emit('ideation-stopped', projectId);
    return;
  }

  // 真正的退出：处理成功/失败逻辑
  if (code === 0) { /* 成功 */ }
  else { /* 检查速率限制等 */ }
});

这个机制解决了一个微妙的竞态条件：当用户点击"停止"时，进程会收到终止信号然后退出。如果没有 SpawnId 追踪，exit 事件处理器无法区分"主动停止"和"意外崩溃"，可能错误地显示错误消息或触发重试逻辑。

13.6 速率限制检测与自动恢复

进程退出时，系统会分析所有累积输出来检测速率限制：

// 进程退出处理（简化）
childProcess.on('exit', (code) => {
  if (code !== 0) {
    // 分析最后 10KB 输出，查找速率限制信号
    const rateLimitDetection = detectRateLimit(allOutput);
    if (rateLimitDetection.isRateLimited) {
      const rateLimitInfo = createSDKRateLimitInfo('ideation', rateLimitDetection, {
        projectId
      });
      // 通知主应用，触发账号切换流程
      this.emitter.emit('sdk-rate-limit', rateLimitInfo);
    }
  }
});

// 实时输出收集（只保留最后 10KB）
childProcess.stdout?.on('data', (data: Buffer) => {
  const log = data.toString('utf-8');
  allOutput = (allOutput + log).slice(-10000);
  // ...
});

保留"最后 10KB"而非全部输出是一个内存优化：速率限制错误总是出现在接近进程退出时，无需保留完整的输出历史。

13.7 Git Bash 路径推导（Windows 特例）

Windows 上的 Git 安装带有 Bash，Auto-Claude 在 Windows 上使用 Git Bash 来执行某些命令。deriveGitBashPath() 展示了处理不规则安装路径的健壮方式：

// apps/frontend/src/main/agent/agent-process.ts（简化）

function deriveGitBashPath(gitExePath: string): string | null {
  // Git 可能安装在多种目录结构下：
  // - .../Git/cmd/git.exe
  // - .../Git/bin/git.exe
  // - .../Git/mingw64/bin/git.exe

  const gitDir = path.dirname(gitExePath);
  const gitDirName = path.basename(gitDir).toLowerCase();

  let gitRoot: string;
  if (gitDirName === 'cmd') {
    gitRoot = path.dirname(gitDir);  // .../Git
  } else if (gitDirName === 'bin') {
    const parent = path.dirname(gitDir);
    const parentName = path.basename(parent).toLowerCase();
    if (parentName === 'mingw64' || parentName === 'mingw32') {
      gitRoot = path.dirname(parent);  // .../Git
    } else {
      gitRoot = parent;  // .../Git
    }
  } else {
    gitRoot = path.dirname(gitDir);
  }

  const bashPath = path.join(gitRoot, 'bin', 'bash.exe');
  if (existsSync(bashPath)) return bashPath;

  // 备用路径
  const altBashPath = path.join(path.dirname(gitRoot), 'bin', 'bash.exe');
  return existsSync(altBashPath) ? altBashPath : null;
}

这体现了跨平台开发的一个重要原则：不要假设安装路径，而是从已知的线索（git 可执行文件的位置）推导出相关路径。

13.8 平台抽象层

apps/frontend/src/main/platform/ 提供了跨平台 API 的统一接口：

// apps/frontend/src/main/platform/index.ts（概念化）

export function isWindows(): boolean {
  return process.platform === 'win32';
}

export function isMacOS(): boolean {
  return process.platform === 'darwin';
}

export function getPathDelimiter(): string {
  return isWindows() ? ';' : ':';
}

export function killProcessGracefully(proc: ChildProcess): void {
  if (isWindows()) {
    // Windows 没有 SIGTERM，使用 taskkill
    spawn('taskkill', ['/pid', String(proc.pid), '/f', '/t']);
  } else {
    proc.kill('SIGTERM');
  }
}

规则很简单：凡是依赖平台的操作，都通过这层接口调用，不直接使用 process.platform。这使得平台适配逻辑集中在一处，便于测试和修改。

本章要点回顾

概念	实现位置	关键点
三进程架构	Electron 设计	主进程 + 渲染进程 + Python 子进程
contextBridge 安全桥接	`preload/index.ts`	渲染进程只能访问白名单 API
IPC 处理器组织	`ipc-handlers/`	按功能域拆分 + 统一注册
六层环境变量优先级	`agent-queue.ts`	OAuth Token 优先于 .env 优先于系统 env
Windows PATH 规范化	`env-utils.ts: normalizeEnvPathKey()`	合并大小写不同的 PATH 键
SpawnId 防幽灵进程	`agent-state.ts`	区分主动停止与意外崩溃
速率限制检测	`agent-queue.ts`	保留最后 10KB 输出
平台抽象层	`platform/index.ts`	`isWindows()`, `killProcessGracefully()`

Lab 13.1：迷你 IPC 系统

本 Lab 用 Node.js EventEmitter 模拟 Electron IPC 的核心模式。

Part A：安全 IPC 桥接（必做）

// lab_13_ipc.ts（在 Node.js 环境运行）
import { EventEmitter } from 'events';

// ============================================================
// 模拟 Electron IPC 核心机制
// ============================================================

type Handler<T = unknown, R = unknown> = (data: T) => R | Promise<R>;
type Listener<T = unknown> = (data: T) => void;

/**
 * 主进程 IPC 系统（模拟 ipcMain）
 *
 * 注册处理器：handle(channel, handler)
 * 响应渲染进程调用：返回 handler 的结果
 */
class MainIPC {
  private handlers = new Map<string, Handler>();
  private listeners = new Map<string, Listener[]>();

  handle<T, R>(channel: string, handler: Handler<T, R>): void {
    this.handlers.set(channel, handler as Handler);
  }

  on<T>(channel: string, listener: Listener<T>): void {
    if (!this.listeners.has(channel)) {
      this.listeners.set(channel, []);
    }
    this.listeners.get(channel)!.push(listener as Listener);
  }

  async dispatch(channel: string, data: unknown): Promise<unknown> {
    const handler = this.handlers.get(channel);
    if (!handler) throw new Error(`No handler for channel: ${channel}`);
    return await handler(data);
  }

  broadcast(channel: string, data: unknown): void {
    const listeners = this.listeners.get(channel) || [];
    listeners.forEach(l => l(data));
  }
}

/**
 * 渲染进程 IPC 系统（模拟 ipcRenderer + preload）
 *
 * TODO: 实现安全 API 桥接（15-20 行）：
 *
 * 设计要求：
 * 1. RendererIPC 持有对 MainIPC 的引用，但渲染进程代码不能直接访问 MainIPC
 * 2. 实现 invoke(channel, data) 方法：调用 main.dispatch() 并返回结果
 * 3. 实现 on(channel, listener) 方法：注册事件监听
 * 4. 实现 exposeAPI() 方法：返回一个白名单对象（模拟 contextBridge.exposeInMainWorld）
 *    白名单只暴露以下方法：
 *    - createTask(data) → invoke('task:create', data)
 *    - startTask(id) → invoke('task:start', id)
 *    - stopTask(id) → invoke('task:stop', id)
 *    - onAgentLog(callback) → on('agent:log', callback)
 *
 * 渲染进程代码只能通过 exposeAPI() 返回的对象访问 IPC
 */
class RendererIPC {
  constructor(private main: MainIPC, private emitter: EventEmitter) {}

  // YOUR CODE HERE
}

Part B：进程状态管理（必做）

// 接续 lab_13_ipc.ts

interface ProcessInfo {
  id: string;
  spawnId: number;
  startedAt: Date;
  type: 'agent' | 'ideation' | 'roadmap';
}

/**
 * 进程状态管理器（模拟 AgentState）
 *
 * TODO: 实现状态管理逻辑（25-35 行）：
 *
 * 需要实现：
 * - addProcess(id, info): 注册进程
 * - getProcess(id): 获取进程信息
 * - deleteProcess(id): 移除进程
 * - generateSpawnId(): 返回递增的唯一 ID
 * - markAsKilled(spawnId): 标记为已主动停止
 * - wasKilled(spawnId): 检查是否被主动停止
 * - clearKilled(spawnId): 清除已停止标记
 * - getRunningIds(): 返回所有运行中的进程 ID
 */
class ProcessStateManager {
  // YOUR CODE HERE
}

// === 验证测试 ===
async function runTests() {
  const mainIPC = new MainIPC();
  const emitter = new EventEmitter();
  const rendererIPC = new RendererIPC(mainIPC, emitter);
  const api = rendererIPC.exposeAPI();

  // 注册主进程处理器
  const tasks = new Map<string, { id: string; status: string }>();
  mainIPC.handle('task:create', (data: any) => {
    const id = `task-${Date.now()}`;
    tasks.set(id, { id, status: 'pending' });
    return { id, status: 'pending' };
  });
  mainIPC.handle('task:start', (id: string) => {
    const task = tasks.get(id);
    if (!task) throw new Error(`Task not found: ${id}`);
    task.status = 'running';
    return { success: true };
  });
  mainIPC.handle('task:stop', (id: string) => {
    const task = tasks.get(id);
    if (task) task.status = 'stopped';
    return { success: true };
  });

  // 测试 1: 创建任务
  const created = await api.createTask({ description: 'Test task' });
  console.assert(created.id, 'Should have task ID');
  console.assert(created.status === 'pending', 'Should start as pending');
  console.log('[PASS] createTask:', created);

  // 测试 2: 启动任务
  const started = await api.startTask(created.id);
  console.assert(started.success, 'Should start successfully');
  console.log('[PASS] startTask:', started);

  // 测试 3: 日志事件
  let receivedLog = '';
  api.onAgentLog((log: string) => { receivedLog = log; });
  mainIPC.broadcast('agent:log', 'Agent started working...');
  await new Promise(r => setTimeout(r, 10));
  console.assert(receivedLog === 'Agent started working...', 'Should receive log');
  console.log('[PASS] onAgentLog:', receivedLog);

  // 测试 4: 安全限制（只能调用白名单方法）
  const hasUnauthorizedAccess = 'dispatch' in api || 'handle' in api;
  console.assert(!hasUnauthorizedAccess, 'Should not expose internal methods');
  console.log('[PASS] Security: unauthorized methods not exposed');

  // 测试 5: 进程状态管理
  const psm = new ProcessStateManager();
  const spawnId1 = psm.generateSpawnId();
  const spawnId2 = psm.generateSpawnId();
  console.assert(spawnId2 > spawnId1, 'SpawnIds should be incrementing');

  psm.addProcess('proc-1', { id: 'proc-1', spawnId: spawnId1,
    startedAt: new Date(), type: 'agent' });
  console.assert(psm.getRunningIds().length === 1, 'Should have 1 running process');

  psm.markAsKilled(spawnId1);
  console.assert(psm.wasKilled(spawnId1), 'Should be marked as killed');
  console.assert(!psm.wasKilled(spawnId2), 'Other spawnId should not be marked');

  psm.clearKilled(spawnId1);
  console.assert(!psm.wasKilled(spawnId1), 'After clear, should not be killed');
  console.log('[PASS] ProcessStateManager');

  console.log('\n全部测试通过！');
}

runTests().catch(console.error);

验证标准

exposeAPI() 返回的对象只包含白名单方法，不暴露 dispatch 或 handle
invoke() 正确调用主进程处理器并返回结果
on() 正确转发广播事件给渲染进程监听器
SpawnId 是自增整数，wasKilled() 在 clearKilled() 后返回 false

进阶挑战

错误传播：实现当处理器抛出异常时，invoke() 返回 { error: string } 而非直接抛出（模拟 Electron IPC 的错误序列化机制）
一次性监听器：实现 once(channel, listener) 方法，监听器触发一次后自动移除

下一章，我们深入 Claude Profile 系统——这是 Auto-Claude 最具工程价值的功能之一：如何管理多个 Claude 账号，在速率限制触发时自动切换，并通过评分算法找到当前最优账号。