go-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Go Skills for LlamaFarm CLI

LlamaFarm CLI的Go语言技能指南

Shared Go best practices for LlamaFarm CLI development. These guidelines ensure idiomatic, maintainable, and secure Go code.

分享LlamaFarm CLI开发中的Go语言最佳实践。这些准则确保代码符合Go语言惯用风格、易于维护且安全。

Tech Stack

技术栈

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

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

Directory Structure

目录结构

cli/
  cmd/           # Command implementations
    config/      # Configuration types and loading
    orchestrator/ # Service management
    utils/       # Shared utilities
    version/     # Version and upgrade handling
  internal/      # Internal packages
    tui/         # TUI components
    buildinfo/   # Build information

cli/
  cmd/           # 命令实现
    config/      # 配置类型与加载逻辑
    orchestrator/ # 服务管理
    utils/       # 共享工具库
    version/     # 版本与升级处理
  internal/      # 内部包
    tui/         # TUI组件
    buildinfo/   # 构建信息

Quick Reference

快速参考

Error Handling

错误处理

Always wrap errors with context:
```
fmt.Errorf("operation failed: %w", err)
```
Use sentinel errors for expected conditions:
```
var ErrNotFound = errors.New("not found")
```
Check errors immediately after function calls

始终为错误添加上下文信息：
```
fmt.Errorf("operation failed: %w", err)
```

为预期场景使用哨兵错误：

var ErrNotFound = errors.New("not found")

函数调用后立即检查错误

Concurrency

并发处理

Use
```
sync.Mutex
```
for shared state protection
Use
```
sync.RWMutex
```
when reads dominate writes
Use channels for goroutine communication
Always use
```
defer
```
for mutex unlocks

使用
```
sync.Mutex
```
保护共享状态
当读取操作远多于写入时，使用
```
sync.RWMutex
```
使用通道进行goroutine间通信
始终使用
```
defer
```
来解锁互斥锁

Testing

测试

Use table-driven tests for comprehensive coverage
Use interfaces for mockability
Test file names:
```
*_test.go
```
in same package

使用表驱动测试实现全面覆盖
利用接口提升可模拟性
测试文件命名规则：同包下的
```
*_test.go
```

Security

安全性

Never log credentials or tokens
Redact sensitive headers in debug logs
Validate all external input
Use
```
context.Context
```
for cancellation

绝不要记录凭据或令牌
在调试日志中脱敏敏感请求头
验证所有外部输入
使用
```
context.Context
```
处理取消操作

Checklist Files

检查清单文件

File	Description
patterns.md	Idiomatic Go patterns
concurrency.md	Goroutines, channels, sync
error-handling.md	Error wrapping, sentinels
testing.md	Table-driven tests, mocks
security.md	Input validation, secure coding

文件	描述
patterns.md	Go语言惯用编程模式
concurrency.md	Goroutine、通道与同步机制
error-handling.md	错误包装与哨兵错误
testing.md	表驱动测试与模拟
security.md	输入验证与安全编码

Go Proverbs to Remember

Go语言箴言

"Don't communicate by sharing memory; share memory by communicating"
"Errors are values"
"A little copying is better than a little dependency"
"Clear is better than clever"
"Design the architecture, name the components, document the details"

"不要通过共享内存来通信；要通过通信来共享内存"
"错误也是值"
"少量的复制优于少量的依赖"
"清晰比聪明更重要"
"先设计架构，再命名组件，最后记录细节"

Common Patterns in This Codebase

代码库中的常见模式

HTTP Client Interface

HTTP客户端接口

type HTTPClient interface {
    Do(req *http.Request) (*http.Response, error)
}

type HTTPClient interface {
    Do(req *http.Request) (*http.Response, error)
}

Process Management with Mutex

带互斥锁的进程管理

type ProcessManager struct {
    mu        sync.RWMutex
    processes map[string]*ProcessInfo
}

type ProcessManager struct {
    mu        sync.RWMutex
    processes map[string]*ProcessInfo
}

Cobra Command Pattern

Cobra命令模式

var myCmd = &cobra.Command{
    Use:   "mycommand",
    Short: "Brief description",
    RunE: func(cmd *cobra.Command, args []string) error {
        // Implementation
        return nil
    },
}

var myCmd = &cobra.Command{
    Use:   "mycommand",
    Short: "Brief description",
    RunE: func(cmd *cobra.Command, args []string) error {
        // Implementation
        return nil
    },
}

Bubbletea Model Pattern

Bubbletea模型模式

type myModel struct {
    // State fields
}

func (m myModel) Init() tea.Cmd { return nil }
func (m myModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { /* ... */ }
func (m myModel) View() string { return "" }

type myModel struct {
    // State fields
}

func (m myModel) Init() tea.Cmd { return nil }
func (m myModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { /* ... */ }
func (m myModel) View() string { return "" }