moby 仓库内的 tonistiigi/vt100：VT100/ANSI 终端屏幕阅读器的源码实现解析

本篇技术指南聚焦于 Moby（Docker 容器生态）主仓库中 vendor 的第三方 Go 库 github.com/tonistiigi/vt100（v0.0.0-20240514184818-90bafcd6abab，见 modules.txt）。该库是一个以 Go 编写的"可编程 ANSI 终端模拟器 / 屏幕阅读器"（VT100 screen reader），它能吃掉一串带着光标移动、颜色、擦除等转义序列的字节流，并像真实终端一样维护一份可随时读取的"屏幕快照"。读完本文，你将理解它的能力边界、核心数据结构、ANSI 命令解码流程、SGR 属性映射表，以及它如何在构建工具链的终端 UI 中承担"把 tty 输出正确地画进界面"的关键职责。

一、它是什么：为什么容器生态需要一个终端屏幕阅读器

tonistiigi/vt100 的作者是 BuildKit 的主要维护者，因此在 moby 仓库中它是作为 github.com/moby/buildkit 的依赖被整体 vendor 进来的。其官方定位（见 README.md）：

"This is a vt100 screen reader. It seems to do a pretty decent job of parsing the nethack input stream, which is all I want it for anyway."

它最初源于上游 [jaguilar/vt100] 项目的改造。所谓"屏幕阅读器"，是指：程序以子进程方式运行另一个期望真终端的程序（如 nethack 这类全屏游戏、或 docker build 中输出转义序列的构建步骤），把对方写入 stdout 的字节流原样交给 vt100，由它跟踪光标位置、颜色与终端状态，从而让上层应用"读懂"画面内容。这对容器构建场景尤其有价值——当构建容器内的程序直接向 tty 写入 ANSI 控制序列时，宿主侧的进度 UI 需要一个模拟终端来正确还原最终画面，而不是把转义字节原样打印成乱码。

其包文档也直白地自我定位（vt100.go）：

"quick-and-dirty programmable ANSI terminal emulator ... It tracks the position of the cursor, colors, and various other aspects of the terminal's state, and allows you to inspect them. We do very much mean the dirty part."

也就是说：它不是一个追求像素级完美的完整终端模拟器，而是一个"够用就好、便于程序检查屏幕状态"的最小模拟器。README 明确声明 API 不稳定（"The API is not stable! This is a v0 package."），使用时不宜对接口稳定性做长期承诺。

二、能力清单：已支持与明确不支持

README 列出的当前已支持特性，应与仓库内的实现一一对应：

能力	README 表述	对应实现
光标移动	Cursor movement	command.go 中 A/B/C/D（上/下/右/左）、H/f（home/定位）等处理器
擦除	Erasing	K（擦行）、J（擦屏）处理器，见 command.go
文本属性	underline, inverse, blink, etc.	Format 结构体中的 Underscore/Conceal/Blink/Inverse，见 vt100.go
十六色	Sixteen colors	codeColors 数组映射 30-37/40-47 前景/背景色，见 command.go
光标保存/恢复	Cursor saving and unsaving	save/unsave，对应 ESC s、ESC 7、CSI u、ESC 8，见 command.go
UTF-8	UTF-8	解码层以 rune 为单位读取并支持多字节字符，见 scanner.go
滚动	Scrolling	Write → put → scrollIfNeeded 的写入触底自动上滚逻辑，见 vt100.go

README 同时给出明确不支持（且无计划支持）的部分：

• Prompts（提示符）；
• 其他 cooked mode（行缓冲/回声等终端熟模式）特性。

一处值得注意的文档出入：vt100.go 的包注释仍写着"目前只处理 raw mode，不含 cooked mode 的滚动等特性"，且 advance() 中滚动逻辑以 TODO 注释形式保留；但实际代码中 scrollIfNeeded() 已实现写入触底上滚，README 也把 Scrolling 列为已支持。应以实际代码为准——这是"quick-and-dirty"项目的典型状态。

三、源码构成与核心数据结构

vendor 目录下仅有四个文件（目录）：LICENSE、README.md 与三个 Go 源文件，职责划分清晰：

• vt100.go：终端状态模型与渲染，即"屏幕本身"；
• scanner.go：把字节流解码为一条条终端命令；
• command.go：命令的语义执行（含 SGR 属性、光标、擦除等）。

3.1 VT100 终端对象

核心结构体定义在 vt100.go：

type VT100 struct {
    Height, Width int           // 终端尺寸
    Content [][]rune            // 每个单元格的字符
    Format  [][]Format          // 每个单元格的显示格式
    Cursor  Cursor              // 当前光标（坐标 + 将要写入的格式）
    savedCursor Cursor          // save() 时快照的光标状态
    unparsed []byte             // 跨 Write 调用残留的不完整字节
}

屏幕被建模为 Height × Width 的字符矩阵 Content 与等尺寸的格式矩阵 Format。每个字符单元在创建时被初始化为空格 ' '、默认格式（见 NewVT100，若宽高为 0 会直接 panic）。

配套的常用方法：

• UsedHeight() int：统计存在非空格字符的最高行数（vt100.go），用于判断哪些行实际"有内容"；
• Resize(y, x int)：动态扩缩终端（vt100.go），带最小尺寸保护（宽度最小 6、高度最小 1），增加行/列时填充空格，缩短时直接截断；
• Write(dt []byte) (int, error)：实现 io.Writer，是喂数据的主要入口（详见下文解码流程）；
• HTML() string：把当前屏幕渲染成一段 HTML 片段，主要用于调试与（如构建日志的）远程展示。

3.2 颜色与 Intensity 的建模

颜色使用标准库 image/color 的 color.RGBA，定义于 vt100.go：

• DefaultColor = {0,0,0,0}（透明）表示"未显式设置"，在渲染 CSS 时会被跳过；
• 八种标准色 Black…White 的 alpha 均为 255，与 DefaultColor 形成区分，从而能判断"是黑色字还是未上色"；
• 代码注释特别提醒：规范上 RGBA 要求预乘 alpha，但 CSS 不这么期望，因此该文件不做预乘。

文本亮度 Intensity（vt100.go）取值 Normal / Bright / Dim，其 alpha() 分别映射 170 / 255 / 85——即"加亮/普通/变暗"是通过调整前景色 alpha 实现的（注释在 vt100.go 明确说明亮度只作用于前景）。在把格式转 CSS 时（Format.css()，见 vt100.go），会先将反显（Inverse）的 fg/bg 对调，再输出 color: rgba(...) 等属性；Conceal 对应 display:none、Blink 对应 text-decoration:blink。输出前还会对属性列表排序，以保证相同格式总是生成相同顺序的 CSS——这是为了让 HTML 输出在测试中可稳定比对。

四、命令解码：从字节流到 Command

4.1 三个层级的命令抽象

command.go 定义了命令接口与两类实现：

type Command interface {
    display(v *VT100) error
}

• runeCommand(rune)：最简单的命令——把普通可打印字符写到当前单元格并推进光标（v.put）；
• escapeCommand{cmd rune, args string}：一条控制序列（CSI），如 \x1b[31m；
• controlCommand(rune)：控制字符，如 \b、\n、\r。

所有命令最终都通过 VT100.Process(c Command) error 分发执行（vt100.go，本质就是调用 c.display(v)）。

4.2 Decode：单条命令的识别

解码入口是 Decode(s io.RuneScanner)，它按 rune 读取并做三层判断：

1. 非法 UTF-8 检测：读到的 rune 是替换字符（U+FFFD）且只占 1 字节，则返回 non-utf8 data from reader 错误；
2. 转义序列开头：ESC（\u001b）或"单字符 CSI 指示符" U+009B（monogram CSI），则回退一个 rune 并转入 scanEscapeCommand；
3. 控制字符：unicode.IsControl(r) 为真则包装成 controlCommand；否则就是普通字符，包装为 runeCommand。

值得注意的是代码支持两种开启控制序列的方式：经典的 ESC [ 两字节序列，以及单字节的 U+009B（对应 ESC [ 的合并编码），定义见 scanner.go。

4.3 scanEscapeCommand：扫描完整转义序列

scanEscapeCommand 从转义引导 rune 开始向后扫描：若首字符是 [ 则确认进入 CSI 模式；非 CSI 的单字符转义（如 ESC 7/ESC 8）直接返回 escapeCommand{该字符, ""}；CSI 模式则持续收集参数，直到遇到"最终字节"——其判定采用 Unicode 区间 @(64)~~(126)（csEnd，见 scanner.go）。参数中还处理了引号（"）翻转，为潜在的非整数参数（如字符串类参数）预留了空间。

4.4 Write：面对分块数据流的稳健处理

真实场景中日志以不定长 chunk 到达，一条 CSI 序列可能被拆在两三次 Write 之间。VT100.Write（vt100.go）为此做了防拆包处理：

func (v *VT100) Write(dt []byte) (int, error) {
    n := len(dt)
    if len(v.unparsed) > 0 {
        dt = append(v.unparsed, dt...) // 拼接上次的残留
        v.unparsed = nil
    }
    buf := bytes.NewBuffer(dt)
    for {
        if buf.Len() == 0 { return n, nil }
        cmd, err := Decode(buf)
        if err != nil {
            if l := buf.Len(); l > 0 && l < 12 { // 残留过小则缓存，等待下次数据
                v.unparsed = buf.Bytes()
            }
            return n, nil
        }
        v.Process(cmd) // ignore error
    }
}

即：遇到解码错误时，若剩余不足 12 字节则暂存为 unparsed 等下次拼接，否则丢弃跳过。Write 返回原始输入长度、错误被忽略，保证它作为 io.Writer 可以安全地被持续调用。

五、命令执行集：一张表看懂它能做什么

command.go 中的 intHandlers 表定义了全部被识别并处理的转义命令（参数均为整数），这是理解该库能力边界的最直接索引：

转义序列（CSI / 非 CSI）	最终字节	语义	实现函数
CSI s / ESC 7	s / 7	保存光标状态	save
CSI u / ESC 8	u / 8	恢复光标状态	unsave
CSI n A	A	光标上移 n 行	relativeMove(-1,0)
CSI n B	B	光标下移 n 行	relativeMove(1,0)
CSI n C	C	光标右移 n 列	relativeMove(0,1)
CSI n D	D	光标左移 n 列	relativeMove(0,-1)
CSI n K	K	擦除行（0/1/2 分别=光标到行尾/行首到光标/整行）	eraseColumns
CSI n J	J	擦除屏（0/1/2 方向同 K）	eraseLines
CSI y;x H / f	H / f	光标定位（1 起始坐标）	home
CSI ... m	m	更新字符属性（SGR）	updateAttributes

定位参数是 1 起始的（真实终端协议如此），内部转换为 0 起始索引；越界坐标会被 sanitize 夹取回合法范围并返回错误（见 command.go）。相对移动则先算出目标绝对坐标再复用 home 的夹取逻辑。行擦除 K、屏擦除 J 内部统一调用 eraseRegion 把区间单元格重置为空格 + 默认格式（vt100.go）。

控制字符方面（command.go）仅处理三个：\b 退格（支持跨行回绕）、\n 换行（Y++ 且 X 归零）、\r 回车（X 归零）。注意 \t、\v、\f 虽被定义为常量但未在 switch 中处理，属于静默忽略。

六、SGR 属性映射：m 命令的完整对照表

CSI ... m（Select Graphic Rendition）是文本样式指令，映射逻辑集中在 updateAttributes。它对 ; 分隔的每个参数编号逐一切换：

SGR 码	效果	SGR 码	效果
0	全部重置为默认 Format{}	28	关闭隐藏（Conceal off）
1	Bright（加亮）	30-37	前景色 Black→White
2	Dim（变暗）	39	前景恢复默认
22	Normal（正常亮度）	40-47	背景色 Black→White
4	开启下划线	49	背景恢复默认
24	关闭下划线	5 / 6	开启闪烁（不区分快慢）
7	开启反显（Inverse）	25	关闭闪烁
27	关闭反显	8	开启隐藏（Conceal）

其中 codeColors（command.go）是一个长度 10 的数组，下标 30-37（前景）与 40-47（背景）通过 x-30 / x-40 直接取色，第 9 个元素是占位空值，第 10 个是 DefaultColor（对应 39/49 恢复默认）。显式不支持 38/48（真彩色/256 色扩展）——代码注释明确写了 "38 and 48 not supported. Maybe someday."。未识别的编号会被汇总并上报为 UnsupportedError。

6.1 不支持命令的观测通道

当解析出无法执行的命令时，库并不中断工作，而是通过 Go 的 expvar 包维护一个全局计数器 vt100-unsupported-operations（command.go），每次 supportError 都 Add 一次。因此集成方可以起一个 debug HTTP 服务，直接在 /debug/vars 上观察累计的未知操作（vt100.go 的 Process 文档也提示了这一点），这比逐个打日志更适合判断"终端模拟是否遗漏了客户端用到的特性"。

七、它如何"嵌入" moby 仓库：BuildKit 进度 UI 的实盘用法

在 moby 主仓库中，vt100 的直接消费者是 BuildKit 的进度显示模块 vendor/github.com/moby/buildkit/util/progress/progressui/display.go。这正是该库的典型生产用途：当构建步骤的输出带 ANSI 控制序列（例如容器内进程直接操作 tty）时，用它把字节流模拟成屏幕，再取回干净的行文本画进 UI。

关键调用链如下：

1. 为每个日志来源建模拟终端：每个 vertex（构建节点）持有一个 term *vt100.VT100（display.go#L369），在需要展示 tty 类输出时按当前 UI 行高创建：vt100.NewVT100(termHeight, w)（display.go#L672）；

2. 持续喂入日志字节流：收到 BuildKit 推送的 Logs 后先比对宽度，必要时 v.term.Resize(...)，随后直接 v.term.Write(l.Data)，并附带一句很有意思的注释（display.go#L751-L757）：

   // error unhandled on purpose. don't trust vt100

   即：上游刻意忽略 vt100 的返回错误，因为它的职责只是"尽力还原"，不应让模拟器故障拖垮整个进度渲染；

3. 读出屏幕内容并重绘：当需要展示某构建步骤的终端画面时，term.Resize(termHeight, width-termPad) 后遍历 term.Content，跳过空行（isEmpty），把每一行以 => => # %s 的弱化样式（aec.Faint）输出（display.go#L1068-L1080）；

4. 用于界面空间预算：term.UsedHeight() 被用来计算当前各 vertex 终端画面实际占用的行数，从而判断需要隐藏多少个任务以适配屏幕高度（display.go#L972）。

这一使用方式完整印证了库的三个设计取向：Write 面向分块数据流、错误可容忍（"don't trust vt100"）、以及"屏幕矩阵可被外部程序逐行检查"这一 screen reader 核心定位。

八、API 速查与注意事项

面向集成方的核心 API 一览（均在 vt100.go）：

API	签名	用途
构造	NewVT100(y, x int) *VT100	创建指定尺寸的模拟终端，宽高为 0 会 panic（vt100.go#L147）
写入	(v *VT100) Write(dt []byte) (int, error)	实现 io.Writer，喂入 ANSI 字节流（vt100.go#L229）
处理	(v *VT100) Process(c Command) error	执行一条已解码的命令（vt100.go#L259）
调整尺寸	(v *VT100) Resize(y, x int)	动态扩缩屏幕（vt100.go#L183）
有效高度	(v *VT100) UsedHeight() int	返回有内容的最大行数（vt100.go#L170）
HTML 调试	(v *VT100) HTML() string	渲染为带样式 span 的 HTML 片段（vt100.go#L265）
解码	Decode(s io.RuneScanner) (Command, error)	从流中读出一条命令（scanner.go#L21）

直接访问 Content [][]rune / Format [][]Format / Cursor 即可逐单元格读取屏幕状态；修改格式请先 v.Cursor.F = ... 再写入文本。集成时需注意的边界条件可归纳为：

1. 版本策略：README 声明 API 不稳定（v0 级），本仓库 vendor 的是 v0.0.0-20240514184818-90bafcd6abab 快照，跨版本升级需自行回归；
2. 功能子集：仅 raw mode 语义；prompts 等 cooked mode 特性、SGR 38/48（256 色/真彩）不支持，未知命令会被忽略并计入 expvar 计数器；
3. 错误容忍：Write 阶段错误被有意的忽略设计，上游使用方甚至明言 "don't trust vt100"，需要精确还原时应对结果做校验；
4. 源码级文档提醒：包顶部注释（vt100.go#L8-L10）中关于滚动能力的历史描述与现状存在出入，判断能力请以 intHandlers 表与 scrollIfNeeded 实现为准。

九、小结

tonistiigi/vt100 的定位清晰：它是一个面向"程序化读取"的极简 VT100/ANSI 终端模拟器——以 Write 吞吐字节流、以 Content/Format 矩阵暴露屏幕快照、以 HTML() 输出可调试的富文本渲染。它完整覆盖了绝大多数全屏应用所依赖的控制能力（光标定位与移动、擦除、8 前景 + 8 背景色、SGR 文本样式、光标保存恢复、UTF-8、滚动），并诚实地保留了 v0 级别的粗糙度与对未知命令的容错策略。在 moby / BuildKit 中，它正是借助这些特性，把不可信的 tty 日志安全地"翻译"为构建进度界面上整洁的逐行画面——这是"终端屏幕阅读器"在容器工具链中最有说服力的一次实践。