CopilotChat.nvim 将 GitHub Copilot Chat 的功能直接引入 Neovim，注重透明性和用户控制。

• 🤖 多种 AI 模型 - GitHub Copilot（包括 GPT-4o、Gemini 2.5 Pro、Claude 4 Sonnet、Claude 3.7 Sonnet、Claude 3.5 Sonnet、o3-mini、o4-mini）+ 自定义提供者（Ollama、Mistral.ai）。可用模型的具体列表取决于您的 GitHub Copilot 设置以及 GitHub API 提供的模型。
• 🔧 工具调用 - LLM 可在您明确批准的情况下调用工作区函数（文件读取、git 操作、搜索）
• 🔒 隐私优先 - 仅共享您明确请求的内容，无后台数据收集
• 📝 交互式聊天 - 带有补全、差异和 quickfix 集成的交互式 UI
• 🎯 智能提示 - 可组合的模板和粘性提示，以保持一致的上下文
• ⚡ 高效计数 - 资源替换可防止重复上下文，通过 tiktoken 计数进行历史管理
• 🔗 可脚本化 - 全面的 Lua API，用于自动化和无头模式操作
• 🔌 可扩展 - 自定义函数 和 提供者，以及如 mcphub.nvim 等集成

安装

要求

• Neovim 0.10.0+
• curl 8.0.0+
• 在 GitHub 设置中启用 IDE 中的 Copilot 聊天
• plenary.nvim

[!WARNING] 对于 Neovim < 0.11.0，请在 completeopt 中添加 noinsert 或 noselect，否则聊天自动补全将无法正常工作。 为获得最佳自动补全体验，即使在 Neovim 0.11.0+ 上，也请在 completeopt 中添加 popup。

可选依赖项

• tiktoken_core - 用于准确的 token 计数
  • Arch Linux：从 AUR 安装 luajit-tiktoken-bin 或 lua51-tiktoken-bin
  • 通过 luarocks：sudo luarocks install --lua-version 5.1 tiktoken_core
  • 手动：从 lua-tiktoken 发布页面 下载，并将其保存为 tiktoken_core.so 放入您的 Lua 路径中
• git - 用于 git diff 上下文功能
• ripgrep - 用于提升搜索性能
• lynx - 用于改善 URL 上下文功能

与 picker 的集成

为了让各种插件的 picker 正确工作，您需要将 vim.ui.select 替换为您想要的 picker（因为默认的 vim.ui.select 非常基础）。以下是一些示例：

• fzf-lua - 调用 require('fzf-lua').register_ui_select()
• telescope - 设置 telescope-ui-select.nvim 插件
• snacks.picker - 启用 ui_select 配置
• mini.pick - 设置 vim.ui.select = require('mini.pick').ui_select

lazy.nvim

return {
  {
    "CopilotC-Nvim/CopilotChat.nvim",
    dependencies = {
      { "nvim-lua/plenary.nvim", branch = "master" },
    },
    build = "make tiktoken",
    opts = {
      -- 选项请参阅配置部分
    },
  },
}

vim-plug

call plug#begin()
Plug 'nvim-lua/plenary.nvim'
Plug 'CopilotC-Nvim/CopilotChat.nvim'
call plug#end()

lua << EOF
require("CopilotChat").setup()
EOF

核心概念

• 资源 (#<name>) - 将特定内容（文件、git diffs、URL）添加到您的提示中
• 工具 (@<name>) - 给予 LLM 在您批准后可以调用的功能访问权限
• 粘性提示 (> <text>) - 在单次聊天会话中保持上下文
• 模型 ($<model>) - 指定用于聊天的 AI 模型
• 提示 (/PromptName) - 使用预定义的提示模板处理常见任务

示例

# 将特定文件加入上下文

#file:src/main.lua

# 给 LLM 工作区工具的访问权限

@copilot 这个项目里有哪些文件？

# 持续存在的粘性提示

> #buffer:active
> 你是一位乐于助人的编程助手

当您使用 @copilot 时，LLM 可以调用诸如 bash、edit、file、glob、grep、gitdiff 等函数。您会看到拟议的函数调用，并可在执行前批准或拒绝。

使用方法

命令

命令	描述
:CopilotChat <input>?	打开带有可选输入的聊天
:CopilotChatOpen	打开聊天窗口
:CopilotChatClose	关闭聊天窗口
:CopilotChatToggle	切换聊天窗口
:CopilotChatStop	停止当前输出
:CopilotChatReset	重置聊天窗口
:CopilotChatSave <name>?	保存聊天历史
:CopilotChatLoad <name>?	加载聊天历史
:CopilotChatPrompts	查看/选择提示模板
:CopilotChatModels	查看/选择可用模型
:CopilotChat<PromptName>	使用特定提示模板

聊天键映射

插入模式	普通模式	动作
<Tab>	-	触发/接受标记的补全菜单
<C-c>	q	关闭聊天窗口
<C-l>	<C-l>	重置并清空聊天窗口
<C-s>	<CR>	提交当前提示
-	grr	切换光标下一行的固定提示
<C-y>	<C-y>	接受最近的差异
-	gj	跳转到最近差异的部分
-	gqa	将聊天中的所有答案添加到 quickfix 列表
-	gqd	将聊天中的所有差异添加到 quickfix 列表
-	gy	将最近的差异复制到寄存器
-	gd	显示源代码与最近差异之间的差异
-	gc	显示当前聊天的信息
-	gh	显示帮助信息

[!WARNING] 一些插件（例如 copilot.vim）也可能在插入模式下映射常用键，如 <Tab>。
为避免冲突，请通过以下方式禁用 Copilot 的默认 <Tab> 映射：

vim.g.copilot_no_tab_map = true
vim.keymap.set('i', '<S-Tab>', 'copilot#Accept("\\<S-Tab>")', { expr = true, replace_keycodes = false })

您也可以在配置中自定义 CopilotChat 的键映射。

预定义函数

所有预定义函数都属于 copilot 组。

函数	类型	描述	示例用法
bash	工具	执行 bash 命令并返回输出	@copilot 仅限
buffer	资源	从缓冲区中获取内容及诊断信息	#buffer:active
clipboard	资源	提供对系统剪贴板内容的访问	#clipboard
edit	工具	将统一差异应用到文件	@copilot 仅限
file	资源	读取指定文件路径的内容	#file:path/to/file
gitdiff	资源	获取 git 差异信息	#gitdiff:staged
glob	资源	列出工作区中匹配特定模式的文件名	#glob:**/*.lua
grep	资源	在工作区内的文件中搜索模式	#grep:TODO
selection	资源	包含当前可视选区及其诊断信息	#selection
url	资源	从指定 URL 获取内容	#url:https://...

类型说明：

• 资源：可通过 #function 语法手动使用
• 工具：仅可由 LLM 通过 @copilot 调用（出于安全和复杂性考虑）

预定义提示

提示	描述
Explain	以段落形式撰写所选代码的详细解释
Review	全面的代码审查，提供逐行问题报告
Fix	查找问题并改写代码，附带修复和解释
Optimize	通过优化策略提升性能和可读性
Docs	为选定的代码添加文档注释
Tests	为选定的代码生成测试
Commit	根据暂存更改，按照 commitizen 规范生成提交信息

配置

有关所有可用配置选项，请参阅 lua/CopilotChat/config.lua。

快速设置

大多数用户只需配置几个选项即可：

{
  model = 'gpt-4.1',           -- 使用的 AI 模型
  temperature = 0.1,           -- 较低 = 专注，较高 = 创意
  window = {
    layout = 'vertical',       -- 'vertical', 'horizontal', 'float'
    width = 0.5,              -- 屏幕宽度的 50%
  },
  auto_insert_mode = true,     -- 打开时自动进入插入模式
}

窗口与外观

{
  window = {
    layout = 'float',
    width = 80, -- 固定宽度（列数）
    height = 20, -- 固定高度（行数）
    border = 'rounded', -- 'single', 'double', 'rounded', 'solid'
    title = '🤖 AI Assistant',
    zindex = 100, -- 确保窗口始终位于最上层
  },

  headers = {
    user = '👤 You',
    assistant = '🤖 Copilot',
    tool = '🔧 Tool',
  },

  separator = '━━',
  auto_fold = true, -- 自动折叠非助手消息
}

缓冲区行为

-- 自动命令，用于自定义聊天缓冲区的行为
vim.api.nvim_create_autocmd('BufEnter', {
  pattern = 'copilot-*',
  callback = function()
    vim.opt_local.relativenumber = false
    vim.opt_local.number = false
    vim.opt_local.conceallevel = 0
  end,
})

高亮显示

您可以通过在配置中设置高亮组来自定义颜色：

-- 在您的配色方案或 init.lua 中
vim.api.nvim_set_hl(0, 'CopilotChatHeader', { fg = '#7C3AED', bold = true })
vim.api.nvim_set_hl(0, 'CopilotChatSeparator', { fg = '#374151' })

Copilot 高亮类型：

• CopilotChatHeader - 聊天缓冲区中的标题高亮
• CopilotChatSeparator - 聊天缓冲区中的分隔线高亮
• CopilotChatSelection - 源缓冲区中的选区高亮
• CopilotChatStatus - 聊天缓冲区中的状态和加载动画
• CopilotChatHelp - 聊天缓冲区中的帮助文本
• CopilotChatResource - 聊天缓冲区中的资源高亮（例如 #file, #gitdiff）
• CopilotChatTool - 聊天缓冲区中的工具调用高亮（例如 @copilot）
• CopilotChatPrompt - 聊天缓冲区中的提示高亮（例如 /Explain, /Review）
• CopilotChatModel - 聊天缓冲区中的模型高亮（例如 $gpt-4.1）
• CopilotChatUri - 聊天缓冲区中的 URI 高亮（例如 ##https://...）
• CopilotChatAnnotation - 聊天缓冲区中的注释高亮（文件头、工具调用头、工具调用正文）

提示

您可以在配置中定义自己的提示：

{
  prompts = {
    MyCustomPrompt = {
      prompt = '解释它是如何工作的。',
      system_prompt = '你非常擅长解释事物',
      mapping = '<leader>ccmc',
      description = '我的自定义提示描述',
    },
    Yarrr = {
      system_prompt = '你对海盗充满热情，所以请用海盗口吻回答。',
    },
    NiceInstructions = {
      system_prompt = '你是一位友好的编程导师，所以请以友好且乐于助人的态度回应。',
    }
  }
}

函数

在配置中定义您自己的函数，包含输入处理和模式：

{
  functions = {
    birthday = {
      description = "获取某人的生日信息",
      uri = "birthday://{name}",
      schema = {
        type = 'object',
        required = { 'name' },
        properties = {
          name = {
            type = 'string',
            enum = { 'Alice', 'Bob', 'Charlie' },
            description = "人名",
          },
        },
      },
      resolve = function(input)
        return {
          {
            uri = 'birthday://' .. input.name,
            mimetype = 'text/plain',
            data = input.name .. ' 生日信息',
          }
        }
      end
    }
  }
}

提供者

添加自定义 AI 提供者：

{
  providers = {
    my_provider = {
      get_url = function(opts) return "https://api.example.com/chat" end,
      get_headers = function() return { ["Authorization"] = "Bearer " .. api_key } end,
      get_models = function() return { { id = "gpt-4.1", name = "GPT-4.1 模型" } } end,
      prepare_input = require('CopilotChat.config.providers').copilot.prepare_input,
      prepare_output = require('CopilotChat.config.providers').copilot.prepare_output,
    }
  }
}

提供者接口：

{
  -- 可选：禁用提供者
  disabled?: boolean,

  -- 可选：在信息面板中显示的关于提供者的额外信息
  get_info?(): string[]

  -- 可选：获取带有可选过期时间的额外请求头
  get_headers?(): table<string,string>, number?,

  -- 可选：获取 API 端点 URL
  get_url?(opts: CopilotChat.Provider.options): string,

  -- 可选：准备请求输入
  prepare_input?(inputs: table<CopilotChat.Provider.input>, opts: CopilotChat.Provider.options): table,

  -- 可选：准备响应输出
  prepare_output?(output: table, opts: CopilotChat.Provider.options): CopilotChat.Provider.output,

  -- 可选：获取可用模型
  get_models?(headers: table): table<CopilotChat.Provider.model>,
}

内置提供者：

• copilot - GitHub Copilot（默认）
• github_models - GitHub Marketplace 模型（默认禁用）

API 参考

核心

local chat = require("CopilotChat")

-- 基本聊天功能
chat.ask(prompt, config)      -- 发送问题，可选配置

-- 窗口管理
chat.open(config)             -- 打开聊天窗口，可选配置
chat.close()                  -- 关闭聊天窗口
chat.toggle(config)           -- 切换聊天窗口可见性，可选配置
chat.reset()                  -- 重置聊天
chat.stop()                   -- 停止当前输出

-- 提示词与模型管理
chat.select_prompt(config)    -- 打开提示词选择器，可选配置
chat.select_model()           -- 打开模型选择器

-- 历史记录管理
chat.load(name, history_path) -- 加载聊天历史
chat.save(name, history_path) -- 保存聊天历史

-- 配置
chat.setup(config)            -- 更新配置
chat.log_level(level)         -- 设置日志级别（debug、info 等）

聊天窗口

您还可以通过 chat.chat 对象访问聊天窗口的 UI 方法：

local window = require("CopilotChat").chat

-- 聊天界面状态
window:visible()             -- 检查聊天窗口是否可见
window:focused()             -- 检查聊天窗口是否处于焦点

-- 消息管理
window:get_message(role, cursor)               -- 根据角色获取消息，可以是最后一条或最接近光标的那条
window:add_message({ role, content }, replace) -- 在聊天中添加或替换一条消息
window:remove_message(role, cursor)            -- 根据角色移除消息，可以是最后一条或最接近光标的那条
window:get_block(role, cursor)                 -- 根据角色获取代码块，可以是最后一条或最接近光标的那条

-- 内容管理
window:append(text)          -- 向聊天窗口追加文本
window:clear()               -- 清空聊天窗口内容
window:start()               -- 开始向聊天窗口写入内容
window:finish()              -- 完成向聊天窗口写入内容

-- 源码管理
window.get_source()          -- 获取当前源码缓冲区和窗口
window.set_source(winnr)     -- 设置源码窗口

-- 导航
window:follow()              -- 将光标移动到聊天内容末尾
window:focus()               -- 使聊天窗口获得焦点

-- 高级功能
window:overlay(opts)         -- 显示带有指定选项的覆盖层

提示词解析器

local parser = require("CopilotChat.prompts")

parser.resolve_prompt()         -- 解析提示词引用
parser.resolve_tools()          -- 解析可用于 LLM 自动调用的工具
parser.resolve_model()          -- 从提示词中解析模型（警告：异步操作，需使用 plenary.async.run）

使用示例

-- 打开聊天窗口，提问并处理回复
require("CopilotChat").open()
require("CopilotChat").ask("#buffer 解释这段代码", {
  callback = function(response)
    vim.notify("收到回复：" .. response:sub(1, 50) + "...")
    return response
  end,
})

-- 保存和加载聊天历史
require("CopilotChat").save("my_debugging_session")
require("CopilotChat").load("my_debugging_session")

-- 使用自定义粘性内容和模型
require("CopilotChat").ask("我该如何优化这段代码？", {
  model = "gpt-4.1",
  sticky = {"#buffer", "#gitdiff:staged"}
})

更多示例，请参阅 示例维基页面。

开发

设置

要设置开发环境：

1. 克隆仓库：

git clone https://github.com/CopilotC-Nvim/CopilotChat.nvim
cd CopilotChat.nvim

2. 安装开发依赖：

make install-pre-commit

运行测试：

make test

贡献

1. 分支仓库
2. 创建您的功能分支
3. 进行更改
4. 运行测试和代码检查
5. 提交拉取请求

详细指南请参阅 CONTRIBUTING.md。

贡献者

感谢以下各位贡献者（emoji key）：

gptlang 💻 📖	Dung Duc Huynh (Kaka) 💻 📖	Ahmed Haracic 💻	Trí Thiện Nguyễn 💻	He Zhizhou 💻	Guruprakash Rajakkannu 💻	kristofka 💻
PostCyberPunk 📖	Katsuhiko Nishimra 💻	Erno Hopearuoho 💻	Shaun Garwood 💻	neutrinoA4 💻 📖	Jack Muratore 💻	Adriel Velazquez 💻 📖
Tomas Slusny 💻 📖	Nisal 📖	Tobias Gårdhus 📖	Petr Dlouhý 📖	Dylan Madisetti 💻	Aaron Weisberg 💻 📖	Jose Tlacuilo 💻 📖
Kevin Traver 💻 📖	dTry 💻	Arata Furukawa 💻	Ling 💻	Ivan Frolov 💻	Folke Lemaitre 💻 📖	GitMurf 💻
Dmitrii Lipin 💻	jinzhongjia 📖	guill 💻	Sjon-Paul Brown 💻	Renzo Mondragón 💻 📖	fjchen7 💻	Radosław Woźniak 💻
JakubPecenka 💻	thomastthai 📖	Tomáš Janoušek 💻	Toddneal Stallworth 📖	Sergey Alexandrov 💻	Léopold Mebazaa 💻	JunKi Jin 💻
abdennourzahaf 📖	Josiah 💻	Tony Fischer 💻 📖	Kohei Wada 💻	Sebastian Yaghoubi 📖	johncming 💻	Rokas Brazdžionis 💻
Sola 📖 💻	Mani Chandra 💻	Nischal Basuti 📖	Teo Ljungberg 💻	Joe Price 💻	Yufan You 📖 💻	Manish Kumar 💻
Anton Ždanov 📖 💻	Fredrik Averpil 💻	Aaron D Borden 💻	Md. Iftakhar Awal Chowdhury 💻 📖	Danilo Horta 💻	Mihamina Rakotomandimby 📖 💻	Ajmal S 💻
Samiul Islam 💻	Rui Costa 💻	CTCHEN 💻	Tobias Wölfel 💻	Alexander Garcia 💻	Max Kharandziuk 💻	Xinyu Xiang 💻
junqizhang 💻	Calum Lynch 💻	sirjls 💻

本项目遵循 all-contributors 规范。欢迎任何形式的贡献！

星标用户

CopilotChat.nvim 快速上手指南

CopilotChat.nvim 将 GitHub Copilot Chat 的原生能力直接集成到 Neovim 中，注重透明度和用户控制权。支持多种 AI 模型、工具调用及自定义提示词。

环境准备

在开始之前，请确保您的系统满足以下要求：

系统要求

• Neovim: 版本 0.10.0 或更高（推荐 0.11.0+）
• GitHub Copilot: 已在 GitHub 设置中启用 Copilot Chat
• curl: 版本 8.0.0 或更高

关键配置警告

对于 Neovim < 0.11.0 用户，必须在 init.lua 或配置文件中添加以下设置，否则自动补全将无法工作：

vim.opt.completeopt:append({ "noinsert", "noselect" })
-- 为了获得最佳体验，即使在新版本中也建议添加 "popup"
vim.opt.completeopt:append({ "popup" })

可选依赖（推荐安装）

• tiktoken_core: 用于精确的 Token 计数（避免超出上下文限制）。
  • Arch Linux: yay -S luajit-tiktoken-bin
  • 通用 (luarocks): sudo luarocks install --lua-version 5.1 tiktoken_core
• git: 用于获取 git diff 上下文。
• ripgrep: 提升代码搜索性能。

选择器集成 (Optional)

若使用 telescope, fzf-lua 等选择器插件，需替换默认的 vim.ui.select 以获得更好的交互体验。例如使用 telescope：

require('telescope').setup{
  extensions = {
    ['ui-select'] = {
      require('telescope.themes').get_dropdown{},
    },
  },
}
require('telescope').load_extension('ui-select')

安装步骤

方式一：使用 lazy.nvim (推荐)

return {
  {
    "CopilotC-Nvim/CopilotChat.nvim",
    dependencies = {
      { "nvim-lua/plenary.nvim", branch = "master" },
    },
    build = "make tiktoken", -- 仅当安装了 tiktoken_core 依赖时需要
    opts = {
      -- 在此处填写配置，见下文“基本使用”
    },
  },
}

方式二：使用 vim-plug

在 init.vim 或 init.lua 中：

call plug#begin()
Plug 'nvim-lua/plenary.nvim'
Plug 'CopilotC-Nvim/CopilotChat.nvim'
call plug#end()

lua << EOF
require("CopilotChat").setup()
EOF

注意: 如果您同时安装了 copilot.vim 且遇到 <Tab> 键冲突，请添加以下配置禁用其默认映射：

vim.g.copilot_no_tab_map = true

基本使用

1. 最小化配置

在您的插件配置 opts 中加入以下基础设置即可启动：

{
  model = 'gpt-4o',              -- 使用的模型 (取决于您的 GitHub 订阅)
  temperature = 0.1,             -- 创造性程度 (0.1 专注，1.0 发散)
  window = {
    layout = 'vertical',         -- 布局：'vertical', 'horizontal', 'float'
    width = 0.5,                 -- 窗口宽度比例
  },
  auto_insert_mode = true,       -- 打开聊天窗口时自动进入插入模式
}

2. 启动聊天

在 Neovim 命令行模式下输入以下命令打开聊天窗口：

:CopilotChat

或者带初始问题打开：

:CopilotChat 解释这段代码的功能

3. 核心交互语法

在聊天输入框中，可以使用以下特殊语法增强上下文：

语法	说明	示例
#资源	手动添加上下文内容	#file:src/main.lua (添加文件) #selection (添加选区) #gitdiff:staged (添加暂存差异)
@工具	允许 AI 调用函数 (需确认)	@copilot 项目中有哪些 lua 文件？ (AI 会请求调用 glob 工具)
> 文本	粘性提示 (持久上下文)	> 你是一个资深 Rust 工程师 (后续对话均以此为背景)
/提示词	使用预设模板	/Review (代码审查) /Fix (修复错误) /Tests (生成测试)

4. 常用快捷键

在聊天窗口中（Normal 模式）：

按键	功能
<CR> (回车)	提交当前输入
q	关闭聊天窗口
<C-l>	重置/清空聊天记录
<C-y>	接受最近的代码差异 (Diff)
gj	跳转到最近的代码差异位置
gqa	将所有回答添加到快速修复列表 (Quickfix)
gh	显示帮助信息

在输入时（Insert 模式）：

• <Tab>: 触发/接受 Token 自动补全。
• <C-s>: 提交输入。
• <C-c>: 关闭窗口。

5. 预设提示词示例

直接运行命令调用预设功能：

:CopilotChatReview      " 对当前选区进行代码审查
:CopilotChatFix         " 修复选区中的错误
:CopilotChatDocs        " 为选区代码生成文档注释
:CopilotChatCommit      " 根据暂存区变更生成 Commit 信息