终端渲染 —— 一个 spinner 只该写 99 个字节
你人在咖啡馆,笔记本连着手机热点,SSH 到公司的开发机。
Agent 在跑,底下的 spinner 在转。你看着它转,每转一格都一顿。滚回去看十几分钟前 的输出,屏幕跳一下,光标回到最底下。你等了一分多钟,觉得哪里不对, 敲了一个字,输出突然刷了一屏。
本地跑同样的东西一点都不卡。区别在链路上:字节从开发机出来,先到 SSH, 再到热点,再到你面前这个终端模拟器。链路上每一跳都要转发你写出去的每一个字节。
而跑内容满屏的 Agent 对话,最朴素的做法是每帧重画一遍全局:
清屏 → 从第 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 毫秒 换一帧。最朴素的做法是每帧重画:
清屏 → 从第 0 行画到第 149 行一帧 12 KB,一秒十帧 120 KB,转一分钟 7.2 MB 打进一个伪终端。本地看不出 问题;走 SSH、走 tmux、走浏览器里的终端模拟器,就开始肉眼可见地卡。
而实际上,这一帧里只有一行变了。
pi-tui 的核心就是这一件事:把"画"和"写"拆开。组件永远重画整棵树
(render(width): string[]),但渲染器只把变了的行写出去。同一个 spinner,
一帧 99 个字节。
99 是怎么来的,这是本章的主线:
\x1b[?2026h 8 同步输出的开始\x1b[2K 4 清掉这一行\r 1 回到第 0 列"…spinner…" 78 这一行的内容\x1b[?2026l 8 同步输出的结束一章 46 个文件,最后落在这五个片段上。中间所有东西——布局、列宽、 ANSI 状态、光标记账、图片、按键——都是为了让这五个片段正确。
二、组件只有一条契约
整个 UI 层只有一个必选方法:
// 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。整个"差分"发生在字符串层面:
if (oldLine !== newLine) { /* 这一行变了 */ }这个选择决定了后面所有事情。好处是简单到可以一次读完;代价是组件必须 自己保证"同一份数据 + 同一个宽度 = 同一个字符串",否则每一帧都会被判定 为"全变了"。
所以组件里到处是缓存:
// 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):
// 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)的权重:
// 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):
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);四步,顺序不能换:
render(width):整棵树渲染成行。这一步永远是全量。- 叠层合成:把浮层按列切开、贴到目标行上。
- 取光标:在合成之后找
CURSOR_MARKER,因为浮层可能盖住它。 - 加行尾复位:每条非图片行末尾补
\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):
const bufferLength = Math.max(height, newLines.length);this.previousViewportTop = Math.max(0, bufferLength - height);也就是说:差分的窗口只有终端高度那么高。150 行内容、24 行屏幕,
previousViewportTop = 126——第 10 行变了,它早就在 scrollback 里,改不了,
只能全量。
这不是省不省字节的问题,是物理上做不到。终端没有"回到第 10 行"这种 操作,你只能往下滚、或者清屏重来。差分渲染的所有设计都被这一条约束着。
四、扫描与差分
扫描本身很简单(:367-393):
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):
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):
// 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),但它最该逐行读:
// 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;}五件事,顺序不能换:
- 开同步输出。此后所有字节进终端缓冲区,直到
\x1b[?2026l。 - 先删图片。
\x1b[2K擦不掉 Kitty 图片,必须显式发删除序列。 - 把目标行挪进视口。
moveTargetRow > prevViewportBottom表示要改的行 还在屏幕下方(内容比屏幕长)。先下移到屏幕底,再\r\n滚scroll行。 滚动会让prevViewportTop和viewportTop一起增大,两个变量必须 同步——漏一个,后面所有相对坐标全错。 - 相对移动光标(
:483-490):
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),账对得上就永远对得上。
- 逐行写(
: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)只做一件事,但它撑起了整套设计:
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):
// 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):
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:
// 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 是"回到左上角"。看起来只要每次都从左上角开始写,就不需要记账了。
不行,两个原因:
\x1b[H回到的是视口左上角,不是内容第 0 行。内容比屏幕长时, 视口已经滚到中间,\x1b[H落在的是第 126 行。- scrollback 里的行不可写。终端只允许你操作最后
height行,更早的 内容已经交给滚动缓冲区,任何写入都会先触发滚动。
所以移动只能用相对的 \x1b[{n}A(上)和 \x1b[{n}B(下),而相对移动
必须知道"现在在哪"。这就是那个字段存在的全部理由。
positionHardwareCursor(:628-659)是唯一动光标的地方,它做的三件事:
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 假光标:两个零宽标记
但有些组件需要"看起来有光标"却拿不到真光标——比如一个没有焦点的输入框, 或者编辑器里的第二个光标。
// 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):
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):
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)逐个属性记账:
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 保存的是原始结束符,而不是归一化后的。
一个看起来纯视觉的东西,底下是一个协议状态机。
八、同步输出与有界写入
所有渲染都被一对序列包着:
\x1b[?2026h ← 开始同步输出(DECSET 2026)…内容…\x1b[?2026l ← 结束同步输出终端收到 h 之后开始缓冲,收到 l 才一次性上屏。没有这个,用户会看到
"清了一半"的中间态——尤其是一帧写了 12 KB 的时候。
差分也要包。虽然只写一行,但那一行的 \x1b[2K 和内容是两次写入,
中间上屏就是一次闪烁。
8.1 为什么还要分块
写入不是一次 terminal.write(bigString),而是经过
BoundedTerminalWriter(tui-main-screen.ts:21-77):
// 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):
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 扩范围
// 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 清图会滚动,就退全量
// 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):
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;5mmight 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 当哨兵
不同终端支持的键位编码能力差三代:
- 旧序列(
ESC [ A= 上箭头),丢了几乎所有修饰键 modifyOtherKeys(xterm 扩展)- Kitty 键盘协议(能区分按下/重复/松开,能报 base layout key)
要问终端"你会不会",标准的做法是发一个查询然后等回复。但"等多久"是个 老问题:等短了老终端来不及回,等长了每次启动都卡。
这里的解法很聪明(terminal.ts:302-316):
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):
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 分派,每条分支里最多试三种编码:
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):
// 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):
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 调色板的第几个槽位借色:
// 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 起)每个等级给一组五阶多项式:
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。
两个可以带走的方法:
- 把规则写成函数,不写成色板。 色板是结果,规则可移植。换一套
品牌色,只要改
FAMILIES,14 个族的亮度全自动适配。 - 给规则加能力边界。
reachable把"做不到"变成一段显式代码, 而不是一个悄悄难看的颜色。
12.3 100 毫秒,和迟到的回复
问终端要颜色的代码只有 20 行(theme-controller.ts:20-40):
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 的主题会被忽略。
这一节和 §七 的宽度、§十一 的键盘协商是同一类问题: 你在跟一个 不守规矩、能力未知、还可能不回话的终端谈判。三种态度——假设它听话 (超宽就崩)、问清楚再画(卡住)、先画再随时纠正(这一节)。只有 第三种能同时满足"不卡"和"对"。
十三、完整链路
把写和读拼起来,一次按键到一次重绘:
【写】组件树 | | 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 是开发依赖,用来做真正的终端
模拟——断言的不是字节,是"屏幕上现在是什么"。
cd packages/tuinode --test test/tui-render.test.ts实验 1:spinner 只写一行
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:确认走的是差分,不是全量
node --test --test-name-pattern="differential" test/tui-render.test.ts判据:"splits large differential updates without a full redraw"(:190)
里那句断言:
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。跑两帧:
- 每帧改最后一行(spinner)
- 每帧改第 0 行、内容 20 行(小于一屏)
判据:第一组每帧约 99 字节,第二组也约 99 字节,而全量是
12,025 和 1,614(§4.2 的表)。再试第三组:150 行内容改第 0 行——
字节数会跳回 12,025,因为 0 < 126。
实验 4:列宽
node --test test/visible-width.test.ts test/wrap-ansi.test.ts判据:test/regression-regional-indicator-width.test.ts 也一起跑——那条
回归用例守的就是 §7.1 说的"区域指示符保守取 2"。
实验 5:输入分帧
node --test test/stdin-buffer.test.ts test/keys.test.ts判据:把一条鼠标序列拆成三次 process() 喂进去,data 事件只应触发一次。
再把 Kitty 回复拆开喂,协议标志应当在重组之后才置位。
实验 6:看 churn
node test/render-churn-bench.ts判据:输出两行,static 和 editor,每行带 written bytes/frame。
static 那一行的字节数接近 0——什么都没变,一帧只写同步输出的两个标记。
五句话
如果只记五句:
- 把"画"和"写"拆开。 组件永远全量重画,渲染器只写变了的行。
- 每行自包含。 开头清行、结尾复位,任意起点写都正确。
- 差分的窗口只有一屏高。 更早的行进了 scrollback,物理上改不了。
- 不可恢复的错误要当场崩。 超宽会触发自动换行,错了修不回来。
- 宽度是列不是字符。 CJK、emoji、代理对都要按列算。
本章小结
- 一帧只写变了的行:spinner 99 字节,全量 12,025。
- 一行是自包含字符串:自带清行、回车、复位。
- 光标是显式状态,不是副作用。
- 宽度是列不是字符;超宽直接崩,不截断。
- 同步输出把一帧包成一对标记,避免撕裂。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 差分 | 只写变了的行;\x1b[2J 出现就是全量 |
§四 |
| 自包含行 | 每行自带清行与复位,任意起点正确 | §五 |
| 显式光标 | 光标位置存在状态里,不靠推断 | §六 |
| 列宽 | 判宽用列,不用字符数 | §七 |
| 同步输出 | 一帧包成一对标记,防撕裂 | §八 |
练习
练习 1(读):§十五 实验 3 说 150 行内容改第 0 行,字节数跳回 12,025。 为什么改第 0 行反而比改最后一行贵?→ 回 §4.2 的表与那个行号判据。
练习 2(改):把实验 3 的 NullTerminal 里 bytesWritten += data.length
改成 Buffer.byteLength(data)。预期:含中文时字节数变大(字符数≠字节数);
回滚:改回 data.length。
常见误区
- 你会以为 一帧写多少字节不重要;实际是 差分与否差两个数量级; 证据 §4.2 的表。
- 你会以为 宽度超了截断更安全;实际是 直接崩,因为自动换行修不回来; 证据 §7.2。
- 你会以为 颜色是选出来的;实际是 按对比度曲线算出来的;证据 §十二。
读完自检
四条,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
| 一帧该写多少字节? | 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 | 分配量与每帧写入字节的基准 |