Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

输入的地狱——终端能力探测与降级

系列第六篇,第 5 篇的下半部。第 2 篇 §4.3 讲过输出侧的能力降级链:颜色从 true color 一路退到 16 色,是“能力有没有“的问题。输入侧是另一半,行业讨论比输出侧少一个数量级,难度却更高:**输出降级是“能力有没有“,输入地狱是“行为一不一致“。**同一个按键,在不同终端模拟器里含义不同;同一条查询序列,有的终端回答、有的沉默、有的只回一半。上一篇讲的 composer 状态机,全部建立在这条事件流可靠的假设上。我从踩到这个坑、到调研、再到解决,花了几百块的 token,这一篇讲这个坑本身。


一、探测:启动时的第一次核对

终端能力没法靠 $TERM 问出来,环境变量会撒谎(SSH 默认只把 TERM 带过去,TERM_PROGRAM 这类变量到远端就没了;进了 tmux,TERM 又换成 tmux 自己的值)。所以严肃的 TUI 都在启动时做一次实况探测:向终端发查询序列,等回应,按回应决定启用哪些增强。

但“等回应“本身就是设计难题:等多久?等来的字节和用户的按键混在同一条 stdin 里,怎么分?三家的答案几乎是一个光谱。

Codex:有预算的轮询,加一条哨兵捷径。 terminal_probe 模块存在的原因是注释里的一句话:crossterm 的公共查询 API 最长会等两秒,“对启动和恢复来说太久,不支持的终端应该干脆退回保守默认”。所以 Codex 自己写探测:每组查询 250ms 预算(研究时为 100ms,Codex 于 2026-09 上调至 250ms,#46855),探光标位置、OSC 10/11 默认前景背景色、kitty 键盘增强支持;探测消耗掉的字节会回放进 crossterm 的解析器,保证探测期间用户的真实按键不丢。kitty 探测里还藏着一条捷径:查询后面跟着一个主设备属性(DA)请求,终端按序应答,DA 到了而键盘标志没到,就立即判定不支持,不必等满 250ms。整个过程带耗时埋点(“terminal startup probes completed”),探测在启动链路里是被当作正式开销来管理的一环。

Claude Code:用顺序代替超时。 同一条哨兵,Claude Code 押得更彻底:terminal-querier 不设超时。技巧叫 DA1 哨兵:每批查询末尾追加一个 DA1 查询(主设备属性),而 VT100 以来的每个终端都会回答 DA1,且终端按顺序应答。于是判定变成纯顺序问题:你的响应先于 DA1 到,说明支持;DA1 先到了,说明不支持。超时这个维度被从判定机制里删掉了,换成对一个老旧但普适的协议不变量的信任。探测目录里的清单也值得看:DECRQM 问同步输出(模式 2026)与 grapheme 聚簇(模式 2027)、OSC 11 问背景色、kitty 键盘查询、XTVERSION 问终端名——XTVERSION 的注释点破了为什么环境变量不可靠:查询走 pty(伪终端)不走环境,能穿透 SSH,而 TERM_PROGRAM 不能。(Claude Code 以打包形式发布、未公开源码;本段的模块名与注释引自其 terminal-querier.ts 源码镜像。)

Kimi:协商式握手。 kitty 键盘协议的完整三件套一次发出:推入目标标志位、查询当前标志、追加设备属性查询(ESC[>7u ESC[?u ESC[c),然后按 150ms 分片超时收集回应。另有一个容易漏的收尾细节:退出前先排空 stdin——否则 kitty 协议下按过的键会留下“释放事件“,终端在你退出后还在吐字节。

还有第四种哲学,是我自己设计出来的:ForgeLoopTUI 不探测。RawTTY.enter() 无条件推入 kitty 消歧标志和 bracketed paste 开关,注释写明理由——“不支持的终端会静默吸收这些序列”。这是拿终端生态的一个经验事实当赌注:未知序列无害。


二、一个键为什么不是一个键

探测的主要对象之一是键盘协议,因为传统终端键盘编码是歧义丛生的:Esc 键和 Alt 前缀共用 0x1b,Ctrl+I 和 Tab 是同一个字节,Ctrl+M 和回车是同一个字节。kitty 键盘协议(CSI-u)的存在意义就是消歧:给每个按键事件完整的键码与修饰符。

启用它是改善,也是新的维护负担。Codex 留了显式逃生门(CODEX_TUI_DISABLE_KEYBOARD_ENHANCEMENT 环境变量);Kimi 除协议外还备了一条原生侧通路——通过原生 helper 直接轮询真实修饰键状态(native-modifiers.ts),协议报不上来的时候问操作系统;Claude Code 则同时解析两套编码——CSI-u 和 xterm 的 modifyOtherKeys——并注释了两者的参数顺序相反(ESC[13;2u vs ESC[27;2;13~),后者主要在 SSH 场景出现,因为“TERM 嗅探认不出 Ghostty,而我们从不主动推 kitty 模式“。

同一条消歧目标,四家四种姿态:Codex 探测后启用、留开关;Kimi 协商加原生兜底;Claude 只解析不推送,把两种编码都当既成事实接受;ForgeLoopTUI 乐观推送、解析器只映射 Enter 一个键(其余 CSI-u 键码静默丢弃。这是够用主义:我要的只是 Shift+Enter 和回车的区分)。

这没有对错,是各自对“多少终端会把我送进歧义“的不同估计。


三、模式开关:开了要对,关了要对,被劫持了也要对

bracketed paste、focus 事件、同步输出、kitty 键盘,输入侧的能力几乎全是模式:进入时打开,退出时关闭。后面会把模式开关列为攻击面,讲它“为什么危险“;这一篇补工程侧:为什么难对。

难在状态的所有权不排他。终端模式是全 fd 共享的全局状态,而进程会挂起:Codex 里 Ctrl+Z 是特殊键位(SUSPEND_KEY),进程切后台再回来,raw mode 可能已经被 shell 或别的程序动过——所以有 reapply_raw_mode_after_resume,resume 时重新核对。外部编辑器(第 5 篇)是同一类问题的放大版:起 $EDITOR 前退 raw mode、暂停事件总线,回来后全部恢复。模式开关的正确性是“开、关、被别人动过之后恢复“的三态核对,一个布尔值装不下。

这也解释了一个看似多余的字段为什么存在:Codex 的输入事件栈从 crossterm 的 EventStream 收敛成七种 TuiEvent——Key、Paste、Resize、Draw、Resume、FocusGained、FocusLost。Resume 和两种 Focus 能进这个清单,本身就是核对需求留下的痕迹:挂起恢复要重同步,焦点得失要影响光标样式与轮询节奏。


四、复用器与 alt screen:中间还有一层翻译

以上所有假设之上还有一层:用户可能隔着 tmux 或 Zellij。复用器是一个中间人终端:它代理你的查询、转译你的模式开关、按自己的窗口管理切割你的输出。后续我会讲 Codex 在这上面的演进:从 Zellij 特判,到特判删除、换成 ScrollbackStrategy 三档策略。这里只补一句输入侧的对称事实:复用器对输出做的是转译,对输入做的是过滤与改造,bracketed paste 标记、kitty 序列、focus 事件过一道复用器之后,可能变形、延迟或消失。上一篇的 paste-burst 启发式,有一部分用户就是复用器制造出来的。

alt screen 的启用判定(Codex 的 determine_alt_screen_mode)因此也不只是读配置,而是一次综合判断:用户配置、终端能力、复用器在不在场,三方一起定。


五、雷区表与它的空缺

把这一篇的对照收成一张表(能力 × 各家策略):

输入侧能力CodexClaude CodeKimi CodeForgeLoopTUI
能力探测250ms 预算 + DA 哨兵提前判定,字节回放DA1 哨兵为唯一机制,无超时协商序列 + 150ms 分片超时不探测,乐观推送
kitty 键盘探测启用 + 环境变量逃生门只解析不推送,兼收 modifyOtherKeys推 flags 7 + 原生修饰键兜底无条件推 ESC[>1u,只映射 Enter
bracketed paste支持,缺标记时走 paste-burst支持,缺标记时 \r 启发式归一支持,缺标记时走 paste-burst支持(ESC[?2004h)
挂起恢复与退出清理resume 重上 raw mode—(未见对应机制)退出前排空 stdin—(引擎层不持有进程模型)
终端身份OSC 10/11 默认颜色、光标位置XTVERSION(穿透 SSH)OSC 颜色判明暗主题不探测

表的最后我想诚实标注一个空缺:我原本想收一张“输入侧能力 × 终端模拟器“的雷区矩阵表,哪个终端在哪个序列上行为异常。结果是压根就收不齐:这类数据存在于各家的 issue tracker 和运维记忆里,每个 TUI 团队都在私下重攒一份。

输入侧的讨论比输出侧少一个数量级,重视程度也低一级,但这不代表这里不重要、坑少,反而处处是大坑,这张填不出来的表就是证据。我在这部分做得并不完备,主要是已经被各种大坑弄得疲惫不堪。


六、总结

输出侧的降级链有一个舒服的终点:颜色退到 16 色,内容还在。

输入侧没有这个终点:按键的含义错了就是错了,谈不上降级。所以输入侧的工程主题是“核对“,不是“降级“:启动时探测核对、模式开关三态核对、挂起恢复核对、复用器在场核对。终端是上世纪七十年代的协议,每一家 agent 都在为它重新核对一次。

输出侧讲完了,输入侧也讲完了。现在可以去中场了。第 7 篇的 Event Sourcing 往上走一层,回答输出侧那几篇不断逼近的问题:为什么这些挣扎最后都收敛到“事件“这个抽象上。


参考与延伸

  • 本篇与第 5 篇同期写成。Codex 部分基于本地快照 main 6b9826e3(2026-09-09)的阅读,探测相关代码在 codex-rs/tui/src/terminal_probe.rs 与 terminal_probe/startup_replay.rs;探测预算此后由 #46855(2026-09-20 合入)从 100ms 上调到 250ms。
  • Claude Code 以打包形式发布、未公开源码;terminal-querier.ts 的模块名与注释引自 2026-03-31 经 npm source map 外泄的公开快照,与第 5 篇所用快照相同。
  • Kimi Code 部分(kitty 握手、native-modifiers.ts)按第 5 篇标注的 kimi-code 本地源码 54117a6b(2026-09-24)理解。
  • ForgeLoopTUI 部分基于 ForgeLoopTUI v1.2.1 源码(RawTTY.enter() 与按键解析)。