1. 项目概述当终端遇见智能体Crush如何重塑你的编程工作流如果你和我一样每天有超过一半的时间是在终端里度过的那么你肯定也经历过这样的场景为了一个复杂的正则表达式绞尽脑汁对着一段陌生的代码库试图理清调用链路或者需要快速写一个脚本却记不清某个命令的精确参数。过去我们可能会打开浏览器搜索或者切换到另一个AI聊天工具再手动把代码片段复制粘贴过去。这个过程不仅打断了心流也让“终端”这个本应高效的核心战场显得有些孤立。直到我遇到了Crush。这个由Charm团队出品的工具彻底改变了游戏规则。它不是一个简单的命令行AI聊天机器人而是一个深度集成在你终端环境中的“智能编程搭档”。想象一下你正在终端里工作突然需要处理一个JSON文件、重构一段代码或者理解一个复杂的系统命令你不再需要离开当前上下文——只需自然地用文字描述你的需求Crush就能理解你的意图调用合适的工具如jq,sed,git甚至结合语言服务器协议LSP来分析你的代码库然后直接在终端里给出可执行的解决方案或代码片段。它的核心魅力在于“Agentic”智能体驱动。这意味着Crush不是一个被动的问答机而是一个能主动采取行动、调用工具、理解上下文并为你完成任务的代理。它支持从OpenAI、Anthropic到本地运行的Ollama等数十种大语言模型并能通过MCP模型上下文协议无限扩展其能力。无论是全栈开发者、系统管理员还是数据工程师只要你与命令行打交道Crush都能无缝融入你的工作流将自然语言指令转化为具体的、可验证的终端操作让编程变得前所未有的直观和高效。2. 核心设计理念与架构解析为何Crush与众不同2.1 从“聊天”到“协作”的范式转变市面上的AI编程助手不少但大多停留在“问答”层面。你提问它给出文本或代码建议然后你需要手动复制、粘贴、验证和执行。Crush的设计哲学是消除这个“手动鸿沟”。它的目标是成为终端里的一个协作者一个能直接操作你工作环境的智能体。这种设计带来了几个根本性优势上下文感知Crush运行在你的项目目录中它能直接读取你的文件结构、.gitignore规则甚至集成LSP来理解代码的语义如函数定义、类型信息。这意味着你问“这个函数是做什么的”时它给出的答案是基于你实际代码的而不是泛泛而谈。工具调用Tool Calling这是智能体的核心能力。Crush内置了数十个工具如ls列出文件、grep搜索、edit编辑文件、bash执行命令等。当你提出需求时Crush会自主规划步骤调用这些工具来探索、修改或验证最后将结果呈现给你。例如你让它“找出所有调用了sendEmail函数的文件”它会内部执行grep -r sendEmail .并整理好结果。会话与状态管理Crush支持基于项目的多会话。每个会话都独立维护对话历史和工作上下文。你可以随时切换模型而上下文不会丢失。这对于长期、复杂的任务如调试一个模块至关重要你可以随时回来继续之前的话题。2.2 模块化与可扩展的架构基石Crush的强大离不开其精心设计的模块化架构这确保了它既能开箱即用又能深度定制。多模型提供商抽象层Crush没有将自己绑定在某个特定的AI服务上。它通过统一的接口支持OpenAI兼容API、Anthropic兼容API等多种后端。无论是使用官方的GPT-4还是通过OpenRouter接入的众多模型或是本地部署的Llama、Qwen你都可以在配置文件中轻松添加。这种设计将“模型能力”与“智能体逻辑”解耦让你能根据成本、速度、能力自由选择最适合当前任务的“大脑”。LSP语言服务器协议集成这是Crush作为“编码专家”的关键。通过配置LSP如Go的gopls、TypeScript的typescript-language-server、Nix的nilCrush能获得与你的IDE同等级别的代码理解能力。当它分析代码时不再是简单的文本匹配而是能理解符号定义、引用关系、类型错误。这使得它的代码建议、重构意见和问题诊断更加精准。MCP模型上下文协议支持如果说LSP让Crush“看懂”代码MCP则让它“连接”万物。MCP是一个新兴的开放标准允许外部服务器向AI模型提供动态的上下文和工具。通过配置MCP服务器Crush可以获取数据库schema、查询API文档、读取Notion页面甚至控制智能家居。你可以在配置中通过stdio、http、sse三种方式连接MCP服务器极大地扩展了Crush的能力边界。例如连接一个GitHub MCP服务器后你可以直接让Crush“查看issue #123的评论”或“为我创建一个新的PR”。Agent Skills智能体技能这是另一个层次的扩展。Skills是包含SKILL.md说明文件的文件夹定义了Crush在特定领域如“代码审查”、“数据库迁移”应遵循的指令和工作流程。你可以将常用的、复杂的任务流程封装成Skill放在全局或项目目录下Crush会自动发现并在相关场景中激活它们。这相当于为你的智能体搭档编写了“专项工作手册”。注意启用工具调用和MCP意味着Crush获得了在你的系统上执行命令和访问外部资源的权限。Crush默认会在每次执行工具前请求你的确认这是一个至关重要的安全设计。切勿轻易使用--yolo标志或盲目在配置中允许所有工具尤其是在处理生产环境或敏感数据时。3. 从零开始安装、配置与核心功能上手3.1 跨平台安装与初始设置Crush的安装体验非常友好几乎覆盖了所有主流平台。我个人推荐使用包管理器便于后续更新。macOS (Homebrew):brew install charmbracelet/tap/crush这是最简洁的方式Homebrew会自动处理依赖和路径。Linux (Debian/Ubuntu):首先添加Charm的APT仓库以获取自动更新sudo mkdir -p /etc/apt/keyrings curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg echo deb [signed-by/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * * | sudo tee /etc/apt/sources.list.d/charm.list sudo apt update sudo apt install crushWindows:推荐使用Winget这是微软官方的包管理器winget install charmbracelet.crush安装后在PowerShell或Windows Terminal中直接输入crush即可启动。通用方法Go语言环境如果你有Go环境这是最直接的方式能确保获得最新版本go install github.com/charmbracelet/crushlatest安装后确保$GOPATH/bin默认为~/go/bin在你的系统PATH中。首次运行与密钥配置安装完成后在终端输入crush。首次运行时Crush会引导你进行配置。最关键的一步是设置API密钥。你有几种选择交互式引导Crush会列出检测到的可用提供商如OpenAI、Anthropic你可以选择其中一个并粘贴API密钥。环境变量更推荐的方式是预先设置环境变量。例如使用OpenAIexport OPENAI_API_KEYsk-your-key-here然后运行crush它会自动识别并使用该密钥。你可以在shell配置文件如~/.bashrc或~/.zshrc中永久设置。配置文件对于多模型或复杂配置直接编辑配置文件~/.config/crush/crush.json后文详述。3.2 核心交互模式与日常使用场景启动Crush后你会进入一个交互式会话。界面通常分为上下两部分上方是对话区域下方是输入框。它的使用非常直观直接提问像和同事交流一样用自然语言描述你的需求。场景1代码理解- “解释一下src/utils/auth.js文件中validateToken函数的作用。”场景2文件操作- “把config.yaml里所有debug: true的行找出来并告诉我分别在哪些文件里。”场景3系统命令- “帮我写一个命令找出当前目录下所有超过100MB的.log文件并按大小排序。”上下文操作Crush能记住当前会话的对话历史。你可以进行追问比如“用sed命令把刚才找到的那些debug: true都改成debug: false。”工具调用确认当Crush需要执行一个可能修改文件或运行命令的工具时如edit、bash它会暂停并请求你的许可。你会看到类似[?] Allow tool call ‘edit’? (Y/n)的提示。输入Y确认n拒绝。这是保证你控制权的关键步骤。切换模型在会话中你可以随时输入/model命令来查看可用模型列表并用/model provider-name/model-id来切换。例如从一个较慢但强大的模型切换到另一个更快的模型来处理简单任务。一个典型的工作流示例假设你接手了一个新项目需要快速熟悉。在项目根目录打开终端输入crush。“这个项目是做什么的主要技术栈是什么” Crush会读取package.json、go.mod、Cargo.toml等文件并结合目录结构给你一个概述。“帮我运行一下测试看看有没有失败。” Crush可能会识别出项目的测试运行器如npm test、go test ./...、pytest执行它并总结测试结果。“我想在/api路径下添加一个新的用户查询接口。” Crush可以结合现有的代码模式为你生成符合项目风格的控制器、路由和模型代码片段甚至直接创建文件。3.3 项目初始化与上下文构建要让Crush在一个项目中发挥最大效力初始化是关键一步。在项目根目录下运行crush --init或者直接在Crush会话中输入“初始化这个项目”。这个命令会触发Crush深度分析你的代码库。它会扫描项目结构识别主要语言和框架。读取配置文件如.gitignore,package.json,Makefile。尝试理解项目的构建、测试和运行命令。将所有这些信息整合生成一个名为AGENTS.md默认的上下文文件。这个AGENTS.md文件就是Crush在这个项目中的“工作手册”。它包含了项目特有的指令例如# Project Context - **Language:** TypeScript with Node.js - **Framework:** Express.js - **Test Runner:** Jest - **Linting:** ESLint with Airbnb config - **Build Command:** npm run build - **Run Command:** npm start - **Key Conventions:** Use async/await, error handling middleware in src/middlewares/.未来无论谁包括你自己在这个目录下启动Crush它都会先读取这个文件从而快速进入角色给出的建议会更贴合项目规范。你可以通过配置options.initialize_as来改变这个文件名或路径例如设为docs/Onboarding.md。4. 深度配置指南打造你的专属智能体Crush的默认配置已经足够强大但它的真正潜力在于深度定制。配置文件遵循优先级项目目录下的.crush.json或crush.json优先级最高其次是用户全局配置~/.config/crush/crush.json。4.1 配置核心模型、LSP与MCP一个完整的配置文件骨架如下我们逐一拆解关键部分{ $schema: https://charm.land/crush.json, providers: { /* 模型提供商配置 */ }, lsp: { /* 语言服务器配置 */ }, mcp: { /* 模型上下文协议服务器配置 */ }, options: { /* 各种行为选项 */ }, permissions: { /* 工具权限控制 */ } }1. 自定义模型提供商 (Providers):这是配置的重头戏。除了使用环境变量你可以在配置中硬编码或引用环境变量来定义多个提供商。添加一个OpenAI兼容的本地模型如Ollama:{ providers: { ollama-local: { id: ollama, name: 本地 Ollama, type: openai-compat, base_url: http://localhost:11434/v1, api_key: ollama, // Ollama通常不需要真密钥但字段必填 models: [ { id: qwen2.5:7b, name: Qwen2.5 7B, context_window: 32768, default_max_tokens: 4096 } ] } } }关键点type字段非常重要。对于真正的OpenAI服务用openai对于其他兼容OpenAI API的第三方服务如Ollama, LM Studio, 本地部署的vLLM必须使用openai-compat否则可能无法正常工作。配置一个自定义的Anthropic兼容端点:{ providers: { my-claude-proxy: { type: anthropic, base_url: https://your-proxy.com/v1, api_key: $MY_CUSTOM_API_KEY, // 使用环境变量更安全 extra_headers: { Custom-Header: value }, models: [ { id: claude-3-5-sonnet-20241022, name: 我的Claude代理, context_window: 200000, default_max_tokens: 8192 } ] } } }2. 集成语言服务器 (LSP):LSP能让Crush“理解”代码。你需要确保对应的LSP二进制文件已在系统PATH中。{ lsp: { python: { command: pylsp, enabled: true }, rust: { command: rust-analyzer, enabled: true }, bash: { command: bash-language-server, args: [start], enabled: true } } }配置后当Crush处理相应语言的文件时会自动启动LSP服务器从而获得代码补全、定义跳转、类型检查等高级功能支持。3. 连接外部数据源 (MCP):MCP是扩展Crush视野的利器。以下是一个连接本地文件系统MCP服务器和HTTP API MCP服务器的例子。{ mcp: { local-files: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/your/project], timeout: 30 }, web-search: { type: http, url: https://your-mcp-search-server.com/mcp, headers: { Authorization: Bearer $(echo $SEARCH_API_KEY) } } } }配置成功后你可以向Crush提问“在我的项目/path/to/your/project里上周修改了哪些文件” 它会通过MCP服务器获取信息并回答。4.2 权限、忽略与行为微调权限控制 (Permissions):安全第一。你可以精细控制哪些工具可以不经确认直接运行。{ permissions: { allowed_tools: [ls, cat, grep, find] // 仅允许这些只读工具自动运行 } }对于edit编辑文件、bash执行任意命令这类高风险工具强烈建议保持默认的确认提示。文件忽略 (.crushignore):和.gitignore类似你可以在项目根目录创建.crushignore文件列出不希望Crush读取或纳入上下文的文件和目录例如node_modules/,*.log,config/secrets.yml。这能提升响应速度并避免泄露敏感信息。界面与通知选项 (Options):{ options: { tui: { compact_mode: true // 使用紧凑模式显示更多信息 }, disable_notifications: false, // 保持桌面通知当终端失焦时提醒 debug: false // 除非排查问题否则关闭调试日志以免输出过多 } }5. 高级技巧与实战问题排查5.1 技能Skills的创建与使用Skills是提升Crush专业度的终极武器。假设你经常需要做数据库迁移可以创建一个database-migration技能。创建技能目录结构mkdir -p ~/.config/crush/skills/database-migration cd ~/.config/crush/skills/database-migration编写技能说明文件SKILL.md:# Database Migration Assistant You are an expert in database schema migrations. When activated, you will help the user create, review, and apply database migrations. ## Context - The project uses Prisma ORM. - The database is PostgreSQL. - Migration files are located in prisma/migrations/. ## Instructions 1. Always suggest using npx prisma migrate dev to create a new migration after schema changes. 2. Before applying migrations to production, remind the user to review the generated SQL in the migration file. 3. For complex migrations, recommend breaking them down into multiple steps and using prisma migrate diff to generate safe SQL. 4. Never run destructive operations (like DROP TABLE) without explicit confirmation from the user. ## Examples User: I added a new field emailVerified to the User model. Assistant: I see youve updated the Prisma schema. Lets create a migration for that. Ill run npx prisma migrate dev --name add_email_verified to generate and apply the migration. Would you like to proceed?这个文件用自然语言定义了Crush在“数据库迁移”这个任务中应该扮演的角色、拥有的上下文知识、必须遵循的指令以及示例对话。使用技能下次当你在相关项目中提到“数据库”或“迁移”时Crush可能会自动激活这个技能或者你可以手动提示它“请使用数据库迁移技能来帮我处理这个问题。”5.2 常见问题与解决方案速查表在实际使用中你可能会遇到以下问题。这里是我总结的排查清单问题现象可能原因解决方案启动Crush后无反应或立即退出1. API密钥未设置或无效。2. 网络问题无法连接到配置的模型端点。3. 配置文件语法错误。1. 检查环境变量echo $OPENAI_API_KEY或配置文件中的api_key。2. 运行crush --debug查看详细错误日志通常会在.crush/logs/crush.log中。3. 使用JSON验证工具检查crush.json格式。Crush无法理解我的项目代码1. 未安装或未配置对应语言的LSP。2. LSP服务器启动失败。3. 项目未初始化缺少上下文。1. 确保安装了对应LSP如gopls,pylsp并位于PATH中。2. 在配置中启用debug_lsp: true查看LSP通信日志。3. 在项目根目录运行crush --init生成AGENTS.md。工具调用失败如bash命令不执行1. 该工具在disabled_tools列表中被禁用。2. 权限不足被用户拒绝。3. 工具本身执行出错命令不存在等。1. 检查配置文件的options.disabled_tools。2. 确认在提示时按了Y。可临时使用--yolo标志需极其谨慎。3. 查看Crush日志确认它尝试运行的具体命令是什么。切换模型后上下文丢失不同模型提供商的API对上下文格式的处理可能有细微差异。这是当前多模型切换的一个已知挑战。对于需要长期上下文的任务建议在一个会话中固定使用一个模型。重要的上下文可以手动总结后输入给新模型。在Linux上复制/粘贴不工作缺少必要的剪贴板工具。根据你的桌面环境安装-Wayland:sudo apt install wl-clipboard(包含wl-copy和wl-paste)-X11:sudo apt install xclip或sudo apt install xsel桌面通知不显示1. 终端不支持焦点状态报告。2. 在配置中禁用了通知。3. 系统通知设置被关闭。1. 尝试使用支持此功能的终端如iTerm2 (macOS), WezTerm, 或Windows Terminal。2. 检查配置中options.disable_notifications是否为false。3. 检查操作系统级别的通知权限。5.3 日志分析与调试技巧当遇到复杂问题时日志是你的第一手资料。Crush的日志默认位于项目目录下的.crush/logs/crush.log。查看实时日志在另一个终端标签页运行crush logs --follow这就像打开了调试控制台所有内部过程、API请求、工具调用都会滚动显示。定位错误如果Crush崩溃或无响应查看日志末尾的ERROR级别信息。常见的错误包括API请求失败检查网络和密钥、LSP初始化失败检查LSP安装、或权限错误。启用深度调试在配置文件或启动命令中加入--debug标志会输出更详细的网络请求和内部状态信息对排查MCP连接或复杂工具调用问题特别有用。5.4 性能优化与成本控制心得模型选择策略将“重型”和“轻型”模型搭配使用。我通常将Claude 3.5 Sonnet或GPT-4配置为默认模型用于复杂的代码生成和架构设计。同时配置一个快速的本地模型如通过Ollama运行的Qwen2.5-Coder或低成本API模型如DeepSeek用于简单的文件查找、命令生成等任务并在需要时用/model快速切换。这能有效平衡效果与成本/速度。利用上下文文件务必为每个重要项目运行crush --init。一个信息丰富的AGENTS.md能极大减少Crush在每次会话中反复分析基础信息所消耗的Token提升响应速度和质量。精细化配置.crushignore将node_modules,build,dist,.git,*.log,*.db等大型或无关目录加入忽略列表。这能显著减少Crush在构建项目上下文时的扫描负担并避免将无关文件内容意外送入模型。管理会话长度对于超长对话模型的上下文窗口可能不够导致性能下降或遗忘早期内容。对于不同的子任务可以开启新的Crush会话CtrlC退出后重新进入或者主动使用“/clear”命令如果支持来清空历史保持会话焦点。经过数月的深度使用Crush已经从我的一个“新奇玩具”变成了终端里不可或缺的“副驾驶”。它最让我欣赏的不是它能生成多么炫酷的代码而是它那种无感融入工作流的能力——我不需要改变习惯只需要用最自然的方式表达意图剩下的脏活累活它都能默默地、可靠地帮我处理好。从自动化繁琐的文本处理到快速理解陌生代码库再到安全地执行一系列系统命令Crush极大地扩展了终端这个古老界面的能力边界。如果你也生活在命令行里我强烈建议你花点时间配置它体验一下这种“言出法随”的编程新范式。
Crush：终端智能体如何重塑开发者的命令行工作流
1. 项目概述当终端遇见智能体Crush如何重塑你的编程工作流如果你和我一样每天有超过一半的时间是在终端里度过的那么你肯定也经历过这样的场景为了一个复杂的正则表达式绞尽脑汁对着一段陌生的代码库试图理清调用链路或者需要快速写一个脚本却记不清某个命令的精确参数。过去我们可能会打开浏览器搜索或者切换到另一个AI聊天工具再手动把代码片段复制粘贴过去。这个过程不仅打断了心流也让“终端”这个本应高效的核心战场显得有些孤立。直到我遇到了Crush。这个由Charm团队出品的工具彻底改变了游戏规则。它不是一个简单的命令行AI聊天机器人而是一个深度集成在你终端环境中的“智能编程搭档”。想象一下你正在终端里工作突然需要处理一个JSON文件、重构一段代码或者理解一个复杂的系统命令你不再需要离开当前上下文——只需自然地用文字描述你的需求Crush就能理解你的意图调用合适的工具如jq,sed,git甚至结合语言服务器协议LSP来分析你的代码库然后直接在终端里给出可执行的解决方案或代码片段。它的核心魅力在于“Agentic”智能体驱动。这意味着Crush不是一个被动的问答机而是一个能主动采取行动、调用工具、理解上下文并为你完成任务的代理。它支持从OpenAI、Anthropic到本地运行的Ollama等数十种大语言模型并能通过MCP模型上下文协议无限扩展其能力。无论是全栈开发者、系统管理员还是数据工程师只要你与命令行打交道Crush都能无缝融入你的工作流将自然语言指令转化为具体的、可验证的终端操作让编程变得前所未有的直观和高效。2. 核心设计理念与架构解析为何Crush与众不同2.1 从“聊天”到“协作”的范式转变市面上的AI编程助手不少但大多停留在“问答”层面。你提问它给出文本或代码建议然后你需要手动复制、粘贴、验证和执行。Crush的设计哲学是消除这个“手动鸿沟”。它的目标是成为终端里的一个协作者一个能直接操作你工作环境的智能体。这种设计带来了几个根本性优势上下文感知Crush运行在你的项目目录中它能直接读取你的文件结构、.gitignore规则甚至集成LSP来理解代码的语义如函数定义、类型信息。这意味着你问“这个函数是做什么的”时它给出的答案是基于你实际代码的而不是泛泛而谈。工具调用Tool Calling这是智能体的核心能力。Crush内置了数十个工具如ls列出文件、grep搜索、edit编辑文件、bash执行命令等。当你提出需求时Crush会自主规划步骤调用这些工具来探索、修改或验证最后将结果呈现给你。例如你让它“找出所有调用了sendEmail函数的文件”它会内部执行grep -r sendEmail .并整理好结果。会话与状态管理Crush支持基于项目的多会话。每个会话都独立维护对话历史和工作上下文。你可以随时切换模型而上下文不会丢失。这对于长期、复杂的任务如调试一个模块至关重要你可以随时回来继续之前的话题。2.2 模块化与可扩展的架构基石Crush的强大离不开其精心设计的模块化架构这确保了它既能开箱即用又能深度定制。多模型提供商抽象层Crush没有将自己绑定在某个特定的AI服务上。它通过统一的接口支持OpenAI兼容API、Anthropic兼容API等多种后端。无论是使用官方的GPT-4还是通过OpenRouter接入的众多模型或是本地部署的Llama、Qwen你都可以在配置文件中轻松添加。这种设计将“模型能力”与“智能体逻辑”解耦让你能根据成本、速度、能力自由选择最适合当前任务的“大脑”。LSP语言服务器协议集成这是Crush作为“编码专家”的关键。通过配置LSP如Go的gopls、TypeScript的typescript-language-server、Nix的nilCrush能获得与你的IDE同等级别的代码理解能力。当它分析代码时不再是简单的文本匹配而是能理解符号定义、引用关系、类型错误。这使得它的代码建议、重构意见和问题诊断更加精准。MCP模型上下文协议支持如果说LSP让Crush“看懂”代码MCP则让它“连接”万物。MCP是一个新兴的开放标准允许外部服务器向AI模型提供动态的上下文和工具。通过配置MCP服务器Crush可以获取数据库schema、查询API文档、读取Notion页面甚至控制智能家居。你可以在配置中通过stdio、http、sse三种方式连接MCP服务器极大地扩展了Crush的能力边界。例如连接一个GitHub MCP服务器后你可以直接让Crush“查看issue #123的评论”或“为我创建一个新的PR”。Agent Skills智能体技能这是另一个层次的扩展。Skills是包含SKILL.md说明文件的文件夹定义了Crush在特定领域如“代码审查”、“数据库迁移”应遵循的指令和工作流程。你可以将常用的、复杂的任务流程封装成Skill放在全局或项目目录下Crush会自动发现并在相关场景中激活它们。这相当于为你的智能体搭档编写了“专项工作手册”。注意启用工具调用和MCP意味着Crush获得了在你的系统上执行命令和访问外部资源的权限。Crush默认会在每次执行工具前请求你的确认这是一个至关重要的安全设计。切勿轻易使用--yolo标志或盲目在配置中允许所有工具尤其是在处理生产环境或敏感数据时。3. 从零开始安装、配置与核心功能上手3.1 跨平台安装与初始设置Crush的安装体验非常友好几乎覆盖了所有主流平台。我个人推荐使用包管理器便于后续更新。macOS (Homebrew):brew install charmbracelet/tap/crush这是最简洁的方式Homebrew会自动处理依赖和路径。Linux (Debian/Ubuntu):首先添加Charm的APT仓库以获取自动更新sudo mkdir -p /etc/apt/keyrings curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg echo deb [signed-by/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * * | sudo tee /etc/apt/sources.list.d/charm.list sudo apt update sudo apt install crushWindows:推荐使用Winget这是微软官方的包管理器winget install charmbracelet.crush安装后在PowerShell或Windows Terminal中直接输入crush即可启动。通用方法Go语言环境如果你有Go环境这是最直接的方式能确保获得最新版本go install github.com/charmbracelet/crushlatest安装后确保$GOPATH/bin默认为~/go/bin在你的系统PATH中。首次运行与密钥配置安装完成后在终端输入crush。首次运行时Crush会引导你进行配置。最关键的一步是设置API密钥。你有几种选择交互式引导Crush会列出检测到的可用提供商如OpenAI、Anthropic你可以选择其中一个并粘贴API密钥。环境变量更推荐的方式是预先设置环境变量。例如使用OpenAIexport OPENAI_API_KEYsk-your-key-here然后运行crush它会自动识别并使用该密钥。你可以在shell配置文件如~/.bashrc或~/.zshrc中永久设置。配置文件对于多模型或复杂配置直接编辑配置文件~/.config/crush/crush.json后文详述。3.2 核心交互模式与日常使用场景启动Crush后你会进入一个交互式会话。界面通常分为上下两部分上方是对话区域下方是输入框。它的使用非常直观直接提问像和同事交流一样用自然语言描述你的需求。场景1代码理解- “解释一下src/utils/auth.js文件中validateToken函数的作用。”场景2文件操作- “把config.yaml里所有debug: true的行找出来并告诉我分别在哪些文件里。”场景3系统命令- “帮我写一个命令找出当前目录下所有超过100MB的.log文件并按大小排序。”上下文操作Crush能记住当前会话的对话历史。你可以进行追问比如“用sed命令把刚才找到的那些debug: true都改成debug: false。”工具调用确认当Crush需要执行一个可能修改文件或运行命令的工具时如edit、bash它会暂停并请求你的许可。你会看到类似[?] Allow tool call ‘edit’? (Y/n)的提示。输入Y确认n拒绝。这是保证你控制权的关键步骤。切换模型在会话中你可以随时输入/model命令来查看可用模型列表并用/model provider-name/model-id来切换。例如从一个较慢但强大的模型切换到另一个更快的模型来处理简单任务。一个典型的工作流示例假设你接手了一个新项目需要快速熟悉。在项目根目录打开终端输入crush。“这个项目是做什么的主要技术栈是什么” Crush会读取package.json、go.mod、Cargo.toml等文件并结合目录结构给你一个概述。“帮我运行一下测试看看有没有失败。” Crush可能会识别出项目的测试运行器如npm test、go test ./...、pytest执行它并总结测试结果。“我想在/api路径下添加一个新的用户查询接口。” Crush可以结合现有的代码模式为你生成符合项目风格的控制器、路由和模型代码片段甚至直接创建文件。3.3 项目初始化与上下文构建要让Crush在一个项目中发挥最大效力初始化是关键一步。在项目根目录下运行crush --init或者直接在Crush会话中输入“初始化这个项目”。这个命令会触发Crush深度分析你的代码库。它会扫描项目结构识别主要语言和框架。读取配置文件如.gitignore,package.json,Makefile。尝试理解项目的构建、测试和运行命令。将所有这些信息整合生成一个名为AGENTS.md默认的上下文文件。这个AGENTS.md文件就是Crush在这个项目中的“工作手册”。它包含了项目特有的指令例如# Project Context - **Language:** TypeScript with Node.js - **Framework:** Express.js - **Test Runner:** Jest - **Linting:** ESLint with Airbnb config - **Build Command:** npm run build - **Run Command:** npm start - **Key Conventions:** Use async/await, error handling middleware in src/middlewares/.未来无论谁包括你自己在这个目录下启动Crush它都会先读取这个文件从而快速进入角色给出的建议会更贴合项目规范。你可以通过配置options.initialize_as来改变这个文件名或路径例如设为docs/Onboarding.md。4. 深度配置指南打造你的专属智能体Crush的默认配置已经足够强大但它的真正潜力在于深度定制。配置文件遵循优先级项目目录下的.crush.json或crush.json优先级最高其次是用户全局配置~/.config/crush/crush.json。4.1 配置核心模型、LSP与MCP一个完整的配置文件骨架如下我们逐一拆解关键部分{ $schema: https://charm.land/crush.json, providers: { /* 模型提供商配置 */ }, lsp: { /* 语言服务器配置 */ }, mcp: { /* 模型上下文协议服务器配置 */ }, options: { /* 各种行为选项 */ }, permissions: { /* 工具权限控制 */ } }1. 自定义模型提供商 (Providers):这是配置的重头戏。除了使用环境变量你可以在配置中硬编码或引用环境变量来定义多个提供商。添加一个OpenAI兼容的本地模型如Ollama:{ providers: { ollama-local: { id: ollama, name: 本地 Ollama, type: openai-compat, base_url: http://localhost:11434/v1, api_key: ollama, // Ollama通常不需要真密钥但字段必填 models: [ { id: qwen2.5:7b, name: Qwen2.5 7B, context_window: 32768, default_max_tokens: 4096 } ] } } }关键点type字段非常重要。对于真正的OpenAI服务用openai对于其他兼容OpenAI API的第三方服务如Ollama, LM Studio, 本地部署的vLLM必须使用openai-compat否则可能无法正常工作。配置一个自定义的Anthropic兼容端点:{ providers: { my-claude-proxy: { type: anthropic, base_url: https://your-proxy.com/v1, api_key: $MY_CUSTOM_API_KEY, // 使用环境变量更安全 extra_headers: { Custom-Header: value }, models: [ { id: claude-3-5-sonnet-20241022, name: 我的Claude代理, context_window: 200000, default_max_tokens: 8192 } ] } } }2. 集成语言服务器 (LSP):LSP能让Crush“理解”代码。你需要确保对应的LSP二进制文件已在系统PATH中。{ lsp: { python: { command: pylsp, enabled: true }, rust: { command: rust-analyzer, enabled: true }, bash: { command: bash-language-server, args: [start], enabled: true } } }配置后当Crush处理相应语言的文件时会自动启动LSP服务器从而获得代码补全、定义跳转、类型检查等高级功能支持。3. 连接外部数据源 (MCP):MCP是扩展Crush视野的利器。以下是一个连接本地文件系统MCP服务器和HTTP API MCP服务器的例子。{ mcp: { local-files: { type: stdio, command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/your/project], timeout: 30 }, web-search: { type: http, url: https://your-mcp-search-server.com/mcp, headers: { Authorization: Bearer $(echo $SEARCH_API_KEY) } } } }配置成功后你可以向Crush提问“在我的项目/path/to/your/project里上周修改了哪些文件” 它会通过MCP服务器获取信息并回答。4.2 权限、忽略与行为微调权限控制 (Permissions):安全第一。你可以精细控制哪些工具可以不经确认直接运行。{ permissions: { allowed_tools: [ls, cat, grep, find] // 仅允许这些只读工具自动运行 } }对于edit编辑文件、bash执行任意命令这类高风险工具强烈建议保持默认的确认提示。文件忽略 (.crushignore):和.gitignore类似你可以在项目根目录创建.crushignore文件列出不希望Crush读取或纳入上下文的文件和目录例如node_modules/,*.log,config/secrets.yml。这能提升响应速度并避免泄露敏感信息。界面与通知选项 (Options):{ options: { tui: { compact_mode: true // 使用紧凑模式显示更多信息 }, disable_notifications: false, // 保持桌面通知当终端失焦时提醒 debug: false // 除非排查问题否则关闭调试日志以免输出过多 } }5. 高级技巧与实战问题排查5.1 技能Skills的创建与使用Skills是提升Crush专业度的终极武器。假设你经常需要做数据库迁移可以创建一个database-migration技能。创建技能目录结构mkdir -p ~/.config/crush/skills/database-migration cd ~/.config/crush/skills/database-migration编写技能说明文件SKILL.md:# Database Migration Assistant You are an expert in database schema migrations. When activated, you will help the user create, review, and apply database migrations. ## Context - The project uses Prisma ORM. - The database is PostgreSQL. - Migration files are located in prisma/migrations/. ## Instructions 1. Always suggest using npx prisma migrate dev to create a new migration after schema changes. 2. Before applying migrations to production, remind the user to review the generated SQL in the migration file. 3. For complex migrations, recommend breaking them down into multiple steps and using prisma migrate diff to generate safe SQL. 4. Never run destructive operations (like DROP TABLE) without explicit confirmation from the user. ## Examples User: I added a new field emailVerified to the User model. Assistant: I see youve updated the Prisma schema. Lets create a migration for that. Ill run npx prisma migrate dev --name add_email_verified to generate and apply the migration. Would you like to proceed?这个文件用自然语言定义了Crush在“数据库迁移”这个任务中应该扮演的角色、拥有的上下文知识、必须遵循的指令以及示例对话。使用技能下次当你在相关项目中提到“数据库”或“迁移”时Crush可能会自动激活这个技能或者你可以手动提示它“请使用数据库迁移技能来帮我处理这个问题。”5.2 常见问题与解决方案速查表在实际使用中你可能会遇到以下问题。这里是我总结的排查清单问题现象可能原因解决方案启动Crush后无反应或立即退出1. API密钥未设置或无效。2. 网络问题无法连接到配置的模型端点。3. 配置文件语法错误。1. 检查环境变量echo $OPENAI_API_KEY或配置文件中的api_key。2. 运行crush --debug查看详细错误日志通常会在.crush/logs/crush.log中。3. 使用JSON验证工具检查crush.json格式。Crush无法理解我的项目代码1. 未安装或未配置对应语言的LSP。2. LSP服务器启动失败。3. 项目未初始化缺少上下文。1. 确保安装了对应LSP如gopls,pylsp并位于PATH中。2. 在配置中启用debug_lsp: true查看LSP通信日志。3. 在项目根目录运行crush --init生成AGENTS.md。工具调用失败如bash命令不执行1. 该工具在disabled_tools列表中被禁用。2. 权限不足被用户拒绝。3. 工具本身执行出错命令不存在等。1. 检查配置文件的options.disabled_tools。2. 确认在提示时按了Y。可临时使用--yolo标志需极其谨慎。3. 查看Crush日志确认它尝试运行的具体命令是什么。切换模型后上下文丢失不同模型提供商的API对上下文格式的处理可能有细微差异。这是当前多模型切换的一个已知挑战。对于需要长期上下文的任务建议在一个会话中固定使用一个模型。重要的上下文可以手动总结后输入给新模型。在Linux上复制/粘贴不工作缺少必要的剪贴板工具。根据你的桌面环境安装-Wayland:sudo apt install wl-clipboard(包含wl-copy和wl-paste)-X11:sudo apt install xclip或sudo apt install xsel桌面通知不显示1. 终端不支持焦点状态报告。2. 在配置中禁用了通知。3. 系统通知设置被关闭。1. 尝试使用支持此功能的终端如iTerm2 (macOS), WezTerm, 或Windows Terminal。2. 检查配置中options.disable_notifications是否为false。3. 检查操作系统级别的通知权限。5.3 日志分析与调试技巧当遇到复杂问题时日志是你的第一手资料。Crush的日志默认位于项目目录下的.crush/logs/crush.log。查看实时日志在另一个终端标签页运行crush logs --follow这就像打开了调试控制台所有内部过程、API请求、工具调用都会滚动显示。定位错误如果Crush崩溃或无响应查看日志末尾的ERROR级别信息。常见的错误包括API请求失败检查网络和密钥、LSP初始化失败检查LSP安装、或权限错误。启用深度调试在配置文件或启动命令中加入--debug标志会输出更详细的网络请求和内部状态信息对排查MCP连接或复杂工具调用问题特别有用。5.4 性能优化与成本控制心得模型选择策略将“重型”和“轻型”模型搭配使用。我通常将Claude 3.5 Sonnet或GPT-4配置为默认模型用于复杂的代码生成和架构设计。同时配置一个快速的本地模型如通过Ollama运行的Qwen2.5-Coder或低成本API模型如DeepSeek用于简单的文件查找、命令生成等任务并在需要时用/model快速切换。这能有效平衡效果与成本/速度。利用上下文文件务必为每个重要项目运行crush --init。一个信息丰富的AGENTS.md能极大减少Crush在每次会话中反复分析基础信息所消耗的Token提升响应速度和质量。精细化配置.crushignore将node_modules,build,dist,.git,*.log,*.db等大型或无关目录加入忽略列表。这能显著减少Crush在构建项目上下文时的扫描负担并避免将无关文件内容意外送入模型。管理会话长度对于超长对话模型的上下文窗口可能不够导致性能下降或遗忘早期内容。对于不同的子任务可以开启新的Crush会话CtrlC退出后重新进入或者主动使用“/clear”命令如果支持来清空历史保持会话焦点。经过数月的深度使用Crush已经从我的一个“新奇玩具”变成了终端里不可或缺的“副驾驶”。它最让我欣赏的不是它能生成多么炫酷的代码而是它那种无感融入工作流的能力——我不需要改变习惯只需要用最自然的方式表达意图剩下的脏活累活它都能默默地、可靠地帮我处理好。从自动化繁琐的文本处理到快速理解陌生代码库再到安全地执行一系列系统命令Crush极大地扩展了终端这个古老界面的能力边界。如果你也生活在命令行里我强烈建议你花点时间配置它体验一下这种“言出法随”的编程新范式。
