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/fantasySDK 统一封装各家 LLM API - 自动摘要：当上下文超过阈值时，调用小模型生成摘要
- 标题生成：为新会话自动生成标题
4. 工具系统 (internal/agent/tools/)
Crush 提供了丰富的工具让 AI 操作你的环境：
| 工具 | 功能 |
|---|---|
bash | 执行 Shell 命令（支持后台任务） |
edit / multiedit | 精确编辑文件 |
view | 读取文件内容 |
glob / grep | 文件搜索和内容搜索 |
ls | 目录浏览 |
fetch | HTTP 请求 |
web_fetch / web_search | 网页抓取和搜索 |
lsp_references / lsp_diagnostics | LSP 代码智能 |
mcp | MCP 协议扩展工具 |
- 危险命令（如
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) │
└─────────────┘ ◀────执行结果──── └─────────────┘
---
技术栈总结
| 类别 | 技术 |
|---|---|
| 语言 | Go 1.26 |
| CLI 框架 | Cobra + Bubble Tea v2 |
| 样式 | Lipgloss v2 |
| LLM SDK | charm.land/fantasy |
| 数据库 | SQLite + sqlc |
| LSP | 自研客户端 |
| 扩展协议 | MCP (Model Context Protocol) |
设计亮点
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