OpenBot 源码分析:Electron 桌面端为什么用起来流畅
AI 参与说明(Agent:Codex):本文由 Codex 核对固定提交、发布记录与上游性能测试,整理客户端调用链,并使用项目 humanizer-zh 编辑中文正文。执行入口为 Codex Desktop。
OpenBot 是一个在本机运行并管理多个 AI Agent 的工作台,桌面端用的是 Electron 45.3.0 + SolidJS 2.0.0。macOS 的系统窗口按钮和透明效果让它看起来像原生应用。交互上,窗口准备好绘制后才露出,长对话只挂载视口附近的历史行,连续输出的文字分批更新。本文以北京时间 2026 年 11 月 20 日的 main 提交 10442afd 为源码基线。当时最新的正式桌面发行版是 v0.74.0。依赖版本 · 固定提交 · v0.74.0 · 发行版与源码基线的差异
| 英文术语 | 中文名称 | 简要解释 |
|---|---|---|
| Main process | 主进程 | 管理 Electron 窗口、桌面能力和应用服务 |
| Renderer process | 渲染进程 | 运行界面代码,处理输入、布局和绘制 |
| Preload | 预加载脚本 | 在界面启动前建立一组受控的桌面 API |
| IPC | 进程间通信 | 在 Main process 和 Renderer process 之间传递请求与事件 |
| Delta | 增量 | 一条消息新到达的一小段文本 |
| Virtualization | 列表虚拟化 | 只为视口附近的列表项挂载 DOM,滚动时再换入其他项 |
桌面客户端用了什么方案
OpenBot runs its desktop UI in an Electron renderer and exposes desktop capabilities through a typed preload bridge. package.json 指向构建后的 out/main/start.js。electron-vite 分别构建 Main process、Preload 和 Renderer process,界面用 SolidJS。正式包从 openbot-app://app/index.html 加载本地界面。Main process 管理窗口与应用服务,Preload 用 contextBridge 暴露应用 API,packages/contracts 定义跨边界传递的类型。仓库里还有独立的 Expo React Native 客户端,Web 客户端则复用 SolidJS 控件和会话运行时接口,并通过已认证的 Host 连接收发数据。构建入口 · 正式包入口 · Preload bridge · 模块边界 · Web 客户端
在 macOS 上,BrowserWindow 隐藏系统标题栏,保留并定位系统的三色窗口按钮。开启透明窗口选项时,OpenBot 使用 Electron 的 under-window vibrancy。窗口以隐藏状态创建,等 ready-to-show 再显示,减少首次露出时看到空白界面的机会。这个时刻和工作区真正可操作的时刻应分开观察。当前代码在界面加载前仍等待基础应用服务初始化,之后才预热 Agent 数据库并异步启动本地 Agent backend。设置、全局搜索、Marketplace 等视图独立按需加载。窗口配置 · 窗口材质 · 启动顺序 · 加载后工作 · 按需视图 · Electron BrowserWindow
为什么翻长对话时仍然跟手
最新的历史记录和向上翻页都按 50 条消息读取。进入 ConversationTimeline 后,Virtualization 处理的是组装后的展示行,计数可能和消息条数不同。启用前,100 行以内直接渲染。超过 100 行后启用 TanStack Virtual,回落到 90 行或更少时才退出。这个阈值差让列表在临界点附近少切换模式。视口两端各多渲染 5 行,并复用标识不变的行对象,减少滚动时重新挂载 DOM 和传播更新的次数。最新一页 · 向上翻页 · 时间线渲染 · Virtualization 实现
正在看最新内容时,新回复可以继续把视口留在底部。翻到上方读旧消息时,界面保留当前位置,避免底部的回复增高把读者拉走。即使两次滚动花费的时间差不多,后一项行为也会影响体感。上游有覆盖短对话、长对话和频道的回归脚本,检查历史阅读位置和流式输出期间的滚动行为。滚动控制 · 滚动回归用例
一条流式回复如何出现在屏幕上
点下发送后,客户端先把带本地 ID 的待发消息放进会话,再异步提交。这条待发消息让发送操作立即有反馈,实际的发送结果随后更新。待发消息状态
以本地 Codex 为例,OpenBot 通过 stdio 启动 Codex App Server。模型的新文本先进入 OpenBot backend,随后用 IPC 将带会话修订号的 Delta 送到 Renderer process。回复能否连贯地出现在屏幕上,取决于存储、状态更新和文字呈现三处的节奏。Codex 进程启动 · 事件转发
flowchart TB
codex["Codex App Server"] -->|"stdio 通知"| buffer["OpenBot backend 合并 Delta"]
buffer -->|"批量写入 SQLite"| send["Main process 发送会话事件"]
send -->|"IPC 经 Preload"| update["SolidJS 会话状态按帧应用 Delta"]
update --> render["消息行更新、Markdown 分段解析与渐显"]
- backend 合并写入。
DeltaBuffer按线程、轮次和消息合并文本,通常由约 100 ms 的定时器统一刷写,累积中的单条消息达到 8 KiB 可提前刷写。定时批次可以把多个 Agent 的增量放入一次 SQLite 事务。写入成功后,才把带修订号的conversation-delta发出去。这样减少了碎片写入和事件数量,也给单个 Delta 增加了可能的等待时间,不能用这段定时器预测首字延迟。缓冲和写入 · 事件内容 · 事务变更记录 - Renderer process 把同一帧里的变化攒起来。 窗口可见时用
requestAnimationFrame调度,隐藏时用定时器。连续到达、修订号递增且属于同一 Agent 和消息的 Delta 可以合并。SolidJS 再把变更应用到对应消息行。这样,同一帧里收到两段文本,通常只需要让相关的响应式订阅消费一次合并后的值。帧调度 · 合并和状态更新 - 界面控制解析成本和可见节奏。
MarkdownMessageText尽量复用已经稳定的 Markdown 块,只重新解析仍在追加的尾部,遇到链接定义等情况会回退到完整解析。MessageRendering还有独立的文字渐显,默认以约 40 ms 为步进间隔,并按积压调整呈现速度。它按含空白的词边界推进,所以连续无空格的中文值得单独测一次。这层能解释字符为什么平稳出现,其计时独立于模型出字和实际帧率。Markdown 增量解析 · 文字渐显 · 词边界处理
上游测过什么
上游 PR #11651 用 fake Codex 让 96 个 Agent 同时输出,并打开一个有 2,000 条消息的频道。三次运行的中位数里,Main process 的事件循环 p99 延迟由 65.2 ms 降到 37.5 ms,窗口 p99 lag 由 159.6 ms 降到 64.7 ms。这批改动一起优化了 SQLite 事务、对象复用和布局测量。PR 还记录了升级 SolidJS 2.0 后的一次界面卡死,跑分同时检查了页面报错。这组数字说明高负载下减少重复工作有效,但无法从一次合并改动推算 SolidJS 单独贡献了多少,也无法据此推算具体设备上的体感。并发负载测试与变更细节
对照后续版本时,可以在支持桌面运行的环境,按上游指南准备好固定版本的开发依赖,再运行项目自带的聊天和并发场景。长对话场景会在 2,000 条消息里来回滚动,再切换 Agent。并发场景用 fake Codex 产生输出。先确认脚本完成目标场景,再在相同机器、刷新率和数据量下对比延迟。本文核对了脚本入口和场景定义,尚未在真机上重跑这些基准。开发指引 · 参数 · 长对话场景 · 并发场景
bun run dev:bench --scenario=s4-long-chat --runs=3
bun run dev:bench --scenario=s14-agents-100 --runs=3
迭代记录
| 更新日期 | 源码与发行基线 | 本次跟进 |
|---|---|---|
| 2026-11-20 | main 的 10442afd,正式版 v0.74.0 | 建立 Electron 窗口、聊天滚动和流式回复的源码基线。v0.74.0 还修了 Renderer process 崩溃后重载时的黑屏与草稿恢复。后续可分开观察冷启动到工作区可用、长对话滚动、中文流式文字和多 Agent 并发。 |
后续沿用这页记录发生变化的机制,保留原有 commit 链接,再补上新 tag 和对应 PR。对冷启动,优先看窗口可见与工作区可用之间的间隔。对流式聊天,可同时看输入排队延迟与 p99 lag,再结合性能轨迹判断开销落在 SQLite、IPC 还是布局和绘制。Releases · 重载修复 · Renderer process 计时