决策点： 对于每个功能，回答：

• "这需要主进程访问吗？"
• "所需的最小 IPC 接口是什么？"

步骤 3：IPC 设计

目标： 设计安全、类型安全的 IPC 通信。

思考框架：

• "主进程和渲染器之间流动什么数据？"
• "谁发起通信？"
• "两端需要什么验证？"

IPC 模式选择：

IPC 安全检查清单：

• 所有通道都有明确的名称
• 主进程处理器进行输入验证
• 不从渲染器输入执行任意代码
• 敏感操作需要用户确认
• 对昂贵操作进行速率限制

类型安全模式：

// 在 shared/ 中定义通道类型
interface IpcChannels {
  'file:open': { args: void; return: string | null };
  'file:save': { args: { path: string; content: string }; return: boolean };
}

步骤 4：预加载脚本设计

目标： 在隔离环境之间创建一个最小、安全的桥梁。

思考框架：

• "渲染器绝对需要的最小功能是什么？"
• "我是否暴露了超出必要的功能？"
• "每个暴露的函数都经过验证了吗？"

预加载设计原则：

1. 最小接口： 仅暴露绝对需要的功能
2. 不暴露原始 IPC： 包装 ipcRenderer，不要直接暴露
3. 类型定义： 为渲染器提供 TypeScript 类型
4. 单向绑定： 优先使用 invoke 而非 send/on 对

需要避免的反模式：

// 错误：暴露原始 ipcRenderer
contextBridge.exposeInMainWorld('electron', { ipcRenderer });

// 错误：任意通道执行
contextBridge.exposeInMainWorld('api', {
  send: (channel, data) => ipcRenderer.send(channel, data)
});

// 正确：显式、有限的 API
contextBridge.exposeInMainWorld('api', {
  openFile: () => ipcRenderer.invoke('dialog:openFile'),
  saveFile: (content: string) => ipcRenderer.invoke('file:save', content)
});

步骤 5：窗口管理策略

目标： 为应用程序设计合适的窗口管理。

思考框架：

• "此应用需要多少个窗口？"
• "窗口之间如何通信？"
• "窗口关闭时会发生什么？"

窗口模式：

窗口配置检查清单：

• 为每种窗口类型设置合适的 webPreferences
• 窗口状态持久化（位置、大小）
• 正确的关闭/退出行为（隐藏 vs 销毁）
• 深度链接 / 协议处理

步骤 6：数据持久化策略

目标： 设计安全、可靠的数据存储。

思考框架：

• "哪些数据需要持久化？"
• "这些数据的敏感性如何？"
• "数据是否需要跨设备同步？"

存储选项：

数据安全检查清单：

• 敏感数据在静态时加密
• 凭证存储在系统密钥链中，而非文件
• 备份/导出功能
• 更新时的数据迁移策略

步骤 7：打包与分发

目标： 配置可靠的跨平台分发。

思考框架：

• "目标平台是哪些？"
• "如何交付更新？"
• "需要哪些签名/公证？"

平台检查清单：

自动更新策略：

• electron-updater 配置
• 更新服务器（GitHub releases、S3 等）
• 关键更新的分阶段推出
• 回滚能力

步骤 8：测试策略

目标： 确保应用程序在所有平台上都可靠。

测试层级：

• 单元测试： 主进程中的业务逻辑
• 集成测试： IPC 通信
• 端到端测试： 使用 Spectron/Playwright 进行 UI 流程测试
• 平台测试： 针对所有目标平台的 CI 矩阵

测试检查清单：

• 隔离测试 IPC 处理器
• 测试预加载脚本的类型契约
• 关键用户流程的端到端测试
• 平台特定行为测试

使用方法

搭建新项目

bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh [project-name] [ui-framework] [package-manager]

参数：

• project-name - 项目名称（默认：my-electron-app）
• ui-framework - UI 框架：vanilla、react、svelte、vue（默认：vanilla）
• package-manager - 包管理器：pnpm、npm、yarn（默认：pnpm）

示例：

bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh my-app
bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh my-app react
bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh my-app svelte pnpm

安全默认设置：

• nodeIntegration: false
• contextIsolation: true
• sandbox: true

文档资源

官方文档：

• Electron: https://www.electronjs.org/docs/latest/
• Electron Forge: https://www.electronforge.io/
• electron-builder: https://www.electron.build/

项目结构

src/
├── main/
│   ├── main.ts              # 主进程入口
│   ├── ipc/                  # IPC 处理器
│   │   └── file-handlers.ts
│   ├── services/             # 后端服务
│   │   └── database.ts
│   └── menu.ts               # 应用程序菜单
├── preload/
│   └── preload.ts            # 上下文桥接
├── renderer/                 # UI (React/Svelte/Vue)
│   ├── App.tsx
│   └── components/
└── shared/
    └── types.ts              # 共享类型定义

安全配置

BrowserWindow 设置

// main.ts - 安全配置
const mainWindow = new BrowserWindow({
  width: 1200,
  height: 800,
  webPreferences: {
    nodeIntegration: false,      // 禁用 Node.js
    contextIsolation: true,      // 启用上下文隔离
    sandbox: true,               // 沙盒模式
    preload: path.join(__dirname, 'preload.js'),
    webSecurity: true,           // 强制执行同源策略
  }
});

预加载脚本模式

// preload.ts - 安全的 API 暴露
import { contextBridge, ipcRenderer } from 'electron';

contextBridge.exposeInMainWorld('electronAPI', {
  // 单向：渲染器 → 主进程
  saveFile: (content: string) =>
    ipcRenderer.invoke('file:save', content),

  // 单向：主进程 → 渲染器
  onUpdateAvailable: (callback: (version: string) => void) =>
    ipcRenderer.on('update-available', (_, version) => callback(version)),

  // 请求-响应模式
  openFile: () => ipcRenderer.invoke('dialog:openFile'),
});

// 渲染器的类型声明
declare global {
  interface Window {
    electronAPI: {
      saveFile: (content: string) => Promise<boolean>;
      onUpdateAvailable: (callback: (version: string) => void) => void;
      openFile: () => Promise<string | null>;
    }
  }
}

主进程处理器

// main/ipc/file-handlers.ts
import { ipcMain, dialog } from 'electron';
import { readFile, writeFile } from 'fs/promises';

export function registerFileHandlers() {
  ipcMain.handle('dialog:openFile', async () => {
    const { canceled, filePaths } = await dialog.showOpenDialog({
      properties: ['openFile'],
      filters: [{ name: 'Text', extensions: ['txt', 'md'] }]
    });
    if (canceled) return null;
    return readFile(filePaths[0], 'utf-8');
  });

  ipcMain.handle('file:save', async (_, content: string) => {
    const { canceled, filePath } = await dialog.showSaveDialog({});
    if (canceled || !filePath) return false;
    await writeFile(filePath, content);
    return true;
  });
}

IPC 通信模式

模式 1：Invoke（请求-响应）

// 渲染器
const data = await window.electronAPI.fetchData(id);

// 主进程
ipcMain.handle('fetch-data', async (event, id) => {
  return await database.get(id);
});

模式 2：Send/On（发送即忘）

// 主进程 → 渲染器
mainWindow.webContents.send('notification', message);

// 渲染器
window.electronAPI.onNotification((msg) => showToast(msg));

模式 3：双向事件

// 渲染器发送，等待主进程响应
const result = await window.electronAPI.processFile(path);

打包配置

Electron Forge

{
  "config": {
    "forge": {
      "packagerConfig": {
        "asar": true,
        "icon": "./assets/icon"
      },
      "makers": [
        { "name": "@electron-forge/maker-squirrel" },
        { "name": "@electron-forge/maker-dmg" },
        { "name": "@electron-forge/maker-deb" }
      ]
    }
  }
}

向用户呈现结果

提供 Electron 解决方案时：

• 始终遵循安全最佳实践
• 提供完整的 IPC 通信示例
• 考虑跨平台兼容性
• 包含 API 的 TypeScript 类型
• 注意 Electron 版本差异

故障排除

"require is not defined"

• nodeIntegration 已正确禁用
• 使用带有 contextBridge 的预加载脚本

"Cannot access window.electronAPI"

• 检查预加载脚本路径是否正确
• 验证 contextIsolation 是否为 true
• 确保调用了 contextBridge.exposeInMainWorld

"IPC message not received"

• 验证通道名称是否完全匹配
• 检查处理器是否在窗口加载前注册
• 对异步响应使用 invoke

每周安装数

75

仓库

tomlord1122/tomtom-skill

首次出现

Jan 22, 2026

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

opencode68

gemini-cli62

github-copilot61

codex60

cursor56

claude-code51

1. Least Privilege: Renderer should have minimal capabilities
2. Defense in Depth: Multiple layers of protection
3. Explicit Communication: All IPC channels are explicit and validated

Architecture Decision Matrix:

Decision Point: For each feature, answer:

• "Does this need Main process access?"
• "What is the minimal IPC surface needed?"

Step 3: IPC Design

Goal: Design safe, type-safe IPC communication.

Thinking Framework:

• "What data flows between Main and Renderer?"
• "Who initiates the communication?"
• "What validation is needed on each end?"

IPC Pattern Selection:

IPC Security Checklist:

• All channels have explicit names
• Input validation on Main process handlers
• No arbitrary code execution from renderer input
• Sensitive operations require user confirmation
• Rate limiting for expensive operations

Type Safety Pattern:

// Define channel types in shared/
interface IpcChannels {
  'file:open': { args: void; return: string | null };
  'file:save': { args: { path: string; content: string }; return: boolean };
}

Step 4: Preload Script Design

Goal: Create a minimal, secure bridge between worlds.

Thinking Framework:

• "What is the absolute minimum the renderer needs?"
• "Am I exposing more than necessary?"
• "Is each exposed function validated?"

Preload Design Principles:

1. Minimal Surface: Only expose what's absolutely needed
2. No Raw IPC: Wrap ipcRenderer, don't expose directly
3. Type Definitions: Provide TypeScript types for renderer
4. One-Way Binding: Prefer invoke over send/on pairs

Anti-Patterns to Avoid:

// BAD: Exposes raw ipcRenderer
contextBridge.exposeInMainWorld('electron', { ipcRenderer });

// BAD: Arbitrary channel execution
contextBridge.exposeInMainWorld('api', {
  send: (channel, data) => ipcRenderer.send(channel, data)
});

// GOOD: Explicit, limited API
contextBridge.exposeInMainWorld('api', {
  openFile: () => ipcRenderer.invoke('dialog:openFile'),
  saveFile: (content: string) => ipcRenderer.invoke('file:save', content)
});

Step 5: Window Management Strategy

Goal: Design appropriate window management for the application.

Thinking Framework:

• "How many windows does this app need?"
• "How do windows communicate?"
• "What happens when windows are closed?"

Window Patterns:

Window Configuration Checklist:

• Appropriate webPreferences for each window type
• Window state persistence (position, size)
• Proper close/quit behavior (hide vs destroy)
• Deep linking / protocol handling

Step 6: Data Persistence Strategy

Goal: Design secure, reliable data storage.

Thinking Framework:

• "What data needs to persist?"
• "How sensitive is this data?"
• "Does data need to sync across devices?"

Storage Options:

Data Security Checklist:

• Sensitive data encrypted at rest
• Credentials in system keychain, not files
• Backup/export functionality
• Data migration strategy for updates

Step 7: Packaging and Distribution

Goal: Configure reliable cross-platform distribution.

Thinking Framework:

• "Which platforms are targets?"
• "How will updates be delivered?"
• "What signing/notarization is needed?"

Platform Checklist:

Auto-Update Strategy:

• electron-updater configuration
• Update server (GitHub releases, S3, etc.)
• Staged rollouts for critical updates
• Rollback capability

Step 8: Testing Strategy

Goal: Ensure the application is reliable across platforms.

Testing Layers:

• Unit Tests: Business logic in Main process
• Integration Tests: IPC communication
• E2E Tests: Spectron/Playwright for UI flows
• Platform Tests: CI matrix for all target platforms

Testing Checklist:

• Test IPC handlers in isolation
• Test preload script type contracts
• E2E tests for critical user flows
• Platform-specific behavior tests

Usage

Scaffold New Project

bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh [project-name] [ui-framework] [package-manager]

Arguments:

• project-name - Name of the project (default: my-electron-app)
• ui-framework - UI framework: vanilla, react, svelte, vue (default: vanilla)
• package-manager - Package manager: pnpm, npm, yarn (default: pnpm)

Examples:

bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh my-app
bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh my-app react
bash /mnt/skills/user/electron-architect/scripts/scaffold-project.sh my-app svelte pnpm

Security defaults:

• nodeIntegration: false
• contextIsolation: true
• sandbox: true

Documentation Resources

Official Documentation:

• Electron: https://www.electronjs.org/docs/latest/
• Electron Forge: https://www.electronforge.io/
• electron-builder: https://www.electron.build/

Project Structure

src/
├── main/
│   ├── main.ts              # Main process entry
│   ├── ipc/                  # IPC handlers
│   │   └── file-handlers.ts
│   ├── services/             # Backend services
│   │   └── database.ts
│   └── menu.ts               # Application menu
├── preload/
│   └── preload.ts            # Context bridge
├── renderer/                 # UI (React/Svelte/Vue)
│   ├── App.tsx
│   └── components/
└── shared/
    └── types.ts              # Shared type definitions

Security Configuration

BrowserWindow Settings

// main.ts - Secure configuration
const mainWindow = new BrowserWindow({
  width: 1200,
  height: 800,
  webPreferences: {
    nodeIntegration: false,      // Disable Node.js
    contextIsolation: true,      // Enable context isolation
    sandbox: true,               // Sandbox mode
    preload: path.join(__dirname, 'preload.js'),
    webSecurity: true,           // Enforce same-origin
  }
});

Preload Script Pattern

// preload.ts - Safe API exposure
import { contextBridge, ipcRenderer } from 'electron';

contextBridge.exposeInMainWorld('electronAPI', {
  // One-way: Renderer → Main
  saveFile: (content: string) =>
    ipcRenderer.invoke('file:save', content),

  // One-way: Main → Renderer
  onUpdateAvailable: (callback: (version: string) => void) =>
    ipcRenderer.on('update-available', (_, version) => callback(version)),

  // Request-response pattern
  openFile: () => ipcRenderer.invoke('dialog:openFile'),
});

// Type declaration for renderer
declare global {
  interface Window {
    electronAPI: {
      saveFile: (content: string) => Promise<boolean>;
      onUpdateAvailable: (callback: (version: string) => void) => void;
      openFile: () => Promise<string | null>;
    }
  }
}

Main Process Handlers

// main/ipc/file-handlers.ts
import { ipcMain, dialog } from 'electron';
import { readFile, writeFile } from 'fs/promises';

export function registerFileHandlers() {
  ipcMain.handle('dialog:openFile', async () => {
    const { canceled, filePaths } = await dialog.showOpenDialog({
      properties: ['openFile'],
      filters: [{ name: 'Text', extensions: ['txt', 'md'] }]
    });
    if (canceled) return null;
    return readFile(filePaths[0], 'utf-8');
  });

  ipcMain.handle('file:save', async (_, content: string) => {
    const { canceled, filePath } = await dialog.showSaveDialog({});
    if (canceled || !filePath) return false;
    await writeFile(filePath, content);
    return true;
  });
}

IPC Communication Patterns

Pattern 1: Invoke (Request-Response)

// Renderer
const data = await window.electronAPI.fetchData(id);

// Main
ipcMain.handle('fetch-data', async (event, id) => {
  return await database.get(id);
});

Pattern 2: Send/On (Fire-and-Forget)

// Main → Renderer
mainWindow.webContents.send('notification', message);

// Renderer
window.electronAPI.onNotification((msg) => showToast(msg));

Pattern 3: Two-Way Events

// Renderer sends, awaits Main response
const result = await window.electronAPI.processFile(path);

Packaging Configuration

Electron Forge

{
  "config": {
    "forge": {
      "packagerConfig": {
        "asar": true,
        "icon": "./assets/icon"
      },
      "makers": [
        { "name": "@electron-forge/maker-squirrel" },
        { "name": "@electron-forge/maker-dmg" },
        { "name": "@electron-forge/maker-deb" }
      ]
    }
  }
}

Present Results to User

When providing Electron solutions:

• Always follow security best practices
• Provide complete IPC communication examples
• Consider cross-platform compatibility
• Include TypeScript types for the API
• Note Electron version differences

Troubleshooting

"require is not defined"

• nodeIntegration is correctly disabled
• Use preload script with contextBridge

"Cannot access window.electronAPI"

• Check preload script path is correct
• Verify contextIsolation is true
• Ensure contextBridge.exposeInMainWorld is called

"IPC message not received"

• Verify channel names match exactly
• Check if handler is registered before window loads
• Use invoke for async responses

Weekly Installs

75

Repository

tomlord1122/tomtom-skill

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode68

gemini-cli62

github-copilot61

codex60

cursor56

claude-code51