阅读指南：先抓住数据流

Ghostty 的目录很大：源码包含 Zig 核心、终端协议、字体、渲染、GTK、macOS Swift、构建工具、测试、基准和发行打包。直接从目录顺序读，容易把“共享核心”和“平台宿主”混成一团。更有效的方式是先锁定一次输出和一次输入。

三个问题

每一章都用同样的三个问题组织：

是什么：这个模块在产品里负责哪一种稳定责任？
怎么做：一次真实事件经过哪些类型、线程、队列和状态变更？
为什么：哪些限制、故障或性能目标迫使它这样设计？

正文把“源码明确写出的事实”和“从结构推导出的解释”分开。伪代码只表达控制流，不保证可直接编译。

最小入口集

如果只有一小时，先打开这些文件：

文件	先看什么
`src/main_ghostty.zig`	进程级初始化、CLI action、`App` 和 runtime 启动
`src/App.zig`	app 级 surface 列表、mailbox、配置传播
`src/Surface.zig`	单个 terminal surface 拥有的 renderer/IO/thread 资源
`src/termio/Termio.zig`	terminal、backend、stream handler 和线程入口
`src/termio/Thread.zig`	IO 线程的 xev loop、写入和异步消息
`src/terminal/Parser.zig`	VT 状态机和 action 输出
`src/terminal/Terminal.zig`	screen、cursor、mode、color、scrolling region
`src/terminal/PageList.zig`	active page、scrollback page、resident/compressed storage
`src/renderer/Thread.zig`	renderer wakeup、定时刷新、cursor blink、压缩调度
`src/renderer/generic.zig`	cell rebuild、字体、图片、GPU 抽象和 frame

两条主链

输出链：shell → pixels

child process
  → pty read
  → termio.Termio
  → StreamHandler.Stream
  → terminal.Parser.next
  → Terminal dispatch
  → Screen/Page dirty state
  → renderer.Thread wakeup
  → generic.Renderer.rebuildCells
  → font.SharedGrid / atlas
  → Metal/OpenGL frame

输入链：key/mouse → shell

Swift/GTK event
  → C ABI or apprt callback
  → Surface key/mouse handler
  → input.Binding / action
  → terminal mouse/key encoding
  → Termio mailbox
  → writer thread
  → pty write

两条链不是对称的：输出解析是热路径，尽量少锁、少分配；输入则要先判断 Ghostty 自己是否消费了事件，再决定把它编码给 PTY 或交回窗口系统。

证据边界

这份 ghostty-main 没有 .git 目录，所以无法可靠给出提交哈希。文中以以下证据优先级为准：

类型定义、函数体、错误处理和测试；
AGENTS.md、README.md、构建选项和 C 头文件；
从对象关系和线程同步推导的设计解释；
上游网站或 README 中的愿景，只在源码能够对应时才视作已实现。

建议阅读路线

理解终端核心：01 → 04 → 05 → 06 → 07
理解桌面启动：01 → 02 → 03 → 08
嵌入与二次开发：02 → 08 → 09 → 10
性能排查：04 → 05 → 06 → 07 → 12

阅读指南：先抓住数据流

On this page