Ghostty C 库 Mode 工具实战：打包/解包 ANSI 与 DEC 模式标识符，编码 DECRPM 响应序列

本文以 Ghostty 官方示例 c-vt-modes 为主体，完整讲解 ghostty-vt C 库中终端模式（Mode）工具的用法：如何使用 16 位紧凑结构打包与解包 ANSI/DEC private 模式标识符，以及如何将 DECRPM（DEC Private Mode Report）响应序列编码到调用方提供的缓冲区中。读完本文，你可以基于同一套 API 在自己的 C 程序中实现模式识别、模式查询应答等终端底层功能。

示例要解决的问题

example/c-vt-modes/README.md 说明了本示例的定位：演示如何使用 ghostty-vt 的 mode 工具集完成两类操作：

1. 打包/解包模式标识符——将一个“模式号 + 是否 ANSI 模式”的二元信息编码进一个 16 位整数，并提供反向解包；
2. 编码 DECRPM 响应——把“某模式当前是 set/reset/不识别”这一状态编码为标准的转义序列（如 ESC[?25;1$y）。

文档同时指出一个关键工程事实：本示例虽然使用 build.zig 和 Zig 来构建 C 程序（以便复用 Ghostty 的构建逻辑、直接依赖源码树），但 Ghostty 输出的是一个标准 C 库，可以用任何 C 工具链来使用，并不绑定 Zig。

构建与运行

示例目录结构为：

• build.zig——Zig 构建脚本；
• build.zig.zon——包清单，声明对 Ghostty 的依赖；
• src/main.c——C 示例程序。

构建脚本的核心逻辑（见 build.zig）：

1. 通过 b.createModule 创建模块，并用 addCSourceFiles 直接编译 src/main.c，无需任何 CMake 或 Makefile；
2. 通过 b.lazyDependency("ghostty", .{}) 以懒加载方式引入 Ghostty 依赖——只有真正构建时才解析它；
3. 调用 exe_mod.linkLibrary(dep.artifact("ghostty-vt"))，链接 Ghostty 导出的 ghostty-vt 库产物；
4. 注册 run 步骤，支持透传命令行参数。

关于依赖声明（见 build.zig.zon）有两点值得注意：

• 本仓库的示例使用路径依赖（指向仓库根目录），保证示例始终对着随附的同一份源码测试；
• 文件中注释给了 URL 依赖的写法示例（指向某一 commit 的源码 tar 包并带哈希校验），生产嵌入场景中通常采用这种形式，把 Ghostty 锁定到确定版本。

build.zig 中还有一个性能相关的注释：将 lazy 依赖的 .simd 设为 false 可以得到一个纯静态构建（甚至不需要 libc），但存在显著的性能损失；如果你的宿主程序本来就需要 libc，应保持 simd 启用。

运行方式与原文档一致，在示例目录下执行：

zig build run

头文件 API：16 位打包布局

所有 API 定义在 include/ghostty/vt/modes.h 中。文件头部的注释给出了最核心的设计：

一个 mode 是终端模式标识符的紧凑 16 位表示，同时编码了数字模式值（最多 15 位）以及该模式是 ANSI 模式还是 DEC private 模式（? 前缀）。

打包布局（从最低有效位开始）：

位段	含义
Bits 0–14	模式数值（u15，取值 0–32767）
Bit 15	ANSI 标志：0 = DEC private 模式，1 = ANSI 模式

类型定义为 typedef uint16_t GhosttyMode;，配套三个 static inline 函数，构造与检查均只需一次位运算（对应 modes.h 中 L118–L144）：

函数	作用	实现
ghostty_mode_new(uint16_t value, bool ansi)	由模式数值与 ANSI 标志构造打包模式	(value & 0x7FFF) | (ansi << 15)
ghostty_mode_value(GhosttyMode mode)	提取模式数值（0–32767）	mode & 0x7FFF
ghostty_mode_ansi(GhosttyMode mode)	判断是否为 ANSI 模式	(mode >> 15) != 0

文档还特别提醒：应使用这些内联辅助函数来构造和检查模式，而不要直接手工操作位。

常用模式常量速查

头文件以宏的形式提供了 ANSI 与 DEC private 两组常用模式（modes.h 中 L45–L98），每个宏都是 ghostty_mode_new 的常量调用。摘录常用项：

ANSI 模式

宏	模式号	说明
GHOSTTY_MODE_KAM	2	Keyboard action（禁用键盘）
GHOSTTY_MODE_INSERT	4	Insert 插入模式
GHOSTTY_MODE_SRM	12	Send/receive mode
GHOSTTY_MODE_LINEFEED	20	Linefeed/new line mode

DEC private 模式（节选）

宏	模式号	说明
GHOSTTY_MODE_DECCKM	1	光标键模式
GHOSTTY_MODE_REVERSE_COLORS	5	反色显示
GHOSTTY_MODE_ORIGIN	6	原点模式
GHOSTTY_MODE_WRAPAROUND	7	自动回绕
GHOSTTY_MODE_CURSOR_BLINKING	12	光标闪烁
GHOSTTY_MODE_CURSOR_VISIBLE	25	光标可见（DECTCEM）
GHOSTTY_MODE_KEYPAD_KEYS	66	应用模式小键盘
GHOSTTY_MODE_BACKARROW_KEY_MODE	67	Backarrow 键模式（DECBKM）
GHOSTTY_MODE_NORMAL_MOUSE	1000	普通鼠标追踪
GHOSTTY_MODE_SGR_MOUSE	1006	SGR 格式鼠标事件
GHOSTTY_MODE_ALT_SCROLL	1007	备选滚动模式
GHOSTTY_MODE_ALT_SCREEN	1047	备选屏幕
GHOSTTY_MODE_SAVE_CURSOR	1048	保存光标（DECSC）
GHOSTTY_MODE_ALT_SCREEN_SAVE	1049	备选屏幕 + 保存光标 + 清屏
GHOSTTY_MODE_BRACKETED_PASTE	2004	括号粘贴
GHOSTTY_MODE_SYNC_OUTPUT	2026	同步输出
GHOSTTY_MODE_PASTE_EVENTS	5522	Kitty 剪贴板协议粘贴事件

示例源码逐段解析

完整示例见 example/c-vt-modes/src/main.c，只包含 #include <stdio.h> 和 #include <ghostty/vt.h> 两个头文件。

1. 打包与解包：modes_example

对应源码 main.c 中 L4–L20：

void modes_example() {
  // Create a mode for DEC mode 25 (cursor visible)
  GhosttyMode tag = ghostty_mode_new(25, false);
  printf("value=%u ansi=%d packed=0x%04x\n",
      ghostty_mode_value(tag),
      ghostty_mode_ansi(tag),
      tag);

  // Create a mode for ANSI mode 4 (insert mode)
  GhosttyMode ansi_tag = ghostty_mode_new(4, true);
  printf("value=%u ansi=%d packed=0x%04x\n",
      ghostty_mode_value(ansi_tag),
      ghostty_mode_ansi(ansi_tag),
      ansi_tag);
}

按打包布局推演两个例子：

• DEC mode 25：value = 25，ansi = 0，打包结果 = 25 | (0 << 15) = 0x0019；
• ANSI mode 4：value = 4，ansi = 1，打包结果 = 4 | (1 << 15) = 0x8004。

可以看到同一个数值（如 mode 4）在 ANSI 与 DEC 两套编号空间里完全靠第 15 位区分，这正是“模式号 + 前缀”二元组被压缩进 16 位的意义：可作为哈希键、数组下标或 C 库跨边界传递的紧凑标识。

2. 编码 DECRPM 响应：decrpm_example

对应源码 main.c 中 L22–L39：

void decrpm_example() {
  char buf[32];
  size_t written = 0;

  // Encode a report that DEC mode 25 (cursor visible) is set
  GhosttyResult result = ghostty_mode_report_encode(
      GHOSTTY_MODE_CURSOR_VISIBLE,
      GHOSTTY_MODE_REPORT_SET,
      buf, sizeof(buf), &written);

  if (result == GHOSTTY_SUCCESS) {
    printf("Encoded %zu bytes: ", written);
    fwrite(buf, 1, written, stdout);
    printf("\n");  // prints: ESC[?25;1$y
  }
}

ghostty_mode_report_encode 的声明见 modes.h 中 L187–L192：

GHOSTTY_API GhosttyResult ghostty_mode_report_encode(
    GhosttyMode mode,
    GhosttyModeReportState state,
    char* buf,
    size_t buf_len,
    size_t* out_written);

参数与语义：

• mode：要报告的模式（打包的 GhosttyMode）；
• state：报告状态，见下表；
• buf / buf_len：输出缓冲区，可以为 NULL（用于探测所需长度）；
• out_written：成功时写入实际字节数；返回 GHOSTTY_OUT_OF_SPACE 时写入所需的缓冲区大小，调用方可据此扩容后重试。

生成的序列格式（DEC private 与 ANSI 的区别仅在于有无 ? 前缀）：

模式类型	序列格式
DEC private 模式	CSI ? Ps1 ; Ps2 $ y
ANSI 模式	CSI Ps1 ; Ps2 $ y

报告状态枚举 GhosttyModeReportState（modes.h 中 L152–L164）对应 DECRPM 响应中的 Ps2 参数：

枚举值	数值	含义
GHOSTTY_MODE_REPORT_NOT_RECOGNIZED	0	模式不被识别
GHOSTTY_MODE_REPORT_SET	1	模式已设置（启用）
GHOSTTY_MODE_REPORT_RESET	2	模式已复位（禁用）
GHOSTTY_MODE_REPORT_PERMANENTLY_SET	3	模式永久设置
GHOSTTY_MODE_REPORT_PERMANENTLY_RESET	4	模式永久复位

因此示例编码 DEC mode 25 的 set 状态，输出即 8 字节的 ESC[?25;1$y。

底层实现与测试佐证

C 层的导出函数最终落到 src/terminal/c/modes.zig 的 report_encode（L18–L43），从源码实现可以看出三个细节：

1. 类型转换：GhosttyMode 被 bitCast 回内部的 modes.ModeTag，报告状态则经 std.enums.fromInt 转为内部 modes.Report.State；状态值非法时直接返回 .invalid_value，不会写入任何数据；
2. 缓冲区不足的两段式协议：先用定长 writer（std.Io.Writer.fixed）写入，若发生 WriteFailed，就用 Discarding writer 重新编码一遍，只统计字节数，再把该数写入 out_written 并返回 .out_of_space——这保证了“探测长度”路径（buf == NULL）与“缓冲区不足”路径返回一致的长度；
3. 与头文件契约一致：GHOSTTY_SUCCESS / GHOSTTY_OUT_OF_SPACE / 无效值三类结果与 modes.h 的 Doxygen 注释一一对应。

同文件内的单元测试（modes.zig 中 L45–L104）覆盖了这些行为，可作为期望输出参考：

测试	输入	断言结果
encode DEC mode set	DEC 模式 1，state=1	输出 \x1B[?1;1$y
encode DEC mode reset	DEC 模式 1，state=2	输出 \x1B[?1;2$y
encode ANSI mode	ANSI 模式 4，state=1	输出 \x1B[4;1$y（无 ? 前缀）
encode not recognized	DEC 模式 9999，state=0	输出 \x1B[?9999;0$y
encode with insufficient buffer	1 字节缓冲	返回 .out_of_space 且 written > 1
encode with invalid state	state=99	返回 .invalid_value
encode with null buffer	buf = NULL	返回 .out_of_space 且 written > 0

小结

c-vt-modes 示例虽然只有百余行 C 代码，但覆盖了嵌入 ghostty-vt 时处理终端模式的完整闭环：用 modes.h 的 16 位打包布局在 ANSI/DEC 两套模式编号空间之间无歧义地传递标识符，用 ghostty_mode_report_encode 以“缓冲不足即可探测长度”的两段式协议输出 DECRPM 序列，并用 build.zig + build.zig.zon 的最小配置完成 C 源码与 ghostty-vt 库产物的链接。由于 Ghostty 输出的是标准 C 库，这套 API 同样适用于任何 C 工具链的嵌入场景，行为细节则以 src/terminal/c/modes.zig 的实现与测试为准。