kitty 终端杂项协议扩展详解XTSAVE 全量模式恢复、SGR 221/222、鼠标离窗事件与私有 DCS 命令【免费下载链接】kittyIf you live in the terminal, kitty is made for you! Cross-platform, fast, feature-rich, GPU based.项目地址: https://gitcode.com/GitHub_Trending/ki/kitty导读kitty 在标准终端协议之上实现了一系列小而精的扩展它们主要服务于 kitty 自身的 kitten 子程序但对 TUI 应用开发者同样开放。本文基于 misc-protocol.rst系统讲解 5 类协议扩展无参数 XTSAVE/XTRESTORE 的全量终端模式保存恢复、SGR 221/222 对 bold/faint 的独立重置、SGR Pixel 鼠标协议中的离窗事件、把屏幕内容整体移入滚动缓冲的CSI 22 J以及以\x1bPkitty-开头的私有 DCS 命令族。读完本文你将掌握这些转义序列的精确编码、语义边界与源码级实现依据可直接在 TUI 或终端自动化脚本中使用。协议扩展概览扩展名称转义序列/编码主要用途全量模式保存/恢复CSI ? s/CSI ? r无参数形式一键保存/恢复全部无副作用终端模式bold/faint 独立重置CSI 221 m/CSI 222 m只重置加粗或只重置暗淡互不影响鼠标离窗事件SGR Pixel 事件首数字第 8 位置 1应用感知鼠标离开窗口屏幕移入滚动缓冲CSI 22 J清屏的同时保留全部内容可回滚查看kitty 私有 DCSDCS kitty-...ST远程控制、kitten 结果回传、SSH 等内部通信下面逐项展开并给出 kitty/screen.c、kitty/cursor.c、kitty/vt-parser.c 中的实现证据。终端模式的整体保存与恢复无参数 XTSAVE/XTRESTORE背景与问题XTerm 提供了 XTSAVE / XTRESTORE 转义序列CSI ? Pm s/CSI ? Pm r用于保存和恢复终端私有模式但调用方必须显式列出要保存/恢复的模式列表。对 TUI 应用而言维护这份清单既繁琐又容易遗漏。kitty 的扩展语义kitty 扩展了这一协议当省略参数列表时默认保存/恢复所有无副作用side-effect free的模式。所谓副作用指那些会影响其他终端状态如光标位置、屏幕内容的模式。文档明确给出两个有副作用的反例DECOM设置/重置后会影响光标定位方式与区域边界DECCOLM切换列数会导致屏幕内容被清空或重新布局。这类模式被排除在全量保存范围之外因为它们一旦被整体还原会连带破坏屏幕内容与光标状态违背只恢复模式、不扰动画面的初衷。这一设计让 TUI 应用只需发送一次无参数序列即可完整保存或恢复仿真器状态无需自行维护模式列表。例如# 保存当前所有无副作用模式 printf \x1b[?s # ... 临时修改若干模式 ... # 恢复之前保存的全部模式 printf \x1b[?r源码级实现在 kitty/screen.c 中screen_save_modes()与screen_restore_modes()的注释明确写着 kitty extension to XTSAVE / XTRESTOREL2688-L2716void screen_save_modes(Screen *self) { // kitty extension to XTSAVE that saves a bunch of no side-effect modes copy_specific_modes(self, self-modes, self-saved_modes); } void screen_restore_modes(Screen *self) { // kitty extension to XTRESTORE that saves a bunch of no side-effect modes copy_specific_modes(self, self-saved_modes, self-modes); }copy_specific_modes()L2670-L2686实际覆盖的模式包括LNM换行模式IRM插入/替换模式DECARM自动重复键BRACKETED_PASTE括号粘贴FOCUS_TRACKING焦点追踪对应1004模式见 kitty/modes.hCOLOR_PREFERENCE_NOTIFICATION颜色偏好通知INBAND_RESIZE_NOTIFICATION带内尺寸变化通知VISIBILITY_REPORTS可见性报告PASTE_EVENTS粘贴事件DECCKM光标键应用模式DECTCEM光标可见性DECAWM自动换行三类鼠标追踪模式button / motion / move tracking鼠标编码协议UTF-81005/ SGR1006DECSCNM反显屏幕而copy_specific_mode()L2614-L2657中通过SIDE_EFFECTS(DECOM)与SIDE_EFFECTS(DECCOLM)两个宏单独处理副作用模式当目标是当前活动模式集合dest self-modes即执行恢复操作时会通过set_mode_from_const()真正应用该模式包括由此触发的屏幕重排等副作用其余情况仅复制位。DECSCLM、DECNRCM则被直接忽略。解析入口位于 kitty/vt-parser.cCSI ? s无参数时调用screen_save_modes()带参数时走常规handle_mode()路径对应地CSI ? r的无参数形式执行整体恢复。bold 与 faint 的独立重置SGR 221 / 222标准 SGR 的缺陷标准终端里加粗由SGR 1开启、暗淡faint由SGR 2开启但重置时只有一个编号SGR 22且它会同时重置两者。也就是说TUI 无法做到只关掉 bold、保留 faint或反之——这正是很多文本渲染器如强调与弱化同时出现的 diff 视图遇到的经典问题。kitty 的扩展kitty 引入两个新编号解决该问题SGR 编号作用CSI 221 m仅重置 bold加粗CSI 222 m仅重置 faint暗淡CSI 22 m同时重置 bold 和 faint标准行为保持兼容使用示例# 设置加粗并开启暗淡 printf \x1b[1;2mbold-and-faint\x1b[0m\n # 只关闭加粗暗淡保留 printf \x1b[1;2mbold\x1b[221mfaint-only\x1b[0m\n # 只关闭暗淡加粗保留 printf \x1b[1;2mfaint\x1b[222mbold-only\x1b[0m\n源码级实现kitty/cursor.c 的 SGR 解析直接体现了这一语义case 1: self-sgr.bold true; break; case 2: self-sgr.dim true; break; ... case 221: self-sgr.bold false; break; case 222: self-sgr.dim false; break; case 22: self-sgr.bold false; self-sgr.dim false; break;可以看到221只触碰sgr.bold222只触碰sgr.dim而标准的22仍然同时清掉两者。同一文件中对单元格级属性的处理case 221/case 222也保持一致kitty/cursor.c确保光标级与渲染单元格级的行为统一。kitty 在文档中建议终端模拟器与 TUI 应用将221/222视为22的安全细分若仿真器不支持这两个编号退化为22也不会破坏渲染正确性。鼠标离开窗口事件SGR Pixel 协议的离窗报告编码规则kitty 扩展了 xterm 创建的 SGR Pixel 鼠标报告协议即CSI Cb ; Cx ; Cy M/m形式的1006模式事件使其在鼠标移出窗口时也能上报。该事件仍编码为普通的 SGR pixel 事件但通过第一个数字Cb的位标志加以区分第 8 位bit 8置位表示这是鼠标已离开窗口事件第 5 位bit 5置位表示这是与 motion移动相关的事件其余位bit 1-7除 5 外继续用于编码按钮与修饰键信息当第 8 位置位时其他所有位都应被忽略像素坐标值Cx、Cy也不可信必须忽略。举例来说假设一条 SGR 事件首个数字为M0-based 编码中的Cb值当Cb 128非零即表示离窗事件接收方只应据此判断鼠标离开了窗口而不应尝试从中提取按钮/坐标信息。使用前提应用需先通过CSI ? 1000;1006 h之类的序列开启鼠标追踪并选用 SGR1006编码协议相关模式常量MOUSE_SGR_MODE (1006 5)定义于 kitty/modes.h随后即可在鼠标移出窗口边界时收到携带离窗标志的事件。这对需要暂停悬停高亮、自动收起浮动面板或暂停滚动跟随的 TUI 应用非常有用——例如在 diff 查看器、面板式 UI 中鼠标离开窗口即可立刻清除 hover 状态避免画面残留。设计说明离窗事件把 鼠标不在了 作为一个独立信号与普通坐标事件区分正是因为离开窗口时最后一个已知坐标没有语义价值甚至可能是窗口外的非法值。kitty 将坐标标记为不可信并强制忽略防止应用把过期坐标当作有效输入。CSI 22 J把屏幕内容整体移入滚动缓冲与标准清屏的区别标准清屏序列CSI 2 J会清空整个显示区域但内容一去不返。kitty 提供的CSI 22 J忽略书写时的空格即\x1b[22J会把全部屏幕内容——包括文本和图片——移入滚动缓冲scrollback屏幕最终状态与执行CSI 2 J完全一致。这意味着用户可以像滚动历史输出一样向上翻看清屏前的完整画面。对于less -R、git diff分页器、构建日志循环输出这类清屏重绘场景应用只需把清屏序列换成22 J就能让用户随时回看被清掉的上一屏内容且无需应用自行维护历史。源码级实现kitty/screen.c 的screen_erase_in_display()中how 22的分支L2950-L2954case 22: screen_move_into_scrollback(self); nuke_multicell_chars false; // they have been moved into scrollback and we would get double deletions how 2; /* fallthrough */ case 2:它先调用screen_move_into_scrollback()把当前显示缓冲整体压入历史缓冲随后fallthrough到how 2的标准全屏擦除路径grman_clear()同时清理文本行与图形层how 3时连滚动缓冲一并清除对应CSI 3 J语义。注释特别指出they have been moved into scrollback and we would get double deletions避免多单元字符被二次删除——这正是移动而非复制清除的实现细节。文档也明确指出22 J只作用于主屏幕main screen中的内容。kitty 私有 DCS 转义码族\x1bPkitty-协议形态kitty 私有转义码是一族 DCSDevice Control String序列统一以\x1bPkitty-忽略空格实际为ESC P kitty-开头以 STESC \结束。它们被 kitty 用于远程控制、kitten 结果回传等多种内部机制文档出于完整性考虑予以公开。已定义的子命令从 kitty/vt-parser.c 的parse_kitty_dcs()分发表可以看到完整子命令集合子命令前缀处理器用途cmd{handle_remote_cmd远程控制命令配合 child 进程管道overlay-ready|handle_overlay_ready覆盖层就绪通知kitten-result|handle_kitten_resultkitten 执行结果回传print|handle_remote_print请求打印echo|handle_remote_echo回声测试ssh|handle_remote_sshSSH 相关交互ask|handle_remote_askpass询问口令askpassclone|handle_remote_clone克隆/复制窗口相关edit|handle_remote_edit请求编辑restore-cursor-appearance|handle_restore_cursor_appearance恢复光标外观解析器首先校验前缀kitty-随后按|或{分隔符匹配子命令无法识别的前缀会走REPORT_UKNOWN_ESCAPE_CODE上报未知转义码。与远程控制的关联远程控制命令的底层通道即由此族序列承载kitty/child-monitor.c 定义了KITTY_CMD_PREFIX \x1bPkitty-cmd{子进程向终端发送以该前缀开头的 DCS 字符串终端解析后执行对应动作。若需在脚本中手动发送远程控制指令可将kitten 命令行语法与本文所述 DCS 通道相互印证详见 docs/remote-control.rst。这些协议扩展整体被记录于 docs/protocol-extensions.rst与键盘、图形、剪贴板等协议扩展并列。兼容性与使用建议渐进增强上述扩展均以标准转义序列为基础做增量扩展22 J之前2 J仍然有效、221/222之外22依旧兼容、XTSAVE 带参形式未被破坏因此不支持扩展的终端模拟器只会忽略或降级处理不会造成数据损坏。XTSAVE 全量保存仅在明确需要备份-临时改模式-还原的 TUI 场景使用注意有副作用的DECOM/DECCOLM不在全量范围内避免还原时扰动屏幕布局。离窗事件务必按文档约定先判断第 8 位再决定是否读取坐标且不要依赖坐标值。私有 DCS\x1bPkitty-前缀属于 kitty 专用命名空间kitten 开发者可将其作为与主程序通信的轻量通道第三方应用若要与 kitty 交互优先考虑官方的远程控制接口而非直接构造 DCS 载荷。以上内容全部可对照当前仓库源码验证模式保存/恢复见 kitty/screen.c 与 kitty/vt-parser.cSGR 221/222 见 kitty/cursor.c22 J见 kitty/screen.c私有 DCS 见 kitty/vt-parser.c 与 kitty/child-monitor.c。【免费下载链接】kittyIf you live in the terminal, kitty is made for you! Cross-platform, fast, feature-rich, GPU based.项目地址: https://gitcode.com/GitHub_Trending/ki/kitty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考