源码地图：按问题反查入口
Ghostty 主要目录、类型和排障路径速查
源码地图：按问题反查入口
目录 → 问题
| 想理解什么 | 优先打开 |
|---|---|
| 启动/CLI action | src/main_ghostty.zig, src/main_c.zig, src/cli/ |
| app 和 surface 生命周期 | src/App.zig, src/Surface.zig, src/apprt/ |
| PTY/shell | src/pty.zig, src/termio/Exec.zig, src/termio/Termio.zig |
| IO thread | src/termio/Thread.zig, src/termio/mailbox.zig, src/termio/message.zig |
| VT 解析 | src/terminal/Parser.zig, parse_table.zig, stream_terminal.zig |
| ANSI/OSC/CSI | src/terminal/ansi.zig, csi.zig, osc.zig, sgr.zig |
| 屏幕/滚动 | Terminal.zig, Screen.zig, ScreenSet.zig, PageList.zig, page.zig |
| 图片/Kitty | terminal/kitty/, terminal/apc/, renderer/image.zig |
| 字体 | font/discovery.zig, font/SharedGrid.zig, font/shaper/, font/Atlas.zig |
| GPU | renderer/generic.zig, renderer/Thread.zig, renderer/Metal.zig, renderer/OpenGL.zig |
| 配置 | config/Config.zig, config/file_load.zig, config/conditional.zig, config/CApi.zig |
| keybind/action | input/Binding.zig, input/key_mods.zig, input/command.zig, Surface.zig |
| macOS | macos/Sources/Ghostty/, macos/Sources/Helpers/, src/main_c.zig |
| GTK | src/apprt/gtk/, src/build/gtk.zig |
| 库/WASM | src/lib_vt.zig, src/lib/, src/config/Wasm.zig, src/os/wasm/ |
| build/release | build.zig, src/build/, pkg/, flatpak/, nix/ |
按故障定位
“窗口是空白的”
先看 termio/Thread.zig 的错误展示，再看 renderer/Thread.zig 是否收到 wakeup，最后进入 renderer/generic.zig 的 rebuildCells 和 backend frame health。若 Terminal 有内容但没有画面，问题更可能在 renderer/runtime，而不是 Parser。
“shell 输出卡住”
检查 PTY readable、IO thread xev loop、SPSC mailbox 是否 drain，再看 synchronized output 是否触发 reset timer。若 terminal dirty 改变但 renderer 不动，追踪 renderer_wakeup 和 renderer mailbox。
“按键没有写入 shell”
从平台 event → Surface.key → Binding match → terminal keyboard mode → write request 逐段看。binding 被消费、readonly、mouse mode、focus 状态都可能是正常行为，不要直接假设 PTY 坏了。
“滚动历史占内存”
看 Terminal.Options 的 bytes/lines limit，再看 PageList resident/compressed、compression scheduling 和 viewport 是否触发 restore。历史 page 的物理表示和逻辑可见性是两个问题。
“macOS 崩溃在释放 surface”
检查 Swift Surface.deinit 是否回到 MainActor、C API ownership 是否成对、core thread 是否已经 join。surface pointer 失效后不能继续调用任何 callback。
最小调用链索引
main_ghostty.zig::main
→ App.create / App.init
→ apprt runtime
→ Surface.init
→ Termio.init / Thread.threadMain
→ Parser.next
→ Terminal / PageList
→ renderer.Thread.threadMain
→ generic.Renderer.drawFrame这条链足以作为读源码、加日志、写 benchmark 和设计新功能的共同坐标系。