input-handling

TUI 输入处理、原始模式、键盘、鼠标、粘贴和焦点

当 TUI 需要读取按键、处理快捷键、支持鼠标、编辑文本、管理焦点或确保安全粘贴行为时，使用此技能。

输入约定

• 仅在交互式 TTY 会话中进入原始模式或 cbreak 模式。
• 为脚本、管道和 CI 提供非交互式替代方案。
• 将输入解码与应用操作分开。
• 确保每项操作都能通过键盘完成。
• 将鼠标支持视为可选的渐进增强。
• 除非用户可以重新绑定快捷键，否则保留预期的终端快捷键。

原始模式规则

原始模式会禁用行规程并改变信号行为。应集中管理原始模式，并可靠地恢复终端状态。验证 Ctrl-C、Ctrl-Z/挂起（在支持的情况下）、EOF、调整大小、终端关闭和致命异常时的行为。密码和令牌不得回显。

快捷键设计

优秀的快捷键易于发现、保持一致，并能避免冲突。

• 始终为常见操作提供可见帮助。
• 仅当与工作流风险相符时，才使用 q、Esc 或 Ctrl-C 退出或取消。
• 对破坏性操作进行确认；对不可逆操作要求更强的确认。
• 除非可配置，否则避免占用常见的终端、Shell、编辑器和复用器快捷键。
• 尽可能同时支持助记快捷键和导航按键。
• 区分全局快捷键与焦点所在组件的快捷键。

焦点模型

每个交互元素都需要：

• 稳定的标识。
• 焦点资格规则。
• 不单靠颜色来表示的可见焦点指示器。
• 适用时支持 Tab/Shift-Tab 或方向键导航。
• 明确规定禁用、隐藏、模态和嵌套控件的行为。
• 鼠标点击时先更新焦点，再执行操作。

粘贴与鼠标安全

为 Shell、编辑器、命令面板和多行输入启用括号粘贴。解析粘贴开始/结束标记，并将粘贴文本视为数据，而非一系列命令。对于鼠标输入，应根据当前布局验证坐标，并在调整大小后忽略过期事件。

故障模式

症状	可能原因	修复方法
Esc 响应有延迟	解析器正在等待，以区分 Alt 前缀	调整超时时间或使用框架的协议支持
Ctrl-C 无法退出	原始模式吞掉了信号	显式映射 Ctrl-C 并恢复终端状态
粘贴会触发操作	未启用括号粘贴，或将粘贴内容当作按键	启用粘贴协议并将内容作为文本处理
鼠标点击了错误的行	调整大小或滚动后布局已过期	根据当前视口验证坐标
焦点消失	移除组件后没有设置焦点回退目标	计算下一个符合资格的焦点目标

参考文件

• references/input-protocols.md - 键盘、鼠标、粘贴、焦点和调整大小事件的详细信息。
• references/keybinding-design.md - 快捷键设计、避免冲突以及表单/编辑器相关内容。