Terax 终端渲染器池架构解析：模型所有权、呈现资源租约与故障恢复

Terax 终端渲染器池架构解析：模型所有权、呈现资源租约与故障恢复

【免费下载链接】terax-aiLightweight (7MB) Terminal-first AI-native dev workspace项目地址: https://gitcode.com/GitHub_Trending/te/terax-ai

导读

Terax 是一套终端优先的 AI 原生开发工作区，其终端内核基于 libghostty（WASM），默认走 WebGPU 渲染，并以自研 WebGL2 渲染器作为兼容回退。本文以 docs/architecture/terminal-renderer-pool.md 为骨架，系统讲解 Terax 的终端模型（model）所有权模型、GPU 呈现资源池（renderer pool）的租约机制、分窗帧率调度、窗口遮挡与休眠下的资源回收策略，以及渲染器替换的"事务式恢复"流程。读完你将理解：为什么切换标签页、切换图形 API 甚至 GPU 上下文丢失都不会重置终端的解析器、回滚缓冲、选区、搜索与命令块状态，以及 Terax 如何在约 7~8 MB 的轻量级打包体积下维持多标签终端的高性能呈现。

核心所有权模型：一个叶子 = 一个模型 + 一个 PTY

TERAX.md 与本文档共同确立的第一条不可变约定是：

每个终端叶子（terminal leaf）独占一个 libghostty 模型与一个 PTY；渲染器租约（renderer lease）永远不拥有终端状态。

这意味着状态归属被严格划分：

• 模型与会话状态（解析器、回滚缓冲、选区、搜索、命令块）挂靠在叶子（tab / pane）上，由useGhosttyTerminalSession每个叶子持有一个持久模型与 PTY；
• 呈现资源（GPU 设备、pipeline、图集租约、损伤调度器）是窗口级共享的，由运行时（runtime）统一管理，任何表面（surface）只以租约形式借用。

因此，切换标签页、更换图形 API（WebGPU → WebGL）、GPU 上下文丢失、窗口遮挡恢复，都只是"呈现事务"层面的变化，永远触碰不到模型。TERAX.md明确写道："WebGPU can fail over to WebGL without replacing the model, PTY, selection, search, or block history"（WebGPU 可以无缝降级到 WebGL，而无需替换模型、PTY、选区、搜索或命令块历史）。这是整个渲染器池设计的第一性约束。

呈现资源：WebGPU 共享运行时

WebGPU 路径的核心是 WebGpuTerminalRuntime。它通过模块级单例getWebGpuTerminalRuntime()提供给整个窗口，一个窗口只持有一份GPU 设备（device）、两个渲染管线（color pipeline 与 glyph pipeline）、图集（atlas）租约与损伤调度器。

从源码中可以确认的关键常量与机制：

帧提交采用"每帧一个 encoder/submission"的策略：flushFrame中，只要dirtySurfaces非空，就创建一个带Terax terminal window frame标签的GPUCommandEncoder，遍历本批表面逐一渲染，最后只调用一次queue.submit([encoder.finish()])。inFlightFrames达到MAX_IN_FLIGHT_FRAMES时requestFrame直接返回，脏帧被合并而不会产生新的上传与提交——这正是文档所述"至多两个提交等待 GPU 完成"的实现。

图集以租约（GlyphAtlasLease）形式发放：acquireGlyphAtlas/acquireIsolatedGlyphAtlas会以字体、字号、字重、行高、字距与 DPR 组合成 key，同一 key 复用同一图集；release()幂等地减少引用计数并触发延迟回收（scheduleAtlasReap）。空闲 CPU 字形缓存（glyph cache）保留一份、30 秒空闲生命周期，其覆盖像素约 1 MiB，只有使用 emoji 后才额外增加 1 MiB 彩色像素。

WebGL 兼容回退：至多五个渲染器槽位的池

当 webview 不支持 WebGPU 时，Terax 使用自研的 WebGL2 渲染器（适配自上游 Ghostty 呈现层，保留上游 MIT 署名，见 webgl/UPSTREAM.md，不安装、不携带任何 xterm 运行时或插件）。

WebGlTerminalRuntime 实现了与 WebGPU 对称的池化模型：

每个槽位独占一个WebGlCellRenderer，它消费同一个 Ghostty 模型与同样的脏行（dirty-row）信息——与 WebGPU 渲染器共享模型侧的全部状态。槽位租约的生命周期是：

1. acquire(surface, host, profile)：按渲染 profile（字体、DPR 等）查找空闲槽位；若 5 个槽位都已占用且无空闲，则抛出WebGL terminal renderer pool exhausted (5 visible panes)错误；
2. 槽位绑定 surface 后resetModel()并将 canvasattach(host)；
3. release(surface)：槽位归还池中，detach()，记录lastUsed并安排空闲清扫定时器；
4. sweepIdleSlots()：超过 30 秒未使用的空闲槽位被dispose()并从池中移除，但至少保留 1 个暖槽位。

discard(surface)用于渲染器出错场景，直接销毁该槽位。窗口隐藏时trimForHiddenDocument()会清掉所有无主槽位。

值得强调的是池化的边界：源码注释明确写道 "Ghostty models are never pooled here"（这里从不池化 Ghostty 模型）。WebGL 池只池化呈现器，隐藏标签页释放 GPU 槽位的同时，WASM 终端状态保持存活。

帧率调度：60 / 30 / 15 的按面板（per-pane）截止时间

帧率并非全局统一，而是由 SurfaceFramePacer 按"每个面板自己的截止时间（deadline）"驱动，核心常量在 renderScheduling.ts 中：

关键实现细节：

• terminalFrameIntervalMs(windowFocused, hasFocusedSurface)决定基础帧间隔，但聚焦面板的输出不会把后台面板拉到 60 fps——每个 surface 独立计算自己的 deadline；
• interact(surface, now)为交互面板写入now + 150ms的优先截止时间，期间按聚焦帧率渲染；150 ms 到期即回落，不启动任何空闲定时器或帧循环；
• delay()返回"最早截止时间 - 当前时间 - FRAME_LEAD_MS(1/60s)"，调度器据此使用setTimeout或requestAnimationFrame，避免 RAF 回调抖动跳过本可呈现的帧；
• WebGPU 的MAX_IN_FLIGHT_FRAMES = 2保证 GPU 落后时脏工作只合并、不堆积。

窗口生命周期：遮挡、睡眠与两秒宽限

呈现资源的回收完全由窗口可见性驱动，由 windowPresentation.ts 提供的单一共享订阅组合了三路信号：DOMvisibilitychange、原生 macOS 窗口遮挡（occlusion）与睡眠/唤醒通知（通过 Tauri 事件terax:window-presentation与window_presentation_state命令桥接）。

各状态下的呈现行为可归纳为：

源码层面的佐证：WebGpuTerminalRuntime.handleVisibility收到reclaim时挂起所有零引用图集；WindowPresentationPolicy与WebGlTerminalRuntime的handleVisibility在不可见时直接cancelScheduledFrame()，而 WebGPU canvas 被回收前会先"unconfigure"再缩放到 1x1，同时保留目标几何信息供下一次呈现事务恢复。原生快照携带单调递增的revision，迟到的 IPC 初始响应不会覆盖更新的状态。

无论窗口如何变化，PTY 与终端模型始终保持：隐藏标签页的模型会继续解析输出（通过有界的两消息窗口与 2 MiB 待处理/在途字节上限），直到叶子关闭。文档与 ghostty-resource-efficiency.md 都强调："Models keep parsing until their leaves close"（模型持续解析直到其叶子关闭）。

命令块与辅助输出：惰性加载、归属模型、随呈现挂起

命令块（command blocks）是 Ghostty 模型/会话的一部分，包括其跟踪的原生 pin（marker）：

• 命令锚点（endpoint columns）在解析期（parser-time）由 Ghostty 生成，因此命令范围能跨回流（reflow）存活，且不会把后续提示符和命令包含进去；
• 原生 marker 环上限2,048 个 pin；JavaScript 侧历史上限1,000 条块 / 512 KiB（UTF-16 估算的命令与 cwd 文本）；
• 块控制器（block controller）与覆盖层（overlay）惰性加载，只在块会话中使用；隐藏或被遮挡时块的呈现工作停止；
• 共享 shell 编辑器拥有提示符输入；交互式命令与备选屏（alternate-screen）应用拥有网格输入；WebGPU 与 WebGL 两套呈现后端施加完全相同的输入与光标策略。

可访问输出（accessible output，即屏幕阅读器文本）是opt-in、惰性、有界的：限制为 256 行 / 64 KiB，可见时每秒最多刷新 4 次（250 ms 合并），并随窗口呈现一起挂起。它直接读取原生文本范围，不会移动渲染器视口或选区——即使可访问文本刷新，用户的滚动位置与选区保持不变。

事务式恢复：替换呈现，永不触碰模型

渲染器替换（renderer replacement）是本文档描述的最关键恢复路径，其实现位于 replaceSessionSurface.ts，核心顺序是：

1. 从旧表面快照搜索状态（searchController().snapshot()）并挂起旧搜索；
2. 创建替换表面（create()）并先 attach 新表面；
3. 将搜索快照恢复到新表面（restore(search)）——不重置查询、不跳过当前匹配；
4. 全部成功后，才释放旧表面与旧输入（previousInput?.dispose()+previous?.dispose()）；
5. 若中途失败：释放已创建的替换资源、resume()旧搜索，并重新抛出错误——旧表面与模型保持完好。

这一"先建后拆"的顺序保证了替换是原子的：呈现层永远不存在"无渲染器可用"的窗口期。

对应的故障处理语义：

• WebGL 回退失败：显示带重试（Retry）操作的错误呈现，同时保持存活的模型与 PTY——用户重试只是再次替换呈现，而不是重启会话；
• WebGPU 设备丢失：recoverDevice会先释放设备与图集、隐藏期间推迟设备重建，窗口恢复可见后再重新初始化；初始化期间丢失的设备被隔离（quarantine）而不是进入无界恢复循环；
• 文档明确禁止用"序列化、重放、清空或重新 spawn 终端"来修复呈现问题——呈现损坏与终端状态是两回事。

TERAX.md补充了两个相关约束：延迟导入（WebGL 表面与渲染器只在选中、需要回退或被诊断显式请求时加载）不能安装进已关闭、已重启或已替换的会话；不支持图形能力时展示可见错误与重试，而不是悄悄更换模型。

资源边界与度量证据

配套的 ghostty-resource-efficiency.md 记录了该所有权模型下的实测数据（注意：这些是核心 WASM 分配与压力测量，不是应用总 RSS）：

• 20 个空 120x40 模型在首帧渲染前：候选实现 10.375 MiB，对比基线 15.4375 MiB（约 32.8% 的 WASM 分配下降）；单模型从 2.250 MiB 降到 1.938 MiB；
• 五模型压力运行（每变体 655,360 次更新、约 62 MiB 输入字节）：SIMD 与标量变体最终均稳定在 68.125 MiB WASM 内存，最后 16 个采样窗口零增长；启用原生块 pin 时每模型恰有 2,048 个 marker；
• 原生呈现数组（cell arrays 及其 grapheme、hyperlink、placement 快照）首次呈现时才分配，回收时释放，但解析器、回滚、选区与命令 pin 全部保留；隐藏期间的写入与 resize 不会重建呈现；
• 回归测试断言：100 个未变化的已调度帧零上传零绘制；WebGPU 单行上传 7,680 字节、WebGL 4,800 字形字节；短暂停后不重新打包 cell；隐藏光标/未聚焦窗口无闪烁唤醒；1,000 次合并的搜索失效只推进一次搜索步骤；选区行损伤不触发原生渲染更新。

复现与验证入口

如果你想在本地验证本文描述的呈现池行为，仓库提供了可复现的工具链（均不启动应用）：

# 五模型压力测试：颜色、Unicode、emoji、OSC 8 链接、回滚修剪、隐藏解析、呈现释放、resize 压缩 TERAX_SOAK_REPORT=/tmp/terax-ghostty-soak.json pnpm soak:ghostty # 启用原生命令 pin 的块压力测试 TERAX_SOAK_BLOCKS=1 TERAX_SOAK_REPORT=/tmp/terax-block-soak.json pnpm soak:ghostty # 分配与解析工作负载的按产物对比（每个产物独立进程） TERAX_PROFILE_BASELINE=/tmp/terax-core-baseline TERAX_PROFILE_REPORT=/tmp/terax-core-profile.json pnpm profile:ghostty

运行时诊断可这样开启：

localStorage.setItem("terax:terminal-diagnostics", "1"); // 重新加载后： window.__teraxTerm(); // 前端计数器 await window.__teraxTermSnapshot(); // 原生队列计数器与宿主 RSS var trace = window.__teraxTermTrace(); // 有界 10 分钟资源记录（最多 600 个样本，1 秒一次） JSON.stringify(trace.stop()); // 切换桌面/遮挡/睡眠后捕获

注意：window.__teraxTermSnapshot()的宿主 RSS 只覆盖 Rust 宿主进程，不含 WebContent 与 GPU 进程，不能当作应用总内存。

与相关文档的关系

本文档是 TERAX.md 的展开说明，若两者冲突以 TERAX.md 为准。关于所有权上限、测量方法与局限性的完整记录见 ghostty-resource-efficiency.md；发布前的平台验证（macOS 13 WKWebView、Windows WebView2/ConPTY、Linux WebKitGTK）与打包验证门禁见 ghostty-release-readiness.md。两者都确认：当前自动化检查建立的是"可复现的核心/资源不变量"，尚未完成多平台、多日的打包级生产认证。

【免费下载链接】terax-aiLightweight (7MB) Terminal-first AI-native dev workspace项目地址: https://gitcode.com/GitHub_Trending/te/terax-ai