parrot.nvim 🦜

这是 parrot.nvim，一款终极的 随机鹦鹉模型，旨在支持你在 Neovim 中进行文本编辑。

功能 • 演示 • 快速入门 • 命令 • 配置 • 路线图 • 常见问题

功能

parrot.nvim 提供开箱即用的无缝体验，将当前的 LLM API 与你的 Neovim 工作流紧密集成，专注于文本生成。精选的核心功能包括 按需文本补全和编辑，以及在原生 Neovim 缓冲区 中进行的 类聊天会话。

此插件面向那些真正知道自己在做什么，并且重视 隐私与透明度 的用户。用户始终完全掌控将发送到 LLM API 端点的内容，因此该插件完全 排除 了诸如 codex、claude-code 和 gemini-cli 等工具所提供的代理概念。

代码的很大一部分基于 Tibor Schmidt 华丽作品 gp.nvim 的早期分支。

• 持久对话以 Markdown 文件形式存储在 Neovim 的标准路径或用户定义的位置
• 基于用户指令和带有预设系统提示的聊天的自定义钩子，用于内联文本编辑
• 统一的提供者系统，支持任何兼容 OpenAI 的 API：
  • OpenAI API
  • Anthropic API
  • Google Gemini API
  • xAI API
  • 通过 ollama 进行本地和离线服务
  • 任何可配置函数的自定义 OpenAI 兼容端点；还支持 Perplexity.ai API、Mistral API、Groq API、DeepSeek API、GitHub Models 和 NVIDIA API
• 来自不同来源的灵活 API 凭证管理：
  • 环境变量
  • Bash 命令
  • 密码管理器 CLI（惰性求值）
• 使用 .parrot.md 文件通过 PrtContext 命令实现仓库特定的指令
• 无 自动补全，无 在后台隐藏请求来分析你的文件

演示

无缝切换提供商和模型。

根据注释触发代码补全。

让鹦鹉帮你修复 bug。

快速入门

依赖项

此插件需要最新版本的 Neovim，并依赖于一组精心挑选的成熟插件。

• neovim 0.10+
• plenary
• ripgrep（可选）
• fzf（可选，需要 ripgrep）
• telescope（可选）

安装

{
  "frankroeder/parrot.nvim",
  dependencies = { "ibhagwan/fzf-lua", "nvim-lua/plenary.nvim" },
  opts = {}
}

require("packer").startup(function()
  use({
    "frankroeder/parrot.nvim",
    requires = { 'ibhagwan/fzf-lua', 'nvim-lua/plenary.nvim'},
    config = function()
      require("parrot").setup()
    end,
  })
end)

git clone --depth=1 https://github.com/frankroeder/parrot.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/parrot/start/parrot.nvim

设置

最低要求是至少设置一个提供者，例如下面提供的那个，或者从 提供者配置示例 中选择一个。

{
  "frankroeder/parrot.nvim",
  dependencies = { 'ibhagwan/fzf-lua', 'nvim-lua/plenary.nvim' },
  -- 可选地包含 "folke/noice.nvim" 或 "rcarriga/nvim-notify" 以获得精美的通知
  config = function()
    require("parrot").setup {
      -- 必须显式设置提供者才能使其可用。
      providers = {
        openai = {
          name = "openai",
          api_key = os.getenv "OPENAI_API_KEY",
          endpoint = "https://api.openai.com/v1/chat/completions",
          params = {
            chat = { temperature = 1.1, top_p = 1 },
            command = { temperature = 1.1, top_p = 1 },
          },
          topic = {
            model = "gpt-4.1-nano",
            params = { max_completion_tokens = 64 },
          },
          models ={
            "gpt-4o",
            "o4-mini",
            "gpt-4.1-nano",
          }
        },
      },
    }
  end,
}

使用

聊天基础

parrot.nvim 中的聊天本质上是标准的 Markdown 缓冲区。

工作原理：

1. 打开聊天：使用 :PrtChatNew 打开一个新的聊天缓冲区（或使用 :PrtChatToggle 切换最近的一个）。
2. 输入提示：在用户前缀 🗨: 后直接在缓冲区中写下你的问题或指令。
3. 触发 LLM：按下触发键映射（默认为插入模式下的 <C-g><C-g>）或使用 :PrtChatRespond 命令。
4. 接收响应：LLM 会将响应流式传输到光标所在位置。
5. 停止生成：随时按下 <C-g>s 可以停止生成。

关键概念：

• 上下文：整个缓冲区内容都会作为上下文发送（除非使用了隐藏注释）。
• 系统提示：你可以为每个聊天或全局设置独特的系统提示。
• 持久化：聊天会以 .md 文件的形式保存在你配置的目录中。

命令模式（交互式命令）

命令模式允许你在不离开当前缓冲区的情况下，直接对代码与 LLM 进行交互。

可用命令：

• :PrtRewrite – 根据你的提示重写可视选区。
• :PrtAppend – 在选区后追加生成的文本。
• :PrtPrepend – 在选区前插入生成的文本。
• :PrtRetry – 重试上次的重写/追加/插入操作。
• :PrtEdit – 编辑并重新运行上一条命令，同时修改提示。

工作流程：

1. 使用可视化模式选择需要修改的代码。
2. 运行上述命令之一（例如 :PrtRewrite fix the bug）。
3. LLM 处理你的选区，并将结果流式传输过来，或者显示一个差异视图。

独立的模型选择： parrot.nvim 维持 两套独立的模型选择：

• 聊天模型：用于聊天缓冲区。可在聊天缓冲区内部使用 :PrtModel 进行切换。
• 命令模型：用于交互式命令（如 PrtRewrite 等）。可在任何非聊天缓冲区中使用 :PrtModel 进行切换。

这使得你可以为快速的内联编辑使用速度快、成本低的模型，而为深入的对话交流则使用功能更强大的模型。

命令

以下是可配置为快捷键的可用命令。这些命令已包含在默认配置中。此外，还有一些有用的命令通过钩子实现（见下文）。

通用

其中 <target> 表示在以下目标位置之一打开聊天的命令（默认为 toggle_target）：

• popup：打开一个弹出窗口，可通过下方提供的选项进行配置。
• split：在水平分割窗口中打开聊天。
• vsplit：在垂直分割窗口中打开聊天。
• tabnew：在新标签页中打开聊天。

所有聊天相关命令（PrtChatNew, PrtChatToggle）以及自定义钩子都支持在触发时将可视选区显示在聊天中。而交互式命令则要求用户利用 模板占位符，以便在 API 请求中考虑可视选区。

配置

选项

{
    -- 提供商定义包括端点、API密钥、默认参数，
    -- 以及用于聊天摘要的主题模型参数。你可以为你的提供商使用任意名称，
    -- 并通过自定义函数进行配置。
    providers = {
      openai = {
        name = "openai",
        endpoint = "https://api.openai.com/v1/chat/completions",
        -- 用于在线查询可用模型的端点
        model_endpoint = "https://api.openai.com/v1/models",
        api_key = os.getenv("OPENAI_API_KEY"),
        -- 可选：获取API密钥的替代方法
        -- 使用GPG解密：
        -- api_key = { "gpg", "--decrypt", vim.fn.expand("$HOME") .. "/my_api_key.txt.gpg" },
        -- 使用macOS Keychain：
        -- api_key = { "/usr/bin/security", "find-generic-password", "-s my-api-key", "-w" },
        --- 用于聊天和交互式命令的默认模型参数
        params = {
          chat = { temperature = 1.1, top_p = 1 },
          command = { temperature = 1.1, top_p = 1 },
        },
        -- 用于总结聊天的主题模型参数
        topic = {
          model = "gpt-4.1-nano",
          params = { max_completion_tokens = 64 },
        },
        -- Parrot可以在会话间记住的一组模型
        -- 注意：在未来的版本中，这将得到更智能的处理
        models = {
          "gpt-4.1",
          "o4-mini",
          "gpt-4.1-mini",
          "gpt-4.1-nano",
        },
      },
      ...
    }

    -- 聊天会话和命令流程中使用的默认系统提示
    system_prompt = {
      chat = ...,
      command = ...
    },

    -- 所有命令使用的前缀
    cmd_prefix = "Prt",

    -- curl 的可选参数
    curl_params = {},

    -- 存储持久化状态信息的目录，例如
    -- 当前提供商和所选模型
    state_dir = vim.fn.stdpath("data"):gsub("/$", "") .. "/parrot/persisted",

    -- 存储聊天记录的目录（可通过 PrtChatFinder 搜索）
    chat_dir = vim.fn.stdpath("data"):gsub("/$", "") .. "/parrot/chats",

    -- 聊天用户提示前缀
    chat_user_prefix = "🗨:",

    -- LLM 提示前缀
    llm_prefix = "🦜:",

    -- 明确确认删除聊天文件
    chat_confirm_delete = true,

    -- 本地聊天缓冲区快捷键
    chat_shortcut_respond = { modes = { "n", "i", "v", "x" }, shortcut = "<C-g><C-g>" },
    chat_shortcut_delete = { modes = { "n", "i", "v", "x" }, shortcut = "<C-g>d" },
    chat_shortcut_stop = { modes = { "n", "i", "v", "x" }, shortcut = "<C-g>s" },
    chat_shortcut_new = { modes = { "n", "i", "v", "x" }, shortcut = "<C-g>c" },

    -- 完成回复后将光标移动到文件末尾的选项
    chat_free_cursor = false,

    -- PrtChatToggle、PrtChatNew、PrtContext 以及从 ChatFinder 打开的聊天的默认目标
    -- 取值：popup / split / vsplit / tabnew
    toggle_target = "vsplit",

    -- 交互式用户输入的方式可以是“原生”的
    -- 对于 vim.ui.input，也可以是“缓冲区”，即在原生 nvim 缓冲区中查询输入
    -- （见下方视频演示）
    user_input_ui = "native",

    -- 弹出窗口布局
    -- 边框样式：single、double、rounded、solid、shadow、none
    style_popup_border = "single",

    -- 边距以字符或行数表示
    style_popup_margin_bottom = 8,
    style_popup_margin_left = 1,
    style_popup_margin_right = 2,
    style_popup_margin_top = 2,
    style_popup_max_width = 160

    -- 用于交互式 LLM 调用的提示模板，例如 PrtRewrite，其中 {{llm}} 是
    -- LLM 名称的占位符
    command_prompt_prefix_template = "🤖 {{llm}} ~ ",

    -- 自动选择命令响应（便于命令链式调用）
    -- 如果设置为 false，则会释放缓冲区光标以便在其他地方继续编辑
    command_auto_select_response = true,

    -- 模型缓存刷新的时间间隔（小时）
    -- 设置为 0 可禁用模型缓存
    model_cache_expiry_hours = 48,

    -- 安装插件时，PrtModel 和 PrtChatFinder 使用的 fzf_lua 选项
    fzf_lua_opts = {
        ["--ansi"] = true,
        ["--sort"] = "",
        ["--info"] = "inline",
        ["--layout"] = "reverse",
        ["--preview-window"] = "nohidden:right:75%",
    },

    -- 启用查询加载动画
    enable_spinner = true,
    -- 加载时显示的动画类型
    -- 可选：dots、line、star、bouncing_bar、bouncing_ball
    spinner_type = "star",
    -- 显示通过 @file、@buffer 或 @directory 补全添加的上下文提示
    show_context_hints = true

    -- 在应用重写/追加/前置更改之前显示差异预览
    enable_preview_mode = true,
    preview_auto_apply = false, -- 如果为真，预览超时后会自动应用更改
    preview_timeout = 10000, -- 自动应用前的等待时间（毫秒）
    preview_border = "rounded",
    preview_max_width = 120,
    preview_max_height = 30,
}

演示

键位绑定

该插件提供了以下默认键映射：

提供商配置示例

统一的提供商系统允许你配置任何兼容 OpenAI 的 API 提供商。以下是几个流行提供商的示例：

providers = {
  perplexity = {
    name = "perplexity",
    endpoint = "https://api.perplexity.ai/chat/completions",
    model_endpoint = "https://api.perplexity.ai/models",
    api_key = os.getenv "PERPLEXITY_API_KEY",
    params = {
      chat = { temperature = 1.0, top_p = 1 },
      command = { temperature = 1.0, top_p = 1 },
    },
    topic = {
      model = "pplx-70b-chat",
      params = { max_tokens = 32 },
    },
    headers = function(self)
      return {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer " .. self.api_key,
      }
    end,
    models = {
      "pplx-70b-chat",
      "pplx-70b-instruct",
      "pplx-40b-chat",
      "pplx-40b-instruct",
      "pplx-22b-chat",
      "pplx-22b-instruct",
    },
    preprocess_payload = function(payload)
      for _, message in ipairs(payload.messages) do
        message.content = message.content:gsub("^%s*(.-)%s*$", "%1")
      end
      if payload.messages[1] and payload.messages[1].role == "system" then
        -- 移除作为系统提示的第一条消息，因为 Perplexity 要求系统提示应包含在 API 请求体中，而非消息列表中
        payload.system = payload.messages[1].content
        table.remove(payload.messages, 1)
      end
      return payload
    end,
  },
}

providers = {
  llama = {
    name = "llama",
    endpoint = "https://api.llama-api.com/v1/chat/completions",
    model_endpoint = "https://api.llama-api.com/v1/models",
    api_key = os.getenv "LLAMA_API_KEY",
    params = {
      chat = { temperature = 1.0, top_p = 1 },
      command = { temperature = 1.0, top_p = 1 },
    },
    topic = {
      model = "Llama-3.1-8B-Instruct",
      params = { max_tokens = 32 },
    },
    headers = function(self)
      return {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer " .. self.api_key,
      }
    end,
    models = {
      "Llama-3.1-8B-Instruct",
      "Llama-3.1-70B-Instruct",
      "Llama-3.1-405B-Instruct",
    },
    preprocess_payload = function(payload)
      for _, message in ipairs(payload.messages) do
        message.content = message.content:gsub("^%s*(.-)%s*$", "%1")
      end
      if payload.messages[1] and payload.messages[1].role == "system" then
        -- 移除作为系统提示的第一条消息，因为 Llama API 要求系统提示应包含在请求体中
        payload.system = payload.messages[1].content
        table.remove(payload.messages, 1)
      end
      return payload
    end,
  },
}

providers = {
  qwen = {
    name = "qwen",
    endpoint = "https://dashscope.aliyuncs.com/compatible/oss/api/v1/chat/completions",
    model_endpoint = "https://dashscope.aliyuncs.com/compatible/oss/api/v1/models",
    api_key = os.getenv "QWEN_API_KEY",
    params = {
      chat = { temperature = 1.0, top_p = 1 },
      command = { temperature = 1.0, top_p = 1 },
    },
    topic = {
      model = "Qwen-Max",
      params = { max_tokens = 32 },
    },
    headers = function(self)
      return {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer " .. self.api_key,
      }
    end,
    models = {
      "Qwen-Max",
      "Qwen-Turbo",
      "Qwen-Long",
      "Qwen-Plus",
    },
    preprocess_payload = function(payload)
      for _, message in ipairs(payload.messages) do
        message.content = message.content:gsub("^%s*(.-)%s*$", "%1")
      end
      if payload.messages[1] and payload.messages[1].role == "system" then
        -- 移除作为系统提示的第一条消息，因为 Qwen API 要求系统提示应包含在请求体中
        payload.system = payload.messages[1].content
        table.remove(payload.messages, 1)
      end
      return payload
    end,
  },
}

providers = {
  deepseek = {
    name = "deepseek",
    endpoint = "https://api.deepseek.com/v1/chat/completions",
    model_endpoint = "https://api.deepseek.com/v1/models",
    api_key = os.getenv "DEEPSEEK_API_KEY",
    params = {
      chat = { temperature = 1.0, top_p = 1 },
      command = { temperature = 1.0, top_p = 1 },
    },
    topic = {
      model = "DeepSeek-V2-Lite",
      params = { max_tokens = 32 },
    },
    headers = function(self)
      return {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer " .. self.api_key,
      }
    end,
    models = {
      "DeepSeek-V2-Lite",
      "DeepSeek-V2-Pro",
      "DeepSeek-V2.5-Lite",
      "DeepSeek-V2.5-Pro",
    },
    preprocess_payload = function(payload)
      for _, message in ipairs(payload.messages) do
        message.content = message.content:gsub("^%s*(.-)%s*$", "%1")
      end
      if payload.messages[1] and payload.messages[1].role == "system" then
        -- 移除作为系统提示的第一条消息,因为 DeepSeek API 要求系统提示应包含在请求体中
        payload.system = payload.messages[1].content
        table.remove(payload.messages, 1)
      end
      return payload
    end,
  },
}

providers = {
  gigachat = {
    name = "gigachat",
    endpoint = "https://gigachat.app/api/v1/chat/completions",
    model_endpoint = "https://gigachat.app/api/v1/models",
    api_key = os.getenv "GIGACHAT_API_KEY",
    params = {
      chat = { temperature = 1.0, top_p = 1 },
      command = { temperature = 1.0, top_p = 1 },
    },
    topic = {
      model = "GigaChat Pro",
      params = { max_tokens = 32 },
    },
    headers = function(self)
      return {
        ["Content-Type"] = "application/json",
        ["Authorization"] = "Bearer " .. self.api_key,
      }
    end,
    models = {
      "GigaChat Pro",
      "GigaChat Lite",
      "GigaChat Turbo",
    },
    preprocess_payload = function(payload)
      for _, message in ipairs(payload.messages) do
        message.content = message.content:gsub("^%s*(.-)%s*$", "%1")
      end
      if payload.messages[1] and payload.messages[1].role == "system" then
        -- 移除作为系统提示的第一条消息,因为 Yandex GigaChat 要求系统提示应包含在请求体中
        payload.system = payload.messages[1].content
        table.remove(payload.messages, 1)
      end
      return payload
    end,
  },
}

providers = {
  perplexity = {
    name = "perplexity",
    api_key = os.getenv("PERPLEXITY_API_KEY"),
    endpoint = "https://api.perplexity.ai/chat/completions",
    headers = function(self)
      return {
        ["Content-Type"] = "application/json",
        ["Accept"] = "application/json",
        ["Authorization"] = "Bearer " .. self.api_key,
      }
    end,
    topic = {
      model = "r1-1776",
      params = {
        max_tokens = 64,
      },
    },
    models = {
      "sonar",
      "sonar-pro",
      "sonar-deep-research",
      "sonar-reasoning",
      "sonar-reasoning-pro",
      "r1-1776",
    },
  }
}

添加新命令

提问并以弹出窗口形式接收答案

require("parrot").setup {
    -- ...
    hooks = {
      Ask = function(parrot, params)
        local template = [[
          根据你现有的知识库，请生成一个简洁明了、直接回答问题的回复。在回答中优先考虑准确性和相关性，尽量利用你所掌握的最新信息。力求用简练的语言，抓住问题的核心要点。
          问题: {{command}}
        ]]
        local model_obj = parrot.get_model("command")
        parrot.logger.info("正在调用模型: " .. model_obj.name)
        parrot.Prompt(params, parrot.ui.Target.popup, model_obj, "🤖 询问 ~ ", template)
      end,
    }
    -- ...
}

使用预设聊天提示开始对话，检查拼写

require("parrot").setup {
    -- ...
    hooks = {
      SpellCheck = function(prt, params)
        local chat_prompt = [[
          你的任务是将提供的文本改写成清晰、语法正确的版本，同时尽可能保留原文的意思。请纠正其中的拼写错误、标点符号错误、动词时态问题、用词不当以及其他语法错误。
        ]]
        prt.ChatNew(params, chat_prompt)
      end,
    }
    -- ...
}

更多钩子和键绑定可以参考我的 个人 lazy.nvim 配置 或者 其他用户的配置。

提示语集合

如果你在使用 PrtRewrite、PrtAppend 或 PrtPrepend 时，反复输入相同的提示语，那么可以考虑一种更轻量级的方式——直接定义提示语，而不是通过用户命令（即钩子）来实现：

require("parrot").setup {
    -- ...
    prompts = {
        ["Spell"] = "我希望你校对所提供的文本，并修正其中的错误。" -- 例如：:'<,'>PrtRewrite Spell
        ["Comment"] = "请添加注释，解释这段代码的作用。" -- 例如：:'<,'>PrtPrepend Comment
        ["Complete"] = "请继续完成文件 {{filename}} 中提供的代码片段。" -- 例如：:'<,'>PrtAppend Complete
    }
    -- ...
}

这些提示语可以直接作为上述交互式命令的参数使用，也可以与 模板占位符 结合使用。

模板占位符

用户可以在钩子和系统模板中使用以下占位符，以注入额外的上下文信息：

下面是一个如何在补全钩子中使用这些占位符的示例，该钩子会接收整个文件上下文和选中的代码片段作为输入。

require("parrot").setup {
    -- ...
    hooks = {
      CompleteFullContext = function(prt, params)
        local template = [[
        我有来自 {{filename}} 的如下代码：

        ```{{filetype}}
        {{filecontent}}
        ```

        请特别关注以下部分：
        ```{{filetype}}
        {{selection}}
        ```

        请仔细且逻辑严谨地完成上述代码。请仅回复应插入的代码片段。
        ]]
        local model_obj = prt.get_model("command")
        prt.Prompt(params, prt.ui.Target.append, model_obj, nil, template)
      end,
    }
    -- ...
}

此外，{{filetype}} 和 {{filecontent}} 占位符也可以用于自定义钩子中调用 prt.ChatNew(params, chat_prompt) 时，直接注入整个文件的内容。

require("parrot").setup {
    -- ...
      CodeConsultant = function(prt, params)
        local chat_prompt = [[
          你的任务是分析提供的 {{filetype}} 代码，并提出优化建议以提升其性能。找出代码中可以变得更高效、更快或更节省资源的地方。提供具体的优化方案，并说明这些改动将如何提升代码性能。优化后的代码应保持与原代码相同的功能，同时展现出更高的效率。

          这里是代码：
          ```{{filetype}}
          {{filecontent}}
          ```
        ]]
        prt.ChatNew(params, chat_prompt)
      end,
    }
    -- ...
}

补全功能

除了使用 模板占位符 外，parrot.nvim 还支持通过 nvim-cmp 和 blink.cmp 实现内联补全，从而提供更多上下文信息：

• @buffer:foo.txt - 包含名为 foo.txt 的打开缓冲区的内容
• @file:test.lua - 包含名为 test.lua 的文件内容
• @directory:src/ - 包含目录 src/ 下的所有文件内容

提示：启用 show_context_hints 选项后，你可以直观地看到请求所考虑的实际文件内容提示。补全文本（如 @file）需要放在 新行 上！

配置 nvim-cmp

要启用 parrot.nvim 的补全功能，只需将该源添加到你的 nvim-cmp 配置中：

...
sources = cmp.config.sources({
  { name = "parrot" },
}),
...

配置 blink.cmp

对于 blink.cmp，你需要将 "parrot" 添加到默认的源列表中，并按以下方式配置提供者：

...
parrot = {
    module = "parrot.completion.blink",
    name = "parrot",
    score_offset = 20,
    opts = {
        show_hidden_files = false,
        max_items = 50,
    }
},
...

状态栏支持

使用您最喜欢的状态栏插件，可以显示当前的聊天或命令模式。下面我们提供一个针对 lualine 的示例：

  -- 定义函数及信息格式化
  local function parrot_status()
    local status_info = require("parrot.config").get_status_info()
    local status = ""
    if status_info.is_chat then
      status = status_info.prov.chat.name
    else
      status = status_info.prov.command.name
    end
    return string.format("%s(%s)", status, status_info.model)
  end

  -- 添加到 lueline 区域
  require('lualine').setup {
    sections = {
      lualine_a = { parrot_status }
  }

添加自定义提供者

如果默认提供者不可用，您可以根据需要定义任意数量的自定义提供者。这使您可以自定义各种方面，例如端点、可用模型、默认参数、头部以及处理 LLM 响应的函数。 请注意，以这种方式配置提供者是为高级用户设计的。如果您需要帮助或对改进提供者支持有任何建议，请随时提交问题或讨论。

  providers = {
    my_custom_provider = {
      name = "my_custom_provider",
      api_key = os.getenv("MY_API_KEY"),
      endpoint = "https://api.example.com/v1/chat/completions",
      model = { "model-1", "model-2" },
      -- 提供者特定的 curl 参数（可选）
      curl_params = { "--insecure", "--max-time", "30", "--proxy", "http://proxy:8080" },
      -- 自定义头部函数
      headers = function(api_key)
        return {
          ["Content-Type"] = "application/json",
          ["Authorization"] = "Bearer " .. api_key,
          ["X-Custom-Header"] = "custom-value",
        }
      end,
      -- 自定义负载预处理
      preprocess_payload = function(payload)
        -- 根据您的 API 格式修改负载
        return payload
      end,
      -- 自定义响应处理
      process_stdout = function(response)
        -- 解析来自您的 API 的流式响应
        local success, decoded = pcall(vim.json.decode, response)
        if success and decoded.content then
          return decoded.content
        end
      end,
    },
  }

取消操作

您可以随时使用多种方法停止正在进行的 Parrot 生成：

方法

1. 快捷键：<C-g>s（可通过 chat_shortcut_stop 配置）
2. 命令：:PrtStop（在任何地方都有效）

行为

当您取消生成时：

• 立即终止：API 请求会立即停止
• 保留已生成文本：目前为止生成的文本仍保留在缓冲区中
• 视觉反馈：您会收到确认取消的通知
• 预览模式：如果在流式传输过程中取消，则不会显示预览
• 多任务处理：如果有多个生成任务正在运行，所有任务都会被停止

自动命令事件

当生成被取消时，会触发 User PrtCancelled 事件，允许您创建自定义钩子：

vim.api.nvim_create_autocmd("User", {
  pattern = "PrtCancelled",
  callback = function()
    -- 您的自定义逻辑在此处
    print("Parrot 生成已被取消")
  end,
})

高级用法

对于自定义代码中的特定缓冲区取消操作：

-- 仅停止当前缓冲区的任务
local chat_handler = require("parrot").chat_handler
chat_handler:stop({ buffer = vim.api.nvim_get_current_buf() })

-- 不发送通知地停止
chat_handler:stop({ notify = false })

附赠

可以直接从终端访问 parrot.nvim：

command nvim -c "PrtChatNew"

也可以将内容直接通过管道输入到聊天中：

ls -l | command nvim - -c "normal ggVGy" -c ":PrtChatNew" -c "normal p"

路线图

• 添加状态栏集成/通知功能，用于总结使用的 token 数量或花费金额
• 改进文档
• 制作教程视频
• 降低整体代码复杂度并提高健壮性

常见问题解答

• 我遇到了与状态相关的错误。

  如果状态损坏，只需删除文件 ~/.local/share/nvim/parrot/persisted/state.json 即可。

• 补全功能无法正常工作，并且出现了错误。

  请确保您有足够的 API 余额，并检查日志文件 ~/.local/state/nvim/parrot.nvim.log 中是否有任何错误。

• 聊天和交互式命令的模型选择是如何工作的？

  聊天和交互式命令的模型选择是分开的。要更改聊天模型，您必须位于使用 PrtChatNew 启动的聊天窗口中。在聊天窗口之外切换模型只会影响交互式命令的模型（例如 PrtRewrite、PrtAppend）。一旦设置，这些选择就会保持不变。

• 我发现了一个 bug，有一个功能建议，或者有一个总体的想法来改进这个项目。

  欢迎所有人参与该项目！如果您有任何建议、想法或 bug 报告，请随时提交问题。

相关项目

• parrot.nvim 是早期版本 robitx/gp.nvim 的分支，于 2024 年 1 月从提交 607f94d361f36b8eabb148d95993604fdd74d901 分支出来。此后，原始代码的很大一部分已被移除或重写，这一努力将持续进行，直到 parrot.nvim 发展成为其独立的版本。原始的 MIT 许可证已被保留并将继续维持。
• huynle/ogpt.nvim
• PrtCmd 的想法受到 exit.nvim 的启发。

星标历史

parrot.nvim 快速上手指南

parrot.nvim 是一款专为 Neovim 设计的 AI 辅助插件，主打隐私透明与完全可控。它不支持后台自动分析或代理模式，所有发送给 LLM 的内容均由用户明确指令触发。支持 OpenAI、Anthropic、Google Gemini、Ollama 本地模型及任何兼容 OpenAI 格式的接口。

环境准备

系统要求

• Neovim: 版本 0.10+ (必须)
• 操作系统: Linux, macOS, Windows

前置依赖

插件核心依赖以下工具，建议提前安装：

• plenary.nvim: Neovim Lua 通用库 (必须)
• fzf-lua: 用于模糊搜索和模型选择 (推荐，替代原 fzf/ripgrep 组合以获得更好体验)
• ripgrep: 可选，用于增强搜索功能
• Telescope: 可选，若偏好 Telescope 而非 fzf

国内加速建议：

• 安装 Neovim 或 Lua 插件时，若遇到网络问题，可配置 GitHub 镜像源或使用代理。
• 使用 Ollama 等本地模型时，可直接从国内镜像站下载模型文件。

安装步骤

推荐使用 lazy.nvim 进行包管理。

1. 使用 lazy.nvim 安装

在你的插件配置文件中（如 lua/plugins/parrot.lua 或 init.lua）添加以下内容：

{
  "frankroeder/parrot.nvim",
  dependencies = { "ibhagwan/fzf-lua", "nvim-lua/plenary.nvim" },
  -- 可选：添加通知插件以获得更美观的提示
  -- dependencies = { "ibhagwan/fzf-lua", "nvim-lua/plenary.nvim", "rcarriga/nvim-notify" },
  opts = {}
}

2. 手动安装 (不推荐)

git clone --depth=1 https://github.com/frankroeder/parrot.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/parrot/start/parrot.nvim

基本配置

parrot.nvim 必须至少配置一个 Provider（服务提供商）才能使用。以下是一个基于 OpenAI 的最小化配置示例。

请在插件配置中添加 config 部分：

{
  "frankroeder/parrot.nvim",
  dependencies = { "ibhagwan/fzf-lua", "nvim-lua/plenary.nvim" },
  config = function()
    require("parrot").setup {
      providers = {
        openai = {
          name = "openai",
          -- 请确保环境变量 OPENAI_API_KEY 已设置，或直接填入字符串
          api_key = os.getenv "OPENAI_API_KEY", 
          endpoint = "https://api.openai.com/v1/chat/completions",
          params = {
            chat = { temperature = 1.1, top_p = 1 },
            command = { temperature = 1.1, top_p = 1 },
          },
          topic = {
            model = "gpt-4.1-nano", -- 用于生成聊天标题的小模型
            params = { max_completion_tokens = 64 },
          },
          models = {
            "gpt-4o",
            "o4-mini",
            "gpt-4.1-nano",
          }
        },
        -- 如需使用 Ollama 本地模型，可取消注释并配置：
        -- ollama = {
        --   name = "ollama",
        --   endpoint = "http://localhost:11434/v1/chat/completions",
        --   api_key = "ollama", 
        --   models = { "llama3", "qwen2.5-coder" }
        -- }
      },
    }
  end,
}

注意：如果你使用的是国内大模型（如 DeepSeek、Moonshot 等），只需将 endpoint 改为对应的 API 地址，并在 models 列表中填入可用模型名称即可，因为它们通常兼容 OpenAI 格式。

基本使用

1. 开启对话聊天 (Chat Mode)

在任意 Neovim 缓冲区中执行以下命令打开聊天窗口：

:PrtChatNew

或者使用 :PrtChatToggle 切换上一个聊天窗口。

操作流程：

1. 在打开的 Markdown 缓冲区中，找到用户前缀 🗨:。
2. 输入你的问题或指令（例如："解释这段代码" 或 "写一个 Python 快速排序"）。
3. 按下触发键 <C-g><C-g> (在插入模式下) 或运行命令 :PrtChatRespond。
4. AI 的回答将直接流式输出到缓冲区中。
5. 如需停止生成，按 <C-g>s。

2. 交互式代码编辑 (Command Mode)

无需离开当前代码文件，直接对选中的代码进行操作。

操作流程：

1. 进入可视模式 (v, V, 或 Ctrl-v) 选中一段代码。
2. 执行以下任一命令（可在命令后追加具体指令）：

" 重写选中的代码
:PrtRewrite 优化这段代码的性能

" 在选中内容后追加代码
:PrtAppend 为这个函数添加错误处理

" 在选中内容前插入代码（如注释）
:PrtPrepend 为这个函数添加文档注释

" 重试上一次操作
:PrtRetry

3. 插件会调用 LLM 处理选中内容，并以 Diff 视图或直接替换的方式展示结果。

3. 切换模型与提供商

parrot.nvim 允许为“聊天”和“命令行交互”分别设置不同的模型（例如：聊天用强大的 gpt-4o，行内编辑用快速的 haiku 或本地模型）。

• 切换提供商：:PrtProvider (留空参数可触发 fzf 选择)
• 切换命令行模型：在非聊天缓冲区使用 :PrtModel
• 切换聊天模型：需在聊天缓冲区内部使用 :PrtModel

常用命令速查