我是安徽最忧郁程序员无隅前言Agent Runtime 已经能调用工具、生成回答为什么用户拿到它时仍觉得“产品没做完”因为用户需要的还有稳定的交互入口、可恢复的会话、能解释失败的界面以及离开开发环境后仍能运行的安装包。本文以 Folio 为案例沿着一次 Agent 运行的数据路径拆解 TypeScript Electron 如何承载这些能力。读完后你应能判断一个桌面 Agent 项目的进程职责、IPC 契约、状态归属和发布检查是否清楚。一、先看全局Runtime 如何进入桌面产品假设我们已经有一个函数输入用户问题调用模型和工具最后返回答案。它解决的是“Agent 能否完成任务”。桌面产品还要回答另一组问题窗口关闭后会话在哪执行到一半如何展示Runtime 崩溃时用户看到什么打包后资源路径还能否找到Folio 的主线可以概括为Renderer 发起命令并显示状态Preload 限定可调用的接口Main 托管 AgentKernelHostKernel 管理会话与运行底层适配器与 Pi Runtime 通信。先看这张图重点观察哪一层拥有真实的会话和运行记录。这里有一个容易说错的概念。Electron 文档主要区分Main 进程和 Renderer 进程Preload 是加载在 Renderer 侧、运行于隔离上下文的脚本并非独立的第三个操作系统进程。为了讨论职责我们仍可以把 Main、Preload、Renderer 称为“三层”但不宜把它们说成“三个进程”。Electron 的进程模型和上下文隔离说明给出了这条边界。在 Folio 中apps/electron/src/main/index.ts创建窗口时开启contextIsolation和sandbox关闭nodeIntegration并加载 Preload。Preload 通过contextBridge.exposeInMainWorld(electronAPI, electronAPI)暴露一组具体方法。这样界面只能调用被允许的操作例如创建会话、启动运行、获取消息文件系统、凭证和运行时进程留在 Main 一侧。Electron 官方也建议通过受限桥接 API 处理跨进程通信而不是把整个ipcRenderer暴露给页面见 IPC 指南与安全指南。状态归属是这张图的核心。Folio 的AgentKernel组合SessionManager、RunManager和 Runtime 适配器。Renderer 中的 Jotai atoms 只保存当前窗口需要显示的会话列表、消息和运行投影。应用重启后UI 可以重新从 Kernel 读取数据界面缓存本身不承担持久化事实源的职责。二、跨进程契约一次命令与一串事件桌面 Agent 的一次执行其实包含两种时间尺度用户点击“运行”后需要立即知道命令有没有被接受随后几秒或更长时间里还会陆续收到文本增量、工具调用和最终状态。把两者塞进同一种返回值会让界面难以区分“启动失败”和“执行中失败”。Folio 将通道命名为domain:action例如sessions:create、runs:start。Preload 中的startRun调用ipcRenderer.invoke(runs:start, input)Main 用ipcMain.handle(runs:start, ...)接收。这一对invoke/handle处理的是请求与响应适合创建会话、读取数据、启动或取消运行。命名中的 domain 方便读者从通道名判断职责它是项目约定不是 Electron 的强制语法。业务命令的响应被包成IpcResultT。下面是依据 Folio 类型整理的最小形式typeIpcResultT|{ok:true;data:T}|{ok:false;error:{code:string;message:string;action?:string}};这层信封让 UI 不必猜测返回值究竟是数据、空值还是异常。ok: false时code便于区分参数错误、运行时不可用等原因message供界面展示action可以提供下一步操作。Folio 的toIpcResult会捕获错误并转成这一结构不过窗口最小化等少数窗口控制通道直接返回结果因此“所有 IPC 响应都使用信封”是业务契约的概括不能机械地套到每个通道。启动命令被接受后持续发生的事改走事件推送。AgentKernelHost.attach()订阅 Kernel 事件通过window.webContents.send(agent:event, event)发给窗口Preload 只开放onAgentEvent(callback)并返回取消订阅函数Renderer 的KernelBridge再把事件送入 Jotai reducer。Folio 同时还有agent:stream协议通道用于按运行记录事件序列。下图把两条通路并排画出上方回答“命令有没有启动”下方回答“运行现在发生了什么”。TypeScript 类型只约束编译时调用IPC 消息到达 Main 时仍应按外部输入检查。Folio 的处理函数接收unknownstartRun()先要求对象结构再检查会话 ID、内容和工作区上下文等字段。比如界面传来的activeView只有在属于允许的视图值时才会进入 Runtime。Preload 的白名单限制“能调用什么”Main 的重验证限制“传来的内容是否合法”这两个边界解决不同的问题。Electron 官方的安全指南还要求校验 IPC 消息的发送方尤其在应用加载远程内容或存在多个窗口时应把发送方校验纳入设计。三、运行与持久化Main 为什么要持有 Kernel如果把 Agent Runtime 放进某个 React 组件组件卸载、窗口刷新或界面异常就可能牵连执行状态。Folio 让AgentKernelHost驻留 Main并在启动时创建AgentKernel。它负责连接会话、运行、模型、工具、凭证和各类产品服务窗口通过 IPC 请求它而不直接拥有它。一次运行可以沿着这条路径理解Renderer 通过 Preload 发出runs:startMain 校验输入并交给AgentKernelHost.startRun()。Kernel 的RunManager管理运行生命周期Runtime 适配器执行任务Pi 适配器通过子进程的 JSONL/stdio 通道与底层 Runtime 交互。Kernel 发出运行和消息事件Main 将它们推送到 RendererUI 更新当前投影。会话、消息、运行记录由仓储写入本地存储。窗口重开后kernel:hydrate和读取消息的命令重建界面。这里的“Main 持有”不是说所有逻辑都堆进一个文件。它说的是生命周期与权限归属谁创建 Kernel谁负责进程退出时释放资源谁有权接触凭证和磁盘谁决定一个运行最终是完成、失败还是取消。Folio 的代码把这些职责分到AgentKernelHost、AgentKernel、SessionManager、RunManager与 Runtime 适配器Main 作为组合入口。存储层也体现同一个原则。JsonFileStore写 JSON 时先在目标目录创建独立临时文件写完后再重命名到目标文件SessionRepository管会话索引消息与运行记录有各自仓储。对调用者来说业务代码依赖“列出、读取、写入会话”这样的仓储操作而不需要每次自己拼文件名。临时文件加替换能降低读到半份 JSON 的风险但它不等于跨多个文件的数据库事务。如果未来需要复杂查询或多记录原子更新仓储边界也为更换存储实现留出位置。四、用户能感知的产品状态别让失败变成沉默底层有running、failed等状态还不足以构成产品体验。用户看到的是页面上的反馈有没有开始目前完成到哪一步数据显示不全时是否仍可用信息是否过期下一步能做什么可以用六类状态审视一个页面但它们不是必须建成六个独立组件状态用户需要知道的事适合呈现的内容Loading请求仍在进行进度或等待提示避免把暂时无数据误判为空结果Empty请求成功但确实没有内容空结果原因与可执行的首次操作Partial有部分结果仍存在缺口已有内容、缺失范围及影响Stale有旧数据当前性不足数据时间与刷新入口Error本次操作失败可理解的原因必要时给出详情Retry用户可继续处理明确的重试对象与诊断入口Folio 中可见几处具体做法。研究报告把runStatus partial与全部完成分开显示避免把部分结果包装成完整报告。研究证据区还显示数据获取时间供读者判断新鲜度。Agent 面板在 Runtime 基础设施失败时显示独立提示区提供“重试”和“打开诊断”操作而不是把系统错误伪装成普通助手回答。这里的状态表是从这些实现抽象出的设计检查表并不表示 Folio 已经在每个页面完整实现了六种状态。为什么这件事与 Agent 特别相关因为 Agent 的失败点比普通表单多模型服务、工具、子进程、网络、数据源都可能只完成一部分工作。产品需要保留“已完成”和“未完成”的边界用户才知道应该相信哪部分结果、是否继续等待或重试。界面可以简洁但不能用一个空白区域替代状态说明。五、工程落地组织代码、诊断和发布读 Folio 的代码建议按一次运行的调用路径前进而不是先打开最大的文件从头看到尾阅读顺序文件或目录要回答的问题1apps/electron/src/preload/index.tsRenderer 被允许调用哪些能力2apps/electron/src/main/index.ts哪个 IPC 通道接收命令窗口安全设置是什么3apps/electron/src/main/kernelHost.ts输入如何校验Kernel 如何创建、订阅和释放4packages/shared/src/kernel/会话与运行的事实源在哪里5packages/shared/src/storage/哪些数据落盘如何写入6packages/ui/src/components/kernel/KernelBridge.tsx与packages/ui/src/atoms/事件如何变成屏幕状态这一顺序还能帮助你定位问题。如果命令根本没到 Main先查 Preload 与通道名如果命令成功却没有增量显示查事件订阅和 UI reducer如果重启后数据丢失查 Kernel 与仓储如果开发环境正常、安装包异常查资源定位和打包清单。定位时始终问“数据最后一次被正确看见在哪一层”打包与发布也要沿这条边界检查。Folio 的 Electron 包脚本分别构建 Renderer、Preload、Main 和扩展然后交给electron-builder打包配置还会把技能与扩展资源放进应用。项目的发布门禁文档列了类型检查、构建、真实 Electron E2E、打包应用冒烟测试和全新安装流程。其含义不是“测试越多越好”而是验证用户拿到安装包后能否在没有源码仓库和开发环境的机器状态下完成关键路径。本文只核对了这些脚本与文档的存在没有运行打包或发布测试因此不把它们写成已通过的结果。回到最初的问题前三板斧让 Agent 有材料、能力和可评测的运行逻辑第四板斧让这些逻辑拥有稳定的进程边界、可恢复的数据、可解释的界面状态和可交付的安装形态。学 Folio 的价值不是照搬每个模块而是学会追踪一条命令从用户动作到 Runtime、再从事件回到用户界面的完整闭环。参考资料Electron 进程模型 · Electron IPC 指南 · Electron 上下文隔离 · Electron 安全指南。Folio 案例依据用户提供的“第四板斧”课程摘录及本文写作时检视的项目源码。