tui-design

TUI 和 CLI 设计

设计平静、可预测、快速且尊重终端媒介特性的终端软件。将此文件视为工作流与横切关注点的约定。请从负责该主题的唯一参考文档中加载详细指南，而不是在此处重新整理或重复说明。

回答前先确定参考文档

需求	权威参考文档
Go、Bubble Tea、Lipgloss、Bubbles、tview、gocui	references/ecosystem-go.md
Rust、Ratatui、crossterm、Cursive	references/ecosystem-rust.md
Python、Textual、Rich、prompt_toolkit、urwid	references/ecosystem-python.md
TypeScript/JavaScript、Ink、OpenTUI、Clack、Inquirer	references/ecosystem-typescript.md
一次性命令、参数、流、退出码、--json 和错误、补全、分页、配置、Windows、CLI 测试、自动化	references/cli-basics.md
布局和线框图、内联界面与备用屏幕、边框、层级、颜色、信息密度、响应式行为和最小尺寸、状态（空、加载中、部分完成、错误、过期）、表格、差异视图、模态框、状态栏和消息、进度和微调器、主题、图标和 Nerd Fonts、本地化和 Unicode 宽度、无障碍（屏幕阅读器、纯文本模式、动画）	references/visual-patterns.md
按键、Esc/q/Ctrl+C 退出顺序、tmux 或按键编码会截获的按键、焦点、导航、搜索和筛选、多选、帮助和命令面板、滚动、实时数据选择、日志跟随模式、树、文本输入、表单、鼠标、确认、撤销	references/interaction-patterns.md
闪烁或撕裂、转义序列和终端模式（括号粘贴、键盘协议以及无法传入的 Shift+Enter、鼠标、焦点、同步输出、光标、标题、进度）、tmux、screen、Zellij、SSH 和 Windows 行为、剪贴板、链接、通知、色深和主题检测	references/terminal-protocols.md
案例研究：lazygit、k9s、fzf、btop、helix、yazi、atuin	references/exemplar-apps.md
屏幕截图或演示录屏	已安装时使用 vhs-cli-demos 技能；否则使用 references/cli-basics.md → 演示录屏

仅加载任务所需的参考文档。如果提示中点名了框架或生态系统，在对 API、生命周期、实现或测试作出说明前，务必先加载对应的生态系统参考文档。具体细节以生态系统参考文档为准。视觉和交互参考文档适用于所有生态系统的相应领域。示例应用是证据和灵感来源，不能替代模式参考文档。

如果没有指定语言，只有在生态系统选择会显著影响答案或实现时才提问。否则，给出合理建议并继续：打磨成熟的单文件二进制程序选 Go，注重控制力和可靠性选 Rust，快速构建产品选 Python，已有 React 或 npm 分发优势时选 TypeScript。

先确定产品类型

在选择框架或布局前，先确定输出约定：

产品形态	默认约定
一次性 CLI	不使用实时全屏界面。结果写入稳定的 stdout，诊断信息写入 stderr，并使用有意义的退出码。加载 cli-basics.md。
呼出–选择–退出工具	Shell 上下文很重要时，优先使用内联界面。将交互界面输出到 stderr 或 /dev/tty，并将所选结果输出到 stdout。只有在大型预览或工作集需要稳定空间时，才使用全屏界面。
全屏会话	使用备用屏幕和稳定的空间模型。将终端恢复、调整大小、挂起和重绘行为视为产品要求。

然后确定工作流形态——持久面板、Miller 列、逐层深入堆栈、仪表板、IDE 式窗格、覆盖层或标签页——并根据 visual-patterns.md 核验。编写代码前，先画出各状态和布局：初始、加载中、空、部分完成、成功、错误、断开连接和尺寸过小（visual-patterns.md → 状态）。在设计方案中，除了宽屏布局，还应提供最小尺寸（60 列）下的 ASCII 布局草图。

完成任务

1. 判断产品形态及其 stdout/stderr 契约。
2. 找出主要用户操作循环和最常见的 5–8 项操作。
3. 选择生态系统，并加载其参考资料及任何相关模式参考。
4. 勾勒宽屏、标准、窄屏和最小尺寸下的布局与状态转换。
5. 使用生态系统的原生架构实现；在框架允许的情况下，将状态、更新和事件处理与渲染分开。
6. 验证生命周期清理、输入可发现性、输出行为、宽度处理和异步工作。
7. 先测试成本最低且稳定的层，再测试渲染帧；只有当集成风险足以证明其合理时，才进行小规模 PTY 冒烟测试。

对于设计问题，先给出建议，再进行解释。对于实现，先检查现有架构和依赖，再引入新框架或抽象。对于评审，引用具体观察，并按对用户造成的伤害程度排列改进项。

保留以下跨领域契约

终端生命周期

• 对于全屏会话，使用备用屏幕；对于有界和单次工作流，尽可能以内联方式呈现。
• 优先使用框架管理的终端清理。在所有退出路径（包括错误和 panic）中恢复原始模式、屏幕缓冲区、光标和输入模式。如果框架已负责信号处理，就不要自行实现。
• 窗口大小变化时，基于当前帧或窗口尺寸重新布局。只有布局开销较大时，才合并连续的尺寸变化事件。
• 将最终关闭与临时交接视为不同的边界。对于编辑器、shell 或受支持的挂起操作，优先使用框架的交接 API：暂停 UI 输入，恢复面向 shell 的终端状态，等待，然后重新进入各模式、重新加载外部可变数据，并强制完整重绘。重绘只会重新绘制当前模型，不会刷新已更改的数据。需要恢复运行的应用不要执行最终卸载；也不要假设 Windows 上存在 POSIX 信号。
• 不要让日志和调试输出出现在 TUI 占用的屏幕上。请使用文件、框架控制台或独立的诊断流。

渲染、数据与性能

• 绝不要让 UI/事件线程在磁盘、网络或子进程操作上阻塞。通过命令、消息、任务、通道或框架事件返回结果。
• 在输入、数据变化、尺寸变化或有意设置的计时器触发时渲染；不要在无条件循环中重复绘制未变化的状态。
• 测量终端单元格宽度，而不是字节、码点、len() 或 JavaScript 字符串长度。测试 CJK 字符、组合附加符号和 emoji。
• 对可能增长到数百行以上的集合进行虚拟化。表格内应截断而非换行；在详情视图中展示完整值。
• 除非用户明确更改布局，否则保持面板位置稳定。空间记忆是导航的一部分。

含义与无障碍

• 定义语义化的样式令牌，不要到处散布颜色字面量。在自动颜色模式下遵循 NO_COLOR，并在单色模式下保留含义。
• 绝不要仅依赖颜色传达信息。应搭配文本、形状、位置或符号；Unicode 支持不确定时，提供 ASCII 备用方案。
• 确保每项操作都能通过键盘完成。鼠标支持可以提升操作效率，但不能成为操作的必要条件。
• 仅在不与文本输入或完整的有界提示词键位映射冲突时，才提供常见的导航别名。保留预期的保留按键行为：Ctrl+C 用于取消或退出，Ctrl+Z 通过框架挂起。其他哪些按键为保留按键，以及原始模式为何会释放 Ctrl+S，请参阅 interaction-patterns.md → 保留按键。
• 根据复杂程度提供相应的操作发现机制：有界提示词应提供完整的内联控件；操作丰富的全屏应用应提供上下文提示、帮助，并可选择提供命令面板。
• 当自动化或重要的无障碍需求需要时，提供纯文本的 --no-tui 或等效模式；visual-patterns.md → 无障碍 说明了该模式必须包含的内容。

主动运用两项评审准则

这些准则能发现用户很少会明确指出的问题。无论问题是否与布局有关，都要将两项准则用于你设计或评审的每个布局。

执行杂乱度审查

让“繁杂”变得可计量。报告：

• 边框嵌套深度——从终端边缘到内容之间通常不应超过一层边框；
• 有多少种信号编码了相同状态——[PASS]、绿色、勾号和行标记，就有四种；
• 每一行都出现的标记——既然如此，它们就什么也没标示；
• 用于装饰、标签和重复模板内容，而非数据的单元格占比。

明确指出要移除的具体边框、标记、标签或重复字段。不要止步于“简化一下”。使用 visual-patterns.md → 杂乱度审查 中的完整方法。

压测最低尺寸

说明在 80×24 和 60 列 tmux 分屏中会发生什么：哪个面板优先、哪些内容会隐藏、哪些会截断、哪些会改为下钻展示，以及何时会显示如实的“终端太小”状态。每种多列布局都需要单面板回退方案。使用 visual-patterns.md → 响应式设计 中的断点阶梯和最小尺寸方法。

构建与验证规范

让业务状态足够独立，以便无需终端即可测试。在 MVU 或即时模式系统中，将合成事件传入更新逻辑并断言状态。在保留式／组件系统中，驱动负责该行为的最小组件或应用程序测试框架。

采用底部宽、顶部窄的测试金字塔：

1. 对状态转换、解析、排序、筛选和命令构建进行单元测试。
2. 在固定的终端尺寸和色彩配置下，对渲染帧进行快照测试或黄金测试，包括 80×24、60 列和硬性最小尺寸。
3. 使用一到两个 PTY 端到端流程验证生命周期和真实键盘集成，不要将其作为主要测试套件。

至少验证：

• 正常退出、中断、错误和 panic 后的清理；
• 支持时的调整大小、尺寸过小时的行为，以及挂起／恢复；
• 空、加载中、部分完成、错误、断开连接和大数据状态；
• 键盘可达性、焦点可见性和帮助信息准确性；
• NO_COLOR、16 色或单色、ASCII 回退，以及非 TTY 输出；
• 宽字符、组合标记、截断、排序和虚拟化；
• 不破坏 stdout，且事件／渲染路径中没有阻塞 I/O。
• 对于一次性 CLI，在黄金测试中验证 stdout、stderr 和退出码，并确保无 TTY 且设置 NO_COLOR 时也能正常工作（cli-basics.md → 测试一次性 CLI）。

使用生态参考文档中的准确测试和调试 API。切勿向正在运行原始模式或备用屏幕的 UI 输出诊断信息。

评审现有界面

按优先级顺序报告依据：

1. 产品形态是否合适，还是应将全屏流程改为内联或一次性流程？
2. 是否有任何退出路径会遗留原始模式、光标状态、鼠标捕获或屏幕缓冲区？
3. UI 是否会阻塞、进行无谓重绘、在调整大小时崩溃，或错误计算单元格宽度？
4. 首次使用的用户能否找到并使用重要操作，同时不影响文本输入或违反终端惯例？
5. 杂乱度审查统计了什么，应删掉哪些具体元素？
6. 在 80×24、60 列和声明的最小尺寸下会发生什么？
7. 输出流、退出码、非 TTY 行为、NO_COLOR 和纯文本模式，是否支持脚本和无障碍使用？
8. 状态转换和固定帧是否在适当的测试层级得到覆盖？

避免泛泛而谈。让每项建议都对应用户可见的问题、实现风险或可衡量的降噪效果。

提供有用的建议

对于实践中已形成共识的做法，要给出明确建议：使用语义化颜色、干净地恢复终端、提供响应式回退、避免阻塞工作、根据宽度调整渲染方式，以及如实定义流式传输契约。说明内嵌式与全屏式、模态与非模态输入、鼠标支持以及破坏性操作确认之间的实际权衡。

采用所选生态的惯用做法，而不是照搬另一种框架的架构。如果某项设计选择仍较抽象，请指向 exemplar-apps.md 中的相关案例研究，并说明其中哪些解决方案可以借鉴。