tui-troubleshooting

TUI 故障排查：冻结、卡住、空白屏幕和终端状态损坏

当用户报告 TUI“冻结了”“卡住了”“终端变成空白了”“无法再接受输入了”“终端无法正常使用了”或“在一个终端中正常，但在另一个终端中不正常”时，请使用此技能。在证实并非如此之前，应将这些情况视为终端生命周期故障。

首次响应规则

不要只给出浅显的检查清单。应先确定故障类型，检查启动和清理顺序，并寻找具体的生命周期 bug：

1. 应用是否进入了 raw mode、alternate screen、mouse、focus 或 bracketed paste 模式？
2. 每种模式是否都会在正常退出、Ctrl-C、异常、panic、promise 被拒绝和提前返回时恢复？
3. 终端设置完成后，stdin 是否仍在传输数据？
4. 应用是否至少渲染并刷新了一帧，然后才等待异步任务或输入？
5. 日志、stderr、后台任务或子进程是否会写入同一个终端界面？
6. 问题是否仅在 tmux、SSH、Windows/ConPTY、CI 或非 TTY 管道中复现？

高概率冻结原因

在排查少见的终端协议问题之前，优先检查以下原因：

• Raw mode 未恢复。 回显已禁用，行编辑也不可用，因此崩溃或提前返回后，shell 看起来像是卡住了。
• 暂停的 stdin 从未恢复。 在 Node 中，调用 process.stdin.pause() 后进入 raw mode，却没有调用 resume()，会导致 data 事件不再触发；UI 可能会无限等待。
• 缺少首次渲染。 应用进入 alternate screen/raw mode 后启动异步状态检查，却从未刷新初始帧，因此用户看到的是空白屏幕。
• 启动工作阻塞。 首次绘制前运行的同步文件、网络或进程调用会阻塞事件循环或渲染循环。
• 输入模式不匹配。 代码在 stdin 处于 raw mode 时等待面向行的输入，或在 stdin 处于 cooked mode 或已暂停时等待原始按键事件。
• 清理时模式未恢复。 退出后，alternate screen、mouse reporting、focus events 或 bracketed paste 仍处于启用状态。

基本诊断思路

请询问或检查：

• 使用的语言、框架和终端库。
• 从进程启动到首次渲染的启动顺序。
• 清理逻辑、guard、finally、defer、Drop、atexit 和信号处理程序。
• stdin/stdout/stderr 是否为 TTY。
• 问题是在本地、SSH、tmux/screen/Zellij、Windows 还是 CI 中发生。
• 终端的原始症状：回显关闭、光标隐藏、alternate screen 空白、粘贴包装符、鼠标点击被吞掉、序列乱码。

用户恢复命令

终端卡住时，请先告知用户如何恢复，再进行深入调试：

stty sane
reset
printf '\033[?1049l\033[?25h\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?1004l\033[0m'

在 Windows PowerShell 中，如果子进程使 ConPTY 状态异常，关闭选项卡有时是最快的恢复方法。

建议采用的修复模式

每个 TUI 都应由一个生命周期管理者负责：

1. 验证 TTY，或选择非 TUI 模式。
2. 首先安装清理保护。
3. 进入 alternate screen/raw mode，以及可选的 mouse/paste/focus 模式。
4. 如果需要原始按键事件，则恢复或引用 stdin。
5. 立即渲染并刷新初始帧。
6. 在首帧渲染后启动异步工作。
7. 将日志输出到受控终端界面之外。
8. 严格按相反顺序恢复各模式，且只恢复一次。

参考文件

• references/freeze-hang-diagnosis.md - 启动和运行时卡住问题的根本原因、症状、诊断方法、修复示例和预防模式。
• references/terminal-state-corruption.md - 显示乱码、颜色错误、光标问题、部分渲染、写入交错，以及调整大小与渲染竞态。
• references/diagnostic-playbook.md - 针对冻结、终端状态卡住、无输入、SSH/tmux、Windows 和输出乱码问题的决策树及具体命令。