用途
terminal-ui 是一套开发者体验（DevEx）指南，用于在使用 Ink（React for CLIs）和 Clack 提示库构建 TypeScript 终端用户界面（TUI）时提供性能与用户体验方面的最佳实践。它包含 42 条规则，分为 8 个类别，按影响程度排序，可用于指导自动化重构和代码生成。
适用时机
在以下场景中可参考这些指南：
- 使用 @clack/prompts 构建带交互式提示的 CLI 工具
- 使用 Ink 创建基于 React 的终端 UI
- 处理键盘输入和用户交互
- 优化终端渲染并防止闪烁
- 设计对开发者友好的 CLI 体验
规则类别（按优先级）
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 渲染与输出 | CRITICAL | render- |
| 2 | 输入与键盘 | CRITICAL | input- |
| 3 | 组件模式 | HIGH | tuicomp- |
| 4 | 状态与生命周期 | HIGH | tuistate- |
| 5 | 提示设计 | MEDIUM-HIGH | prompt- |
| 6 | 用户体验与反馈 | MEDIUM | ux- |
| 7 | 配置与 CLI | MEDIUM | tuicfg- |
| 8 | 健壮性与兼容性 | LOW-MEDIUM | robust- |
快速参考
1. 渲染与输出（CRITICAL）
- render-single-write：将终端输出批量合并为单次写入
- render-overwrite-dont-clear：覆盖内容而非清除后重绘
- render-synchronized-output：动画使用同步输出协议
- render-60fps-baseline：以 60fps 为目标实现流畅动画
- render-partial-updates：仅更新发生变化的区域
- render-escape-sequence-batching：将 ANSI 转义码生成推迟到最终输出
2. 输入与键盘（CRITICAL）
- input-useinput-hook：使用 useInput Hook 处理键盘输入
- input-immediate-feedback：为输入提供即时视觉反馈
- input-modifier-keys：正确处理修饰键
- input-isactive-focus：使用 isActive 选项管理焦点
- input-escape-routes：始终提供退出路径
3. 组件模式（HIGH）
- tuicomp-box-flexbox：使用 Box 组件配合 Flexbox 进行布局
- tuicomp-text-styling：所有可见内容使用 Text 组件
- tuicomp-measure-element：使用 measureElement 实现动态尺寸
- tuicomp-static-for-logs：日志输出使用 Static 组件
- tuicomp-percentage-widths：使用百分比宽度实现响应式布局
- tuicomp-border-styles：使用边框样式构建视觉结构
4. 状态与生命周期（HIGH）
- tuistate-useapp-exit：使用 useApp Hook 管理应用生命周期
- tuistate-cleanup-effects：卸载时始终清理副作用
- tuistate-functional-updates：使用函数式状态更新避免过期闭包
- tuistate-usecallback-stable：使用 useCallback 稳定回调
- tuistate-usememo-expensive：使用 useMemo 缓存昂贵计算
5. 提示设计（MEDIUM-HIGH）
- prompt-group-flow：使用 Clack group() 实现多步骤提示
- prompt-validation：尽早验证输入并提供描述性消息
- prompt-cancellation：使用 isCancel 优雅处理取消
- prompt-spinner-tasks：长时间操作使用 Spinner 和 Tasks
- prompt-custom-render：使用 @clack/core 构建自定义提示
6. 用户体验与反馈（MEDIUM）
- ux-progress-indicators：超过 1 秒的操作显示进度
- ux-color-semantics：语义化且一致地使用颜色
- ux-error-messages：编写可操作的错误消息
- ux-next-steps：完成后显示后续步骤
- ux-intro-outro：使用 Intro 和 Outro 框定会话
7. 配置与 CLI（MEDIUM）
- tuicfg-sensible-defaults：为所有选项提供合理默认值
- tuicfg-env-vars：支持标准环境变量
- tuicfg-flags-over-args：优先使用标志而非位置参数
- tuicfg-help-system：实现全面的帮助系统
- tuicfg-json-output：支持机器可读的输出格式
8. 健壮性与兼容性（LOW-MEDIUM）
- robust-tty-detection：检测 TTY 并相应调整行为
- robust-signal-handling：优雅处理进程信号
- robust-exit-codes：使用有意义的退出码
- robust-terminal-restore：退出时始终恢复终端状态
- robust-graceful-degradation：在受限终端中优雅降级
使用方式
阅读各个参考文件以获取详细说明和代码示例：
- Section definitions：类别结构与影响级别
- Rule template：添加新规则的模板
- render-single-write：示例规则文件
- input-useinput-hook：示例规则文件
完整编译文档
如需包含所有规则展开的完整指南，请参阅 AGENTS.md。