第 10 章：Electron 桌面应用与本地运行时
本章定位
Electron 是前端构建桌面工具和本地 Agent Runtime 的重要路径。本章重点不是打包，而是主进程、渲染进程、preload 和 contextBridge 之间的安全边界。
必须掌握清单
必须掌握
能区分主进程、渲染进程和 preload 的职责。
相关答案： 主进程管理窗口、应用生命周期和系统能力；渲染进程负责网页 UI，应按不可信页面对待；preload 在隔离环境中把经过约束的能力桥接给渲染进程。文件和进程操作不应直接放进渲染层。
具体例子： React 页面请求打开文件，preload 暴露
openDocument()，主进程显示系统对话框并读取文件；页面拿不到任意fs或child_process对象。能解释
contextBridge的最小暴露原则。相关答案： 只暴露完成具体业务动作所需的窄接口，并在 preload 和主进程验证参数；不能把
ipcRenderer.send、Node 模块或可任意指定通道的方法原样暴露，否则被注入的页面脚本可扩大为系统权限。具体例子： 暴露
window.desktop.saveText({ name, content })，而不是window.desktop.invoke(channel, args)；前者可限制文件名、大小和保存目录，后者允许调用未授权 IPC。能设计可靠的 IPC 和消息生命周期。
相关答案： IPC 请求要定义通道、参数、结果和错误 schema，并使用关联 ID 处理响应；窗口销毁、超时和取消时必须释放监听器。持续事件还需要订阅与取消订阅成对出现。
具体例子： 长任务返回
taskId，进度事件携带相同 ID；渲染窗口关闭时 preload 调用 unsubscribe，主进程发现没有消费者后取消任务，避免向已销毁 WebContents 发送消息。能理解本地文件工具的执行边界。
相关答案： 本地工具必须限制允许目录、解析真实路径、防止路径穿越与符号链接逃逸，并区分只读和写入权限。模型建议不能等同于执行授权，敏感写入仍需策略或用户确认。
具体例子： “读取项目文件”只能访问用户选择的工作区，
../路径经规范化后若越界就拒绝；覆盖配置文件前显示目标绝对路径和变更摘要并请求确认。能处理崩溃、退出和会话恢复。
相关答案： 持久化数据应采用原子写入或事务，运行中状态要能从稳定日志重建；退出时停止新任务、取消或保存进行中任务，崩溃后区分可恢复会话和已经失效的系统资源。
具体例子： 消息事件先追加到临时文件并原子替换索引；应用重启后回放已落盘事件，把未完成工具调用标记为“执行中断”，而不是误显示成功。
原理讲解
渲染进程不应直接获得 Node.js 能力。preload 使用 contextBridge 暴露一组有限的、明确的方法，主进程处理文件、进程和系统调用。这样渲染进程被攻击时，也不能随意读写文件系统。
IPC 需要成对处理请求和响应，以及发送方或接收方销毁后的清理。本地 Agent 执行文件工具时，用户确认和执行必须分离，危险操作还要有白名单和沙箱。
代码示例或模板
import { contextBridge, ipcRenderer } from "electron";
contextBridge.exposeInMainWorld("agentDesktop", {
readFile(path: string) {
return ipcRenderer.invoke("file:read", path);
},
onToolResult(listener: (event: unknown, result: unknown) => void) {
const handler = (_: unknown, result: unknown) => listener(_, result);
ipcRenderer.on("tool:result", handler);
return () => ipcRenderer.off("tool:result", handler);
},
});这个 preload 只暴露读取文件和工具结果两个能力，实际项目还需要参数校验、权限确认和错误处理。
AI Agent 概念对照
- 主进程对应本地 Agent Runtime。
- 渲染进程对应工具 UI。
contextBridge对应最小权限暴露。- 本地文件工具对应 sandbox 和审批。
面试追问
1. 为什么不能直接给渲染进程开 nodeIntegration？
查看深度解析
标准回答： 渲染进程处理 HTML、Markdown、第三方依赖和可能不可信内容，一旦发生 XSS，开启 Node 集成会把脚本执行直接升级为文件、进程和系统权限。应关闭 Node 集成、启用 context isolation 与 sandbox，并通过窄 IPC 暴露能力。
原理展开： Electron 把浏览器攻击面和桌面权限放在同一应用中，必须用进程与能力边界降低影响；加载远程内容时风险更高。
工程示例： 模型生成 Markdown 中的恶意脚本在普通网页可能窃取页面数据，若 renderer 可用 child_process，就可能直接执行本地命令。
常见误区： 认为内容是“自己的页面”就可信，忽略依赖、用户文件和远程数据都可能成为注入入口。
继续追问： 只设置 nodeIntegration: false 是否足够？
回答方向： 不足够；还要启用 contextIsolation 和 sandbox、限制导航与新窗口、校验 IPC 参数并保持 Electron 更新。
2. preload 和 contextBridge 的安全边界是什么？
查看深度解析
标准回答： preload 位于受信任桥接层，可接触有限 Node/Electron 能力；contextBridge 只负责跨隔离上下文暴露 API，并不会自动让 API 安全。必须一条业务动作一个方法，过滤参数，不能暴露通用 send/invoke 或整个 ipcRenderer。
原理展开： 跨桥数据受可序列化类型限制，函数由代理调用。最终权限校验仍应在主进程执行，因为 renderer 能调用所有已暴露方法。
工程示例： 暴露 loadPreferences()，而不是 invoke(channel, args)；主进程只接受固定通道并校验 payload schema。
常见误区： 把 contextIsolation: true 当作安全完成项，却桥接 fs、任意路径读写或原始 IPC。
继续追问： preload 回调订阅如何安全暴露？
回答方向： 丢弃原始 IPC event，只传校验后的数据，返回 unsubscribe，并在窗口销毁时清理监听器。
3. 本地文件工具如何把用户确认和执行隔离开？
查看深度解析
标准回答： 先由规划阶段生成不可变调用意图，包含规范化目标、动作、风险和内容摘要；权限层据此返回 allow、deny 或 ask。用户批准后签发绑定该调用 ID 和参数哈希的一次性授权，执行器不能接受模型临时替换参数。
原理展开： 确认与执行分离能防止 TOCTOU 和“展示一个路径、执行另一个路径”。执行前仍要重新解析真实路径、检查工作区边界和符号链接。
工程示例： 覆盖配置前展示绝对路径与 diff，批准 token 绑定该 diff；文件变化后参数哈希失效，必须重新确认。
常见误区： 使用永久“以后都允许”覆盖任意写入，或确认弹窗只显示工具名不显示影响对象。
继续追问： 批量文件操作怎么确认？
回答方向： 展示确定的文件集合、数量和变更摘要，授权绑定清单；范围变化或新增文件时重新审批。
4. 主进程崩溃后如何恢复 Agent 会话？
查看深度解析
标准回答： 会话事实要在运行中追加到持久化日志或事务存储，UI 快照可以重建。重启后回放已提交事件，未收到最终事件的请求或工具调用标记为 interrupted，再根据工具幂等性决定查询、重试或人工确认。
原理展开： 内存状态和 renderer UI 不是恢复依据；写入需要原子性、事件版本和 checkpoint。文件句柄、子进程等外部资源不能假装恢复。
工程示例： tool_started 已落盘但没有 tool_finished，重启后显示“执行中断”；查询型工具可重新执行，写入型工具先用 idempotency key 查询外部结果。
常见误区： 自动重放所有未完成工具，可能重复扣款或覆盖文件；或只恢复聊天文本丢失工具状态。
继续追问： 日志写到一半崩溃怎么办？
回答方向： 使用事务数据库或长度/校验和帧，启动时截断最后不完整记录；定期 checkpoint 但保留可验证事件链。
实践任务
实现一个 Electron 壳，封装本地文件工具调用，使用 preload 暴露最小 API，并在前端展示工具状态。
验收标准
- 渲染进程没有直接访问 Node.js 能力。
- 工具调用有明确的用户确认或白名单。
- 能说明 IPC 清理和错误回传。