Crush 项目概览
项目背景与设计目标
Crush 是由 Charm Bracelet 开发的终端 AI 编程助手，旨在将大型语言模型（LLM）的能力无缝集成到开发者的终端工作流中。项目的核心设计哲学是：
“Your tools, your code, and your workflows, wired into your LLM of choice.” （你的工具、代码和工作流，无缝接入你选择的 LLM）
核心设计目标
- 终端原生体验: 基于 TUI（Text User Interface）提供沉浸式终端体验，无需离开终端即可与 AI 协作
- 多模型支持: 不绑定单一 LLM 提供商，支持 Anthropic、OpenAI、Gemini、Bedrock 等主流提供商
- 会话管理: 基于 SQLite 的持久化会话系统，支持多项目、多会话并行工作
- 工具扩展: 内置丰富的代码操作工具 + MCP（Model Context Protocol）扩展机制
- 代码智能: LSP（Language Server Protocol）集成，提供代码补全、定义跳转等智能功能
核心功能与技术特点
1. 多 LLM 提供商支持
| 提供商 | 特点 | 配置方式 |
|---|---|---|
| Anthropic | Claude 系列模型，支持推理和工具调用 | API Key |
| OpenAI | GPT 系列，函数调用能力强 | API Key |
| Gemini | Google 多模态模型 | API Key |
| Bedrock | AWS 托管的 Claude 模型 | AWS Credentials |
| VertexAI | Google Cloud 平台 | GCP 认证 |
| Ollama/LM Studio | 本地模型支持 | OpenAI-compatible API |
技术实现: 通过 charm.land/fantasy 库抽象不同提供商的 API 差异，统一接口调用。
2. 会话管理系统
- 基于 SQLite 的持久化: 会话历史、消息记录、文件追踪全部本地存储
- 自动命名: 首次对话自动生成会话标题（基于 LLM 内容分析）
- 消息队列: 支持消息排队，当 Agent 忙碌时自动缓存后续提示
- 自动摘要: 长会话自动触发上下文压缩，保持上下文窗口高效利用
3. 工具系统（Tools）
内置 15+ 代码操作工具，覆盖开发全流程：
文件操作: view, write, edit, glob, ls
代码搜索: grep, rg, references
命令执行: bash, shell
开发工具: fetch, download, job_output
其他: safe, todos
工具调用流程:
- Agent 根据用户提示决定调用哪些工具
- 工具执行前检查权限（permission.Service）
- 工具执行并返回结果
- 结果自动添加到对话上下文
- Agent 基于结果继续推理或回复用户
4. MCP（Model Context Protocol）扩展
支持三种传输类型的 MCP 服务器：
- stdio: 命令行工具（如文件系统 MCP）
- http: HTTP 端点（如 GitHub Copilot MCP）
- sse: Server-Sent Events 流式接口
MCP 让 Crush 可以动态加载外部工具和能力，无需修改核心代码。
5. LSP 集成
- 自动发现: 基于项目类型自动检测可用的 LSP 服务器
- 按需启动: 用户首次需要时才启动 LSP，节省资源
- 智能提示: LSP 提供符号定义、引用、错误等额外上下文给 LLM
6. TUI 界面
基于 charm.land/bubbletea/v2 构建，特点：
- 响应式设计: 适配不同终端尺寸
- 实时流式输出: LLM 回复逐字显示，低延迟体验
- 富文本渲染: 代码高亮、Markdown 渲染、图片显示
- 对话模式: 类 ChatGPT 的对话界面，支持附件上传
架构图（文字描述）
┌─────────────────────────────────────────────────────────────────┐
│ CLI Layer │
│ (cobra commands) │
│ crush run / crush login / crush sessions │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ App Initialization │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│ │ Config │ │ SQLite DB │ │ LSP Mgr │ │ MCP Mgr │ │
│ │ (crush.json)│ │ (sessions) │ │(lang servers)│ │(extensions)│
│ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Coordinator │
│ (协调多个 SessionAgent 的生命周期) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SessionAgent │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────────────┐ │ │
│ │ │ Large │ │ Small │ │ System Prompt │ │ │
│ │ │ Model │ │ Model │ │ (Go Template) │ │ │
│ │ └─────────────┘ └─────────────┘ └───────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────┐│ │
│ │ │ Message Queue & State ││ │
│ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ││ │
│ │ │ │ Active │ │ Queued │ │ Messages│ │ Session │ ││ │
│ │ │ │Requests │ │ Prompts │ │ (DB) │ │ (DB) │ ││ │
│ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ ││ │
│ │ └─────────────────────────────────────────────────────┘│ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Tool System │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│ │ Built-in │ │ MCP │ │ LSP │ │ Permission│ │
│ │ Tools │ │ Tools │ │ Context │ │ Check │ │
│ │(view,edit,) │ │(external) │ │(code intel) │ │ (yolo/ask) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ LLM Provider Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│
│ │Anthropic │ │ OpenAI │ │ Gemini │ │ Bedrock │ │ ... ││
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘│
│ │
│ Abstracted by: charm.land/fantasy │
└─────────────────────────────────────────────────────────────────┘
技术栈详解
核心依赖
// go.mod 关键依赖
require (
charm.land/fantasy v0.x.x // LLM 提供商抽象层
charm.land/bubbletea/v2 v2.x.x // TUI 框架
charm.land/lipgloss/v2 v2.x.x // 终端样式
charm.land/glamour/v2 v2.x.x // Markdown 渲染
github.com/mattn/go-sqlite3 v1.x.x // SQLite 驱动
github.com/sqlc-dev/sqlc v1.x.x // SQL 代码生成
)关键技术选型
- Go 1.22+: 利用泛型、协程优化、标准库增强
- SQLite + sqlc: 类型安全的 SQL 操作，编译时检查
- Bubble Tea v2: 响应式 TUI，基于 The Elm Architecture
- charm.land/fantasy: 统一多 LLM 提供商的 Go SDK
- Cobra: CLI 框架，支持子命令和 Flag 解析
与同类项目的对比
| 特性 | Crush | Claude Code | GitHub Copilot CLI | Aider |
|---|---|---|---|---|
| 运行环境 | 本地终端 | 本地终端 | 本地终端 | 本地终端 |
| 开源 | ✅ FSL-1.1-MIT | ✅ Apache 2.0 | ❌ 闭源 | ✅ Apache 2.0 |
| 多 LLM 支持 | ✅ 10+ 提供商 | ⚠️ 仅 Anthropic | ⚠️ OpenAI/GitHub | ✅ 多提供商 |
| TUI 界面 | ✅ Bubble Tea | ✅ 自研 | ✅ 自研 | ⚠️ 简单界面 |
| MCP 支持 | ✅ 完整支持 | ⚠️ 部分支持 | ⚠️ 部分支持 | ❌ 不支持 |
| LSP 集成 | ✅ 自动发现 | ✅ 内置 | ✅ 内置 | ⚠️ 基础支持 |
| 会话管理 | ✅ SQLite 持久化 | ✅ 本地存储 | ✅ 云端同步 | ⚠️ 文件级 |
| 工具系统 | ✅ 15+ 内置 + MCP | ✅ 10+ 内置 | ✅ 8+ 内置 | ⚠️ 基础工具 |
| 本地模型 | ✅ Ollama/LMStudio | ❌ 不支持 | ❌ 不支持 | ✅ 支持 |
核心优势
- 最强扩展性: MCP 协议支持让工具生态无限扩展
- 本地优先: 数据全部本地存储，隐私可控
- 提供商无关: 不锁定单一 LLM，根据场景选择模型
- Charm 生态: 基于成熟的 Charm TUI 组件库，界面精致
- 性能优化: Go 语言 + SQLite，启动快、响应快
适用场景
- 日常开发: 代码解释、重构、Bug 修复
- 代码审查: 结合 LSP 理解代码上下文，提供精准建议
- 项目初始化: 生成项目结构、配置文件、文档
- 多文件操作: 跨文件重构、批量修改
- 学习探索: 理解新代码库，生成学习笔记
总结
Crush 代表了新一代终端 AI 编程助手的演进方向：开放、可扩展、本地优先。通过模块化的架构设计，它将 LLM 能力、代码智能和开发者工作流无缝融合，同时保持了对多种模型和工具的开放支持。对于追求效率和控制权的开发者来说，Crush 提供了一个功能强大且高度可定制的 AI 编程伙伴。
相关文档:
- Crush_agent_源码 - Agent 系统核心实现
- Crush_工具系统 - 工具系统详解
- Crush_设计思想 - 架构设计哲学