Crush 架构深度解析：终端里的 AI 编程搭档

Charmbracelet 出品，一个让 LLM 直接操作你终端的开源工具

项目简介

Crush 是 Charmbracelet 团队推出的终端 AI 助手。它最大的特点是：AI 可以直接访问你的终端、执行命令、编辑文件——就像有一个真实的编程搭档坐在你旁边。

支持 Windows/macOS/Linux，兼容 OpenAI、Anthropic、Google、Bedrock 等主流 LLM 提供商。

核心架构一览

┌─────────────────────────────────────────────────────────────┐
│                      CLI Layer (cmd/)                        │
│              Cobra 命令 → Bubble Tea TUI                     │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                   App 协调层 (app/)                          │
│         持有所有服务实例，管理生命周期和事件订阅               │
└──────┬───────────────────────────────────────────────┬──────┘
       │                                               │
       ▼                                               ▼
┌──────────────────────┐                   ┌──────────────────────┐
│  Agent 协调器        │                   │   LSP Manager        │
│  (agent/)            │                   │   (lsp/)             │
│  - 会话管理           │                   │   - 多语言支持        │
│  - 工具执行           │                   │   - 诊断/引用         │
│  - 模型切换           │                   └──────────────────────┘
└──────────┬───────────┘
           │
           ▼
┌──────────────────────────────────────────────────────────────┐
│                    工具集 (agent/tools/)                      │
│   bash | edit | glob | grep | view | fetch | mcp | lsp       │
└──────────────────────────────────────────────────────────────┘

核心模块详解

1. CLI 层 (internal/cmd/)

入口点使用 Cobra 框架，提供交互式 TUI 和非交互式两种模式：

• 交互模式：基于 Bubble Tea 构建的全功能终端界面
• 非交互模式：crush run "你的问题" 直接输出结果

// main.go 核心逻辑
func main() {
    cmd.Execute()  // 启动 Cobra 命令
}

2. App 协调层 (internal/app/)

这是整个应用的"大脑"，负责：

• 服务组装：创建并持有 Session、Message、Permission、LSP 等服务
• 事件订阅：通过 pubsub 机制将各服务事件转发给 TUI
• 生命周期管理：优雅关闭，确保所有资源正确释放

type App struct {
    Sessions         session.Service
    Messages         message.Service
    AgentCoordinator agent.Coordinator
    LSPManager       *lsp.Manager
    // ...
}

3. Agent 核心 (internal/agent/)

这是最核心的模块，实现了 AI Agent 的完整生命周期：

主要职责：

• 会话管理（创建、恢复、自动摘要）
• 工具调用（解析 LLM 返回的工具调用请求并执行）
• 消息队列（支持多轮对话排队）
• 模型切换（可在会话中切换大/小模型）

• 使用 charm.land/fantasy SDK 统一封装各家 LLM API
• 自动摘要：当上下文超过阈值时，调用小模型生成摘要
• 标题生成：为新会话自动生成标题

4. 工具系统 (internal/agent/tools/)

Crush 提供了丰富的工具让 AI 操作你的环境：

安全设计：

• 危险命令（如 sudo、rm -rf）会被拦截
• 敏感操作需要用户确认（可通过 --yolo 跳过）

5. LSP 集成 (internal/lsp/)

Crush 内置 LSP 客户端管理器，让 AI 获得 IDE 级别的代码理解能力：

• 自动启动项目配置的 LSP 服务器
• 提供代码诊断（错误、警告）
• 支持查找引用、跳转定义

6. 配置系统 (internal/config/)

• 支持 JSON 配置文件 (crush.json)
• 环境变量覆盖
• 多 Provider 配置
• 模型选择（大模型用于复杂任务，小模型用于摘要/标题）

7. 数据持久化 (internal/db/)

使用 SQLite + sqlc（类型安全的 SQL 生成）：

• 会话存储
• 消息历史
• 文件追踪

数据流

用户输入
    │
    ▼
┌─────────────┐
│  TUI (Tea)  │
└──────┬──────┘
       │ 用户消息
       ▼
┌─────────────┐
│    App      │ ──事件订阅──▶ TUI 更新
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Agent     │
└──────┬──────┘
       │
       ▼
┌─────────────┐     工具调用      ┌─────────────┐
│  LLM API    │ ────────────────▶ │   Tools     │
│ (fantasy)   │                   │ (bash/edit) │
└─────────────┘ ◀────执行结果──── └─────────────┘

技术栈总结

设计亮点

1. 事件驱动架构：所有服务通过 pubsub 通信，TUI 订阅事件实现响应式更新
2. 优雅关闭：Shutdown 时按正确顺序清理资源（先取消 Agent，再关闭 DB）
3. 并发安全：使用 csync 包提供并发安全的值容器
4. 可扩展工具：通过 MCP 协议支持第三方工具扩展
5. 上下文管理：自动摘要避免上下文溢出

快速上手

# macOS
brew install charmbracelet/tap/crush

# 或直接运行
go run . 

首次运行会引导配置 API Key，之后即可在终端里与 AI 对话，让它帮你写代码、修 bug、重构项目。

总结

Crush 的架构设计体现了 Charmbracelet 一贯的工程水准：模块化清晰、职责分离、事件驱动。它不是一个简单的 LLM 包装器，而是一个完整的 AI-Agent 开发框架——如果你想在终端里构建自己的 AI 助手，这是一个很好的参考实现。

源码地址：https://github.com/charmbracelet/crush