企业官网建设流程全解析

ghui是一个面向 GitHub 的终端 TUI 客户端，它把 PR 列表、详情、Diff 审查、评论、合并等操作全部搬进终端。其中 Diff 渲染 是它体验的命门：一个 300+ 文件、上万行改动的大补丁，如何做到启动不卡、滚动不掉帧、切换视图不"跳位"？本文从 ghui 的 Diff 渲染性能优化计划 切入，拆解终端 TUI 中视口窗口化（viewport windowing）与词级高亮（word-diff highlighting）两套核心技术的思路与落地细节，适合想深入理解终端 UI 性能优化的新手阅读 🚀

为什么大补丁 Diff 是终端 TUI 最难的一关

在浏览器里，Diff 页面有虚拟滚动、GPU 合成等成熟手段；而终端 TUI 的渲染模型完全不同——每一行都是一个字符网格上的"可渲染单元"（renderable）。ghui 当前的 PullRequestDiffPane 会把 PR 里每个文件的<diff>渲染器全部挂载进同一个 scrollbox 中：

启动、滚动、布局切换的开销都随"补丁总大小"增长，而不是随"可见视口"增长。

这句话正是 ghui 优化计划的出发点（见 plans/diff-rendering-performance.md）：

• ❌ 现状：成本 ∝ 补丁总行数（全量挂载）
• ✅ 目标：成本 ∝ 视口高度（只渲染可见 + 近可见区域）

对新手来说，这里有个容易忽略的终端特性：终端滚动条的"总高度"必须真实存在，否则滚轮和键盘翻页会失去语义。所以窗口化不能只是"隐藏"，还要用占位行（placeholder）撑起总滚动高度。

语义行模型：先解析一次，测量与渲染解耦

ghui 借鉴了同类终端 diff 工具 hunk 的架构思想：把补丁一次性解析成语义行模型（semantic row model），让几何测量（每段多高、每行在哪）和画面渲染（画什么颜色）彻底分离。

好消息是，这套地基在 ghui 里已经打好了大半，全部集中在 src/ui/diff.ts：

1. 按文件切分补丁

splitPatchFiles 用diff --git行把完整 patch 切成"每个文件一块"，并解析出文件名、文件类型（用于语法高亮）；normalizeHunkLineCounts 会重新统计 hunk 的行数区间，保证渲染器拿到的元数据始终准确。

2. 预计算每个文件的"几何信息"

buildStackedDiffFiles 会为每个文件算出四个关键值：

• headerLine：文件头在整页中的起始行
• diffStartLine：diff 正文起始行
• diffHeight：渲染后占多少行（含换行与 split 视图的左右配平）

其中 patchRenderableLineCount 是精髓：它会模拟 unified/split 两种布局、按内容宽度估算每行的换行行数（estimatedWrappedLineCount），让"未渲染"的文件也有精确的高度——这就是视口窗口化能做占位行的前提。

3. 二分查找 + 吸顶文件头

滚动时"当前处于哪个文件"不需要遍历，stackedDiffFileIndexAtLine 用二分查找在 O(log n) 内定位，PullRequestDiffPane 据此绘制吸顶文件头，甚至能提前 1 行预告"下一个文件"，滚动手感非常顺滑。

4. 评论锚点与画面永不漂移

getDiffCommentAnchors 把每条 review 评论换算成renderLine（渲染行）和colorLine（染色行），split 视图下还会左右配平补齐行差。有了这份预计算，键盘/评论导航即使目标文件还没挂载也能确定性寻址——这是 ghui 计划中"未挂载文件不影响导航"的关键。

视口窗口化：只渲染可见 + 近可见的文件段

计划中的窗口化方案可以概括为三句话：

1. 视口光晕（viewport halo）：用 scroll top + viewport height 算出可见区间，只渲染与之相交的文件段，外加选中/相邻段（留给评论跳转用）；
2. 占位行撑高：屏外文件用与实测高度一致的占位行补齐总滚动高度，滚动条语义不变；
3. 高亮按需、预取先行：语法/词级高亮这种昂贵计算只围绕活跃视口展开，选中与近可见文件提前预取。

配套一个高亮缓存：以"文件内容 + 主题 + 语言 + 视图模式 + 空白模式"为 key，进行中的任务去重，避免来回滚动时重复解析。

ghui 现有的几个机制已经为窗口化铺好了路：

• Diff 预取：useDiffPrefetch 在选中 PR 250ms 后静默预取补丁，且按 PR 修订号（head commit）区分缓存 key（atoms.ts），翻页切换几乎零等待；
• 滚动位置保持：useDiffLocationPreservation 在切换 split/unified、换行、空白模式之前快照"当前锚点 + 屏幕偏移"，重渲染后以 16ms 间隔重试（最多 6 次）直到布局稳定、同一行仍在同一屏幕位置——这对窗口化后的"占位区 ↔ 真实段"切换同样必要；
• 文件导航面板：DiffFilePanel 在宽终端（≥130 列）自动停靠，高亮当前滚动到的文件，点击直达，路径截断还会保留文件名（而不是砍掉文件名）。

词级高亮：叠在语法色之上的"第二层着色"

ghui 的 createDiffSyntaxStyle 已把 keyword、string、comment、function 等 token 映射成主题色，unified 与 split 布局共用同一份样式，保证两种视图下语法色完全一致。

而"词级高亮"要更进一步：在一条被修改的行里，只有真正变动的那几个词（intra-line changed spans）额外着色，叠加在语法高亮之上——就像浏览器里 GitHub 的 diff 一样。计划中的难点在于：

• OpenTUI 的<diff>渲染器目前无法暴露行内词级 span，因此 ghui 计划新增一个自定义行渲染器，直接输出终端 span；
• 词级变更区间由语义行模型在解析阶段产出，与语法 token 同层维护，两种高亮互不覆盖；
• 该能力依赖"解析一次、几何与渲染分离"的架构先行落地，所以排在视口窗口化之后实施。

键盘导航：性能优化的"体感放大器"

再快的渲染，用户感知不到也没用。ghui 的 diffView 键位 把 vim 语义做到了极致：

• j/k、shift+j/k（8 行跳）、count前缀（如15 j）单步移动评论锚点；
• ctrl+u / ctrl+d / ctrl+v半页滚动，且保持当前行在视口中的相对位置（真正的 vim 语义）；
• g g/shift+g直达首末评论，z z / z t / z b把当前锚点对齐到屏幕中/上/下；
• shift+v切 split/unified，w切换行，[/]跨文件，f打开变更文件搜索。

这些操作全部建立在"几何预计算 + 锚点寻址"之上——无论目标文件是否已挂载，跳转结果都确定，这正是窗口化能放心上线的原因。

总结

对终端 TUI 开发者来说，ghui 给的启示很清晰：先让"测量"摆脱"渲染"，把补丁解析成一行行带几何信息的语义模型，窗口化、词级高亮、评论跳转就都成了模型上的查询问题——性能优化从此不是打补丁，而是架构的自然结果。