1. 项目概述当 Neovim 遇见 AI 智能体如果你和我一样是个常年泡在终端和编辑器里的开发者这两年肯定没少折腾各种 AI 编程工具。从 GitHub Copilot 的自动补全到 Cursor 的智能编辑再到 Zed 的 AI 对话每个工具都试图在编码流程中塞入一个“副驾驶”。但不知道你有没有这种感觉这些工具好用是好用但总感觉隔了一层。要么是得频繁切换窗口打断心流要么是配置繁琐不同模型、不同服务之间难以统一管理更别提那些需要特定 CLI 工具才能调用的“智能体”Agent了想用还得额外开个终端。今天要聊的codecompanion.nvim就是来解决这个痛点的。简单说它是一个 Neovim 插件但它的野心远不止“又一个 AI 聊天插件”。它的目标是把所有主流的大语言模型LLM和新兴的智能体客户端协议Agent Client Protocol, ACP都无缝集成到你的 Neovim 编辑器里。这意味着你可以在不离开编辑器的情况下直接调用 Claude、GPT-4、Gemini、DeepSeek甚至是 Docker 的 Cagent、Anthropic 的 Claude Code、Cursor CLI 这类专门的编码智能体。想象一下这个场景你正在写一个复杂的函数遇到了一个模糊的 LSP 错误。传统做法是去搜索引擎或 ChatGPT 网页版提问然后手动把代码和错误信息复制过去。而有了 CodeCompanion你只需要在错误行上按几个键它就能自动捕获当前文件上下文、错误信息并发送给你配置好的模型比如 Claude 3.5 Sonnet答案直接显示在编辑器内的聊天缓冲区里。你甚至可以让它直接修改代码或者通过 ACP 调用一个专门负责重构的智能体来执行更复杂的任务。这个插件适合所有 Neovim 用户无论你是刚接触 AI 编程辅助的新手还是已经重度依赖多个 AI 工具、渴望一个统一工作台的老手。它试图成为你在 Neovim 中的 AI 中枢一个真正的“代码伴侣”。2. 核心架构与设计哲学2.1 核心定位不是聊天机器人是集成平台很多 Neovim 的 AI 插件止步于“在编辑器里开个 ChatGPT 窗口”。CodeCompanion 的出发点则不同。作者 Oli Morris 显然是从一个“工作流整合者”的角度来设计它的。它的核心价值体现在三个层面协议抽象层这是它的基石。它没有把 OpenAI 的 API 或 Anthropic 的 SDK 直接写死而是设计了一套适配器Adapter系统。无论是标准的 HTTP APIOpenAI, Anthropic还是需要特殊 CLI 工具的智能体协议ACP亦或是本地模型Ollama都通过适配器来对接。这带来了极大的灵活性未来任何新的模型或协议理论上都可以通过编写适配器接入。上下文感知引擎AI 编程辅助的核心是“上下文”。CodeCompanion 深度整合了 Neovim 和 Tree-sitter能智能地获取并组织上下文信息。这不仅仅是把当前文件内容扔给 AI而是包括编辑器上下文当前缓冲区内容、可视选区、光标位置、符号树通过 Tree-sitter 解析出的函数、类定义。诊断信息LSP、诊断工具如null-ls报出的错误、警告。项目结构可以通过配置引入相关文件的内容。这种有结构的上下文远比一股脑粘贴代码更能让 AI 理解你的意图。操作执行闭环获取 AI 的回答只是第一步。CodeCompanion 提供了多种方式将 AI 的输出“落地”内联交互在代码行旁边直接与 AI 对话让它解释、重构或重写特定代码块。聊天缓冲区一个功能丰富的聊天界面支持 Markdown 渲染、代码块高亮、历史记录并且可以直接将聊天中的代码建议应用到当前文件。工具与工作流通过 ACP 或自定义工具AI 可以执行更具体的操作比如运行测试、查询文档、甚至执行安全的 Shell 命令在沙盒内。2.2 两大支柱LLM 适配器与 ACP 支持要理解 CodeCompanion必须搞懂它支持的两种主要集成方式。LLM 适配器这是对接各类云服务或本地模型的标准方式。插件内置了十几种适配器覆盖了几乎所有主流选择云服务OpenAI (GPT-4, o1), Anthropic (Claude 3), Google Gemini, DeepSeek, Mistral AI, xAI (Grok)。本地/自托管Ollama (运行本地模型如 Llama 3, CodeLlama), HuggingFace 推理端点。特殊集成GitHub Copilot Chat需要 Copilot 订阅 GitHub Models。每个适配器都需要相应的 API Key 或访问凭证配置在 Neovim 的setup函数中。Agent Client Protocol (ACP) 支持这是 CodeCompanion 的“杀手级”特性。ACP 是一个新兴的开放协议旨在标准化编辑器与外部“编码智能体”之间的通信。这些智能体不是简单的聊天模型而是具备特定能力、可以执行编码任务的程序。例如Claude CodeAnthropic 专门为编码优化的智能体。Cursor CLICursor 编辑器背后的智能体。Docker CagentDocker 推出的、能理解容器和开发环境的智能体。Augment Code一个专注于代码增强和理解的智能体。通过 ACPCodeCompanion 可以直接在 Neovim 内驱动这些强大的外部工具让你无需离开编辑器就能使用 Cursor 或 Claude Code 的核心能力。注意使用 ACP 智能体通常需要你在系统上预先安装并配置好对应的 CLI 工具。CodeCompanion 扮演的是“客户端”角色负责启动并与这些 CLI 工具通信。2.3 性能与体验设计作为一个深度集成工具性能至关重要。CodeCompanion 采用异步执行模型所有网络请求和耗时操作都不会阻塞你的编辑器界面。聊天、请求、工具调用都在后台进行确保你的编辑体验依然流畅。它的 UI 设计也充分考虑了 Neovim 用户的使用习惯。聊天缓冲区是一个普通的 Neovim 缓冲区这意味着你可以用所有熟悉的 Vim 动作j,k,/搜索yy复制来操作它。代码块有正确的语法高亮消息渲染清晰交互按钮如“应用代码块”设计得直观易用。3. 从零开始安装与基础配置实战理论说了不少我们来点实际的。下面我将带你一步步配置 CodeCompanion并连接一个最常用的模型OpenAI 的 GPT-4。3.1 环境准备与依赖安装首先确保你的 Neovim 版本在 0.9 以上推荐 0.10。然后你需要一个包管理器。这里以目前最流行的lazy.nvim为例。CodeCompanion 有两个强依赖必须在配置中声明nvim-lua/plenary.nvim提供 Lua 开发所需的各类实用函数是许多高质量插件的基础库。nvim-treesitter/nvim-treesitter用于解析代码获取精准的符号函数名、类名等信息这对于提供高质量的编辑器上下文至关重要。打开你的 Neovim 配置文件通常是~/.config/nvim/init.lua或~/.config/nvim/lua/plugins.lua添加以下配置块-- 在 lazy.nvim 的 spec 中 { olimorris/codecompanion.nvim, dependencies { nvim-lua/plenary.nvim, nvim-treesitter/nvim-treesitter, }, opts { -- 这里是插件的主配置 -- 我们稍后会在这里填充详细配置 }, -- 可选设置一些快捷键后面会解释 keys { { leadercc, cmdCodeCompanionCR, desc Open CodeCompanion }, { leaderca, cmdCodeCompanionActionsCR, desc Open Action Palette }, }, }保存文件运行:Lazy sync如果你用的是lazy.nvim插件和它的依赖就会被安装。3.2 配置第一个 LLM 适配器OpenAI安装完成后我们需要配置一个能实际使用的模型。以 OpenAI 为例你需要一个有效的 OpenAI API Key。安全提醒永远不要将 API Key 硬编码在配置文件中并上传到公开仓库。推荐使用环境变量或专门的 secrets 管理插件。这里我们使用环境变量。在终端中执行export OPENAI_API_KEYsk-your-actual-api-key-here为了使环境变量在 Neovim 中生效你需要从设置了该环境变量的终端启动 Neovim。然后我们来完善opts部分的配置opts { adapters { -- 定义你要使用的适配器 openai { model gpt-4o, -- 指定模型也可以是 gpt-4-turbo, gpt-3.5-turbo 等 -- api_key 默认会从环境变量 OPENAI_API_KEY 读取所以这里可以不写 -- 如果你想在配置中指定不推荐可以取消下面一行的注释 -- api_key os.getenv(OPENAI_API_KEY), }, }, -- 设置默认使用的适配器 default_adapter openai, }这个最小配置已经能让 CodeCompanion 工作了。重启 Neovim 或重新加载配置:Lazy reload codecompanion.nvim运行:checkhealth codecompanion来检查健康状况。你应该能看到OpenAI适配器显示为已配置。3.3 核心功能初体验聊天缓冲区与内联交互配置好模型后我们来试试两个最核心的功能。打开聊天缓冲区按下我们刚才设置的快捷键leadercc例如如果leader键是空格就是空格cc。一个垂直分割的窗口会打开这就是聊天缓冲区。你可以直接在底部的输入框里打字提问比如“用 Python 写一个快速排序函数”。按Ctrl-Enter或点击发送按钮消息就会发送给 GPT-4回复会以 Markdown 格式呈现代码块会被高亮。内联交互这是更高效的用法。打开一个代码文件将光标移动到某一行或选中一段代码。然后通过命令:CodeCompanionInline或为其设置一个快捷键如leaderci来启动内联模式。一个小窗口会弹出提供一些预设操作比如“解释这段代码”、“重构”、“查找错误”、“写测试”等。选择一项AI 会基于你选中的代码上下文给出建议并允许你直接接受或拒绝修改。实操心得刚开始使用内联交互时建议从“解释”或“生成文档字符串”这类低风险操作开始熟悉 AI 的输出风格和准确度。对于“重构”或“重写”这类高风险操作务必仔细审查 AI 的修改建议尤其是涉及业务逻辑的部分。AI 是强大的助手但不是可靠的工程师。4. 高级配置与深度定制指南基础功能跑通后我们可以根据个人工作流进行深度定制。CodeCompanion 的配置系统非常灵活。4.1 配置多个模型与智能体你很可能不止使用一个模型。比如快速聊天用 GPT-3.5 Turbo便宜复杂推理用 Claude 3.5 Sonnet本地尝试用 Ollama 的 CodeLlama。CodeCompanion 可以轻松管理多个后端。opts { adapters { openai_fast { model gpt-3.5-turbo, -- 可以为不同适配器设置不同的环境变量名 api_key os.getenv(OPENAI_API_KEY), }, openai_smart { model gpt-4o, api_key os.getenv(OPENAI_API_KEY), }, anthropic { model claude-3-5-sonnet-20241022, api_key os.getenv(ANTHROPIC_API_KEY), }, ollama_local { model codellama:7b, -- Ollama 的模型标签 -- Ollama 适配器默认连接到 http://localhost:11434 -- 如果 Ollama 运行在其他地方可以配置 base_url -- base_url http://my-ollama-server:11434, }, -- 配置一个 ACP 智能体例如 Claude Code claude_code { type acp, -- 关键指定类型为 acp command claude-code, -- 系统 PATH 中需要能找到这个命令 -- 可以传递额外的参数给 CLI -- args { --some-flag }, }, }, -- 可以设置一个默认的也可以在每次对话时选择 default_adapter openai_smart, }配置好后在聊天缓冲区中你可以通过命令或 UI 元素快速切换当前对话使用的适配器。例如输入/adapter anthropic就可以切换到 Claude。4.2 打造个性化提示词库与工作流预置的提示词如“解释代码”、“重构”可能不够用。CodeCompanion 允许你创建自己的提示词库、编辑器上下文和斜杠命令。创建自定义提示词在 Neovim 配置目录下如~/.config/nvim/创建一个codecompanion文件夹里面再建一个prompts文件夹。然后创建 Lua 文件例如my_prompts.lua-- ~/.config/nvim/codecompanion/prompts/my_prompts.lua return { { name Review for security issues, prompt [[ Please review the following code for potential security vulnerabilities. Focus on: 1. SQL injection risks. 2. Cross-site scripting (XSS) if its web code. 3. Insecure deserialization. 4. Use of deprecated or insecure cryptographic functions. Provide the findings in a table format with severity (High/Medium/Low), description, and suggested fix. Code: {filetype} {selection}]], context { selection }, -- 这个提示词需要选中代码 filetypes { python, javascript, go, java }, -- 只在这些文件类型中显示 }, { name Generate detailed unit test, prompt [[ As a senior developer, write comprehensive unit tests for the following function. Include:Tests for normal cases.Tests for edge cases and error conditions.Use mocking where appropriate.Add descriptive comments for each test case.Function:{selection}]], context { selection }, }, }然后在主配置中引入 lua opts { -- ... 其他配置 prompts { custom { ~/path/to/your/codecompanion/prompts, -- 指向你的自定义提示词目录 }, }, }重启后打开动作面板leaderca你就能看到自己定义的“安全审查”和“生成单元测试”等选项了。配置编辑器上下文你可以控制每次发送给 AI 的上下文包含什么。比如除了选中代码你还想自动包含当前函数的定义、这个文件的前 50 行后 50 行、以及所有的 LSP 错误。opts { context { -- 内置的上下文提供者 providers { buffer, -- 当前缓冲区 selection, -- 选中内容 filepath, -- 文件路径 symbols, -- Tree-sitter 符号函数、类名 diagnostics, -- LSP 诊断信息 diff, -- 当前文件的 git diff }, -- 为 buffer 提供者设置更多选项 buffer { lines_before 50, lines_after 50, }, }, }4.3 集成 ACP 智能体进行复杂任务ACP 智能体是 CodeCompanion 的进阶玩法。以配置Cursor CLI为例假设你已通过npm install -g cursor/cursor安装配置适配器adapters { cursor_cli { type acp, command cursor, -- Cursor CLI 可能需要额外的启动参数 -- args { --model, claude-3-5-sonnet }, }, },使用当你通过leadercc打开聊天缓冲区并切换到cursor_cli适配器后你的对话对象就变成了 Cursor 的 AI 引擎。你可以让它执行一些 Cursor 特有的复杂任务比如“分析这个代码库的依赖结构”或“为这个模块设计一个测试策略”。智能体可能会调用工具来读取文件、分析代码给出比普通聊天更深入的答案。注意事项ACP 智能体的行为比普通 LLM 更不可预测因为它们可以执行代码和工具。务必在可信的环境下使用并仔细审查它们建议的操作尤其是涉及文件写入或命令执行时。建议先在非关键项目或临时目录中测试。5. 日常使用技巧与高效工作流配置是基础用得好才是关键。下面分享一些我摸索出来的、能极大提升效率的使用模式。5.1 快捷键映射与肌肉记忆把常用操作映射到顺手的快捷键上是融入工作流的第一步。这是我的部分配置vim.keymap.set(n, leadercc, cmdCodeCompanionCR, { desc Open Chat Buffer }) vim.keymap.set(n, leaderca, cmdCodeCompanionActionsCR, { desc Open Action Palette }) -- 内联交互对当前行或视觉选区操作 vim.keymap.set({ n, v }, leaderce, function() require(codecompanion).inline() end, { desc Inline Edit (Explain/Refactor) }) -- 快速提问针对当前错误 vim.keymap.set(n, leadercf, function() require(codecompanion).actions.lsp_fix() end, { desc Fix LSP Error }) -- 切换适配器 vim.keymap.set(n, leadercs, cmdCodeCompanionSelectAdapterCR, { desc Select Adapter })5.2 场景化使用案例案例一即时调试助手当 LSP 报出一个看不懂的错误时将光标移到错误行按下leadercf。CodeCompanion 会自动捕获错误信息和周围代码发送给 AI 并请求解释和修复建议。这比复制粘贴到网页快得多上下文也更完整。案例二代码审查伙伴在提交代码前选中修改的代码块通过动作面板leaderca选择自定义的“安全审查”或“性能审查”提示词。让 AI 以另一个“工程师”的视角快速过一遍常能发现一些自己遗漏的边界条件或潜在问题。案例三学习新代码库打开一个陌生的文件选中整个函数或类使用内联交互的“解释”功能。AI 会为你逐行或分段解释代码逻辑、数据流和设计意图是快速理解遗留代码的神器。案例四生成样板代码当你需要创建一个新的组件、API 接口或配置文件时可以在聊天缓冲区中描述需求并指定文件类型。例如“用 TypeScript 写一个 React 函数组件名叫UserProfile接收name和avatarUrl作为 props并有一个编辑按钮。” AI 生成代码后可以直接用聊天缓冲区内的“应用代码块”功能插入到当前文件。5.3 管理聊天历史与上下文CodeCompanion 的聊天缓冲区支持多会话。你可以为不同的任务如“功能A开发”、“Bug B 排查”、“学习项目X”创建独立的聊天避免上下文混淆。聊天历史会保存在本地具体位置取决于你的配置下次打开时可以继续。合理利用/clear命令清空上下文或者/context命令手动调整附加上下文比如添加另一个相关文件可以显著提升长对话中 AI 回复的准确性和一致性。6. 常见问题排查与性能调优即使配置正确在实际使用中也可能遇到各种问题。下面是一些常见坑点和解决方案。6.1 连接与认证问题问题现象可能原因解决方案运行:checkhealth codecompanion显示适配器错误如“Invalid API Key”1. API Key 未设置或错误。2. 环境变量未在 Neovim 环境中生效。3. 网络代理问题。1. 在终端用echo $OPENAI_API_KEY检查 Key 是否存在且正确。2.务必从设置了环境变量的同一个终端启动 Neovim。3. 尝试在适配器配置中增加api_base或代理设置如果适用。对于 OpenAI可以设置api_base https://api.openai.com/v1默认就是这个。Ollama 适配器连接失败1. Ollama 服务未运行。2. 模型名称错误。1. 在终端运行ollama serve并确保其运行。2. 用ollama list确认模型名称如codellama:7b或llama3.2:latest。ACP 智能体无法启动1. CLI 命令未安装或不在 PATH 中。2. 智能体自身需要额外认证如登录。1. 在终端直接运行cursor或claude-code看是否能启动。2. 查阅对应智能体的官方文档完成初始设置如cursor auth login。6.2 性能与响应缓慢请求超时默认请求可能有超时限制。对于本地 Ollama 或较慢的网络可以增加超时时间。opts { opts { request_timeout 120000, -- 单位毫秒默认可能是 60000 (60秒) }, adapters { ollama_local { model llama3.2, request_timeout 180000, -- 也可以为单个适配器设置 }, }, }上下文过大导致响应慢或 token 超限如果你配置了buffer上下文提供者并设置了很大的lines_before/after或者项目文件很大发送的 token 数会激增。这会导致请求变慢、费用增加对于按 token 计费的 API甚至可能超过模型上下文窗口。建议根据任务调整上下文。对于具体问题使用selection上下文对于文件级问题使用symbols上下文获取结构信息而非整个文件。6.3 模型“幻觉”与输出质量控制AI 模型尤其是代码生成有时会产生“幻觉”即生成看似合理但错误或无效的代码。启用流式输出大部分适配器支持流式输出streaming这能让你看到 AI 的思考过程有时在它“跑偏”时能及时中断。opts { chat { streaming true, -- 默认可能是 true确保开启 }, }使用更具体的提示词模糊的指令容易导致模糊的结果。在自定义提示词中明确指定输出格式、约束条件、需要避免什么。例如“用 Python 写一个函数输入是一个整数列表返回它们的平均值。不要使用内置的sum和len函数请手动迭代计算。将最终代码放在一个代码块中。”结合 LSP 和测试永远不要盲目接受 AI 生成的代码。利用 Neovim 强大的 LSP 功能如vim.lsp.buf.format()和vim.lsp.buf.code_action()对生成的代码进行格式化和检查。对于关键逻辑立即编写或运行相关测试进行验证。6.4 高级调试日志与最小化配置如果遇到诡异的问题开启调试日志是第一步。opts { opts { log_level DEBUG, -- 或者 TRACE 获取最详细日志 }, }设置后运行:checkhealth codecompanion会显示日志文件路径通常在~/.local/state/nvim/codecompanion.log。打开这个文件查看错误堆栈和请求/响应详情。如果怀疑是自己的 Neovim 配置冲突可以使用项目根目录提供的minimal.lua文件进行测试。在终端执行cd /path/to/codecompanion.nvim nvim --clean -u minimal.lua这会在一个几乎纯净的 Neovim 环境中加载 CodeCompanion 和最小依赖。如果在这里工作正常那问题很可能出在你自己的配置上需要逐一排查其他插件或设置。7. 生态扩展与未来展望CodeCompanion 的架构决定了它有很强的扩展性。社区已经贡献了不少第三方适配器如对接国内大模型平台可以在官方文档的“社区适配器”部分找到。模型上下文协议MCP是另一个值得关注的方向。MCP 允许模型动态地访问工具和数据源。CodeCompanion 对 MCP 的初步支持意味着未来 AI 在回答时可以实时查询数据库、调用外部 API 或读取特定文档让回答更精准、更具时效性。从我个人的使用体验来看CodeCompanion 代表了 Neovim 生态中 AI 集成的一个成熟方向不满足于简单的聊天集成而是追求成为一个可编程的、支持多后端的、深度融入编辑工作流的 AI 代理平台。它把选择权交还给用户你可以根据任务需求、成本考虑和响应速度自由切换于 Claude、GPT、本地模型乃至专业的编码智能体之间。当然它也不是没有学习成本。复杂的配置选项、ACP 智能体的额外设置对新手来说可能有些 daunting。但一旦配置妥当它所带来的流畅、集中、高效的 AI 辅助编程体验是频繁切换于不同网页应用和 CLI 工具所无法比拟的。它让 AI 真正成为了编辑器的一部分就像语法高亮和自动补全一样自然。