用途:当代码需要发出或解析终端控制序列、依赖终端特性,或必须在不同模拟器、终端复用器(tmux/screen)与 Windows 控制台主机间保持一致行为时使用本技能。
标准分层:从基础可打印文本、回车、换行、退格、制表符,到 ECMA-48/ANSI/ISO 6429 的 CSI 控制与 SGR 属性,再到 DEC VT 系列(光标移动、备用键盘模式、设备状态、私有模式)、xterm 约定(备用屏幕、鼠标模式、焦点事件、括号粘贴、OSC 扩展),以及现代模拟器扩展(Kitty 键盘/图形、iTerm2 图像、sixel、OSC 8 超链接、OSC 52 剪贴板、主题查询)和平台宿主行为(Windows 虚拟终端处理、ConPTY、tmux/screen 过滤、SSH 延迟)。越往下层越需要检测、回退与清理。
更安全的默认做法:优先使用框架抽象与 terminfo/能力库,而非硬编码控制序列;复杂 SGR 输出后主动重置样式;把未知、缺失或被阻止的响应视为正常;核心功能不依赖剪贴板、图像、焦点事件或扩展键盘协议;启用某模式前先注册清理路径。
常见序列与注意事项:备用屏幕 CSI ? 1049 h/l(可能被复用器禁用,必须清理);SGR 重置 CSI 0 m(退出与出错后重置);真彩色 CSI 38;2;R;G;B m / 48;2;R;G;B m(必要时降采样到 256/16/无色);括号粘贴 CSI ? 2004 h/l(解析粘贴边界,退出时禁用);SGR 鼠标 CSI ? 1006 h 加跟踪模式(需解析器与坐标校验);焦点事件 CSI ? 1004 h(仅作参考,可能不到达);OSC 8 链接(提供可见 URL 回退);OSC 52 剪贴板(常被终端、复用器、SSH 策略或安全设置阻止);DCS 透传(高度依赖环境);终端标题 OSC 0/2(避免意外更改);调色板查询/更改 OSC 4/10/11(需恢复更改并设置查询超时)。
能力协商清单:判断 stdout 是否为 TTY,否则默认避免光标控制与交互模式;处理 TERM 为 dumb、空或未知的情况;判断是否处于 tmux/screen 内;确认 Windows 经典控制台 API 是否启用 VT 处理;优先使用库提供的颜色级别检测;提供 --color、--no-color、--plain、--ascii、--no-mouse 等用户覆盖项;为查询设置超时以免挂起。
清理契约:启用原始模式、备用屏幕、鼠标跟踪、括号粘贴、焦点事件、隐藏光标或键盘协议时,须在正常退出、Ctrl-C、panic、异常、致命错误、部分初始化失败与测试断言失败时验证清理。
参考文件:references/escape-sequence-field-guide.md 与 references/capability-negotiation.md。