tui-fundamentals

TUI 基础、架构与框架选择

当任务涉及终端产品的整体形态时，使用此技能：要构建哪类 TUI、使用哪种抽象、如何组织状态，或者全屏终端 UI 是否合适。

首要决策：TUI 是否合适？

当用户需要持续的视觉反馈、多步骤导航、键盘驱动的探索、从众多条目中进行选择，或类似仪表盘的控制界面时，优先选择丰富的 TUI。如果流程简短、便于脚本化、主要面向自动化，或可能由屏幕阅读器和 CI 系统使用，则优先选择面向行的 CLI、提示或纯文本输出。

生产级终端产品通常同时提供：

• 可脚本化的 CLI 界面，用于自动化、无障碍访问、日志记录和非 TTY 场景。
• 可选的 TUI，用于探索、监控、批量选择或引导式工作流。

架构规则

1. 分离模型、更新和视图。 业务状态不应直接输出到终端。渲染读取状态；输入生成事件；更新逻辑转换状态。
2. 将终端尺寸视为输入。 每次调整大小时，都必须根据宽度和高度重新计算布局。不要将某个终端尺寸写死。
3. 在一个位置管理终端生命周期。 原始模式、备用屏幕、鼠标、焦点、键盘协议和清理逻辑都应集中管理。
4. 确保所有操作都能通过键盘完成。 鼠标支持是增强功能，不应成为主要导航方式。
5. 针对降级情况进行设计。 对于 TERM=dumb、非 TTY 输出、缺少颜色、Windows 控制台差异、tmux/screen、SSH 和 CI，都应有明确的行为。
6. 避免隐藏的全局终端写入。 日志、进度信息和后台任务输出不得破坏屏幕内容。

框架选择速查表

需求	首选方案
需要精确渲染的 Rust 全屏应用	Ratatui + Crossterm
需要组件、CSS 和异步工作线程的 Python 产品级应用	Textual
Python 丰富输出、进度、表格、Markdown 和日志	Rich
Python REPL、Shell、补全和复杂提示输入	prompt_toolkit
经典的轻量级 Unix TUI	curses/ncurses
采用 Elm 风格、支持可组合命令的 Go 应用	Bubble Tea + Bubbles + Lip Gloss
自带表单、表格和树形视图的 Go 框架	基于 tcell 的 tview
可移植的 Go 底层单元格引擎	tcell
Node 中采用 React 风格的终端组件	Ink
Node 类 DOM 的全屏组件	Blessed
.NET 全屏视图	Terminal.Gui
.NET 丰富的 CLI 输出和提示	Spectre.Console

在新项目中确定框架之前，请阅读 references/framework-selection.md。

产品设计清单

• 用一句话定义主要用户流程。
• 决定应用采用全屏、内嵌、提示式还是混合模式。
• 列出所需环境：Windows Terminal、经典 conhost、macOS Terminal、iTerm2、GNOME Terminal、Alacritty、SSH、tmux/screen、CI 和日志。
• 定义终端的最小尺寸，以及小屏幕下的回退方案。
• 定义退出按键、破坏性操作的确认规则和恢复说明。
• 为每项必要操作定义非交互式替代方式。
• 决定如何呈现帮助：页脚提示、?、命令面板、--help、文档。

常见失败模式

• 为本应可脚本化的工作流构建全屏 UI。
• 已有框架能解决布局、输入、清理和测试，却仍选择底层转义序列方案。
• 将业务逻辑与终端写入混在一起，导致测试脆弱、渲染不一致。
• 直到后期才考虑屏幕阅读器用户、CI、管道和 TERM=dumb。
• 假设颜色、Unicode 图标、Nerd Fonts 或鼠标支持始终可用。

参考文件

• references/framework-selection.md - 详细的生态系统比较和决策树。
• references/tui-architecture.md - 状态、事件、生命周期、日志和分发模式。