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