Ghostel架构揭秘:Zig原生模块+Elisp双层设计如何驱动Ghostty的VT引擎libghostty-vt
Ghostel架构揭秘:Zig原生模块+Elisp双层设计如何驱动Ghostty的VT引擎libghostty-vt
Ghostel 是一款运行在 Emacs 内的终端模拟器,核心能力来自 libghostty-vt——Ghostty 终端背后的 Zig 语言 VT 引擎。它采用「Zig 原生模块 + Elisp」的双层架构:Zig 负责解析、渲染等性能敏感路径,Elisp 负责键位、模式和 Emacs 生态集成。本文带你拆解这套设计:数据从按键到屏幕要经过哪些模块,以及为什么本地 cat 一个 10 MB 的日志只需要约 110 ms 而不卡界面。
双层架构总览:Zig 管"快",Elisp 管"广"
Ghostel 的源码清晰地分成两层,官方文档中也明确将其概括为 "Two-layer Zig + Elisp design"(见 README.org):
| 层 | 目录 | 职责 | 关键文件 |
|---|---|---|---|
| Elisp 层 | lisp/ |
键位映射、进程管理、模式、命令 | ghostel.el |
| Zig 模块层 | src/ |
终端引擎、PTY、渲染、输入编码 | module.zig、GhostelTerm.zig、Renderer.zig |
| 扩展包 | extensions/ |
evil / consult 集成 | extensions/ |
这种分工的直接效果:终端输出在 Zig 后台线程里解析,Emacs 主线程只在"需要重绘或回调"时被唤醒,因此界面在输出洪水(output flood)中依然保持响应。
下图是在 Ghostel 缓冲区中运行 btop 的效果,完整的真彩色与 TUI 渲染均由 libghostty-vt 驱动完成:
第一层:Zig 原生模块如何接入 Emacs
入口:从 emacs_module_init 开始
Zig 代码被编译为 Emacs 动态模块(ghostel-module.so / .dylib / .dll)。Emacs 加载模块时会调用 C 入口 emacs_module_init,它完成三件事:初始化与 Emacs 的 C API 绑定、注册所有可供 Elisp 调用的函数、并初始化 comint 过滤器与终端对象。整个过程见 module.zig。
终端状态:GhostelTerm.zig 封装 libghostty-vt
每个 Ghostel 缓冲区背后都有一个 GhostelTerm 实例,它持有 libghostty-vt 的 gt.Terminal(终端网格模型)、gt.Stream(VT 字节流解析器)、渲染器以及原生进程句柄。初始化时开启 grapheme 模式,保证中日韩等宽字符正确排布,代码入口在 GhostelTerm.zig。
可以把它理解为:libghostty-vt 负责"字节流 → 终端网格",GhostelTerm 负责管理这个网格的完整生命周期(创建、锁定、重绘、释放)。
渲染管线:Renderer.zig 把终端网格投影到 Emacs 缓冲区
这是双层设计中最有讲究的部分。Renderer.zig 拥有"终端网格 → Emacs 缓冲区"的投影权:
- 增量重绘:直接读取 libghostty 的页面(pages),结合"脏行 + 光标移动"判断哪些行需要改写,只重写脏行;
- 样式翻译:把终端的字体颜色、加粗、下划线等属性转换为 Emacs 的文本属性(text properties)与 face;
- 位置保持:终端缓冲区不是普通追加式文本流——行会被替换、resize 会重排、scrollback 会生长或回收。渲染器负责在这些变换中维护 point、mark、窗口位置,让 Elisp 代码"像对待普通缓冲区一样"使用它,而无需到处写补救逻辑。
官方架构原则一句话总结:Elisp 决定策略(policy),Renderer 负责渲染的机械后果(README.org)。
yazi 文件管理器中的内联图片预览也是这条管线的产物——Kitty graphics 协议解码出的图像由渲染器放置到缓冲区中:
事件路由:OSC 动作如何从 Zig 回调到 Elisp
终端应用会发送大量 OSC(操作系统命令)序列:设置标题、超链接、Kitty 图像、进度提示……这些动作如果让 Elisp 逐字节解析会非常昂贵。
Ghostel 的做法见 handler.zig:自定义流处理器几乎全部委托给 libghostty 的标准处理器(它已经完成了语义解析),仅在需要与 Emacs 交互的 OSC 动作上拦截,并调用对应的 Elisp 回调——相当于让 Zig 引擎"替 Elisp 读懂了协议",Elisp 只接收结果。
输入路径:按键如何编码回终端
反向数据流同样走 Zig。ghostel--encode-key 把 Emacs 按键事件交给 input.zig 中的 libghostty 按键编码器,编码器会自动遵循当前终端模式(应用光标键、Kitty 键盘协议等),生成的转义序列经 ghostel--write-pty 直接写入 PTY 主端。
原生 PTY 与事件管道:为什么不卡 Emacs 主线程
这是双层架构性能收益的核心。本地缓冲区默认走原生 PTY 路径(ghostel-use-native-pty):
- Zig 打开 PTY、派生子进程:Linux/FreeBSD 使用 PosixPtyProcess.zig,Windows 使用 ConPTY(ConPtyProcess.zig);
- 后台读取线程:NativeProcess.zig 中的 Zig 线程持续读取 PTY 输出,直接喂给 libghostty-vt 解析,全程不经过 Emacs 主线程;
- 事件管道:只有当需要执行 OSC 回调或使缓冲区失效时,才把序列化好的 Lisp 事件表单写入 Emacs 管道进程,由
ghostel--events-filter求值并调度重绘。
对比之下,vterm/eat 在主线程上同步解析字节流,整段传输期间 Emacs 完全冻结。官方基准测试(Apple M4 Max)给出了直观数字(README.org):
| 场景 | Ghostel(原生 PTY) | vterm | eat |
|---|---|---|---|
| 1 MB 流式输出吞吐 | 75 MB/s | 18 MB/s | 6.2 MB/s |
cat 10 MB 文件耗时 |
~110 ms | ~550 ms | ~1.8 s |
而远程 TRAMP 场景则走 Emacs 自身的进程机制,由 ghostel--filter 调用 ghostel--write-vt 同步喂入同一套终端模型——两条路径共享同一套渲染器与输入代码。
小结:这套架构给 Emacs 用户带来了什么
- 性能:解析在 Zig 后台线程,Emacs 主线程只负责重绘,输出洪水不冻结界面;
- 正确性:直接复用 Ghostty 的 VT 引擎,真彩色、Kitty 键盘/图形协议、超链接、同步输出等特性开箱即用;
- 可集成:Elisp 层保留了完整的 Emacs 惯用法——模式、键位、扩展生态(evil-ghostel、consult-ghostel)都可以按常规方式开发。
如果你想动手验证,可以运行仓库自带的基准套件 bench/run-bench.sh 对比两种 PTY 路径,或阅读 bench/ghostel-bench.el 了解测试方法。

