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

输入框——agent TUI 最被低估的组件

第 2 到第 4 篇讲完了输出侧:怎么把内容画对、画快、画不崩。这两篇(05、06)翻过来讲输入侧,难点换成了另一件事:多层交互状态,要在同一条键盘事件流上不打架。


一、最大的单文件

先看一个经验事实:在 Codex 的 TUI 里,代码量最大的单文件是输入框,不是渲染控制器,也不是事件总线。bottom_pane/chat_composer.rs 一个文件 1.3 万行,功能实现约五千行,测试约八千行。

一个“打字的地方“为什么值五千行实现?因为键盘事件流只有一条,而想消费它的东西越来越多:普通文本、光标编辑、历史回溯、slash 命令候选、文件引用弹窗、skill 弹窗、@提及弹窗、粘贴、外部编辑器、组合键。这些消费者不是并存关系,而是互斥又嵌套:弹窗开着的时候,上下方向键归弹窗,不归文本;但 Enter 归谁,要看弹窗里有没有选中项。第 2 篇 §7 讲的光标定位和 IME 是这个组件的底层,第 4 篇 §8 讲的多行输入竞态是它的边界,本篇不再重复;本篇讲的是它的中层:那个决定“这个按键归谁“的仲裁结构。


二、弹窗优先级链

Codex 在这里的判断结构是一条显式的优先级链。按键到达 composer 后,处理函数按固定顺序逐级问询:文件弹窗在不在?在就归它,它选择吞掉还是放行;放行则问 skill 弹窗;再放行问 @提及弹窗;都没有,才走裸文本路径。每一级返回 (InputResult, bool),即结果加“是否已消费“。

这个设计的要点不在链本身(任何 GUI 的响应链都长这样),在于它把“哪个弹窗优先“从运行时状态变成了代码顺序:弹窗之间的优先级不靠注册表、不靠 z-index,靠 if-else 的书写顺序,这是最显式、最不容易被配置改坏的形式。考虑到这些弹窗涉及文件引用和 skill 调用这种直接影响上下文组装的功能,“优先级不可配置“是刻意的保守。

Kimi Code 走了另一条路,而且走得更远:它的 editor-component.ts 把整个编辑器定义成一个可替换接口(EditorComponent),注释明说动机——让扩展可以提供自己的编辑器实现,比如 vim 模式、emacs 模式、自定义键位。Codex 把优先级固化在代码顺序里,Kimi 把整个输入行为做成扩展点。一个防的是“被改坏“,一个赌的是“被扩展“。

笔者注:这一点上我更倾向 Kimi Code,Codex 有些过于保守了。


三、“这段输入是什么“在 composer 内部裁决

回车之后发生什么,答案不是一个字符串,是一个枚举。Codex 的 InputResult 把提交裁决为几类:Submitted{text, text_elements}(普通消息,附带已解析的元素区间)、Command(slash 命令)、CommandWithArgs 等。“这是消息还是命令“的判断在 composer 内部完成,上游拿到的已经是结构化的裁决结果。

slash 命令因此分两层:composer 层负责解析候选、驱动补全弹窗;执行分派在 ChatWidget 侧,slash_dispatch.rs 一个文件 1288 行。另有一个 ! 前缀的 shell 逃生口,提交时剥掉前缀直接进 shell。这个职责切分值得记住:composer 管“这是什么“,是交互状态机;分派层管“拿去怎么做“,是业务路由。


四、粘贴不是一种操作,是四种

“用户粘贴了一段东西“在实现层至少是四种不同的东西:

其一,bracketed paste 事件。 终端用 ESC[200~/ESC[201~ 包裹粘贴内容,TUI 收到一个完整的 Paste 事件,做 CRLF 归一化后进 composer。这是最干净的路径,前提是终端支持并开启了括号粘贴模式,下一篇会讲这个前提有多不牢靠。

其二,系统剪贴板直读。 图片粘贴走的是另一条路:直接读系统剪贴板,探测图片数据、编码、存临时文件、在文本里留占位。Codex 有专门的 clipboard_paste.rs 和一整组 PasteImageError 类型;Claude Code 的发布产物里也有独立的图片粘贴快捷键处理。

其三,大粘贴占位符。 粘贴几万字符的日志,不该把输入框撑爆。Claude Code 的做法:超过一万字符,显示时只留头 500 字符和尾 500 字符,中间折叠成一个占位引用(inputPaste.ts)。Codex 同构:大粘贴替换为占位符,提交时才还原展开(composer 头注释里的 “expands pending paste placeholders”)。两家独立收敛到同一个形态:显示层是占位符,数据层是全文,提交时展开。

**其四,paste-burst:没有括号粘贴时的湍流识别。**这是我最喜欢的一个,因为我自己做的时候深受其扰。

有些终端(特别是 Windows 上)不发 bracketed paste 标记,粘贴到达时就是一串极快的普通按键:人打字到不了那个速度,机器可以。于是识别粘贴变成了湍流识别:Codex 的 paste_burst.rs 和 Kimi 的 paste-burst.ts 是同一个启发式状态机的两次独立实现。字符间隔在毫秒级(Kimi 的参数:连续 ≥8 个字符、间隔 ≤8ms)就怀疑是粘贴;粘贴流里的 Enter 必须当换行而不是提交(Kimi 的 Enter 抑制窗口是 120ms)。两家的文件头注释写着同一个动机:防止粘贴里的回车把半截内容提交出去。

第四种的启示超出粘贴本身:当协议信号缺失时,行为信号(速度分布)可以顶替。 这在终端输入里是通用技法。


五、把键盘交出去:外部编辑器接力

composer 还有一个出栈方向:把整段输入交给 $EDITOR。Codex 的流程是:composer 内触发 → 发 LaunchExternalEditor 事件 → 读 $VISUAL/$EDITOR 起子进程。起进程之前先退出 raw mode,把终端归还给编辑器;编辑器退出后恢复 raw mode、读回文件、灌进 composer。期间事件总线可以暂停和恢复(EventBroker::pause_events/resume_events)。

这是一次跨进程的状态交接:终端模式、按键流、绘制权,全部先交出去再拿回来。任何一个环节没对齐(raw mode 没退干净、事件流没暂停、恢复时状态对不上),用户看到的就是花屏或按键丢失。输入框因此不只是“消费键盘“的组件,还是键盘这个资源的进出关口。


六、keymap 只做解析

最后一个职责切分:keymap 不管行为。Codex 的 keymap.rs 只做“配置 → 运行时键位“的解析(from_config),产出键位表;按键命中表之后做什么,是各组件自己的事。组合键(chord)有等待窗口:按下前缀键后等 KEY_CHORD_TIMEOUT,超时按单键处理,这个等待是用全局帧调度器的 schedule_frame_in 实现的,和状态行动画共用同一套定时基建。

Kimi 的对应物是声明式的:keybindings.ts 是一张全局键位注册表,下游包靠声明合并往里加键位;编辑动作枚举得极细,连 kill-ring(yank/yankPop,emacs 的剪切环)都有。读这些枚举,像在读一份“用户手指习惯“的清单。用户的肌肉记忆是存量,输入组件得接得住。


七、总结

诚实交代 ForgeLoopTUI 的位置。它是渲染引擎不是产品,输入侧停在引擎层:InputPipeline 做 bracketed paste 聚合(ESC[200~ 进、聚合成纯文本、ESC[201~ 出为一个 .paste 事件),KeyParser 把 CSI/CSI-u/SS3/Alt/控制字符归一成 KeyEvent,未知序列静默丢弃。没有弹窗层、没有 slash 命令、没有外部编辑器——这些在它的定位里属于接入方。

读完 Codex 的 composer,我更新了一个判断尺度,而不只是发现“ForgeLoopTUI 缺功能“:**composer 的状态机复杂度是 harness 成熟度的镜子。**一个 agent 产品要支持多少种“输入不只是文本“的情形(文件、skill、图片、命令、长粘贴、外部编辑器……),它的输入框就得在幕后配一套相应的状态机。

输出侧的复杂度藏在渲染管线里,真出了问题变慢卡顿,用户未必那么敏感,可能还以为是网络问题;输入侧的复杂度直接顶在用户手指下面,每一个弹窗优先级、每一毫秒的 Enter 抑制窗,用户都感觉得到,而且非常敏感。

如果你觉得这一篇已经够黑暗了,先别急着感叹,下一篇还要更往下走。这一篇的所有机制都假设键盘事件流是可靠的:按键是什么、粘贴有没有标记、模式开没开。真做过就会发现,这些假设在真实的终端世界里很脆弱,那才是输入侧最难的地方。


参考与延伸

  • 本文基于 2026-10-01 对以下源码的实际阅读:Codex 本地快照 main 6b9826e3(2026-09-09):codex-rs/tui/src/bottom_pane/chat_composer.rs(弹窗优先级链、InputResult)、bottom_pane/paste_burst.rs、clipboard_paste.rs、external_editor.rs、keymap.rs、chatwidget/slash_dispatch.rs。
  • kimi-code 本地源码 54117a6b(2026-09-24):packages/pi-tui/src/editor-component.ts、keybindings.ts、paste-burst.ts。
  • Claude Code 发布产物中的源码(2026-03-31 经 npm source map 外泄的公开快照):src/components/PromptInput/inputPaste.ts、src/hooks/useTextInput.ts。
  • 对照部分基于 ForgeLoopTUI v1.2.1 源码(Input/InputPipeline.swift、Input/KeyParser.swift)。