framework-recipes

框架生态配方

当用户指定某个终端 UI 框架，或需要实用的生态指南时，使用此技能。若 API 语法或特定版本的行为需要精确确认，请获取最新的官方文档。

Rust 配方

Ratatui + Crossterm 是现代 Rust 全屏 TUI 的默认选择。围绕明确的状态、事件处理和渲染函数来构建应用。使用 Crossterm 处理跨平台终端设置和事件。在固定尺寸下对组件进行快照测试，并通过 PTY 对事件循环进行集成测试。

指南：

• 将终端设置和清理放在同一个 guard 中。
• 尽可能从不可变状态进行渲染。
• 使用约束和布局原语，而非绝对坐标。
• 将 panic 视为需要清理终端的事件。

Python 配方

Textual 适用于功能丰富的应用，支持组件、类 CSS 样式、工作线程和测试自动化。Rich 适用于丰富输出、进度、Markdown、表格、面板和日志记录。prompt_toolkit 适用于 shell、REPL、补全、多行编辑和自定义按键绑定。curses/ncurses 适用于经典、依赖轻量的 TUI，但需要谨慎清理。

指南：

• 对于 curses，使用 wrapper/finally 清理，并记住坐标顺序为 y,x。
• 对于 Textual，将应用状态与工作线程分离，并使用框架支持的 pilot 进行测试。
• 对于 Rich，如果丰富的滚动输出就能解决问题，就避免全屏复杂度。

Go 配方

Bubble Tea 使用 Elm 风格的 Model、Update 和 View。搭配 Bubbles 实现常见控件，并使用 Lip Gloss 处理样式和布局。tview 可通过 tcell 构建组件丰富的应用。若需更底层的单元格控制，可直接使用 tcell。

指南：

• 尽可能保持更新逻辑纯粹。
• 通过 commands/goroutines 执行耗时工作，并让它们返回消息。
• 在进行 PTY 测试前，分别测试 Update 和 View。

Node 和 TypeScript 配方

Ink 最适合 React 风格的终端组件、hooks 和组件测试。Blessed 适用于类 DOM 的组件树和手动屏幕生命周期管理。对于简短问卷，提示库通常比全屏应用更合适。

指南：

• 针对具体的库版本，验证调整大小、鼠标和 Windows 行为。
• 避免在渲染函数中执行副作用。
• 对依赖终端行为的流程使用 PTY 集成测试。

.NET 配方

Terminal.Gui 适用于支持视图、键盘导航、鼠标、主题和布局的全屏应用。Spectre.Console 适用于丰富的 CLI 输出、提示、进度、状态、树、表格和命令应用组合。

指南：

• 如果 UI 可以保持面向行的形式，优先选择 Spectre.Console，而非 Terminal.Gui。
• 对控制台 I/O 进行抽象，以便测试。
• 为自动化提供非交互式命令等效项。

C/C++、Zig 和 Swift 配方

ncurses 仍是经典的可移植 C TUI 层。notcurses 适用于现代视觉效果、丰富单元格、受支持时的图像，以及带回退方案的高性能终端图形。FTXUI 提供可组合的 C++ 组件和布局。zig-vaxis 是现代 Zig TUI 工具包，支持感知 Unicode 的终端处理。SwiftTUI 及相关 Swift 终端库适用于原生 Swift CLI，但应仔细验证平台和终端覆盖范围。

指南：

• 底层框架需要明确处理清理、Unicode 测量和功能回退测试。
• 优先选择有维护且明确记录 Windows、tmux 和 Unicode 行为的库。
• 除非部署终端受到控制，否则不要将图像/图形功能设为硬性要求。

参考文件

• references/rust-python-go.md - Ratatui、Textual/Rich/prompt_toolkit/curses、Bubble Tea/tview/tcell 的实用模式。
• references/node-dotnet-and-selection.md - Ink、Blessed、Terminal.Gui、Spectre.Console、迁移和选择方面的注意事项。
• references/low-level-and-emerging.md - C/C++ ncurses/notcurses/FTXUI、Zig vaxis、SwiftTUI 以及新兴工具包的注意事项。