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
一次性命令、参数、流、退出代码、自动化	references/cli-basics.md
布局、缓冲区、边框、层级、颜色、密度、响应式行为、表格、主题、无障碍性（屏幕阅读器、纯文本模式、动画）	references/visual-patterns.md
按键、焦点、导航、模式、表单、鼠标、确认、撤销、OSC 功能	references/interaction-patterns.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	不使用实时全屏 UI。结果写入稳定的 stdout，诊断信息写入 stderr，并返回有意义的退出代码。加载 cli-basics.md。
唤出–选择–退出工具	Shell 上下文重要时优先使用行内界面。将交互界面输出到 stderr 或 /dev/tty，并将所选结果输出到 stdout。只有大型预览或工作集需要稳定空间时才使用全屏界面。
全屏会话	使用备用屏幕和稳定的空间模型。将终端恢复、调整大小、挂起和重绘行为视为产品需求。

然后确定工作流形态——常驻面板、Miller 列、逐层深入堆栈、仪表盘、IDE 风格窗格、覆盖层或标签页——并依据 visual-patterns.md 进行验证。编写代码前先画出状态和布局草图：初始、加载中、空、部分完成、成功、错误、断开连接和窗口过小。

执行任务

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 通过框架挂起。原始模式会将两者作为按键事件传递并禁用 XON/XOFF，因此全屏应用可以绑定 Ctrl+S；流控只影响行模式程序。
• 根据复杂程度匹配可发现性：有界提示词应提供完整的行内控件；功能丰富的全屏应用应提供上下文提示、帮助，并可选择提供命令面板。
• 当自动化或重要的无障碍需求要求线性输出时，提供纯文本 --no-tui 或等效模式；visual-patterns.md → Accessibility 定义了其中必须包含的内容。

主动应用两项审查习惯

这些检查能发现用户鲜少明说的问题。即使问题与布局无关，也要对你设计或审查的每种布局应用这两项检查。

执行杂乱度审查

将“拥挤”量化并报告：

• 边框嵌套深度——终端边缘与内容之间超过一层边框通常就太多了；
• 表达同一状态的信号数量——[PASS]、绿色、勾号和行标记合计就是四种；
• 每行都出现、因而无法起到标记作用的标记；
• 用于装饰、标签和重复样板而非数据的单元格占比。

明确指出要移除的边框、标记、标签或重复字段。不要止步于“简化一下”。请使用 visual-patterns.md → The clutter audit 中的完整方法。

压力测试终端底部尺寸

说明在 80×24 和 60 列 tmux 分屏中会发生什么：哪个窗格优先显示、哪些内容会隐藏或截断、哪些内容会变为可深入查看的内容，以及何时会显示如实的“终端太小”状态。每种多列设计都需要单窗格回退方案。使用 visual-patterns.md → 响应式设计 中的断点层级和最小尺寸方法。

构建与验证规范

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

采用底部较重的测试金字塔：

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

至少验证以下内容：

• 正常退出、中断、错误和 panic 时的清理；
• 支持的情况下，调整大小、尺寸过小时的行为以及挂起／恢复；
• 空、加载中、部分数据、错误、断开连接和大数据状态；
• 键盘可达性、焦点可见性和帮助内容准确性；
• NO_COLOR、16 色或单色、ASCII 回退和非 TTY 输出；
• 宽字符、组合标记、截断、排序和虚拟化；
• 不损坏 stdout，且事件／渲染路径中没有阻塞式 I/O。

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

审查现有界面

按优先级顺序提供证据：

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

避免泛泛而谈。每项建议都要关联到用户可见的问题、实现风险或可衡量的噪声减少。

提供有用的建议

对于实践中已有共识的方面，给出明确建议：语义化颜色、干净恢复终端、响应式回退、非阻塞工作、考虑宽度的渲染，以及诚实的流契约。说明行内与全屏、模态与非模态输入、鼠标支持和破坏性操作确认之间的实际权衡。

采用所选生态系统的惯用方式，不要照搬其他框架的架构。如果某项设计选择仍较抽象，请指向 exemplar-apps.md 中相关的案例研究，并说明其中哪些解决方案适用。