用途
本技能用于使用 Charmbracelet 生态构建现代 Go CLI，尤其是终端用户界面（TUI）与交互式终端流程。默认以 Bubble Tea 作为有状态 TUI 或交互式终端流程的基础，再按需叠加 Bubbles、Huh、Lip Gloss、Wish、Glamour 与 Log。
起步要点
- 当前 v2 生态使用 charm.land/.../v2 导入路径。
- Bubble Tea 视为应用运行时与状态机。
- Bubbles 视为可复用组件，而非应用外壳。
- Lip Gloss 负责布局与样式。
- Huh 是构建表单与向导最快的方式。
- Glamour 负责 Markdown 转 ANSI 渲染。
- Log 用于向 stderr 或文件输出诊断信息，不写入 TUI 界面。
- Wish 是远程终端应用的 SSH 传输层。
何时选用哪个库
- 需要完整 TUI、应用状态、按键处理、消息循环：参考 references/bubbletea-core.md
- 需要真实应用架构、命令、子模型、异步模式：参考 references/bubbletea-patterns.md
- 需要 list、table、textinput、viewport、help 等可复用组件：参考 references/bubbles.md
- 需要表单、提示、向导、内嵌表单屏幕：参考 references/huh.md
- 需要样式、间距、边框、颜色、布局组合：参考 references/lipgloss.md
- 需要 SSH 原生 TUI 或远程 CLI 应用：参考 references/wish.md
- 需要 Markdown 帮助面板、文档、发布说明、预览：参考 references/glamour.md
- 需要结构化 CLI 日志与诊断：参考 references/log.md
- 需要高层库选择与 API 地图：参考 references/api-surface.md
- 需要具体实现配方：参考 references/common-use-cases.md
- 迁移问题与易踩坑：参考 references/troubleshooting-workarounds.md
- 上游示例短名单：参考 references/examples.md
默认构建策略
- 当用户要求 TUI、终端 UI、仪表盘、选择器、向导或交互式 CLI 时，从 Bubble Tea 开始。
- 使用 Bubbles，而不是手工重建常见组件。
- 当布局或视觉层次重要时加入 Lip Gloss。
- 当交互以表单为主时加入 Huh。
- 当应用渲染 Markdown 内容时加入 Glamour。
- 当需要诊断、后台任务或服务器日志时加入 Log。
- 仅当应用需通过 SSH 运行时才加入 Wish。
核心规则
- 业务逻辑与 Bubble Tea 模型保持分离。
- I/O 放在 tea.Cmd 中执行，不要直接在 Update 或 View 中做。
- 用 tea.WindowSizeMsg 处理尺寸变化，保持布局响应式。
- 当样式依赖明暗模式时，用 tea.RequestBackgroundColor 请求背景色。
- 在 Bubble Tea v2 中，通过 tea.View 字段（如 AltScreen 和 MouseMode）声明终端行为。
- 在独立的 Lip Gloss 或 Glamour 输出中，使用 Lip Gloss writers 打印，以便颜色降采样生效。
- 在 Wish 应用中，注意中间件按声明的逆序执行。
- 在 Bubble Tea 应用中，日志写入 stderr 或文件，不要写入 stdout。
Bubble Tea 最小骨架
package main
import tea "charm.land/bubbletea/v2"
type model struct{}
func (m model) Init() tea.Cmd { return nil }
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) { switch msg := msg.(type) { case tea.KeyPressMsg: switch msg.String() { case "q", "ctrl+c": return m, tea.Quit } } return m, nil }
func (m model) View() tea.View { v := tea.NewView("Hello from Bubble Tea") return v }
后续阅读
- 阅读 references/bubbletea-core.md 了解 Bubble Tea 的模型、命令、消息与程序生命周期。
- 阅读 references/bubbletea-patterns.md 了解应用结构、异步工作、Cobra 集成与多模型组合。
- 在迁移旧 Charmbracelet 代码或将过时示例与 v2 代码混用之前，阅读 references/troubleshooting-workarounds.md。
适用场景
适用于用 Go 构建 TUI、终端仪表盘、选择器、表单向导、交互式 CLI、SSH 远程终端应用，以及需要渲染 Markdown 帮助面板或结构化日志的终端程序。
限制
本资料未提供收费、价格、平台限制、具体版本支持范围及性能相关说明，暂未提供。