Gp.nvim (GPT prompt) Neovim AI 插件

类 ChatGPT 的会话、可指导的文本/代码操作、语音转文本以及在您最喜欢的编辑器中生成图像。

YouTube 演示视频

• 5 分钟演示（2023 年 12 月）
• 较早的 5 分钟演示（屏幕录像，无声音）

目标与特性

目标是以一种简单、不突兀且可扩展的方式，将 GPT 模型的强大功能扩展到 Neovim 中。
同时尽可能保持原生性——复用并良好地集成 (Neo)vim 的自然特性。

• 流式响应
  • 无需旋转的加载动画和等待完整答案
  • 可以在响应生成过程中途取消
  • 完美支持撤销（只需按一下 u 键即可撤销响应）
• 无限可扩展性，通过配置中指定的钩子函数实现
  • 钩子函数可以访问插件中的所有内容，并自动注册为命令
  • 详情请参见 5. 配置 和 扩展功能 部分
• 最少依赖项（neovim、curl、grep，可选 sox）
  • 不依赖其他 Lua 插件，以最大限度减少出错的可能性
• 类 ChatGPT 的会话
  • 使用格式化为 Markdown 的传统 Neovim 缓冲区，具备自动保存功能和少量缓冲区绑定的快捷键
  • 最近的聊天记录可通过可切换的弹出窗口快速访问
  • 聊天查找器——一个用于搜索、预览、删除和打开聊天会话的管理弹出窗口
• 可指导的文本/代码操作
  • 提供模板机制，可将用户指令、选区等内容组合成 GPT 查询
  • 多模态支持——同一命令适用于普通模式和插入模式，无论是带选区还是范围均可使用
  • 输出目标多样——重写、前置、追加、新建缓冲区、弹出窗口等
  • 提供非交互式命令模式，适用于可由简单钩子实现的常见重复性任务
    （例如，在弹出窗口中解释某事、将选中的代码单元测试写入新缓冲区、根据注释完成选中代码等）
  • 支持按仓库自定义指令，通过 .gp.md 文件实现
    （指示 GPT 使用特定库、包、规范等来生成代码）
• 语音转文本支持
  • 说话的速度通常是打字的 2 到 4 倍——在合适的情况下充分利用这一优势
    （口述注释和笔记、向 GPT 提问、给出代码操作指令等）
• 图像生成
  • 无需再打开浏览器，直接在 Neovim 中就能生成图像，进一步提升效率

安装

1. 安装插件

您常用包管理器的代码片段：

-- lazy.nvim
{
    "robitx/gp.nvim",
    config = function()
        local conf = {
            -- 如需自定义，请参考文档/README 中的“安装 > 配置”部分
        }
        require("gp").setup(conf)

        -- 在此处设置快捷键（参见文档/README 中的“使用 > 快捷键”部分）
    end,
}

-- packer.nvim
use({
    "robitx/gp.nvim",
    config = function()
        local conf = {
            -- 如需自定义，请参考文档/README 中的“安装 > 配置”部分
        }
        require("gp").setup(conf)

        -- 在此处设置快捷键（参见文档/README 中的“使用 > 快捷键”部分）
    end,
})

-- vim-plug
Plug 'robitx/gp.nvim'

local conf = {
    -- 如需自定义，请参考文档/README 中的“安装 > 配置”部分
}
require("gp").setup(conf)

-- 在此处设置快捷键（参见文档/README 中的“使用 > 快捷键”部分）

2. OpenAI API 密钥

请确保您已拥有 OpenAI API 密钥。在此处获取，并在 5. 配置 中使用它。同时建议设置 使用限制，以免月底收到意外账单。

OpenAI API 密钥可以通过多种方式传递给插件：

方法	示例	安全级别
硬编码字符串	openai_api_key: "sk-...",	低
默认环境变量	在 shell 配置中设置 OPENAI_API_KEY 环境变量	中等
自定义环境变量	openai_api_key = os.getenv("CUSTOM_ENV_NAME"),	中等
从文件读取	openai_api_key = { "cat", "path_to_api_key" },	中高
密码管理器	openai_api_key = { "bw", "get", "password", "OAI_API_KEY" },	高

如果 openai_api_key 是一个表，Gp 会异步执行它，以避免阻塞 Neovim（密码管理器可能需要一两秒钟）。

3. 多个提供商

除了 OpenAI 之外，目前还支持以下 LLM 提供商：

• Ollama，用于本地/离线的开源模型。该插件假设您已启动并运行 Ollama 服务，并配置了可用的模型（默认的 Ollama 代理使用 Llama3）。
• GitHub Copilot，需要 Copilot 许可证（可通过 zbirenbaum/copilot.lua 或 github/copilot.vim 实现自动补全）。您可以无需额外付费即可访问底层的 GPT-4 模型（相当于无限制地使用 GPT-4）。
• Perplexity.ai，Pro 用户每月可获得价值 5 美元的免费 API 信用额度（默认的 PPLX 代理使用 Mixtral-8x7b）。
• Anthropic，用于访问 Claude 模型，这些模型在某些基准测试中目前表现优于 GPT-4。
• Google Gemini，提供相当慷慨的免费使用范围，但存在一些地理限制（例如欧盟地区）。
• 任何其他兼容“OpenAI chat/completions”接口的端点（如 Azure、LM Studio 等）。

以下是启用其中部分提供商的相关配置示例。secret 字段的功能与 openai_api_key 相同（为保持兼容性，openai_api_key 仍被支持）。

	providers = {
		openai = {
			endpoint = "https://api.openai.com/v1/chat/completions",
			secret = os.getenv("OPENAI_API_KEY"),
		},

		-- azure = {...},

		copilot = {
			endpoint = "https://api.githubcopilot.com/chat/completions",
			secret = {
				"bash",
				"-c",
				"cat ~/.config/github-copilot/apps.json | sed -e 's/.*oauth_token...//;s/\".*//'",
			},
		},

		pplx = {
			endpoint = "https://api.perplexity.ai/chat/completions",
			secret = os.getenv("PPLX_API_KEY"),
		},

		ollama = {
			endpoint = "http://localhost:11434/v1/chat/completions",
		},

		googleai = {
			endpoint = "https://generativelanguage.googleapis.com/v1beta/models/{{model}}:streamGenerateContent?key={{secret}}",
			secret = os.getenv("GOOGLEAI_API_KEY"),
		},

		anthropic = {
			endpoint = "https://api.anthropic.com/v1/messages",
			secret = os.getenv("ANTHROPIC_API_KEY"),
		},
	},

每个提供商都预配置了一些代理。以下是一个禁用预定义的 ChatGPT3-5 代理并创建自定义代理的示例。如果缺少 provider 字段，则出于向后兼容性考虑，默认会使用 OpenAI。

	agents = {
		{
			name = "ChatGPT3-5",
			disable = true,
		},
		{
			name = "MyCustomAgent",
			provider = "copilot",
			chat = true,
			command = true,
			model = { model = "gpt-4-turbo" },
			system_prompt = "Answer any query with just: Sure thing..",
		},
	},

4. 依赖项

核心插件仅需安装 curl 来调用 OpenAI API，以及 grep 用于 ChatFinder 功能。因此，Linux、BSD 和 Mac OS 均可支持。

语音命令（:GpWhisper*）依赖于 SoX（Sound eXchange）来处理音频录制和处理：

• Mac OS：brew install sox
• Ubuntu/Debian：apt-get install sox libsox-fmt-mp3
• Arch Linux：pacman -S sox
• Redhat/CentOS：yum install sox
• NixOS：nix-env -i sox

5. 配置

以下是包含默认值的代码片段链接，但我建议从尽可能简单的配置开始（如果您尚未设置 OPENAI_API_KEY 环境变量，则只需配置 openai_api_key 即可）。默认值会随时间变化以改进功能，某些选项可能会被弃用等；因此，最好只修改那些默认设置无法满足您需求的部分。

https://github.com/Robitx/gp.nvim/blob/b910a540f16875af77b27e49288021368cc674cf/lua/gp/config.lua#L10-L650

使用方法

聊天命令

:GpChatNew

在当前窗口中打开一个新的聊天窗口。它可以是空的，也可以包含可视选区或指定范围作为上下文。此命令还支持布局指定子命令：

• :GpChatNew vsplit 在垂直分屏窗口中打开一个新的聊天窗口。
• :GpChatNew split 在水平分屏窗口中打开一个新的聊天窗口。
• :GpChatNew tabnew 在新标签页中打开一个新的聊天窗口。
• :GpChatNew popup 在弹出窗口中打开一个新的聊天窗口。

:GpChatPaste

将选区或指定范围的内容粘贴到最近的聊天窗口中，从而简化将多个文件中的代码合并到单个聊天缓冲区的操作。此命令也支持布局指定子命令：

• :GpChatPaste vsplit 将内容粘贴到垂直分屏窗口中的最新聊天中。
• :GpChatPaste split 将内容粘贴到水平分屏窗口中的最新聊天中。
• :GpChatPaste tabnew 将内容粘贴到新标签页中的最新聊天中。
• :GpChatPaste popup 将内容粘贴到弹出窗口中的最新聊天中。

:GpChatToggle

以可切换的弹出窗口形式打开聊天，显示上次活跃的聊天，或者以选区或指定范围作为上下文打开一个新的聊天窗口。此命令也支持布局指定子命令：

• :GpChatToggle vsplit 在垂直分屏窗口中切换聊天。
• :GpChatToggle split 在水平分屏窗口中切换聊天。
• :GpChatToggle tabnew 在新标签页中切换聊天。
• :GpChatToggle popup 在弹出窗口中切换聊天。

:GpChatFinder

打开一个对话框，用于搜索聊天记录。

:GpChatRespond

为当前聊天请求新的 GPT 回答。使用 :GpChatRespond N 可以仅以最近 N 条消息作为上下文请求新的 GPT 回答，即从最后一条消息开始，直到第 N 次出现的 🗨:.. 为止（N=1 相当于在新聊天中提问）。

:GpChatDelete

删除当前聊天。默认情况下，删除前需要确认，但您可以在配置中通过设置 chat_confirm_delete = false 来禁用此确认提示。

文本/代码命令

:GpRewrite

打开一个用于输入提示的对话框。在对话框中提供提示指令后，生成的回复会替换普通模式或插入模式下的当前行、可视模式下的选中行，或者指定的范围（例如，:GpRewrite % 会将重写应用到整个缓冲区）。

:GpRewrite {prompt} 直接使用指定的 {prompt} 指令执行，跳过对话框。适用于将重复性任务映射到键盘快捷键，或通过终端或 Shell 脚本以无头模式运行 Neovim 进行自动化。

:GpAppend

与 :GpRewrite 类似，但答案会被添加到当前行、可视选区或范围之后。

:GpPrepend

与 :GpRewrite 类似，但答案会被添加到当前行、可视选区或范围之前。

:GpEnew

与 :GpRewrite 类似，但答案会被添加到当前窗口中的新缓冲区中。

:GpNew

与 :GpRewrite 类似，但答案会被添加到一个新的水平分割窗口中。

:GpVnew

与 :GpRewrite 类似，但答案会被添加到一个新的垂直分割窗口中。

:GpTabnew

与 :GpRewrite 类似，但答案会被添加到一个新的标签页中。

:GpPopup

与 :GpRewrite 类似，但答案会被添加到一个弹出窗口中。

:GpImplement

示例钩子命令，用于根据可视选区或指定范围内的注释来开发代码。

:GpContext

为每个仓库提供自定义上下文：

• 在可切换的窗口中打开给定仓库的 .gp.md 文件。

• 在可视模式或范围模式下使用时，会将选区或范围追加到上下文文件中。

• 还支持布局指定的子命令：

  • :GpContext vsplit 在垂直分割窗口中打开 .gp.md。
  • :GpContext split 在水平分割窗口中打开 .gp.md。
  • :GpContext tabnew 在新标签页中打开 .gp.md。
  • :GpContext popup 在弹出窗口中打开 .gp.md。

• 更多详情请参阅自定义指令。

语音命令

:GpWhisper {lang?}

转录内容会替换当前缓冲区中的当前行、可视选区或范围。你可以用口述的方式在聊天缓冲区中提问，而不是手动输入；也可以口述一些代码注释、笔记，甚至是你的下一部小说……

对于其余的 Whisper 命令，转录内容会被用作等效非 Whisper 命令的可编辑提示——例如，GpWhisperRewrite 口述的指令会用于 GpRewrite 等命令。

你可以通过设置 {lang} 参数来覆盖默认语言，该参数应为你的语言的两位字母简称（例如，“en”代表英语，“fr”代表法语等）。

:GpWhisperRewrite

与 :GpRewrite 类似，但提示指令对话框会使用转录后的语音指令。

:GpWhisperAppend

与 :GpAppend 类似，但提示指令对话框会使用转录后的语音指令来在当前行、可视选区或范围之后添加内容。

:GpWhisperPrepend

与 :GpPrepend 类似，但提示指令对话框会使用转录后的语音指令来在当前行、选区或范围之前添加内容。

:GpWhisperEnew

与 :GpEnew 类似，但提示指令对话框会使用转录后的语音指令来在当前窗口中打开新的缓冲区。

:GpWhisperNew

与 :GpNew 类似，但提示指令对话框会使用转录后的语音指令来在新的水平分割窗口中打开内容。

:GpWhisperVnew

与 :GpVnew 类似，但提示指令对话框会使用转录后的语音指令来在新的垂直分割窗口中打开内容。

:GpWhisperTabnew

与 :GpTabnew 类似，但提示指令对话框会使用转录后的语音指令来在新标签页中打开内容。

:GpWhisperPopup

与 :GpPopup 类似，但提示指令对话框会使用转录后的语音指令来在弹出窗口中显示内容。

代理命令

:GpNextAgent

根据当前缓冲区在可用代理之间循环切换：如果当前缓冲区是聊天缓冲区，则使用聊天代理；否则使用命令代理。代理设置会在磁盘上持久化，跨 Neovim 实例生效。

:GpAgent

显示当前用于聊天和命令指令的代理。

:GpAgent XY

根据代理名称选择新的代理，选项列表基于当前缓冲区（如果当前缓冲区是聊天缓冲区，则显示聊天代理；否则显示命令代理）。代理设置会在磁盘上持久化，跨 Neovim 实例生效。

:GpSelectAgent

使用 vim.ui.select 打开选择界面，从所有可用代理中进行选择，允许你直接从列表中选择所需的代理。如果安装了 Telescope 插件，可以无缝配合使用。

图像命令

:GpImage

打开一个对话框，用于输入描述所需图像的提示。生成完成后，会打开一个对话框，用于将图像保存到磁盘。

:GpImageAgent

显示当前使用的图像代理（配置）。

:GpImageAgent XY

根据名称选择新的“图像代理”。在图像的上下文中，代理基本上是指模型、图像尺寸、质量等方面的配置。代理设置会在磁盘上持久化，跨 Neovim 实例生效。

其他命令

:GpStop

停止所有当前正在运行的响应和作业。

:GpInspectPlugin

在新的临时缓冲区中检查 GPT 提示插件对象。

GpDone 自动命令

像 GpRewrite、GpAppend 等命令都是异步执行的，并会生成 GpDone 事件，因此你可以定义自动命令（比如自动格式化），在 GP 完成时运行：

    vim.api.nvim_create_autocmd({ "User" }, {
        pattern = {"GpDone"},
        callback = function(event)
            print("event fired:\n", vim.inspect(event))
            -- local b = event.buf
            -- DO something
        end,
    })

自定义指令

通过调用 :GpContext，你可以在仓库的根目录下创建一个 .gp.md Markdown 文件。诸如 :GpRewrite、:GpAppend 等命令会尊重该文件中提供的指令（使用 gpt4 时效果更好，而 gpt 3.5 并不总是会听从系统指令）。例如：

使用 C++17。
编写 Go 测试时使用 Testify 库。
采用提前返回/卫语句模式以避免过度嵌套。
...

这里有一个示例。

脚本化

结合 GpDone 事件和 .gp.md 自定义指令，你可以通过终端或 Shell 脚本以无头（neo）Vim 的方式运行 gp.nvim。因此，如果你将其放入循环中，就可以让 gp 在多个文件中执行编辑操作。

test 文件内容如下：

1
2
3
4
5

.gp.md 文件内容如下：

如果用户说“你好”，请回复：

```
嗨，朋友！
```

从终端/脚本调用 gp.nvim：

• 注册自动命令，在 Gp 完成时保存并退出 nvim；
• 第二步跳转到我想要重写/追加/前置的内容出现的位置（本例中为数字 3）；
• 选中该行；
• 调用 gp.nvim 动作。

$ nvim --headless -c "autocmd User GpDone wq" -c "/3" -c "normal V" -c "GpAppend hello there"  test

最终生成的 test 文件内容如下：

1
2
3
嗨，朋友！
4
5

快捷键

默认情况下没有全局快捷键，以便不影响你的自定义配置。以下是一些供你调整或直接使用的示例。

原生快捷键

你可以使用传统的 vim.keymap.set，并在 require("gp").setup(conf) 调用之后（或者如果你想将所有快捷键集中管理，也可以放在其他位置）粘贴以下代码：

local function keymapOptions(desc)
    return {
        noremap = true,
        silent = true,
        nowait = true,
        desc = "GPT 提示 " .. desc,
    }
end

-- 对话命令
vim.keymap.set({"n", "i"}, "<C-g>c", "<cmd>GpChatNew<cr>", keymapOptions("新建对话"))
vim.keymap.set({"n", "i"}, "<C-g>t", "<cmd>GpChatToggle<cr>", keymapOptions("切换对话"))
vim.keymap.set({"n", "i"}, "<C-g>f", "<cmd>GpChatFinder<cr>", keymapOptions("对话查找"))

vim.keymap.set("v", "<C-g>c", ":<C-u>'<,'>GpChatNew<cr>", keymapOptions("视觉模式新建对话"))
vim.keymap.set("v", "<C-g>p", ":<C-u>'<,'>GpChatPaste<cr>", keymapOptions("视觉模式粘贴对话"))
vim.keymap.set("v", "<C-g>t", ":<C-u>'<,'>GpChatToggle<cr>", keymapOptions("视觉模式切换对话"))

vim.keymap.set({ "n", "i" }, "<C-g><C-x>", "<cmd>GpChatNew split<cr>", keymapOptions("新建分屏对话"))
vim.keymap.set({ "n", "i" }, "<C-g><C-v>", "<cmd>GpChatNew vsplit<cr>", keymapOptions("新建垂直分屏对话"))
vim.keymap.set({ "n", "i" }, "<C-g><C-t>", "<cmd>GpChatNew tabnew<cr>", keymapOptions("新建标签页对话"))

vim.keymap.set("v", "<C-g><C-x>", ":<C-u>'<,'>GpChatNew split<cr>", keymapOptions("视觉模式新建分屏对话"))
vim.keymap.set("v", "<C-g><C-v>", ":<C-u>'<,'>GpChatNew vsplit<cr>", keymapOptions("视觉模式新建垂直分屏对话"))
vim.keymap.set("v", "<C-g><C-t>", ":<C-u>'<,'>GpChatNew tabnew<cr>", keymapOptions("视觉模式新建标签页对话"))

-- 提示命令
vim.keymap.set({"n", "i"}, "<C-g>r", "<cmd>GpRewrite<cr>", keymapOptions("内联重写"))
vim.keymap.set({"n", "i"}, "<C-g>a", "<cmd>GpAppend<cr>", keymapOptions("追加（后）"))
vim.keymap.set({"n", "i"}, "<C-g>b", "<cmd>GpPrepend<cr>", keymapOptions("前置（前）"))

vim.keymap.set("v", "<C-g>r", ":<C-u>'<,'>GpRewrite<cr>", keymapOptions("视觉模式重写"))
vim.keymap.set("v", "<C-g>a", ":<C-u>'<,'>GpAppend<cr>", keymapOptions("视觉模式追加（后）"))
vim.keymap.set("v", "<C-g>b", ":<C-u>'<,'>GpPrepend<cr>", keymapOptions("视觉模式前置（前）"))
vim.keymap.set("v", "<C-g>i", ":<C-u>'<,'>GpImplement<cr>", keymapOptions("实现选区代码"))

vim.keymap.set({"n", "i"}, "<C-g>gp", "<cmd>GpPopup<cr>", keymapOptions("弹出窗口"))
vim.keymap.set({"n", "i"}, "<C-g>ge", "<cmd>GpEnew<cr>", keymapOptions("GpEnew"))
vim.keymap.set({"n", "i"}, "<C-g>gn", "<cmd>GpNew<cr>", keymapOptions("GpNew"))
vim.keymap.set({"n", "i"}, "<C-g>gv", "<cmd>GpVnew<cr>", keymapOptions("GpVnew"))
vim.keymap.set({"n", "i"}, "<C-g>gt", "<cmd>GpTabnew<cr>", keymapOptions("GpTabnew"))

vim.keymap.set("v", "<C-g>gp", ":<C-u>'<,'>GpPopup<cr>", keymapOptions("视觉模式弹出窗口"))
vim.keymap.set("v", "<C-g>ge", ":<C-u>'<,'>GpEnew<cr>", keymapOptions("视觉模式 GpEnew"))
vim.keymap.set("v", "<C-g>gn", ":<C-u>'<,'>GpNew<cr>", keymapOptions("视觉模式 GpNew"))
vim.keymap.set("v", "<C-g>gv", ":<C-u>'<,'>GpVnew<cr>", keymapOptions("视觉模式 GpVnew"))
vim.keymap.set("v", "<C-g>gt", ":<C-u>'<,'>GpTabnew<cr>", keymapOptions("视觉模式 GpTabnew"))

vim.keymap.set({"n", "i"}, "<C-g>x", "<cmd>GpContext<cr>", keymapOptions("切换上下文"))
vim.keymap.set("v", "<C-g>x", ":<C-u>'<,'>GpContext<cr>", keymapOptions("视觉模式切换上下文"))

vim.keymap.set({"n", "i", "v", "x"}, "<C-g>s", "<cmd>GpStop<cr>", keymapOptions("停止"))
vim.keymap.set({"n", "i", "v", "x"}, "<C-g>n", "<cmd>GpNextAgent<cr>", keymapOptions("下一个助手"))
vim.keymap.set({"n", "i", "v", "x"}, "<C-g>l", "<cmd>GpSelectAgent<cr>", keymapOptions("选择助手"))

-- 可选的 Whisper 命令，带有前缀 <C-g>w
vim.keymap.set({"n", "i"}, "<C-g>ww", "<cmd>GpWhisper<cr>", keymapOptions("低语"))
vim.keymap.set("v", "<C-g>ww", ":<C-u>'<,'>GpWhisper<cr>", keymapOptions("视觉模式低语"))

vim.keymap.set({"n", "i"}, "<C-g>wr", "<cmd>GpWhisperRewrite<cr>", keymapOptions("低语内联重写"))
vim.keymap.set({"n", "i"}, "<C-g>wa", "<cmd>GpWhisperAppend<cr>", keymapOptions("低语追加（后）"))
vim.keymap.set({"n", "i"}, "<C-g>wb", "<cmd>GpWhisperPrepend<cr>", keymapOptions("低语前置（前）"))

vim.keymap.set("v", "<C-g>wr", ":<C-u>'<,'>GpWhisperRewrite<cr>", keymapOptions("视觉模式低语重写"))
vim.keymap.set("v", "<C-g>wa", ":<C-u>'<,'>GpWhisperAppend<cr>", keymapOptions("视觉模式低语追加（后）"))
vim.keymap.set("v", "<C-g>wb", ":<C-u>'<,'>GpWhisperPrepend<cr>", keymapOptions("视觉模式低语前置（前）"))

vim.keymap.set({"n", "i"}, "<C-g>wp", "<cmd>GpWhisperPopup<cr>", keymapOptions("低语弹出窗口"))
vim.keymap.set({"n", "i"}, "<C-g>we", "<cmd>GpWhisperEnew<cr>", keymapOptions("低语 Enew"))
vim.keymap.set({"n", "i"}, "<C-g>wn", "<cmd>GpWhisperNew<cr>", keymapOptions("低语新"))
vim.keymap.set({"n", "i"}, "<C-g>wv", "<cmd>GpWhisperVnew<cr>", keymapOptions("低语 Vnew"))
vim.keymap.set({"n", "i"}, "<C-g>wt", "<cmd>GpWhisperTabnew<cr>", keymapOptions("低语 Tabnew"))。

vim.keymap.set("v", "<C-g>wp", ":<C-u>'<,'>GpWhisperPopup<cr>", keymapOptions("视觉模式低语弹出窗口"))
vim.keymap.set("v", "<C-g>we", ":<C-u>'<,'>GpWhisperEnew<cr>", keymapOptions("视觉模式低语 Enew"))
vim.keymap.set("v", "<C-g>wn", ":<C-u>'<,'>GpWhisperNew<cr>", keymapOptions("视觉模式低语新"))
vim.keymap.set("v", "<C-g>wv", ":<C-u>'<,'>GpWhisperVnew<cr>", keymapOptions("视觉模式低语 Vnew"))
vim.keymap.set("v", "<C-g>wt", ":<C-u>'<,'>GpWhisperTabnew<cr>", keymapOptions("视觉模式低语 Tabnew"))。

Whichkey

或者使用 which-key.nvim 插件来实现更炫酷的效果：

require("which-key").add({
    -- 可视模式映射
    -- s、x、v 模式由 which_key 统一处理
    {
        mode = { "v" },
        nowait = true,
        remap = false,
        { "<C-g><C-t>", ":<C-u>'<,'>GpChatNew tabnew<cr>", desc = "新建聊天标签页" },
        { "<C-g><C-v>", ":<C-u>'<,'>GpChatNew vsplit<cr>", desc = "新建聊天垂直分屏" },
        { "<C-g><C-x>", ":<C-u>'<,'>GpChatNew split<cr>", desc = "新建聊天水平分屏" },
        { "<C-g>a", ":<C-u>'<,'>GpAppend<cr>", desc = "可视模式追加（在选区后）" },
        { "<C-g>b", ":<C-u>'<,'>GpPrepend<cr>", desc = "可视模式插入（在选区前）" },
        { "<C-g>c", ":<C-u>'<,'>GpChatNew<cr>", desc = "可视模式新建聊天" },
        { "<C-g>g", group = "生成到新 .." },
        { "<C-g>ge", ":<C-u>'<,'>GpEnew<cr>", desc = "可视模式 GpEnew" },
        { "<C-g>gn", ":<C-u>'<,'>GpNew<cr>", desc = "可视模式 GpNew" },
        { "<C-g>gp", ":<C-u>'<,'>GpPopup<cr>", desc = "可视模式弹出窗口" },
        { "<C-g>gt", ":<C-u>'<,'>GpTabnew<cr>", desc = "可视模式 GpTabnew" },
        { "<C-g>gv", ":<C-u>'<,'>GpVnew<cr>", desc = "可视模式 GpVnew" },
        { "<C-g>i", ":<C-u>'<,'>GpImplement<cr>", desc = "实现选中文本" },
        { "<C-g>n", "<cmd>GpNextAgent<cr>", desc = "下一个助手" },
        { "<C-g>l", "<cmd>GpSelectAgent<cr>", desc = "选择助手" },
        { "<C-g>p", ":<C-u>'<,'>GpChatPaste<cr>", desc = "可视模式粘贴到聊天" },
        { "<C-g>r", ":<C-u>'<,'>GpRewrite<cr>", desc = "可视模式重写" },
        { "<C-g>s", "<cmd>GpStop<cr>", desc = "停止助手" },
        { "<C-g>t", ":<C-u>'<,'>GpChatToggle<cr>", desc = "切换聊天模式" },
        { "<C-g>w", group = "Whisper" },
        { "<C-g>wa", ":<C-u>'<,'>GpWhisperAppend<cr>", desc = "Whisper 追加文本" },
        { "<C-g>wb", ":<C-u>'<,'>GpWhisperPrepend<cr>", desc = "Whisper 插入文本" },
        { "<C-g>we", ":<C-u>'<,'>GpWhisperEnew<cr>", desc = "Whisper 新建文件" },
        { "<C-g>wn", ":<C-u>'<,'>GpWhisperNew<cr>", desc = "Whisper 新建文件" },
        { "<C-g>wp", ":<C-u>'<,'>GpWhisperPopup<cr>", desc = "Whisper 弹出窗口" },
        { "<C-g>wr", ":<C-u>'<,'>GpWhisperRewrite<cr>", desc = "Whisper 内联重写" },
        { "<C-g>wt", ":<C-u>'<,'>GpWhisperTabnew<cr>", desc = "Whisper 新建标签页" },
        { "<C-g>wv", ":<C-u>'<,'>GpWhisperVnew<cr>", desc = "Whisper 新建垂直分屏" },
        { "<C-g>ww", ":<C-u>'<,'>GpWhisper<cr>", desc = "Whisper" },
        { "<C-g>x", ":<C-u>'<,'>GpContext<cr>", desc = "切换 GpContext" },
    },

    -- 普通模式映射
    {
        mode = { "n" },
        nowait = true,
        remap = false,
        { "<C-g><C-t>", "<cmd>GpChatNew tabnew<cr>", desc = "新建聊天标签页" },
        { "<C-g><C-v>", "<cmd>GpChatNew vsplit<cr>", desc = "新建聊天垂直分屏" },
        { "<C-g><C-x>", "<cmd>GpChatNew split<cr>", desc = "新建聊天水平分屏" },
        { "<C-g>a", "<cmd>GpAppend<cr>", desc = "追加文本（在光标后）" },
        { "<C-g>b", "<cmd>GpPrepend<cr>", desc = "插入文本（在光标前）" },
        { "<C-g>c", "<cmd>GpChatNew<cr>", desc = "新建聊天" },
        { "<C-g>f", "<cmd>GpChatFinder<cr>", desc = "聊天查找器" },
        { "<C-g>g", group = "生成到新 .." },
        { "<C-g>ge", "<cmd>GpEnew<cr>", desc = "GpEnew" },
        { "<C-g>gn", "<cmd>GpNew<cr>", desc = "GpNew" },
        { "<C-g>gp", "<cmd>GpPopup<cr>", desc = "弹出窗口" },
        { "<C-g>gt", "<cmd>GpTabnew<cr>", desc = "GpTabnew" },
        { "<C-g>gv", "<cmd>GpVnew<cr>", desc = "GpVnew" },
        { "<C-g>n", "<cmd>GpNextAgent<cr>", desc = "下一个助手" },
        { "<C-g>l", "<cmd>GpSelectAgent<cr>", desc = "选择助手" },
        { "<C-g>r", "<cmd>GpRewrite<cr>", desc = "内联重写" },
        { "<C-g>s", "<cmd>GpStop<cr>", desc = "停止助手" },
        { "<C-g>t", "<cmd>GpChatToggle<cr>", desc = "切换聊天模式" },
        { "<C-g>w", group = "Whisper" },
        { "<C-g>wa", "<cmd>GpWhisperAppend<cr>", desc = "Whisper 追加文本（在光标后）" },
        { "<C-g>wb", "<cmd>GpWhisperPrepend<cr>", desc = "Whisper 插入文本（在光标前）" },
        { "<C-g>we", "<cmd>GpWhisperEnew<cr>", desc = "Whisper 新建文件" },
        { "<C-g>wn", "<cmd>GpWhisperNew<cr>", desc = "Whisper 新建文件" },
        { "<C-g>wp", "<cmd>GpWhisperPopup<cr>", desc = "Whisper 弹出窗口" },
        { "<C-g>wr", "<cmd>GpWhisperRewrite<cr>", desc = "Whisper 内联重写" },
        { "<C-g>wt", "<cmd>GpWhisperTabnew<cr>", desc = "Whisper 新建标签页" },
        { "<C-g>wv", "<cmd>GpWhisperVnew<cr>", desc = "Whisper 新建垂直分屏" },
        { "<C-g>ww", "<cmd>GpWhisper<cr>", desc = "Whisper" },
        { "<C-g>x", "<cmd>GpContext<cr>", desc = "切换 GpContext" },
    },

    -- 插入模式映射
    {
        mode = { "i" },
        nowait = true,
        remap = false,
        { "<C-g><C-t>", "<cmd>GpChatNew tabnew<cr>", desc = "新建聊天标签页" },
        { "<C-g><C-v>", "<cmd>GpChatNew vsplit<cr>", desc = "新建聊天垂直分屏" },
        { "<C-g><C-x>", "<cmd>GpChatNew split<cr>", desc = "新建聊天水平分屏" },
        { "<C-g>a", "<cmd>GpAppend<cr>", desc = "追加文本（在光标后）" },
        { "<C-g>b", "<cmd>GpPrepend<cr>", desc = "插入文本（在光标前）" },
        { "<C-g>c", "<cmd>GpChatNew<cr>", desc = "新建聊天" },
        { "<C-g>f", "<cmd>GpChatFinder<cr>", desc = "聊天查找器" },
        { "<C-g>g", group = "生成到新 .." },
        { "<C-g>ge", "<cmd>GpEnew<cr>", desc = "GpEnew" },
        { "<C-g>gn", "<cmd>GpNew<cr>", desc = "GpNew" },
        { "<C-g>gp", "<cmd>GpPopup<cr>", desc = "弹出窗口" },
        { "<C-g>gt", "<cmd>GpTabnew<cr>", desc = "GpTabnew" },
        { "<C-g>gv", "<cmd>GpVnew<cr>", desc = "GpVnew" },
        { "<C-g>n", "<cmd>GpNextAgent<cr>", desc = "下一个助手" },
        { "<C-g>l", "<cmd>GpSelectAgent<cr>", desc = "选择助手" },
        { "<C-g>r", "<cmd>GpRewrite<cr>", desc = "内联重写" },
        { "<C-g>s", "<cmd>GpStop<cr>", desc = "停止助手" },
        { "<C-g>t", "<cmd>GpChatToggle<cr>", desc = "切换聊天模式" },
        { "<C-g>w", group = "Whisper" },
        { "<C-g>wa", "<cmd>GpWhisperAppend<cr>", desc = "Whisper 追加文本（在光标后）" },
        { "<C-g>wb", "<cmd>GpWhisperPrepend<cr>", desc = "Whisper 插入文本（在光标前）" },
        { "<C-g>we", "<cmd>GpWhisperEnew<cr>", desc = "Whisper 新建文件" },
        { "<C-g>wn", "<cmd>GpWhisperNew<cr>", desc = "Whisper 新建文件" },
        { "<C-g>wp", "<cmd>GpWhisperPopup<cr>", desc = "Whisper 弹出窗口" },
        { "<C-g>wr", "<cmd>GpWhisperRewrite<cr>", desc = "Whisper 内联重写" },
        { "<C-g>wt", "<cmd>GpWhisperTabnew<cr>", desc = "Whisper 新建标签页" },
        { "<C-g>wv", "<cmd>GpWhisperVnew<cr>", desc = "Whisper 新建垂直分屏" },
        { "<C-g>ww", "<cmd>GpWhisper<cr>", desc = "Whisper" },
        { "<C-g>x", "<cmd>GpContext<cr>", desc = "切换 GpContext" },
    },
})

扩展功能

你可以通过将函数放入 config.hooks 中，用自己的功能扩展或覆盖插件的功能。钩子可以访问所有内容（参见默认设置中的 InspectPlugin 示例），并且会自动注册为命令（如 GpInspectPlugin）。

以下是一些更多示例：

• :GpUnitTests

  -- 添加一个为选中文本编写单元测试的命令示例
  UnitTests = function(gp, params)
      local template = "我有来自 {{filename}} 的以下代码：\n\n"
          .. "```{{filetype}}\n{{selection}}\n```\n\n"
          .. "请回复，为上述代码编写基于表格驱动的单元测试。"
      local agent = gp.get_command_agent()
      gp.Prompt(params, gp.Target.vnew, agent, template)
  end,
  

• :GpExplain

  -- 添加一个解释选中文本的命令示例
  Explain = function(gp, params)
      local template = "我有来自 {{filename}} 的以下代码：\n\n"
          .. "```{{filetype}}\n{{selection}}\n```\n\n"
          .. "请回复，解释上述代码。"
      local agent = gp.get_chat_agent()
      gp.Prompt(params, gp.Target.popup, agent, template)
  end,
  

• :GpCodeReview

  -- 使用 enew 作为指定新缓冲区类型的函数示例
  CodeReview = function(gp, params)
      local template = "我有来自 {{filename}} 的以下代码：\n\n"
          .. "```{{filetype}}\n{{selection}}\n```\n\n"
          .. "请分析其中的代码异味并提出改进建议。"
      local agent = gp.get_chat_agent()
      gp.Prompt(params, gp.Target.enew("markdown"), agent, template)
  end,
  

• :GpTranslator

  -- 添加一个专门用于翻译的新聊天窗口的命令示例
  Translator = function(gp, params)
      local chat_system_prompt = "你是一名翻译员，请在英语和中文之间进行翻译。"
      gp.cmd.ChatNew(params, chat_system_prompt)
  
      -- 也可以这样创建一个使用特定固定代理的聊天：
      -- local agent = gp.get_chat_agent("ChatGPT4o")
      -- gp.cmd.ChatNew(params, chat_system_prompt, agent)
  end,
  

• :GpBufferChatNew

  -- 将 :%GpChatNew 制作成一个专用命令，该命令会以当前整个缓冲区作为上下文打开一个新的聊天窗口
  BufferChatNew = function(gp, _)
      -- 在全缓冲区范围内调用 GpChatNew 命令
      vim.api.nvim_command("%" .. gp.config.cmd_prefix .. "ChatNew")
  end,
  

原始插件文本编辑方法 Prompt 的签名如下：

---@param params table  # vim 命令参数，例如范围、参数等。
---@param target integer | function | table  # 回应将被放置的位置
---@param agent table  # 从 get_command_agent 或 get_chat_agent 获取
---@param template string  # 包含模型指令的模板
---@param prompt string | nil  # 对于非交互式命令，值为 nil
---@param whisper string | nil  # 预定义输入（例如从 Whisper 获取）
---@param callback function | nil  # 完成提示后执行的回调函数 (response)
Prompt(params, target, agent, template, prompt, whisper, callback)

• params 是一个 传递给 Neovim 用户命令的表，Prompt 目前使用：

  • range, line1, line2 来处理 范围
  • args 以便可以在命令后直接传递指令（:GpRewrite something something）

  params = {
        args = "",
        bang = false,
        count = -1,
        fargs = {},
        line1 = 1352,
        line2 = 1352,
        mods = "",
        name = "GpChatNew",
        range = 0,
        reg = "",
        smods = {
              browse = false,
              confirm = false,
              emsg_silent = false,
              hide = false,
              horizontal = false,
              keepalt = false,
              keepjumps = false,
              keepmarks = false,
              keeppatterns = false,
              lockmarks = false,
              noautocmd = false,
              noswapfile = false,
              sandbox = false,
              silent = false,
              split = "",
              tab = -1,
              unsilent = false,
              verbose = -1,
              vertical = false
        }
  }
  

• target 指定 GPT 响应的输出位置

  • 可以使用 enew/new/vnew/tabnew 作为函数，并传入新缓冲区的文件类型（enew/enew()/enew("markdown")/..）

  M.Target = {
      rewrite = 0, -- 用于替换选区、范围或当前行
      append = 1, -- 用于在选区、范围或当前行之后追加
      prepend = 2, -- 用于在选区、范围或当前行之前插入
      popup = 3, -- 用于写入弹出窗口
  
      -- 用于写入新缓冲区
      ---@param filetype nil | string # nil = 与原缓冲区相同
      ---@return table # 一个 type=4 且 filetype=filetype 的表
      enew = function(filetype)
          return { type = 4, filetype = filetype }
      end,
  
      --- 用于创建新的水平分割
      ---@param filetype nil | string # nil = 与原缓冲区相同
      ---@return table # 一个 type=5 且 filetype=filetype 的表
      new = function(filetype)
          return { type = 5, filetype = filetype }
      end,
  
      --- 用于创建新的垂直分割
      ---@param filetype nil | string # nil = 与原缓冲区相同
      ---@return table # 一个 type=6 且 filetype=filetype 的表
      vnew = function(filetype)
          return { type = 6, filetype = filetype }
      end,
  
      --- 用于创建新标签页
      ---@param filetype nil | string # nil = 与原缓冲区相同
      ---@return table # 一个 type=7 且 filetype=filetype 的表
      tabnew = function(filetype)
          return { type = 7, filetype = filetype }
      end,
  }
  

• agent 表可以通过 get_command_agent 和 get_chat_agent 方法获取，其签名如下：

  ---@param name string | nil
  ---@return table # { cmd_prefix, name, model, system_prompt, provider }
  get_command_agent(name)
  

• template

  • 发送给 GPT 的用户消息模板

  • 字符串中可以包含以下变量：

    名称	描述
    {{filetype}}	当前缓冲区的文件类型
    {{selection}}	最后一次或当前选中的文本
    {{command}}	用户提供的指令

• prompt

  • 一个字符串，用法类似于终端中的 bash/zsh 提示符，当插件需要用户输入命令传递给 GPT 时使用。
  • 如果为 nil，则不会提示用户输入（适用于一些预定义的特定命令，如文档说明、解释、编写测试等）。
  • 可以使用简单的 🤖 ~，也可以采用不同的提示信息来传达当前调用的方法类型，例如 🤖 rewrite ~、🤖 popup ~、🤖 enew ~、🤖 inline ~ 等。

• whisper

  • 可选的字符串，默认作为输入提示（例如由 Whisper 模型从语音中生成的内容）。

• callback

  • 可选的回调函数，用于对提示响应进行后处理逻辑。 （例如让模型生成提交信息，然后通过回调函数实际执行提交操作。）

gp.nvim 快速上手指南

gp.nvim 是一个强大的 Neovim AI 插件，支持类似 ChatGPT 的对话会话、可指令化的文本/代码操作、语音转文字以及图像生成功能。它旨在以简单、无侵入且可扩展的方式将 GPT 模型的能力集成到编辑器中。

环境准备

系统要求

• Neovim: 建议最新版本
• 操作系统: Linux, macOS, BSD (Windows 需通过 WSL 或类似环境)

前置依赖

核心功能仅需以下工具（通常系统已预装）：

• curl: 用于调用 API
• grep: 用于聊天历史搜索

可选依赖（如需使用语音命令 :GpWhisper*）： 需要安装 SoX (Sound eXchange) 来处理录音：

• macOS: brew install sox
• Ubuntu/Debian: apt-get install sox libsox-fmt-mp3
• Arch Linux: pacman -S sox
• CentOS/RHEL: yum install sox

安装步骤

1. 获取 API Key

在使用前，请确保你拥有有效的 API Key。

• OpenAI: 点击获取
• 其他提供商: 如 Ollama (本地), GitHub Copilot, Perplexity, Anthropic, Google Gemini 等也受支持。

安全提示: 建议将 Key 设置为环境变量 OPENAI_API_KEY，或使用密码管理器读取，避免硬编码在配置文件中。

2. 插件安装

使用你喜欢的包管理器安装。以下是 lazy.nvim 的配置示例：

{
    "robitx/gp.nvim",
    config = function()
        local conf = {
            -- 如果未设置环境变量 OPENAI_API_KEY，可在此处手动指定
            -- openai_api_key = "sk-...", 
            -- 或者配置其他提供商 (Ollama, Copilot 等)
        }
        require("gp").setup(conf)

        -- 在此处设置快捷键 (参考下文基本使用)
    end,
}

如果你使用 Ollama 等本地模型，需在配置中添加 provider 信息：

providers = {
    ollama = {
        endpoint = "http://localhost:11434/v1/chat/completions",
        -- 本地模型通常不需要 secret
    },
},
agents = {
    {
        name = "LocalLlama",
        provider = "ollama",
        chat = true,
        command = true,
        model = { model = "llama3" }, -- 确保本地已拉取该模型
    },
},

基本使用

安装完成后，重启 Neovim 即可使用。以下是核心功能的最简用法：

1. 开启对话聊天

在命令行模式下输入以下命令开启一个新的聊天窗口：

:GpChatNew

支持子命令指定布局: :GpChatNew vsplit (垂直分割), :GpChatNew popup (弹窗) 等。

在打开的缓冲区中直接输入你的问题（支持 Markdown 格式），发送后 AI 将流式输出回答。

2. 代码指令操作

选中一段代码（可视模式），然后运行指令让 AI 处理（例如解释代码、重构、写单元测试）：

:'<,'>GpRewrite Explain this code in Chinese

或者使用预设的命令（需在配置中绑定快捷键或自定义 hook）：

:'<,'>GpAppend Write unit tests for this selection

常用操作目标:

• GpRewrite: 重写选中内容
• GpAppend: 追加到选中内容后
• GpPrepend: 插入到选中内容前
• GpNew: 在新缓冲区生成结果

3. 快捷管理

• 切换最近聊天: :GpChatToggle (快速弹出/隐藏最近的聊天窗口)
• 查找历史会话: :GpChatFinder (搜索、预览或删除过往聊天)
• 重新生成回答: :GpChatRespond (基于当前上下文重新请求回答)

4. 语音输入 (需安装 SoX)

按住快捷键（需自行配置映射）或运行命令开始录音，说完后自动转为文字输入到聊天框：

:GpWhisper

---

提示：更多高级功能（如自定义 Hook、多仓库指令文件 .gp.md）请参考完整文档配置章节。