Pi Agent 源码级教程
M14

终端渲染 —— 一个 spinner 只该写 99 个字节

10,346 字 · 含 320 行代码 · 约 48 分钟

你人在咖啡馆,笔记本连着手机热点,SSH 到公司的开发机。

Agent 在跑,底下的 spinner 在转。你看着它转,每转一格都一顿。滚回去看十几分钟前 的输出,屏幕跳一下,光标回到最底下。你等了一分多钟,觉得哪里不对, 敲了一个字,输出突然刷了一屏。

本地跑同样的东西一点都不卡。区别在链路上:字节从开发机出来,先到 SSH, 再到热点,再到你面前这个终端模拟器。链路上每一跳都要转发你写出去的每一个字节。

而跑内容满屏的 Agent 对话,最朴素的做法是每帧重画一遍全局:

text
清屏 → 从第 0 行画到第 149 行

一帧 12 KB。spinner 每秒十帧,转一分钟就有 7.2 MB 打进这个伪终端。 而实际上,这一帧里只有一行变了。

packages/tui:46 个文件 / 19,971 行。本章只细读其中一个 661 行的文件—— tui-main-screen.ts,差分渲染。其余四十五个文件,知道它们在哪就行。

文件 行数 职责
components/editor.ts 2,484 编辑器:撤销栈、kill ring、补全、鼠标选区
tui-alt-screen.ts 1,801 全屏模式:布局、搜索、选区、滚动条
tui.ts 1,550 Component 契约、叠层、假光标、主题查询
keys.ts 1,512 键位解析:Kitty / modifyOtherKeys / 旧序列
latex.ts 1,507 公式转 Unicode 近似
utils.ts 1,468 列宽、截断、折行、ANSI 状态追踪
components/markdown.ts 1,121 marked + CJK 折行
autocomplete.ts 859 补全
terminal-image.ts 784 Kitty / iTerm2 图片协议
tui-main-screen.ts 661 本章主角:差分渲染
terminal.ts 640 raw mode、StdinBuffer、键盘协商

运行时依赖只有三个:get-east-asian-width(列宽)、marked(Markdown)、 marked-cjk-friendly(中文折行)。没有 chalk(colors.ts 自己写),没有 ink,没有 React,没有 blessed。

这不是一个"UI 框架"。它是一台字节调度器:把一棵组件树变成一串字节, 并且尽可能少写。

它的全部设计可以归为一句:组件可以笨,渲染器必须抠。 组件每次重画整棵树,不用知道任何优化;渲染器把"变了的行"抠出来, 只写那几个字节。


零、读这章之前,你需要先知道一件事

终端转义序列:终端不是"打印文字"的纸,而是一台老式电传打字机。 ESC(字节 27,写作 \x1b 或 \033)后面跟一串字符,组成控制指令, 不是给人看的正文。CSI = ESC [,管光标和颜色;OSC = ESC ],管标题这类带参数的请求。

没有它会怎样:把 \x1b[?2026h 当成乱码;或者在 PowerShell 里 echo 一个 ESC, 屏幕上什么也看不到(它不可打印),于是以为命令没执行。

本书哪里用到:§一 字节表第一行。PowerShell 写法:$([char]27) + "[31m红"。


一、问题:一帧该写多少字节

终端是单向的。你写出去的每个字节都会立刻发生作用,没有"保存"按钮,删不掉。

假设屏幕上有一份 150 行的对话记录,底部有一个 spinner 在转。它每 100 毫秒 换一帧。最朴素的做法是每帧重画:

text
清屏 → 从第 0 行画到第 149 行

一帧 12 KB,一秒十帧 120 KB,转一分钟 7.2 MB 打进一个伪终端。本地看不出 问题;走 SSH、走 tmux、走浏览器里的终端模拟器,就开始肉眼可见地卡。

而实际上,这一帧里只有一行变了。

pi-tui 的核心就是这一件事:把"画"和"写"拆开。组件永远重画整棵树 (render(width): string[]),但渲染器只把变了的行写出去。同一个 spinner, 一帧 99 个字节。

99 是怎么来的,这是本章的主线:

text
\x1b[?2026h   8   同步输出的开始\x1b[2K       4   清掉这一行\r            1   回到第 0 列"…spinner…"  78  这一行的内容\x1b[?2026l   8   同步输出的结束

一章 46 个文件,最后落在这五个片段上。中间所有东西——布局、列宽、 ANSI 状态、光标记账、图片、按键——都是为了让这五个片段正确。


二、组件只有一条契约

整个 UI 层只有一个必选方法:

ts
// tui.ts:117-135(节选)export interface Component {  /**   * Render the component to lines for the given viewport width   * @returns Array of strings, each representing a line   */  render(width: number): string[];  handleInput?(data: string): void;  handleMouse?(event: TuiMouseEvent): TuiMouseEventResult | undefined;}

注意签名:进去一个宽度,出来一个字符串数组。数组里每个字符串是一行 完整的终端字节——含颜色、含超链接、含光标标记。

没有虚拟 DOM,没有节点 diff,没有 reconciler。整个"差分"发生在字符串层面:

ts
if (oldLine !== newLine) { /* 这一行变了 */ }

这个选择决定了后面所有事情。好处是简单到可以一次读完;代价是组件必须 自己保证"同一份数据 + 同一个宽度 = 同一个字符串",否则每一帧都会被判定 为"全变了"。

所以组件里到处是缓存:

ts
// test/render-churn-bench.ts:80-90(测试里的编辑器替身)render(width: number): string[] {  if (this.cachedLines && this.cachedText === this.text    && this.cachedWidth === width) {    return this.cachedLines;  }  ...}

invalidate() 是唯一的失效手段(tui.ts:147)。它的语义是"下次 render 别用缓存",而不是"重画"。

组件一共二十来个,都在 components/ 下:

组件 干什么
text / truncated-text 一段文本,可选内边距
box 带边框的容器
stack / h-stack / v-stack 布局:主轴、basis / grow / shrink
scroll-view 滚动窗口,带滚动条
input / editor 单行输入 / 多行编辑器
markdown Markdown 渲染
image 图片
loader / cancellable-loader 动画
select-list / settings-list 列表选择
spacer / loader / mouse-region 辅助

顶层容器 Container 把子组件按顺序拼起来,TuiBase 在它之上加了"请求 重绘"和"叠层"。真正的屏幕实现只有两个:TuiMainScreen 和 TuiAltScreen。

2.1 布局:栈怎么分高度

render(width) 只拿到宽度,高度是渲染完才知道的——组件返回几行就占几行。 整棵树里只有 Stack(components/stack.ts,154 行)能控制分配。

它的旋钮和 CSS flexbox 同名同义:

字段 含义
basis 主轴初始尺寸,"auto" 取组件内在尺寸
grow 空间富余时的扩张权重,默认 0(不扩张)
shrink 空间不足时的收缩权重,默认 1
minSize / maxSize 钳制区间

算法就两次分配(stack.ts:135-154):

ts
// components/stack.ts:141-153(节选)const sizes = entries.map((entry, index) =>  clampSize(    entry.basis === undefined || entry.basis === "auto"      ? (intrinsicSizes[index] ?? 0)      : entry.basis,    entry,  ),);if (availableSize === undefined) return sizes;const contentSize = Math.max(0,  Math.floor(availableSize) - Math.max(0, entries.length - 1) * gap);const total = sizes.reduce((sum, size) => sum + size, 0);if (total < contentSize) {  distribute(sizes, entries, contentSize - total, "grow");} else if (total > contentSize) {  distribute(sizes, entries, total - contentSize, "shrink");}

先按 basis 定初值,算出差额,一次性交给 distribute。注意 contentSize 里先扣掉了 (n-1) 个 gap:间距不参与伸缩。

有意思的是 distribute(:95-133)的权重:

ts
// components/stack.ts:113-119(节选)const totalWeight = candidates.reduce((sum, { entry, index }) => {  return sum + (mode === "grow"    ? (entry.grow ?? 0)    : (entry.shrink ?? 1) * Math.max(1, sizes[index]!));}, 0);

grow 的权重就是 grow;shrink 的权重是 shrink × max(1, 当前尺寸)。后者 是 CSS 规范里的 scaled shrink factor:一个 40 行的编辑器和一行 1 行的 状态栏同时需要收缩,按"比例"收缩状态栏会被压成 0 行,按"自身大小加权" 则是编辑器让 40 份、状态栏让 1 份。max(1, ...) 保证尺寸为 0 的组件仍能 进分母。

循环还有个出口(:131):distributed === 0 就返回。因为 minSize / maxSize 的钳制会让某一轮一个字节都分不出去,不退出就是死循环;整数除法 本来也会剩下几个字节分不完,这个条件顺手兜住了两种情况。

布局之上还有一层缓存(layout.ts:68-81):Map<Component, Map<width, string[]>>。同一个组件在同一个宽度下的结果直接复用——这就是 §二 那句 "同一份数据 + 同一个宽度 = 同一个字符串"的运行时保证。整条链路上唯一的 失效手段是 invalidate(),它只清缓存,不触发重画。


三、一帧的十条出路

TuiMainScreen.doRender()(tui-main-screen.ts:250-621)是全包最密的一段 代码。它做的事可以概括成一句话:在十条出路里选一条,每条出路写出的字节 量差一到四个数量级。

先看共同的前半段(:266-279):

ts
let newLines = this.resolveFakeCursors(  this.render(width).map((line) => line.replace(OSC133_ZONE_PREFIX, "")),);if (this.hasOverlayEntries) {  newLines = this.compositeOverlays(newLines, width, height);}const cursorPos = this.extractCursorPosition(newLines, height);newLines = this.applyLineResets(newLines);

四步,顺序不能换:

  1. render(width):整棵树渲染成行。这一步永远是全量。
  2. 叠层合成:把浮层按列切开、贴到目标行上。
  3. 取光标:在合成之后找 CURSOR_MARKER,因为浮层可能盖住它。
  4. 加行尾复位:每条非图片行末尾补 \x1b[0m\x1b]8;;\x07。

第 3 步要在第 4 步之前,代码里那句注释说得很直白:"Resolve fake cursors before compositing so overlays and line slicing see plain SGR codes"。光标 标记是一个 APC 序列,如果折行或切列时撞上它,列宽就会算错。

然后是十条出路。这张表值得逐行读,因为每一行都是一个真实踩过的坑:

# 条件 动作 为什么
1 首帧 fullRender(false) 屏幕是干净的,不用清
2 宽度变了 fullRender(true) 折行位置全变,没有一行还对
3 高度变了(非 Termux) fullRender(true) 视口要重新对齐
4 高度变了(Termux) 继续走差分 软键盘一弹就重放全部历史
5 内容变短且开了 clearOnShrink fullRender(true) 否则底下留空行
6 没有任何行变化 只挪光标 光标可能在动,屏幕没动
7 变化全在被删掉的行里 清行 + 回退光标 新内容更短,要擦掉尾巴
8 变化全被删且多出的行 > 高度 fullRender(true) 清不完,会滚出视口
9 firstChanged < previousViewportTop fullRender(true) 那一行已经进了 scrollback
10 其余 差分:从 firstChanged 写到 lastChanged 唯一省字节的路

第 3 条和第 4 条是一对。标准做法是高度变了就全量重绘——但 Termux 里软键盘 的弹出会改变高度,于是每敲一个字就重放一遍全部历史。所以这里给 Termux 开了一个例外(isTermuxSession(),:112-114),代价是视口可能对不齐。

第 9 条是本章最重要的结构事实。previousViewportTop 的算法是 (:317-318):

ts
const bufferLength = Math.max(height, newLines.length);this.previousViewportTop = Math.max(0, bufferLength - height);

也就是说:差分的窗口只有终端高度那么高。150 行内容、24 行屏幕, previousViewportTop = 126——第 10 行变了,它早就在 scrollback 里,改不了, 只能全量。

这不是省不省字节的问题,是物理上做不到。终端没有"回到第 10 行"这种 操作,你只能往下滚、或者清屏重来。差分渲染的所有设计都被这一条约束着。


四、扫描与差分

扫描本身很简单(:367-393):

ts
let firstChanged = -1;let lastChanged = -1;const maxLines = Math.max(newLines.length, this.previousLines.length);for (let i = 0; i < maxLines; i++) {  const oldLine = i < this.previousLines.length ? this.previousLines[i] : "";  const newLine = i < newLines.length ? newLines[i] : "";  if (oldLine !== newLine) {    if (firstChanged === -1) firstChanged = i;    lastChanged = i;  }}

O(n) 的字符串比较,没有哈希、没有最长公共子序列。为什么够用:行数通常 是几百,而 !== 在 V8 里对"同一个字符串对象"是零成本比较——组件因为有 缓存,未变的行返回的是同一个数组里的同一个字符串,等于比指针。

appendedLines 是一个特判(:382-394):

ts
const appendedLines = newLines.length > this.previousLines.length;if (appendedLines) {  if (firstChanged === -1) firstChanged = this.previousLines.length;  lastChanged = newLines.length - 1;}const appendStart =  appendedLines && firstChanged === this.previousLines.length  && firstChanged > 0;

appendStart 为真意味着"只是在末尾追加了几行",这时写的方式不一样: 要先 \r\n 换行再写,而不是回车覆盖。这就是聊天记录往下长的那种情况。

写出的时候只写到 lastChanged(:492-494):

ts
// Only render changed lines (firstChanged to lastChanged), not all lines// to end. This reduces flicker when only a single line changes (e.g.,// spinner animation).const renderEnd = Math.min(lastChanged, newLines.length - 1);

注释说的是 flicker。真正的原因更硬:写到行尾意味着每帧都要重写一遍 下面所有行,而它们一个字节都没变。

4.1 写出的那一段

走到差分这条路上,代码只剩三十来行(:462-490),但它最该逐行读:

ts
// tui-main-screen.ts:464-480(节选)const output = new BoundedTerminalWriter((data) => this.terminal.write(data));output.append("\x1b[?2026h"); // Begin synchronized outputoutput.append(this.deleteChangedKittyImages(firstChanged, lastChanged));const prevViewportBottom = prevViewportTop + height - 1;const moveTargetRow = appendStart ? firstChanged - 1 : firstChanged;if (moveTargetRow > prevViewportBottom) {  const currentScreenRow = Math.max(0,    Math.min(height - 1, hardwareCursorRow - prevViewportTop));  const moveToBottom = height - 1 - currentScreenRow;  if (moveToBottom > 0) {    output.append(`\x1b[${moveToBottom}B`);  }  const scroll = moveTargetRow - prevViewportBottom;  output.append("\r\n".repeat(scroll));  prevViewportTop += scroll;  viewportTop += scroll;  hardwareCursorRow = moveTargetRow;}

五件事,顺序不能换:

  1. 开同步输出。此后所有字节进终端缓冲区,直到 \x1b[?2026l。
  2. 先删图片。\x1b[2K 擦不掉 Kitty 图片,必须显式发删除序列。
  3. 把目标行挪进视口。moveTargetRow > prevViewportBottom 表示要改的行 还在屏幕下方(内容比屏幕长)。先下移到屏幕底,再 \r\n 滚 scroll 行。 滚动会让 prevViewportTop 和 viewportTop 一起增大,两个变量必须 同步——漏一个,后面所有相对坐标全错。
  4. 相对移动光标(:483-490):
ts
const lineDiff = computeLineDiff(moveTargetRow);if (lineDiff > 0) {  output.append(`\x1b[${lineDiff}B`); // Move down} else if (lineDiff < 0) {  output.append(`\x1b[${-lineDiff}A`); // Move up}output.append(appendStart ? "\r\n" : "\r"); // Move to column 0

用 A / B 而不用绝对定位 \x1b[<row>H:后者的行号是相对屏幕的, 屏幕一滚行号就废了;A / B 相对当前光标,而光标位置是自己记的账 (hardwareCursorRow),账对得上就永远对得上。

  1. 逐行写(:494-551):每行先 \x1b[2K 清整行,再写内容。第一行 不补 \r\n(i > firstChanged 才补),因为前面已经有一个 \r 或 \r\n 了,多写一个会把整段下推一行。

收尾在 :557-572:如果旧内容更长,逐行 \r\n\x1b[2K 清掉多余的,再 \x1b[{extraLines}A 回到新内容末尾,最后 \x1b[?2026l 上屏。

4.2 全量 vs 差分:把字节数算出来

现在可以回答本章的量化问题了。终端 80×24,每行 78 个可见字符,共 150 行。

路径 组成 字节
首次全量 16(同步头尾)+ 150×78 + 149×2(\r\n) 12,014
清屏全量 上面 + 11(\x1b[2J \x1b[H \x1b[3J) 12,025
差分(末行) 8 + 4 + 1 + 78 + 8 99
差分(视口内任一行) 同上,只换行长 99
第 10 行变化 10 < 126 → 退化成清屏全量 12,025

比值:99 / 12,025 = 0.82%。

一个 spinner 每秒 10 帧、转 60 秒:

  • 每帧全量:600 × 12,025 = 7,215,000 字节
  • 每帧差分:600 × 99 = 59,400 字节
  • 差 121 倍

内容小于一屏时(20 行)差分更不划算一点,但也差得远:全量 16 + 20×78 + 19×2 = 1,614,差分仍是 99,省 93.9%。

这张表里有两个容易看错的地方:

  • \x1b[2K 是差分独有的成本。全量渲染每行之间只写 \r\n,不清行—— 因为整屏刚刚清过。差分每行要多花 4 个字节清行,否则短内容覆盖长内容会 留尾巴。
  • 差分不是"绝对省"。如果变化区间有 100 行,差分要写 16 + 100×(4+78) + 99×2 = 8,398,而清屏全量是 12,025——省 30%,不是 99%。差分的收益正比于"没变的行有多少"。

五、一行是一个自包含的字符串

applyLineResets(tui.ts:1456-1465)只做一件事,但它撑起了整套设计:

ts
protected applyLineResets(lines: string[]): string[] {  const reset = SEGMENT_RESET;  for (let i = 0; i < lines.length; i++) {    const line = lines[i];    if (!isImageLine(line)) {      lines[i] = normalizeTerminalOutput(line) + reset;    }  }  return lines;}

SEGMENT_RESET 是 "\x1b[0m\x1b]8;;\x07"(tui.ts:429)。两个东西拼在 一起:复位所有 SGR 属性,并且关闭 OSC 8 超链接。

为什么必须这样做:差分渲染会从任意一行开始写。如果第 40 行设置了一个 前景色没关,第 41 行又是从中间开始写的,那个颜色就会泄到别的地方—— 甚至泄到你下次重绘时画的第一行。行尾复位把"每一行"变成了一个自包含的 状态单元:随便从哪一行开始写,结果都一样。

代价是每行多 11 个字节。150 行就是 1,650 字节——首页全量的 13.7%,但差分 一帧只写一行,所以只多 11。这是一次用"每行恒定开销"换"任意起点正确"的 交易,而且只在全量时贵。

normalizeTerminalOutput 处理的是另一个坑(utils.ts:444):泰语和老挝语 的 AM 元音(\u0e33 / \u0eb3)在显示上占两个单元,但很多终端把它当 一个字符加一个组合符处理,于是"宽度算 2、光标走 1",之后所有列坐标都偏。 这里把它拆成显式的两个码点,让宽度计算和终端行为对齐。

5.1 浮层:把一行切三段再缝回去

浮层(模态框、补全菜单、下拉)不是另开一层画布,而是把内容行切开、 中间那段换成浮层的行。这个操作在 compositeTuiLine(tui.ts:432-461):

ts
// tui.ts:439-458(节选)if (isImageLine(baseLine)) return baseLine;const afterStart = startCol + overlayWidth;const base = extractSegments(baseLine, startCol, afterStart,  totalWidth - afterStart, true);const overlay = sliceWithWidth(overlayLine, 0, overlayWidth, true);const beforePad = Math.max(0, startCol - base.beforeWidth);const overlayPad = Math.max(0, overlayWidth - overlay.width);const result =  base.before + " ".repeat(beforePad) + SEGMENT_RESET +  overlay.text + " ".repeat(overlayPad) + SEGMENT_RESET +  base.after + " ".repeat(afterPad);

extractSegments(utils.ts:1391)把底行切成"前段 / 被盖住 / 后段", 而且是带样式的——after 段会继承 afterStart 处的颜色状态,不会因为切 了一刀就变回默认色。三个细节值得看:

  • 每段后面都补 SEGMENT_RESET。底行前半段可能开着红色,浮层是白的; 不复位,浮层的字就继承了红色。这是 §五 那个不变式在更小粒度上的复用: 不是"每行自包含",而是"每个拼接片段自包含"。
  • beforePad 兜住底行太短。底行只有 10 列,浮层从第 30 列开始——中间 得用空格补齐,否则浮层整体左移。
  • overlayPad 兜住宽字符。浮层声明宽度 20 列,里面夹了个 emoji 占 2 列,实际只切到 19 列;这里补 1 个空格让总宽对齐。

图片行直接原样返回:切一刀等于毁掉整条图片序列。

还有一处顺序要求:合完再找光标(tui-main-screen.ts:266-279)。浮层可能 正好盖住光标标记,那么光标就不该出现——先找后合会在被盖住的旧位置留下 一个游标。

一行一个自包含字符串这个不变式,后面三节(光标、列宽、图片)都建立在 它上面。


六、光标是显式状态

终端不告诉你光标在哪。没有 getCursorPosition(),没有查询协议——你只能 自己记账。

TuiMainScreen 为此维护了七个字段(tui-main-screen.ts:129-136):

ts
private previousLines: string[] = [];private previousWidth = 0;private previousHeight = 0;private cursorRow = 0;private hardwareCursorRow = 0;private maxLinesRendered = 0;private previousViewportTop = 0;

cursorRow 和 hardwareCursorRow 是两个不同的东西,注释里说得清楚 (:606-607):前者是"内容末行",用来算视口;后者是"终端光标真实所在", 用来算该往上还是往下走几行。它们经常不相等——内容长 150 行、屏幕 24 行时, cursorRow = 149,但光标停在屏幕第 23 行。

两个坐标系之间差一个 previousViewportTop:

ts
// tui-main-screen.ts:260-264const computeLineDiff = (targetRow: number): number => {  const currentScreenRow = hardwareCursorRow - prevViewportTop;  const targetScreenRow = targetRow - viewportTop;  return targetScreenRow - currentScreenRow;};

6.1 为什么不用 \x1b[H

\x1b[H 是"回到左上角"。看起来只要每次都从左上角开始写,就不需要记账了。

不行,两个原因:

  1. \x1b[H 回到的是视口左上角,不是内容第 0 行。内容比屏幕长时, 视口已经滚到中间,\x1b[H 落在的是第 126 行。
  2. scrollback 里的行不可写。终端只允许你操作最后 height 行,更早的 内容已经交给滚动缓冲区,任何写入都会先触发滚动。

所以移动只能用相对的 \x1b[{n}A(上)和 \x1b[{n}B(下),而相对移动 必须知道"现在在哪"。这就是那个字段存在的全部理由。

positionHardwareCursor(:628-659)是唯一动光标的地方,它做的三件事:

ts
const rowDelta = targetRow - this.hardwareCursorRow;let buffer = "";if (rowDelta > 0) buffer += `\x1b[${rowDelta}B`; // Move downelse if (rowDelta < 0) buffer += `\x1b[${-rowDelta}A`; // Move upbuffer += `\x1b[${targetCol + 1}G`; // Move to absolute column

行列分开处理:行是相对的,列是绝对的。因为列的范围永远是 [1, width], 绝对定位没有副作用;行的绝对值不可靠(见上),只能用增量。

6.2 真光标要给输入法用

光标默认是隐藏的(hideCursor()),只有在渲染结果里找到光标标记时才 显示并定位。理由不是"好看",是输入法:中日韩输入法的候选框跟着终端光标走。 光标如果留在最后一行的末尾,你打字时候选框会出现在屏幕最下面而不是输入框 旁边。

6.3 假光标:两个零宽标记

但有些组件需要"看起来有光标"却拿不到真光标——比如一个没有焦点的输入框, 或者编辑器里的第二个光标。

ts
// tui.ts:202-208export const CURSOR_MARKER = "\x1b_pi:c\x07";export const FAKE_CURSOR_START = "\x1b_pi:fc\x07";export const FAKE_CURSOR_END = "\x1b_pi:/fc\x07";const FOCUSED_FAKE_CURSOR =  /(\x1b_pi:c\x07)\x1b_pi:fc\x07(.*?)(?:\x1b_pi:\/fc\x07|$)/s;

三个都是 APC 序列(ESC _ 开头、BEL 结尾),终端会整段忽略。所以: 它们是零宽的,visibleWidth 会跳过它们(utils.ts 的 ANSI 剥离覆盖 APC), 折行和切列也不会被它们干扰。

resolveFakeCursors 做最后一层判断(tui.ts:1510-1516):

  • 真光标要显示时,把紧跟在 CURSOR_MARKER 后面的假光标删掉——不然 屏幕上会有两个光标。
  • 其余假光标换成 \x1b[7m(反显)和 \x1b[27m(取消反显)。

反显而不是画一个方块,是因为方块要占一列,会把文本挤走。


七、宽度是列,不是字符

visibleWidth 是整包里调用最多的函数。它有三条路径(utils.ts:250-310):

ts
export function visibleWidth(str: string): number {  if (str.length === 0) return 0;  // Fast path: printable ASCII, tabs, and ANSI escape sequences.  const asciiWidth = asciiVisibleWidth(str);  if (asciiWidth !== -1) return asciiWidth;  const cached = widthCache.get(str);  if (cached !== undefined) return cached;  ...  for (const { segment } of graphemeSegmenter.segment(clean)) {    width += graphemeWidth(segment);  }

注释里那句 "Styled lines take this path, so re-rendering after a theme change does not run grapheme segmentation on every line" 说明了第一条路径的价值: 纯 ASCII 加 ANSI 的行根本不做字素切分。绝大多数代码和英文文本走的就是 这条。

第二条是缓存,512 条,FIFO 淘汰(WIDTH_CACHE_SIZE = 512,:51)。

7.1 五条宽度规则

graphemeWidth(:182-245)里的判断顺序值得抄一遍:

输入 宽度 依据
可打印 ASCII 1 0x20..0x7e 直接返回
\t 3 自定约定,不是 8
区域指示符 🇨 2 保守取 2,见下
网络 emoji 序列(RGI) 2 \p{RGI_Emoji}
组合符 / 零宽 0 p{Default_Ignorable_Code_Point} 等
汉字 2 get-east-asian-width

\t 算 3 列是个约定,不是标准。标准里 tab 是"到下一个制表位", 宽度取决于当前列。终端里这不重要(组件很少输出 tab),但代码必须选一个 数:visibleWidth 把 \t 替换成三个空格,graphemeWidth 也返回 3。 两处保持一致。

区域指示符那句注释值得抄(:211-216):

Regional indicator symbols are often rendered as full-width emoji in terminals, even when isolated during streaming. Keep width conservative (2) to avoid terminal auto-wrap drift artifacts.

流式输出会把 🇨🇳 的两半分开到达。单个区域指示符在某些终端里渲染成 1 列, 在某些里 2 列。选 1 的话,如果终端按 2 渲染,光标就偏了一列,而偏一列 之后每一次换行都会偏——这类错位是不可恢复的。所以宁愿保守。

7.2 超宽不是截断,是崩溃

组件超宽时,渲染器选择的不是"截到宽度",而是抛异常(:522-549):

ts
output.append("\x1b[2K"); // Clear current lineif (!isImage && visibleWidth(line) > width) {  const crashLogPath = path.join(this.logDirectory ?? os.tmpdir(),    "pi-tui-crash.log");  ...  this.stop();  throw new Error(errorMsg);}

它甚至先把全部渲染行写成一份 crash log 再崩。这段代码的设计意图写在错误 信息里:

Rendered line 24 exceeds terminal width (86 > 80). This is likely caused by a custom TUI component not truncating its output. Use visibleWidth() to measure and truncateToWidth() to truncate lines.

为什么不能"宽容地截断":一行超过宽度会触发终端自动换行,于是这一行 实际占两行屏幕,但代码以为它占一行。之后每一个 \x1b[1B 都多走一行, 视口计算全错,光标乱跳,而且下一次重绘也修不回来,因为 previousLines 和真实屏幕已经错位了。

自动换行是这套设计里唯一不可恢复的错误,所以它选择了崩。

7.3 截断和折行要带 ANSI 状态

truncateToWidth、sliceByColumn、wrapTextWithAnsi 都在 utils.ts。 它们都要处理同一件事:把一个带样式的行切开后,后半段不能丢掉前面的样式。

AnsiCodeTracker(:595)逐个属性记账:

text
bold / dim / italic / underline / blink / inverse / hidden / strikethroughfgColor / bgColor / activeHyperlink

颜色不只是"31",还有 38;5;240(256 色)和 38;2;r;g;b(真彩),所以 存的是完整参数串。折行时在下一行开头重放当前状态,行尾再复位。

OSC 8 超链接有个额外的坑,注释写得很具体(:608-612):URL 有两种结束符, BEL(\x07)和 ST(\x1b\\)。有些终端只让 BEL 结尾的链接可点。 OAuth 登录 URL 用 BEL,如果折行时重开成 ST,就只有第一行能点。 所以 tracker 保存的是原始结束符,而不是归一化后的。

一个看起来纯视觉的东西,底下是一个协议状态机。


八、同步输出与有界写入

所有渲染都被一对序列包着:

text
\x1b[?2026h   ← 开始同步输出(DECSET 2026)…内容…\x1b[?2026l   ← 结束同步输出

终端收到 h 之后开始缓冲,收到 l 才一次性上屏。没有这个,用户会看到 "清了一半"的中间态——尤其是一帧写了 12 KB 的时候。

差分也要包。虽然只写一行,但那一行的 \x1b[2K 和内容是两次写入, 中间上屏就是一次闪烁。

8.1 为什么还要分块

写入不是一次 terminal.write(bigString),而是经过 BoundedTerminalWriter(tui-main-screen.ts:21-77):

ts
// tui-main-screen.ts:12const MAX_RENDER_WRITE_CHARS = 1024 * 1024;

注释解释了原因(:15):"so a full render never forms one string large enough to exceed V8's limit"。一块 1 MiB 的字符串在终端里不算大,但一个全屏 Kitty 图片的 base64 可以到几十 MB,拼成一个大字符串就会撞上 V8 的字符串 长度上限。

分块的一个细节是不能劈开代理对(:44-52):如果切点正好落在一个 emoji 的 UTF-16 高位和低位之间,两半分别写出去就是两个替换字符。

代价是:一次渲染变成多次 write()。所以分块必须发生在同步输出块内部, 否则每块之间都会上屏一次。


九、两种屏幕

pi-tui 有两个屏幕实现,行数差三倍:

TuiMainScreen TuiAltScreen
用哪块屏 终端主屏 + scrollback 备用屏(\x1b[?1049h)
历史存在哪 终端自己 代码里的 lastDocument
每帧写多少 差分(可能只写一行) 全量(一屏)
视口由谁维护 previousViewportTop 追终端 自己维护 scrollTop
退出后 内容留在终端里 恢复原来的屏幕
行数 660 1,800

60 行对 1,800 行,多出来的不是渲染,是一个迷你窗口系统:滚动条、鼠标 选区、双击选词、搜索高亮、剪贴板、闪烁提示。

9.1 为什么 main screen 是默认

聊天式 UI 想要"上面是历史、下面是输入框、滚上去还能看"。这些需求主屏 天然满足:历史就是 scrollback,会话结束后用户还能往上翻。

代价就是 §三 第 9 条那个 24 行窗口——能改的只有最后一屏。

alt screen 反过来:整块屏幕归你,想怎么画怎么画,但退出时一切都消失。 所以它每帧都全量重绘(一屏就是全部内容),靠 \x1b[?7l 关掉自动换行 (tui-alt-screen.ts:65)来避免"一行超宽把整个视口滚掉"。

9.2 切屏要交接状态

主屏切到备用屏再切回来,previousLines 全都作废了。所以有一对方法专门 处理这件事(tui-main-screen.ts:138-159):

ts
restoreRenderState(state: TuiMainScreenRenderState): void {  this.previousLines = state.previousLines.map((line) =>    isImageLine(line) ? "" : line);  this.previousKittyImageIds = new Set();  this.previousWidth = state.previousWidth;  ...}

注意两处刻意的改写:图片行变成空字符串,图片 id 集合清空。因为图片是用 Kitty 协议"贴"在屏幕上的,切屏时那个贴图已经不在了;如果还认为它在, 下次差分就会跳过重画,留下一块空白。

beforeTerminalStop(:171-179)是退出时的收尾:把光标移到内容之后、 补一个 \r\n。不补的话,shell 的提示符会直接盖在最后一行上。


十、图片是行,不是像素

Kitty 图形协议里,图片不是"画在某个格子里",而是占 N 行。终端把 N 行的高度让出来给这张图,光标按行移动。

于是 newLines 里的一个"图片行"只是一个标记(\x1b_G…),但它实际覆盖 rows 行。这对差分是致命的:只重画标记那一行,下面 N-1 行还是旧图。

10.1 扩范围

ts
// tui-main-screen.ts:220-228(节选)const expandForLines = (lines: string[]): void => {  for (let i = 0; i < lines.length; i++) {    if (extractKittyImageIds(lines[i]).length === 0) continue;    const blockEnd = i + this.getKittyImageReservedRows(lines, i) - 1;    if (i >= firstChanged || (i <= lastChanged && blockEnd >= firstChanged)) {      expandedFirstChanged = Math.min(expandedFirstChanged, i);      expandedLastChanged = Math.max(expandedLastChanged, blockEnd);    }  }};

两次调用,一次扫 previousLines、一次扫 newLines——因为"旧图要删"和 "新图要画"是两个不同的行。门槛也宽:只要图片块碰到变化区间就扩。

getKittyImageReservedRows(:199-211)还要往下数空行:图片后面通常是 几行空白占位,它得数出这段连续空白有多长。碰到非空行就停——那是别人画的。

10.2 删图必须在画之前

\x1b[2K 擦不掉图片。所以每次重画图片区域之前,必须先发 deleteKittyImage(id)(:236-247),否则旧图会叠在新图上面。

这也是为什么全量重绘要带一个 clear 参数:清屏(\x1b[2J)同样擦不掉 Kitty 图片,必须显式删 id。

10.3 清图会滚动,就退全量

ts
// tui-main-screen.ts:500-508if (imageReservedRows > 1) {  const imageStartScreenRow = i - viewportTop;  if (imageStartScreenRow < 0    || imageStartScreenRow + imageReservedRows > height) {    logRedraw(      `kitty image pre-clear would scroll (${imageStartScreenRow}`      + ` + ${imageReservedRows} > ${height})`,    );    fullRender(true);    return;  }

清图片时得先往下走 imageReservedRows - 1 行。如果图片底部已经超出视口, 这一走就会触发滚动,整个视口偏移,之后所有坐标都错。所以这种情况 直接放弃差分。

10.4 离屏图片要缓存

alt screen 里滚动时,图片会暂时离开视口。再滚回来时如果重新传输一遍 base64 会很慢,所以它缓存最近 16 张(tui-alt-screen.ts:78-80):

ts
const MAX_CACHED_OFFSCREEN_KITTY_IMAGES = 16;const MAX_CACHED_OFFSCREEN_KITTY_TRANSMISSION_BYTES = 32 * 1024 * 1024;const MAX_CACHED_OFFSCREEN_KITTY_DECODED_BYTES = 64 * 1024 * 1024;

三个上限:张数、传输字节、解码后字节。解码后是传输的 2 倍——因为缓存的是 像素而不是 base64。


十一、输入侧:把一次 read 拆成按键

写出去难在省字节,读进来难在分帧。

process.stdin 给你的是一团字节。一个鼠标点击 \x1b[<35;20;5M 可能分三次 到达:\x1b、[<35、;20;5M。如果第一段就被当成 Esc 键处理,用户的 点击就变成了"退出"。

StdinBuffer(stdin-buffer.ts,480 行)就是干这个的。文件头示例写得 比我能写的清楚:

The mouse SGR sequence \x1b[<35;20;5m might arrive as:

  • Event 1: \x1b
  • Event 2: [<35
  • Event 3: ;20;5m

它认五种序列族,每族的结束条件不同:

族 前缀 结束条件
CSI ESC [ 最后一个字节在 0x40..0x7e
OSC ESC ] BEL 或 ESC \
DCS ESC P ESC \
APC ESC _ ESC \
SS3 ESC O 一个字节

还有两个特例:老式鼠标 ESC [ M 后面跟三个原始字节(不看范围), 以及括号粘贴 \x1b[200~ … \x1b[201~——里面可以有任何东西,包括看起来 像 Esc 的字节。

11.1 两个超时

场景 等待 为什么
一个不完整的序列 50 ms 给分批到达留时间
一个孤立的 ESC 10 ms 它可能真的是 Esc 键
同上,但在 SSH 里 100 ms 高延迟链路

resolveEscapeTimeoutMs(terminal.ts:150-159)只看两个环境变量:设了 PI_TUI_ESC_TIMEOUT 就用它,否则 SSH_CONNECTION / SSH_TTY 存在就取 100 ms。注释解释了为什么 SSH 要长:旧式 Alt+键就是 ESC 加一个字节, 网络延迟一大,两段就分家了,10 ms 会把每个 Alt 组合都误判成"Esc 然后一个 字符"。

11.2 键盘协商:用 DA1 当哨兵

不同终端支持的键位编码能力差三代:

  1. 旧序列(ESC [ A = 上箭头),丢了几乎所有修饰键
  2. modifyOtherKeys(xterm 扩展)
  3. Kitty 键盘协议(能区分按下/重复/松开,能报 base layout key)

要问终端"你会不会",标准的做法是发一个查询然后等回复。但"等多久"是个 老问题:等短了老终端来不及回,等长了每次启动都卡。

这里的解法很聪明(terminal.ts:302-316):

ts
const KITTY_KEYBOARD_PROTOCOL_QUERY = `\x1b[>${7}u\x1b[?u`;

先发"我要这三个能力"(7 = 1 disambiguate + 2 event types + 4 alternate keys),再发"你现在是什么状态",最后发一个 DA1 查询 \x1b[c。

DA1(设备属性)是所有终端都支持的。于是:

  • 先收到 Kitty 回复 → 启用 Kitty 协议。
  • 先收到 DA1 → 这个终端不认识 Kitty,退回 modifyOtherKeys。
  • 两条路都不需要超时。总有一个回复会先到。

这是"用一个所有终端都实现的最老功能,给一个新功能当哨兵"。0 毫秒启动 延迟,没有猜测。

11.3 三层解析

keys.ts(1,511 行)对外导出十一个符号,但解析的主入口只有 matchesKey(data, keyId)(:909):

ts
let modifier = 0;if (shift) modifier |= MODIFIERS.shift;if (alt) modifier |= MODIFIERS.alt;if (ctrl) modifier |= MODIFIERS.ctrl;if (superModifier) modifier |= MODIFIERS.super;

shift=1 / alt=2 / ctrl=4 / super=8,和 Kitty 协议一致。LOCK_MASK = 64 + 128 是 Caps Lock 和 Num Lock——它们会出现在修饰键位里,但不算修饰,必须 掩掉,否则开了大写锁定之后所有快捷键都失灵。

然后按 key 分派,每条分支里最多试三种编码:

ts
return (  data === "\x1b" ||  matchesKittySequence(data, CODEPOINTS.escape, 0) ||  matchesModifyOtherKeys(data, CODEPOINTS.escape, 0));

1,511 行里绝大部分是这张"键名到码点"的表,以及三个解析器。真正的逻辑 只有一句话:同一个键,三种编码,任意一种匹配就算按下。

KeyId 还是个类型(:152):Key.ctrl("c") 之类返回的是字面量联合类型, 写错键名是编译错误,不是运行时静默失败。

11.4 Kitty 的 CSI-u:六种变体,一个正则

三层解析里最绕的是最上面那层。Kitty 协议在 CSI-u 里塞了两组可选字段 (:625-645):

ts
// keys.ts:626-632(原注释照抄)// CSI u format with alternate keys (flag 4):// \x1b[<codepoint>u// \x1b[<codepoint>;<mod>u// \x1b[<codepoint>;<mod>:<event>u// \x1b[<codepoint>:<shifted>;<mod>u// \x1b[<codepoint>:<shifted>:<base>;<mod>u// \x1b[<codepoint>::<base>;<mod>u (no shifted key, only base)

两个位置各有两个冒号段:

  • 码点后面跟 :shifted(Shift 之后的字符,比如 Shift+2 的 @)和 :base (PC-101 布局上那个键的码点,给俄语输入法这类非拉丁布局用)。
  • 修饰键后面跟 :event(1 按下 / 2 重复 / 3 松开)。

六种组合被一个正则吃下(:636):

ts
const csiUMatch = data.match(  /^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?u$/);

注意第二组是 (\d*) 而不是 (\d+)——\x1b[97::98;5u 里的 :: 表示 "有 base 没有 shifted",冒号中间是空的。用 \d+ 就匹配不上这一种。

解析出来 modifier: modValue - 1:协议里修饰键位是"1 + 位掩码",单独 按下时值是 1,减掉之后才是 0。

同文件还有三条分支处理不走 CSI-u 的键(:648-713):箭头 \x1b[1;<mod>A/B/C/D、~ 结尾的功能键、Home/End 的 H/F。其中 F3 特意不走 \x1b[1;<mod>R 而是走 \x1b[13~——因为前者和光标位置报告 (CPR)的格式撞车,解析器分不清这是 F3 还是终端在汇报光标位置。


十二、主题:颜色不是选出来的,是算出来的

前面十一节算的都是字节和列。最后还剩一件事没算:颜色从哪来。

README 说 Pi 有四个可定制面——extensions、skills、prompt templates、 themes。前三个书里都有节(M07、M08 §五、M08 §六),只剩第四个。 它不在 tui 包里:tui 的 colors.ts(367 行)只管"把 RGB 变成 SGR 字节";"这个 token 该是什么颜色"这一层语义在 coding-agent 里:

文件 行数
theme.ts 1,107
system-theme.ts 656
theme-controller.ts 254
theme-schema.ts 147
theme-tokens.ts 122

五个文件 2,286 行,外加 components/theme-selector.ts(68 行)和 10 个 测试文件。一份"配色",在真仓库里是这个体量。

12.1 色相是借的,亮度是算的

默认主题叫 system。名字容易误会——它不选颜色,它从终端借颜色。 system-theme.ts:4-9:

Hue and saturation come from the terminal's palette color for the family's ANSI slot... Lightness comes from the rules alone.

14 个色族(FAMILIES,:49-64),每族只声明三样:自己的 hue、饱和度 上下限、以及从终端 ANSI 调色板的第几个槽位借色:

ts
// system-theme.ts:49-64(节选,对齐有调整)const FAMILIES = {  blue:   { hue: 231.49, saturation: { min: 0.1, max: 0.68 }, slot: 4 },  green:  { hue: 158.68, saturation: { min: 0.1, max: 0.76 }, slot: 2 },  red:    { hue: 20,     saturation: { min: 0.1, max: 0.92 }, slot: 1 },  yellow: { hue: 82.36,  saturation: { min: 0.5, max: 1 },    slot: 3 },  orange: { hue: 52,     saturation: { min: 0.12, max: 0.85 }, slot: 3 },};

于是同一个 system 主题,在不同终端里颜色不一样——因为色相本来就 该跟终端走(iTerm 的蓝和 Windows Terminal 的蓝不是一回事)。而对比度 在任何终端里都一样,因为亮度不跟终端走。

这一点值得记住:哪些属性该继承环境、哪些必须自己定,是设计问题, 不是技术问题。 色相继承环境叫"融入",亮度继承环境叫"看不清"。

12.2 把设计规则写成曲线

亮度不查表,解方程。LEVELS(:147 起)每个等级给一组五阶多项式:

ts
interface Curve {  coefficients: number[];      // 五阶多项式  reachable: [number, number]; // 这套系数能达到的区间}// system-theme.ts:149(panel 等级,暗色背景){ coefficients: [0.29131, -0.39746, 2.33185, -0.85524, -1.2076, 0.86276],  reachable: [0, 0.979] }

输入是背景(或面板)的 OKLab 亮度,输出是这个 token 站在上面需要的 亮度。想法很直白:背景越暗,前景就得越亮;但"越亮多少"不是线性的, 所以拟合一条曲线,而不是写一句 if (dark) 变亮。

reachable 是这套系数的能力边界:背景亮到 0.98 以上就做不到这个 等级,这时降级要求,而不是硬算出一个做不到的颜色。注释原话: beyond it the level is relaxed。

两个可以带走的方法:

  1. 把规则写成函数,不写成色板。 色板是结果,规则可移植。换一套 品牌色,只要改 FAMILIES,14 个族的亮度全自动适配。
  2. 给规则加能力边界。 reachable 把"做不到"变成一段显式代码, 而不是一个悄悄难看的颜色。

12.3 100 毫秒,和迟到的回复

问终端要颜色的代码只有 20 行(theme-controller.ts:20-40):

ts
const TERMINAL_QUERY_TIMEOUT_MS = 100;query = ui.queryTerminalColors({ timeoutMs: TERMINAL_QUERY_TIMEOUT_MS,                                 onLateReply: apply });

100 毫秒不是拍脑袋:颜色查询后面紧跟一条 DA1 请求当哨兵(就是 §11.2 那个套路),正常终端会连着回。所以 100ms 足够区分"慢"和"根本不会回"。 等不到就先画灰的,回了再改——onLateReply 传的就是 apply 本身。

这和 §八 的有界写入是同一条纪律:帧的时机不能交给外部设备。 终端 不回颜色,界面照样要在 100ms 内出现;SSH 慢到颜色三秒后才到,也不 重画整屏。

12.4 三档降级

system-theme.ts:16-19 把终端能力分三档,生成三种主题:

终端报了什么 生成什么
背景 + 调色板 色相来自调色板,亮度来自背景
只有背景 色族自带的 hue,亮度来自背景
什么都不报 直接输出 ANSI 索引,让终端自己渲染

外加一条:system 是保留名,自定义一个叫 system 的主题会被忽略。

这一节和 §七 的宽度、§十一 的键盘协商是同一类问题: 你在跟一个 不守规矩、能力未知、还可能不回话的终端谈判。三种态度——假设它听话 (超宽就崩)、问清楚再画(卡住)、先画再随时纠正(这一节)。只有 第三种能同时满足"不卡"和"对"。


十三、完整链路

把写和读拼起来,一次按键到一次重绘:

text
【写】组件树 | |  component.render(width) -> string[] |    每行是完整的终端字节:SGR + OSC 8 + 也许一个 APC 光标标记 vContainer.render(width)          按顺序拼接子组件的行 | vdoRender()   (tui-main-screen.ts:250) | +-> render(width)               整棵树,永远全量 +-> compositeOverlays()         浮层按列切开,贴到目标行 +-> extractCursorPosition()     合成之后再找标记(浮层可能盖住它) +-> applyLineResets()           每行尾补 \x1b[0m\x1b]8;;\x07 | +-> 扫 firstChanged / lastChanged      O(n) 字符串比较 | +-> 十条出路选一条       |       +-> fullRender(false)      首帧:不清屏,只写行       +-> fullRender(true)       清屏 + 删图片 + 全部行       +-> 差分                     firstChanged .. lastChanged       +-> 只挪光标                 零行变化,但光标可能在动 | vBoundedTerminalWriter            1 MiB 分块,不劈代理对 |  \x1b[?2026h  ...  \x1b[?2026l vprocess.stdout【读】process.stdin(raw mode + bracketed paste) | vStdinBuffer                      ESC 序列重组,五种族 + 两个超时 |  括号粘贴整段透传:\x1b[200~ ... \x1b[201~ vProcessTerminal 的 data 监听 | +-> 是键盘协议协商的回复?   -> 置标志,不转发 +-> 是主题 / 光标位置回复?  -> 更新状态,不转发 | vmatchesKey(data, "ctrl+c")       三层解析:Kitty / modifyOtherKeys / 旧序列 | vComponent.handleInput(data) | vrequestRender()  ->  16 ms 节流  ->  doRender()

图上有一处值得停一下:读和写走的是同一条时间线。按键触发 requestRender(),而 requestRender 只能等 16 ms 节流窗口( tui.ts:524 的 MIN_RENDER_INTERVAL_MS)。所以按下键到看见字符最多 16 ms 的延迟——这是用户能感知的边界。

所以有一个例外:requestImmediateRender(:1044-1059)。它的注释说明了 优先级:

A previously queued scheduleRender() can create a timer before this callback runs. User input must preempt that throttled frame.

动画可以让路,键盘不行。tui-render.test.ts:120 那条用例的名字就是 "renders keyboard input without waiting for a throttled frame"。


十四、工程暗坑

1. 差分只在最后一屏内成立。 previousViewportTop = max(0, bufferLength - height)(tui-main-screen.ts:318)。 150 行内容 + 24 行屏幕 → 窗口是第 126 行往后。改第 10 行必然全量重绘, 12 KB 一个字节都省不掉。性能问题先量这个数,再谈优化。

2. 清行用 \x1b[2K,不是 \x1b[K。 后者只从光标清到行尾。光标可能停在列 40,前半行的旧内容会留着。差分里 永远写 2K(:521)。

3. 行尾不复位,样式会泄到下一帧。 SEGMENT_RESET = "\x1b[0m\x1b]8;;\x07"(tui.ts:429)。两件事一起做:关 SGR 属性,关 OSC 8 超链接。少关后者,后面所有文本都变成可点链接。

4. \t 在这个代码库里是 3 列。 graphemeWidth 里 if (code === 0x09) return 3,visibleWidth 里把 \t 换成三个空格。按 8 算,所有含 tab 的行宽度都会算错,然后触发第 5 条。

5. 超宽是崩溃,不是截断。 一行超宽会让终端自动换行,这一行实际占两行屏幕,而代码以为占一行。 之后每个 \x1b[1B 都多走一行,previousLines 和真实屏幕永久错位。 所以它写一份 pi-tui-crash.log 然后 stop() + throw(:522-549)。 日志默认落在 os.tmpdir(),因为崩溃时不能指望配置的目录还可写。

6. cursorRow 和 hardwareCursorRow 混用,光标越跳越偏。 前者是内容末行,后者是终端光标真实行。只在一处更新另一个,误差会累积 ——因为相对移动是"从当前位置走",起点错了就再也回不来。

7. maxLinesRendered 只增不减。 它是一个高水位。一个临时的超高组件(比如展开的大 diff)会把水位抬高, 之后正常内容变短时,clearOnShrink 的判定会误以为"缩了很多"而全量重绘。 tui-render.test.ts:917 那条用例的名字就叫 "clears stale content when maxLinesRendered was inflated by a transient component"。

8. Termux 的高度变化不能全量。 软键盘弹出会改 rows。按标准流程全量重绘的结果是:每敲一个字,整个 历史在屏幕上重放一遍。所以这里有个例外(:352-356),代价是视口可能 对不齐。

9. OSC 133 标记必须剥掉。 有些 shell 集成会往输出里插 \x1b]133;A 之类的提示符标记。如果原样写回 终端,终端会把它读成"新提示符开始",进而结束程序状态(OSC 7501)。 所以渲染前统一剥掉(:268-269)。

10. 图片行必须扩范围,且删图在画之前。 \x1b[2K 擦不掉 Kitty 图片。只重画标记那一行,下面 rows-1 行还是旧图; 不先 deleteKittyImage(id),新图会叠在旧图上。

11. 清图会滚动时退全量。 imageStartScreenRow + imageReservedRows > height → 清图前的下移会触发 滚动,视口偏移之后所有坐标都错(:500-508)。

12. 分块不能劈开代理对。 1 MiB 的切点如果落在 emoji 的 UTF-16 高/低位之间,两半就是两个替换字符 (:44-52)。


十五、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。

测试用 Node 自带的 node --test(packages/tui/package.json 的 test 脚本),不需要额外安装。@xterm/headless 是开发依赖,用来做真正的终端 模拟——断言的不是字节,是"屏幕上现在是什么"。

bash
cd packages/tuinode --test test/tui-render.test.ts

实验 1:spinner 只写一行

bash
node --test --test-name-pattern="spinner" test/tui-render.test.ts

判据:用例名 "renders correctly when only a middle line changes (spinner case)"(tui-render.test.ts:721)通过。它改中间一行,然后断言其余行的 屏幕内容没变。

实验 2:确认走的是差分,不是全量

bash
node --test --test-name-pattern="differential" test/tui-render.test.ts

判据:"splits large differential updates without a full redraw"(:190) 里那句断言:

ts
assert.ok(!output.includes("\x1b[2J"),  "the update should stay on the differential render path");

\x1b[2J 出现就是全量。这是判断"差分有没有生效"最省事的办法: 抓终端写入流,搜这四个字节。

实验 3:量字节

照 test/render-churn-bench.ts 的写法做一个 NullTerminal——它把 write(data) 换成 bytesWritten += data.length。跑两帧:

  1. 每帧改最后一行(spinner)
  2. 每帧改第 0 行、内容 20 行(小于一屏)

判据:第一组每帧约 99 字节,第二组也约 99 字节,而全量是 12,025 和 1,614(§4.2 的表)。再试第三组:150 行内容改第 0 行—— 字节数会跳回 12,025,因为 0 < 126。

实验 4:列宽

bash
node --test test/visible-width.test.ts test/wrap-ansi.test.ts

判据:test/regression-regional-indicator-width.test.ts 也一起跑——那条 回归用例守的就是 §7.1 说的"区域指示符保守取 2"。

实验 5:输入分帧

bash
node --test test/stdin-buffer.test.ts test/keys.test.ts

判据:把一条鼠标序列拆成三次 process() 喂进去,data 事件只应触发一次。 再把 Kitty 回复拆开喂,协议标志应当在重组之后才置位。

实验 6:看 churn

bash
node test/render-churn-bench.ts

判据:输出两行,static 和 editor,每行带 written bytes/frame。 static 那一行的字节数接近 0——什么都没变,一帧只写同步输出的两个标记。


五句话

如果只记五句:

  1. 把"画"和"写"拆开。 组件永远全量重画,渲染器只写变了的行。
  2. 每行自包含。 开头清行、结尾复位,任意起点写都正确。
  3. 差分的窗口只有一屏高。 更早的行进了 scrollback,物理上改不了。
  4. 不可恢复的错误要当场崩。 超宽会触发自动换行,错了修不回来。
  5. 宽度是列不是字符。 CJK、emoji、代理对都要按列算。

本章小结

  1. 一帧只写变了的行:spinner 99 字节,全量 12,025。
  2. 一行是自包含字符串:自带清行、回车、复位。
  3. 光标是显式状态,不是副作用。
  4. 宽度是列不是字符;超宽直接崩,不截断。
  5. 同步输出把一帧包成一对标记,避免撕裂。

概念回顾

术语 一句话 在哪
差分 只写变了的行;\x1b[2J 出现就是全量 §四
自包含行 每行自带清行与复位,任意起点正确 §五
显式光标 光标位置存在状态里,不靠推断 §六
列宽 判宽用列,不用字符数 §七
同步输出 一帧包成一对标记,防撕裂 §八

练习

练习 1(读):§十五 实验 3 说 150 行内容改第 0 行,字节数跳回 12,025。 为什么改第 0 行反而比改最后一行贵?→ 回 §4.2 的表与那个行号判据。

练习 2(改):把实验 3 的 NullTerminal 里 bytesWritten += data.length 改成 Buffer.byteLength(data)。预期:含中文时字节数变大(字符数≠字节数); 回滚:改回 data.length。

常见误区

  1. 你会以为 一帧写多少字节不重要;实际是 差分与否差两个数量级; 证据 §4.2 的表。
  2. 你会以为 宽度超了截断更安全;实际是 直接崩,因为自动换行修不回来; 证据 §7.2。
  3. 你会以为 颜色是选出来的;实际是 按对比度曲线算出来的;证据 §十二。

读完自检

四条,能不能不看稿说出来?

自检 一句话答案 不会就去
一帧该写多少字节? spinner 只写 99 字节——差分只写变了的那一行 §一、§四
每行为什么要自带清行和复位? 让"任意起点正确",否则差分渲染全崩 §五
宽度超了为什么直接崩,不截断? 超宽会触发终端自动换行,错了再也修不回来 §7.2
颜色为什么各终端不一样,对比度却一样? 色相与饱和度借终端的调色板,亮度由对比度曲线算 §12.1

十六、收束

16.1 三个可迁移的方法

一、把"画"和"写"彻底分开。 组件每次返回整棵树的完整行(全量、无状态、可缓存),渲染器负责找出差异 并只写变化。两边都不需要知道对方的优化。这条分界线让 46 个文件里只有 660 行在管"怎么少写"。

二、让每个输出单元自包含。 每行开头清行、结尾复位。看起来浪费(每行多 15 字节),换来的是 任意起点正确——而差分渲染的本质就是"从任意一行开始写"。这条不变式 一旦破坏,所有优化都会变成 bug 生成器。

三、把不可恢复的错误变成崩溃。 超宽触发自动换行、代理对被劈开、图片被 2K 漏掉——这些错误的共同点是 "错了之后再也修不回来"。对这种错误,最省事的处理是当场崩,并且把全部 上下文写成一份日志(pi-tui-crash.log 里有每一行的宽度和内容)。 宽容的降级只适用于可恢复的错误。

16.2 这章的边界

没讲的部分:

  • components/editor.ts(2,484 行):撤销栈、kill ring、多行编辑、单词 跳转。本章只用到它的 CURSOR_MARKER。
  • latex.ts(1,507 行):公式转 Unicode 近似,与渲染主线无关。
  • tui-alt-screen.ts(1,801 行)的交互层:鼠标选区、双击选词、搜索高亮、 滚动条拖拽。本章只讲了它的屏幕模型和缓存上限。
  • native/(不在 src/ 里):剪贴板的 N-API 绑定,darwin / linux / win32 三套实现。
  • autocomplete.ts(859 行):补全触发与上下文推断。

一个数字修正:tui 是 46 文件 / 19,971 行,不是 17,734。后者只算了 src/ 的一部分。

16.3 下一站

下一章:M15 schema + telemetry——什么值算合法,什么允许进日志。

M15 讲 schema 与 telemetry:前者 43 文件 / 4,565 行,是一个不用 eval 的 JSON Schema 校验器;后者 8 文件 / 1,572 行,是一套与厂商无关的遥测契约。前一章在省字节,最后一章在定边界——什么值算合法,什么允许进日志。


本章源码索引

文件 行数 职责
tui-main-screen.ts 660 差分渲染:扫描、十条出路、光标记账、图片扩范围
tui.ts 1,549 Component 契约、叠层合成、假光标、16 ms 节流
tui-alt-screen.ts 1,800 备用屏:布局、滚动、选区、搜索、剪贴板
utils.ts 1,467 visibleWidth、truncateToWidth、wrapTextWithAnsi、AnsiCodeTracker
terminal.ts 639 raw mode、键盘协商、StdinBuffer 接线、进度条
stdin-buffer.ts 480 五种 ESC 序列族的重组与两个超时
keys.ts 1,511 键名表、三层解析(Kitty / modifyOtherKeys / 旧序列)
layout.ts 453 布局树、裁剪矩形、按 (组件, 宽度) 缓存
layout-node.ts 51 组件的布局节点接口
components/stack.ts 154 basis / grow / shrink 的尺寸分配
components/scroll-view.ts 224 滚动窗口与滚动条几何
components/editor.ts 2,483 编辑器:撤销栈、kill ring、补全
components/markdown.ts 1,120 marked + CJK 折行 + 代码块高亮
terminal-image.ts 783 Kitty / iTerm2 协议、能力探测、图片尺寸
colors.ts 367 调色板与 SGR 生成(没有用 chalk)
coding-agent/.../theme/theme.ts 1,107 主题模型:token、外观、加载、导出
coding-agent/.../theme/system-theme.ts 656 system 主题:14 个色族、对比度曲线
coding-agent/.../theme/theme-controller.ts 254 终端颜色查询、100 ms 超时、迟到回复
test/virtual-terminal.ts 220 用 @xterm/headless 做真实终端模拟
test/render-churn-bench.ts 205 分配量与每帧写入字节的基准