Charm 出品 · 终端原生 · 10MB 轻量

Crush 中文教程 - 终端 AI 编程助手轻松入门

最全面的 Crush 中文学习教程,从零开始掌握 Charmbracelet 出品的终端 AI 编程助手。Go 语言编写,仅 10MB 大小,支持多种 LLM 模型,LSP 深度集成,简单易学,轻松入门。

📚 中文教程
🚀 快速上手
💡 简单易学
🎯 实战案例

📊 AI 编程助手对比

Crush 与其他主流 AI 编程助手的核心对比,帮你选择最适合的工具:

特性 Crush Claude Code OpenCode Codex CodeBuddy
运行环境 终端 TUI 终端 TUI 终端 TUI 终端 TUI 终端 + GUI
二进制大小 ~10MB ~50MB ~20MB ~30MB ~100MB
支持模型 多种 LLM 仅 Claude 多种 LLM 仅 GPT 多种 LLM
LSP 支持 深度集成
MCP 支持
Skills 支持
TUI 界面 Charm 生态
本地模型
开源
中文教程

💡 Crush 的核心优势

  • 极致轻量:仅 10MB,Go 语言编写,启动速度快
  • Charm 生态:使用 Bubble Tea、Lipgloss 等 Charm 库构建的精美 TUI
  • 模型灵活:支持 OpenAI、Anthropic、Google、本地模型等多种 LLM
  • LSP 深度集成:实时代码分析,精准上下文理解
  • 完全开源:Apache 2.0 协议,社区驱动发展

⬇️ 安装与环境配置

系统要求

  • 操作系统:macOS、Linux、Windows
  • 架构:x86_64、ARM64
  • 依赖:无需额外依赖,单文件可执行

安装方式

bash 一键安装(推荐)
curl -fsSL https://charm.sh/install | bash
bash Homebrew(macOS)
brew install crush
bash Go Install
go install github.com/charmbracelet/crush@latest
bash 手动下载
# 从 GitHub Releases 下载对应平台的二进制文件
# https://github.com/charmbracelet/crush/releases

# 解压并移动到 PATH
sudo mv crush /usr/local/bin/
sudo chmod +x /usr/local/bin/crush
💡 验证安装 运行 crush --version 查看版本信息,确认安装成功。

🚀 5分钟快速上手

第一步:启动 Crush

bash 启动终端 AI 助手
$ crush

💘 Welcome to Crush! How can I help you today?

第二步:配置 API Key

首次使用需要配置 LLM 提供商的 API Key:

bash 设置环境变量
# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# Google Gemini
export GOOGLE_API_KEY="..."

# 或在配置文件中设置
# ~/.config/crush/config.yaml

第三步:开始对话

对话示例
You: 帮我给这个 Go 项目添加单元测试

✓ Analyzing project with LSP...
✓ Found 12 Go files, 0 test files
✓ Generated test files for main modules

Created files:
  - main_test.go
  - handler_test.go
  - utils_test.go

Run go test? (y/n)
📖 提示 Crush 会自动检测项目类型、读取文件、理解代码结构,提供精准的代码建议。

💬 基础命令

常用命令列表

命令 说明 示例
crush 启动交互式 TUI crush
crush ask 单次问答模式 crush ask "如何优化这段代码?"
crush edit 编辑文件模式 crush edit main.go
crush config 查看/修改配置 crush config set model gpt-4
crush history 查看对话历史 crush history list
Ctrl+C 退出程序 -

对话技巧

🎯 明确上下文

使用 @文件名 引用特定文件,@目录名 引用整个目录。

对话示例
You: @main.go @utils/ 重构这个项目的错误处理逻辑

📝 使用斜杠命令

内置斜杠命令提供快速操作:

  • /help - 显示帮助信息
  • /clear - 清空对话
  • /save - 保存对话到文件
  • /model - 切换模型
  • /tokens - 查看 token 使用情况

🤖 模型配置

支持的 LLM 提供商

🟢 OpenAI

GPT-4、GPT-4 Turbo、GPT-3.5 等模型

🟣 Anthropic

Claude 3.5 Sonnet、Claude 3 Opus 等

🔵 Google

Gemini Pro、Gemini Ultra 等

🟡 本地模型

Ollama、LM Studio、LocalAI 等

🔴 Azure OpenAI

Azure 部署的 OpenAI 模型

🟠 自定义端点

支持 OpenAI 兼容的 API 端点

配置示例

yaml ~/.config/crush/config.yaml
# 默认模型
model: gpt-4

# OpenAI 配置
openai:
  api_key: "${OPENAI_API_KEY}"
  base_url: "https://api.openai.com/v1"
  models:
    - gpt-4
    - gpt-4-turbo
    - gpt-3.5-turbo

# Anthropic 配置
anthropic:
  api_key: "${ANTHROPIC_API_KEY}"
  models:
    - claude-3-5-sonnet-20241022
    - claude-3-opus-20240229

# 本地模型(Ollama)
ollama:
  base_url: "http://localhost:11434"
  models:
    - llama3.2
    - codellama
    - deepseek-coder
💡 提示 使用环境变量 ${VAR_NAME} 可以避免在配置文件中硬编码敏感信息。

🔄 工作模式

三种核心模式

1️⃣ Plan 模式(规划优先)

先理解需求,制定计划,再执行。适合复杂任务。

  • 分析项目结构和依赖关系
  • 制定详细的实施计划
  • 分步骤执行,每步确认
  • 降低风险,提高可控性

2️⃣ Build 模式(快速构建)

直接行动,快速迭代。适合简单任务和快速原型。

  • 直接修改文件,快速执行
  • 适合小型项目或简单修改
  • 实时反馈,快速验证
  • 支持撤销和回滚

3️⃣ Ask 模式(仅问答)

只提供建议,不修改文件。适合咨询和学习。

  • 代码审查和优化建议
  • 技术方案讨论
  • 问题诊断和调试帮助
  • 学习新技术和最佳实践

模式切换

对话示例
# 在对话中切换模式
/mode plan     # 切换到 Plan 模式
/mode build    # 切换到 Build 模式
/mode ask      # 切换到 Ask 模式

# 查看当前模式
/mode

⚙️ 配置详解

配置文件位置

  • macOS/Linux: ~/.config/crush/config.yaml
  • Windows: %APPDATA%\crush\config.yaml
  • 项目级配置: .crush/config.yaml

核心配置项

yaml 完整配置示例
# 默认模型
model: claude-3-5-sonnet-20241022

# 最大上下文长度
max_context: 128000

# 温度参数(0-2,越高越随机)
temperature: 0.7

# LSP 配置
lsp:
  enabled: true
  timeout: 5s

# 文件忽略规则
ignore:
  - "node_modules/**"
  - "*.log"
  - ".git/**"
  - "dist/**"
  - "build/**"

# 快捷键绑定
keybindings:
  submit: "Enter"
  newline: "Alt+Enter"
  cancel: "Ctrl+C"

# 主题配置
theme: charm-purple

# 自动保存
autosave: true

🔧 内置工具

文件操作工具

📄 读取文件

读取单个或多个文件内容

✏️ 编辑文件

创建、修改、删除文件

🔍 搜索代码

在项目中搜索文本和正则

📁 列出目录

查看目录结构和文件列表

代码分析工具

🎯 LSP 集成

实时语法分析、跳转定义、查找引用

🌳 AST 解析

深度理解代码结构

📊 依赖分析

分析项目依赖关系

🐛 调试支持

集成调试器,帮助排查问题

Shell 工具

💻 执行命令

安全地执行 Shell 命令,支持:

  • 命令预览和确认
  • 输出实时显示
  • 错误处理和重试
  • 超时控制

🔌 Top 10 MCP 服务器

MCP (Model Context Protocol) 让 Crush 能够连接外部工具和数据源。

排名 MCP 服务器 功能说明 热门度
1 GitHub 仓库管理、Issue、PR 操作 ⭐⭐⭐⭐⭐
2 PostgreSQL 数据库查询和管理 ⭐⭐⭐⭐⭐
3 Filesystem 增强的文件系统操作 ⭐⭐⭐⭐⭐
4 Playwright 浏览器自动化和测试 ⭐⭐⭐⭐
5 Context7 持久化记忆和上下文 ⭐⭐⭐⭐
6 SQLite 轻量级数据库操作 ⭐⭐⭐⭐
7 Puppeteer 网页抓取和自动化 ⭐⭐⭐
8 Docker 容器管理和编排 ⭐⭐⭐
9 Brave Search 网页搜索能力 ⭐⭐⭐
10 Memory 知识图谱和记忆存储 ⭐⭐⭐
💡 安装 MCP 服务器 在配置文件中添加 MCP 服务器配置,Crush 会自动加载和使用。

🎯 Top 10 热门 Skills

Skills 是 AI 智能体的能力扩展包,提供专业化功能。

排名 Skill 名称 功能说明 适用场景
1 Deep Research 深度研究和信息合成 企业级调研
2 Web Search 实时网页搜索和信息获取 信息查询
3 XLSX Handler Excel 文件读写和处理 数据分析
4 PDF Master PDF 文件处理和转换 文档管理
5 AI Image Gen AI 图像生成和处理 创意设计
6 DOCX Creator Word 文档生成和编辑 文档编写
7 Video Gen 视频生成和编辑 内容创作
8 Speech/TTS 语音识别和合成 语音交互
9 Map Services 地图和位置服务 地理应用
10 Stock Research 股票研究和分析 投资决策
📖 注意 Crush 目前不支持 Skills,但 MCP 服务器提供了类似的功能扩展能力。

🏗️ 技术架构

核心组件

🎯 TUI 界面层

基于 Charm 生态的 Bubble Tea 框架构建:

  • Bubble Tea: Elm 架构的 TUI 框架
  • Lipgloss: 样式和布局引擎
  • Bubbles: 可复用的 UI 组件
  • Glamour: Markdown 渲染引擎

🧠 AI 引擎层

统一的多模型接口:

  • Provider 抽象: 统一的 LLM 接口
  • 上下文管理: 智能的上下文压缩和选择
  • 流式响应: 实时显示 AI 输出
  • 工具调用: 结构化的函数调用

⚙️ 工具层

强大的工具生态系统:

  • 文件系统: 读写、搜索、监控
  • LSP 集成: 语法分析、代码补全
  • Shell 执行: 安全的命令执行
  • MCP 协议: 外部工具集成

技术栈

层级 技术 用途
UI 层 Bubble Tea + Lipgloss 精美的终端界面
逻辑层 Go 标准库 高性能核心逻辑
AI 层 官方 SDK 多模型支持
工具层 LSP + MCP 代码分析和工具集成
存储层 SQLite + 文件系统 持久化存储

🛠️ 自定义工具

创建自定义工具

Crush 支持通过 MCP 协议创建自定义工具:

go 自定义工具示例
package main

import (
    "github.com/mark3labs/mcp-go/mcp"
)

func main() {
    // 创建 MCP 服务器
    s := mcp.NewMCPServer(
        "My Custom Tool",
        "1.0.0",
    )
    
    // 添加工具
    s.AddTool(mcp.Tool{
        Name:        "my_tool",
        Description: "My custom tool description",
        InputSchema: mcp.ToolInputSchema{
            Type: "object",
            Properties: map[string]interface{}{
                "input": map[string]interface{}{
                    "type":        "string",
                    "description": "Input parameter",
                },
            },
            Required: []string{"input"},
        },
        Handler: myToolHandler,
    })
    
    // 启动服务器
    s.Serve()
}
💡 提示 参考 MCP 官方文档 了解更多工具开发细节。

🌳 Charm 生态系统

核心库

🫧 Bubble Tea

Elm 架构的 TUI 框架,构建交互式终端应用

💄 Lipgloss

终端样式引擎,支持颜色、边框、布局

🫧 Bubbles

可复用的 TUI 组件库(输入框、列表、进度条等)

✨ Glamour

Markdown 渲染引擎,支持语法高亮

🌊 Harmonica

弹簧动画库,流畅的 UI 动画

📊 Termenv

终端能力检测和颜色支持

Charm 工具

🛠️ 实用工具

  • Gum: Shell 脚本美化工具
  • Glow: 终端 Markdown 阅读器
  • Skipper: HTTP 路由器
  • Huh?: 交互式表单库
  • Wish: SSH 应用框架
  • Crush: AI 编程助手(本教程主角)
📖 Charm 官网 访问 charm.sh 探索更多精彩工具和库。

🔒 隐私与安全

数据安全原则

🛡️ 本地优先

  • 所有代码在本地处理
  • 敏感信息不会上传到云端
  • 配置文件加密存储
  • 支持完全离线使用(本地模型)

🔐 API Key 安全

  • 支持环境变量存储
  • 不在代码中硬编码
  • 配置文件权限控制
  • 支持密钥管理器集成

🎯 最小权限原则

  • 只访问必要的文件和目录
  • 支持黑名单和白名单
  • 危险操作需要确认
  • 提供沙箱模式

最佳实践

⚠️ 安全提示
  • 不要在公共仓库中提交配置文件
  • 定期轮换 API Key
  • 审查 AI 生成的代码
  • 不要让 AI 访问敏感文件

📋 速查表

快捷键

快捷键 功能
Enter 发送消息
Alt+Enter 换行
Ctrl+C 取消/退出
Ctrl+L 清空对话
Ctrl+R 重新生成
Tab 自动补全
? 显示帮助

斜杠命令

命令 功能
/help 显示帮助
/clear 清空对话
/model 切换模型
/mode 切换工作模式
/save 保存对话
/tokens 查看 token 使用
/config 修改配置

❓ 常见问题

Q: Crush 和 Claude Code 有什么区别?

A: Crush 是开源的,支持多种 LLM,体积更小(10MB vs 50MB),使用 Charm 生态构建 TUI。Claude Code 只支持 Claude 模型,但功能更成熟。

Q: 如何使用本地模型?

A: 安装 Ollama 或 LM Studio,在配置文件中添加本地模型端点,然后切换到对应的模型即可。

Q: Crush 支持哪些编程语言?

A: 通过 LSP 集成,支持所有主流编程语言。包括 Go、Python、JavaScript、TypeScript、Rust、Java、C++ 等。

Q: 如何避免 API Key 泄露?

A: 使用环境变量存储 API Key,不要在代码中硬编码,不要将配置文件提交到版本控制系统。

Q: Crush 可以离线使用吗?

A: 可以!使用本地模型(如 Ollama)时,完全支持离线使用,不需要网络连接。

Q: 如何贡献代码?

A: Crush 是开源项目,欢迎贡献!访问 GitHub 仓库 提交 Issue 或 PR。