SuperAPI AI 工具集

tui-troubleshooting

通用与其它

查看项目

更新于 10-16 01:49

技能介绍

该技能面向终端 UI 应用的生命周期故障排查。当用户报告 TUI 冻结、卡死、终端空白、停止接受输入、终端被弄坏,或在某个终端可用而另一个不可用时,应将其视为终端生命周期失败,而非表面现象。

用途:先判定失败类别,检查启动与清理顺序,寻找具体的生命周期缺陷。核心检查点包括:应用是否进入 raw 模式、备用屏幕、鼠标、焦点或括号粘贴模式;这些模式是否在正常退出、Ctrl-C、异常、panic、Promise 拒绝和提前返回时全部恢复;终端设置后 stdin 是否仍在流动;应用是否在等待异步工作或输入前至少渲染并刷新一帧;日志、stderr、后台任务或子进程是否会写入同一终端界面;问题是否只在 tmux、SSH、Windows/ConPTY、CI 或非 TTY 管道中复现。

主要能力:优先排查高概率冻结原因,如 raw 模式未恢复导致回显关闭、stdin 被暂停后未恢复、缺少首帧渲染导致空白屏、阻塞式启动工作、输入模式不匹配、退出后备用屏幕或鼠标报告等清理模式泄漏。诊断时需了解语言/框架和终端库、从进程启动到首帧渲染的启动序列、清理守卫(finally/defer/Drop/atexit/信号处理器)、stdin/stdout/stderr 是否为 TTY,以及本地、SSH、tmux、Windows 或 CI 的复现情况。

使用方式:终端卡住时先告知用户恢复命令,如 stty sane、reset,以及 printf '\033[?1049l\033[?25h\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[?1004l\033[0m';Windows PowerShell 下有时关闭标签页最快。修复建议采用单一生命周期所有者:验证 TTY 或选择非 TUI 模式,先安装清理守卫,再进入备用屏幕/raw 模式及可选模式,按需恢复 stdin,立即渲染并刷新首帧,之后启动异步工作,将日志移出受控终端界面,并按相反顺序恢复模式且只恢复一次。

限制:资料未提供具体安装命令、支持的终端库版本或代码示例,仅含参考文件(freeze-hang-diagnosis.md、terminal-state-corruption.md、diagnostic-playbook.md)供进一步查阅。