Agent Skills
返回列表
💻

Bubble Tea 终端 UI 构建指南

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @kunlungrowth/bubbletea-tui-guide 技能到 AI 助手中。

技能介绍

问题：脚本式 CLI 的状态困境

大部分命令行工具本质上是一堆 print 加 input：一旦需要光标移动、异步刷新、列表导航，代码就退化成状态变量和回调嵌套的意大利面。本技能要解决的正是这个问题——把终端应用从"脚本"升级为有状态、可交互的"小程序"，但不必离开 Go 语言生态。

核心思路：Model-Update-View-Command 四要素

技能基于 Bubble Tea 的 Elm 风格架构，把界面拆成四个职责清晰的部分：

  • Model：定义纯数据结构（光标位置、列表数据、加载状态），作为界面的唯一真相源。
  • Update：接收 Msg（按键、定时器、异步结果）后返回新 Model 与可选 Cmd，必须是无副作用的纯函数。
  • View：根据 Model 渲染字符串，样式交给 Lip Gloss 统一管理。
  • Command：把 HTTP 请求、tea.Tick 定时器等异步操作封装成"执行后发消息"的机制，从而守住 Update 的纯粹性。

典型场景包括交互式 CLI、终端仪表盘、键盘导航的列表/表单界面。

常见陷阱与适用边界

几个反复出现的翻车点：

  • 在 Update 里直接做 IO，破坏纯函数假设，状态从此不可追踪；所有副作用都应走 Cmd。
  • Msg 类型随处定义，导致消息流转混乱、调试困难；建议集中定义统一的消息类型。
  • 长列表不做虚拟滚动，重渲染直接掉帧。
  • 把业务逻辑塞进 View，丧失单测能力；关键状态转换必须有测试。

技能附带的检查清单要求：Model 为纯数据、副作用全部走 Cmd、样式由 Lip Gloss 统一管理、状态转换有单测覆盖。需要说明的是，这是一套开发方法论而非代码生成器，复杂交互场景应优先保证可维护性与可测试性，具体 API 以 Bubble Tea 官方文档为准。

使用场景

  • 用 Go 重构内部运维 CLI：原脚本只能按行打印日志，现需方向键上下移动光标、Enter 确认执行，改为带键盘导航的交互式 TUI。
  • 在终端监控面板中接入 HTTP 接口：按 tea.Tick 每秒拉取一次服务指标，异步刷新列表，异常时标红告警并保留光标位置。
  • 把批量部署脚本升级为交互式工具：显示主机列表，左右方向键移动焦点，Enter 键选中并执行部署，减少误操作。
  • 用 Lip Gloss 统一渲染多级命令面板：按模块分区展示快捷键提示，处理键盘导航时根据 Model 状态切换焦点高亮。

适合人员

  • 使用 Go 编写内部工具的后端工程师：希望在命令行里实现光标移动和表单导航，而不是堆一堆全局变量和 if-else。
  • 维护终端运维工具的 SRE：需要在仪表盘中实时展示服务指标，又不想让异步请求逻辑污染界面渲染代码。
  • 构建开发者 CLI 的开源作者：用 Bubble Tea 的 Model 更新循环重构项目状态管理，让交互逻辑可被单元测试覆盖。
  • 为 Go 项目选型 TUI 框架的架构师：想确认 Bubble Tea 在列表导航、按键处理与纯函数模型上的实际约束，再决定是否采用。