terminal-standards

终端标准、转义序列与能力协商

当代码会输出或解析终端控制序列、依赖终端功能，或必须在不同模拟器、多路复用器和 Windows 控制台主机上正常运行时，请使用此技能。

标准层级

请按以下层级考虑：

1. 基线： 可打印文本、回车、换行、退格、制表符。
2. ECMA-48 / ANSI / ISO 6429： CSI 控制序列和 SGR 属性。
3. DEC VT 系列： 光标移动、备用键盘模式、设备状态模式、私有模式。
4. xterm 约定： 备用屏幕、鼠标模式、焦点事件、括号化粘贴、OSC 扩展。
5. 现代模拟器扩展： Kitty 键盘/图形、iTerm2 图像、sixel、OSC 8 超链接、OSC 52 剪贴板、主题查询。
6. 平台主机行为： Windows 虚拟终端处理、ConPTY、tmux/screen 过滤、SSH 延迟。

越深入这一层级，就越需要检测、回退方案和清理机制。

更安全的默认做法

• 优先使用框架抽象和 terminfo/能力库，而不是硬编码控制序列。
• 有意重置样式；复杂的 SGR 输出后，不要依赖终端默认值。
• 将未知响应、缺失响应和被拦截的查询视为正常情况。
• 核心功能绝不能依赖剪贴板、图像、焦点事件或扩展键盘协议。
• 启用某种模式时，应先注册清理路径，再继续操作。

常见序列和注意事项

功能	典型序列	注意事项
备用屏幕	CSI ? 1049 h / CSI ? 1049 l	可能被禁用或由多路复用器处理。必须进行清理。
SGR 重置	CSI 0 m	退出前及发生错误后都要重置。
真彩色	CSI 38;2;R;G;B m / CSI 48;2;R;G;B m	必要时降级为 256 色、16 色或无颜色。
括号化粘贴	CSI ? 2004 h / CSI ? 2004 l	解析粘贴边界；退出时禁用。
SGR 鼠标	CSI ? 1006 h 加上跟踪模式	需要解析器和坐标验证。
焦点事件	CSI ? 1004 h	仅作参考；事件可能不会到达。
OSC 8 链接	OSC 8 ; ; URI ST	提供可见 URL 作为回退方案。
OSC 52 剪贴板	OSC 52	常被终端、多路复用器、SSH 策略或安全设置拦截。
DCS 直通	DCS ... ST	多路复用器和某些协议会用到；高度依赖环境。
终端标题	OSC 0/2	恢复标题，或避免意外更改标题。
调色板查询/更改	OSC 4/10/11 变体	虽然实用，但实现分散；应恢复更改并为查询设置超时。

详细表格请参阅 references/escape-sequence-field-guide.md。

能力协商检查清单

• stdout 是 TTY 吗？如果不是，默认应避免使用光标控制和交互模式。
• TERM 是否有效？应处理 dumb、空值和未知值。
• 应用是否运行在 tmux/screen 中？应假设某些协议会被过滤或需要直通。
• 经典控制台 API 是否启用了 Windows VT 处理？
• 库是否提供颜色级别检测？优先使用此功能，而不是临时解析环境变量。
• 是否提供用户覆盖选项：--color、--no-color、--plain、--ascii、--no-mouse？
• 查询超时是否有上限，以免应用因等待终端响应而挂起？

清理约定

如果启用了原始模式、备用屏幕、鼠标跟踪、括号化粘贴、焦点事件、隐藏光标或键盘协议，请确认在正常退出、Ctrl-C、panic、异常、致命错误、部分初始化失败和测试断言失败时都能完成清理。

参考文件

• references/escape-sequence-field-guide.md - ANSI/VT/xterm 控制序列和注意事项。
• references/capability-negotiation.md - 不同终端的检测和回退模式。