cli-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Skills for LlamaFarm

LlamaFarm的CLI技能指南

Framework-specific patterns for the LlamaFarm CLI. These guidelines extend the shared Go skills with Cobra, Bubbletea, and Lipgloss best practices.

LlamaFarm CLI的专属框架使用模式。这些指南在通用Go技能基础上，扩展了Cobra、Bubbletea和Lipgloss的最佳实践内容。

Tech Stack

技术栈

Go 1.24+
Cobra (CLI framework)
Bubbletea (TUI framework)
Lipgloss (terminal styling)
Bubbles (TUI components)

Go 1.24+
Cobra（CLI框架）
Bubbletea（TUI框架）
Lipgloss（终端样式工具）
Bubbles（TUI组件库）

Directory Structure

目录结构

cli/
  cmd/             # Cobra command implementations
    config/        # Configuration types and loading
    orchestrator/  # Service management and process control
    utils/         # Shared utilities (HTTP, output, logging)
    version/       # Version and upgrade handling
  internal/        # Internal packages (not exported)
    tui/           # Reusable TUI components
    buildinfo/     # Build-time information

cli/
  cmd/             # Cobra命令实现
    config/        # 配置类型与加载逻辑
    orchestrator/  # 服务管理与进程控制
    utils/         # 共享工具（HTTP、输出、日志）
    version/       # 版本与升级处理
  internal/        # 内部包（不对外导出）
    tui/           # 可复用TUI组件
    buildinfo/     # 构建时信息

Quick Reference

快速参考

Cobra Commands

Cobra命令

Use
```
RunE
```
over
```
Run
```
for error handling
Register flags in
```
init()
```
functions
Use persistent flags for shared options
Validate arguments with
```
Args
```
field

使用
```
RunE
```
而非
```
Run
```
进行错误处理
在
```
init()
```
函数中注册标志
对共享选项使用持久标志
通过
```
Args
```
字段验证参数

Bubbletea TUI

Implement
```
Init()
```
,
```
Update()
```
,
```
View()
```
interface
Use message types for state changes
Return
```
tea.Cmd
```
for async operations
Keep state immutable in
```
Update()
```

实现
```
Init()
```
、
```
Update()
```
、
```
View()
```
接口
使用消息类型处理状态变更
返回
```
tea.Cmd
```
用于异步操作
在
```
Update()
```
中保持状态不可变

Lipgloss Styling

Lipgloss样式设置

Define styles as package-level constants
Use
```
lipgloss.NewStyle()
```
for styling
Handle terminal width dynamically
Support color themes via style variables

将样式定义为包级常量
使用
```
lipgloss.NewStyle()
```
创建样式
动态适配终端宽度
通过样式变量支持配色主题

Shared Go Skills

通用Go技能

This skill extends the base Go skills. See:

Link	Description
go-skills/SKILL.md	Overview and quick reference
go-skills/patterns.md	Idiomatic Go patterns
go-skills/concurrency.md	Goroutines, channels, sync
go-skills/error-handling.md	Error wrapping, sentinels
go-skills/testing.md	Table-driven tests, mocks
go-skills/security.md	Input validation, secure coding

本技能指南基于基础Go技能扩展而来。请参考：

链接	描述
go-skills/SKILL.md	概述与快速参考
go-skills/patterns.md	Go语言惯用模式
go-skills/concurrency.md	Goroutine、通道、同步机制
go-skills/error-handling.md	错误包装、哨兵错误
go-skills/testing.md	表格驱动测试、Mock
go-skills/security.md	输入验证、安全编码

CLI-Specific Checklists

CLI专属检查清单

File	Description
cobra.md	Cobra command patterns, flags, validation
bubbletea.md	Bubbletea Model/Update/View patterns
performance.md	CLI-specific optimizations

文件	描述
cobra.md	Cobra命令模式、标志、验证
bubbletea.md	Bubbletea Model/Update/View模式
performance.md	CLI专属优化方案

Key Patterns in This Codebase

代码库中的核心模式

Command Registration Pattern

命令注册模式

var myCmd = &cobra.Command{
    Use:   "mycommand [args]",
    Short: "Brief description",
    Long:  `Extended description with examples.`,
    Args:  cobra.MaximumNArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        // Implementation with error returns
        return nil
    },
}

func init() {
    rootCmd.AddCommand(myCmd)
    myCmd.Flags().StringVar(&flagVar, "flag", "default", "Flag description")
}

var myCmd = &cobra.Command{
    Use:   "mycommand [args]",
    Short: "Brief description",
    Long:  `Extended description with examples.`,
    Args:  cobra.MaximumNArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        // Implementation with error returns
        return nil
    },
}

func init() {
    rootCmd.AddCommand(myCmd)
    myCmd.Flags().StringVar(&flagVar, "flag", "default", "Flag description")
}

TUI Model Pattern

TUI模型模式

type myModel struct {
    viewport viewport.Model
    textarea textarea.Model
    width    int
    height   int
    err      error
}

func (m myModel) Init() tea.Cmd {
    return tea.Batch(m.textarea.Focus(), doAsyncWork())
}

func (m myModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmds []tea.Cmd
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        m.width = msg.Width
        m.height = msg.Height
    case tea.KeyMsg:
        switch msg.String() {
        case "ctrl+c":
            return m, tea.Quit
        }
    }
    return m, tea.Batch(cmds...)
}

func (m myModel) View() string {
    return lipgloss.JoinVertical(lipgloss.Left,
        m.viewport.View(),
        m.textarea.View(),
    )
}

type myModel struct {
    viewport viewport.Model
    textarea textarea.Model
    width    int
    height   int
    err      error
}

func (m myModel) Init() tea.Cmd {
    return tea.Batch(m.textarea.Focus(), doAsyncWork())
}

func (m myModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmds []tea.Cmd
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        m.width = msg.Width
        m.height = msg.Height
    case tea.KeyMsg:
        switch msg.String() {
        case "ctrl+c":
            return m, tea.Quit
        }
    }
    return m, tea.Batch(cmds...)
}

func (m myModel) View() string {
    return lipgloss.JoinVertical(lipgloss.Left,
        m.viewport.View(),
        m.textarea.View(),
    )
}

Output API Pattern

输出API模式

// Use the output API for consistent messaging
utils.OutputInfo("Starting service %s...", serviceName)
utils.OutputSuccess("Service started successfully")
utils.OutputError("Failed to start service: %v", err)
utils.OutputProgress("Downloading model...")
utils.OutputWarning("Service already running")

// Use the output API for consistent messaging
utils.OutputInfo("Starting service %s...", serviceName)
utils.OutputSuccess("Service started successfully")
utils.OutputError("Failed to start service: %v", err)
utils.OutputProgress("Downloading model...")
utils.OutputWarning("Service already running")

Service Orchestration Pattern

服务编排模式

// Ensure services are running before operations
factory := GetServiceConfigFactory()
config := factory.ServerOnly(serverURL)
orchestrator.EnsureServicesOrExitWithConfig(config, "server")

// Or with multiple services
config := factory.RAGCommand(serverURL)
orchestrator.EnsureServicesOrExitWithConfig(config, "server", "rag", "universal-runtime")

// Ensure services are running before operations
factory := GetServiceConfigFactory()
config := factory.ServerOnly(serverURL)
orchestrator.EnsureServicesOrExitWithConfig(config, "server")

// Or with multiple services
config := factory.RAGCommand(serverURL)
orchestrator.EnsureServicesOrExitWithConfig(config, "server", "rag", "universal-runtime")

Guidelines

指导原则

User Experience First: CLI should feel responsive and provide clear feedback
Graceful Degradation: Handle missing services, network errors, and timeouts gracefully
Consistent Output: Use the output API for all user-facing messages
Cross-Platform: Test on macOS, Linux, and Windows
Terminal Compatibility: Test with different terminal emulators and sizes

用户体验优先：CLI应响应迅速，并提供清晰的反馈
优雅降级：妥善处理服务缺失、网络错误和超时情况
输出一致性：所有面向用户的消息均使用输出API
跨平台兼容：在macOS、Linux和Windows系统上进行测试
终端兼容性：在不同终端模拟器和尺寸下进行测试