Lunel PTY渲染管线揭秘:24fps增量帧同步从wezterm到手机屏幕的完整实现

原创2026-10-14 16:26:541,898 阅读

Lunel PTY渲染管线揭秘:24fps增量帧同步从wezterm到手机屏幕的完整实现

Lunel 是一个 AI 驱动的手机 IDE(AI powered mobile IDE and cloud development platform),让你在手机上写代码、在自己的电脑上执行。它内置的终端模拟器背后,是一条基于 wezterm 引擎的 PTY 渲染管线:Rust 进程负责真实伪终端与屏幕状态计算,再以 24fps 增量帧同步 的方式把"只有变化的行"推送到手机屏幕。本文完整拆解这条管线,从 Rust 端的 wezterm 到 React Native 渲染,带你看清每一帧是怎么诞生的。

Lunel 移动 IDE 应用图标:终端渲染与云端开发平台

一、管线全景:一条帧的旅程

先建立整体心智模型。从你敲下键盘到手机屏幕亮起来,数据经过四段接力:

手机键盘 ──> React Native 应用 ──> Manager/Proxy 中继 ──> lunel-cli
                                                        │ 启动
                                                        ▼
                              lunel-pty (Rust) ── wezterm Terminal 状态机
                              24fps 增量帧 ── JSON 行协议 ── WebSocket ──> 手机屏幕

各模块在仓库中的位置:

模块 路径 职责
PTY 引擎 pty/src/ Rust 二进制,真实 PTY + wezterm 状态机 + 增量帧
协议定义 pty/src/protocol.rs stdin 命令 / stdout 事件的 JSON 行协议
CLI 桥接 cli/src/index.ts 启动 PTY 进程、解析事件、转发 WebSocket
前端 Hook app/hooks/useTerminal.ts 合并增量行、维护屏幕二维缓冲
渲染面板 app/plugins/core/terminal/Panel.tsx Span 合并 + Skia Canvas 绘制

二、服务端:lunel-pty 与 wezterm 状态机

2.1 真实 PTY + wezterm 屏幕模型

Lunel 没有自研终端解析器,而是直接复用 wezterm 的内部库。在 pty/Cargo.toml 中可以看到依赖 wezterm-term 与 wezterm-surface,配合 portable-pty 打开真实伪终端。

会话初始化在 pty/src/session.rs 中完成:

  • 用 portable_pty 打开 PTY,以 TERM=xterm-256color、COLORTERM=truecolor 拉起 shell;
  • 构造 wezterm 的 Terminal 状态机,滚动缓冲区固定为 1000 行(session.rs 的 scrollback_size);
  • 子进程退出码、dirty 标记、exit 标记都以原子变量跨线程共享。

2.2 JSON 行协议:stdin 进命令,stdout 出事件

pty/src/main.rs 的主线程只做一件事:从 stdin 逐行读取 JSON 命令。命令集非常精简(定义在 protocol.rs):

命令 作用
spawn 创建终端会话(id / shell / cols / rows)
write 向 PTY 写入用户输入
resize 调整行列并触发全量重绘
kill 终止会话
scroll 修改回滚偏移,立即唤醒渲染线程

反向的 stdout 输出四类事件:spawned、state、exit、error。其中 state 事件(protocol.rs)就是一帧画面:cells 是"行号 → 单元格数组"的哈希表,附带光标位置、鼠标模式、标题、scrollback 长度等元信息。这种"每行一个 JSON"的极简协议,让 CLI 端用 readline 就能可靠解析。

三、24fps 增量帧同步:核心机制

3.1 三线程协作:读、渲、派

每个会话有一个独立的读线程(session.rs),职责是:

  1. 从 PTY master 端循环读取字节(64KB 缓冲);
  2. 喂给 wezterm 状态机的 advance_bytes()——ANSI 转义序列在这里被解析为屏幕状态;
  3. 置位 dirty 原子标记,并通过 Condvar 唤醒渲染线程。

全局只有一个渲染线程(main.rs),它循环做三件事:等待通知或 100ms 空闲超时(用于检测进程退出);限速到 42ms/帧(min_frame = Duration::from_millis(42),即约 24 FPS,见 main.rs#L49);遍历所有会话,谁的 dirty 被置位,就对谁调用 snapshot() 并发出一帧。

💡 这里有个精妙的取舍:终端输出往往成突发(比如 ls 一口气刷 200 行),如果每读一块就发一帧,手机端会被瞬间打爆。42ms 的帧间隔天然地把突发输出"合并"进同一帧,而 Condvar + dirty 又保证空闲时零 CPU 空转。

3.2 行级 diff:一帧只发变化的行

增量同步的核心在 snapshot()(session.rs):

  1. 每帧先快照当前可视区的每一行,转成 CellJson(字符 + fg 色 + bg 色 + 属性位);
  2. 与 prev_cells 中上一帧缓存的每行做整行比较;
  3. 只有发生变化的行才会进入 cells 哈希表随帧发出;
  4. 顺带做标题 diff——标题没变就不带 title 字段。

这意味着:光标每闪烁、每移动一格,一帧可能就只含 1~2 行数据。配合 24fps 上限,带宽占用几乎可以忽略,这正是手机端流畅的关键。

3.3 全量回退:resize 与 scroll 的边界处理

增量同步有两个必须"退化为全量帧"的场景,代码中都做了显式处理:

  • resize:JS 端会从零重建缓冲区,所以 resize() 直接清空 prev_cells,下一帧发全部行(session.rs#L276-L280);
  • scroll 回滚:视图窗口整体平移,所有行都"变了",snapshot() 在 offset > 0 时同样清空 prev_cells 强制全量帧,同时隐藏光标(session.rs#L356-L359)。

另外,回滚视图的物理行号换算 phys_row = viewport_start - scroll_offset + row(session.rs#L361-L374)决定了手机上的滚动条为什么能精确对应 1000 行回滚缓冲。

四、客户端:从 WebSocket 到手机屏幕

4.1 CLI 层:事件转发

cli/src/index.ts 中,ensurePtyProcess() 启动 lunel-pty 二进制(按平台自动下载 linux/macOS/Windows 版本),用 readline 解析 stdout 的 JSON 行。收到 state 事件后,它把 cells、光标、模式等字段重新封装成 ns: "terminal" 的 WebSocket 消息,经 Manager/Proxy 中继推到 App。键盘方向则完全对称:App 的 write 消息最终变成 {"cmd":"write","id":...,"data":...} 写进 PTY 的 stdin。

4.2 useTerminal:把脏行合进二维缓冲

App 端 app/hooks/useTerminal.ts 的合并逻辑是帧同步的"另一半":

  • 每个终端维护一块 rows × cols 的二维 Cell 缓冲;
  • 收到增量帧后,仅把 cells 里出现的行覆盖写入对应行号(第 84~90 行);
  • 行列尺寸变化时整块重建缓冲——与 Rust 端 resize 清 prev_cells 形成闭环。

这样 React 组件拿到的永远是完整的最新屏幕,而网络与状态更新的成本只与"变化面积"成正比。

4.3 React Native 渲染:Span 合并 + Skia Canvas

最后一段在 app/plugins/core/terminal/Panel.tsx:

  • groupCellsIntoSpans() 把一整行 Cell 按"前景色、背景色、属性"三连相同原则合并成连续 Span——一行 80 列往往只剩几个 Span,文本节点数量骤降;
  • 普通模式用 React Native View + Text 逐 Span 绘制,Rect 铺背景色、Text 写文字;
  • 字体加载后切换到 Skia Canvas 版本(Panel.tsx#L444-L571),整屏文字在单个画布上绘制,下划线、删除线、dim 透明度都用矢量矩形表达,渲染成本进一步降低。

至此,一个字符完成旅程:shell 输出 → PTY 字节流 → wezterm 状态机 → 42ms 合帧 → 行级 diff → JSON → WebSocket → 脏行合并 → Span 合并 → 像素。

五、动手验证

想亲手跑一遍管线,可以直接克隆仓库:

git clone https://gitcode.com/gh_mirrors/lu/lunel
cd lunel/pty && cargo build --release

然后用 echo '{"cmd":"spawn","id":"t1","cols":80,"rows":24}' | ./target/release/lunel-pty,你会看到 stdout 立刻吐出 spawned 和 state 帧——把命令替换成 ls 输出的会话,还能亲眼观察 24fps 下每帧只有几行数据在流动。完整接入则只需在服务器上运行 npx lunel-cli,手机扫码即可。

六、小结

Lunel 的 PTY 渲染管线给出了"手机跑真实终端"的一套标准答案:

  1. 不重造轮子:wezterm 状态机负责最脏最难的 ANSI 解析;
  2. 帧率优先:Condvar + dirty + 42ms 限速,突发输出自动合帧,空闲零开销;
  3. 增量优先:行级 diff 让一帧的数据量只取决于画面变化量;
  4. 边界兜底:resize / scroll 显式退化为全量帧,保证任何状态下屏幕都正确。

这正是它能在几英寸的屏幕上流畅跑 vim、htop 的底层原因。

登录后查看全文
lunel