opencode.nvim

https://github.com/user-attachments/assets/077daa78-d401-4b8b-98d1-9ba9f94c2330

✨ 功能

• 连接到_任何_ opencode，或提供一个集成的实例
• 共享编辑器上下文（缓冲区、选区、诊断信息等）
• 带有补全、高亮和普通模式支持的输入提示
• 从库中选择提示并自定义自己的提示
• 执行命令
• 监控并响应事件
• 查看、接受或拒绝，并重新加载编辑内容
• 通过进程内 LSP 与 opencode 交互
• Vim 风格 — 支持范围操作和点重复
• 简单而合理的默认设置，助你快速上手

📦 安装

lazy.nvim

{
  "nickjvandyke/opencode.nvim",
  version = "*", -- 最新稳定版
  dependencies = {
    {
      -- 推荐但非强制使用 `snacks.nvim` 集成
      ---@module "snacks" <- 加载 `snacks.nvim` 类型以提供配置智能感知
      "folke/snacks.nvim",
      optional = true,
      opts = {
        input = {}, -- 增强 `ask()`
        picker = { -- 增强 `select()`
          actions = {
            opencode_send = function(...) return require("opencode").snacks_picker_send(...) end,
          },
          win = {
            input = {
              keys = {
                ["<a-a>"] = { "opencode_send", mode = { "n", "i" } },
              },
            },
          },
        },
      },
    },
  },
  config = function()
    ---@type opencode.Opts
    vim.g.opencode_opts = {
      -- 您的配置，如有；详情请跳转到类型或字段的定义处
    }

    vim.o.autoread = true -- `opts.events.reload` 所需

    -- 推荐/示例键位映射
    vim.keymap.set({ "n", "x" }, "<C-a>", function() require("opencode").ask("@this: ", { submit = true }) end, { desc = "向 opencode 提问…" })
    vim.keymap.set({ "n", "x" }, "<C-x>", function() require("opencode").select() end,                          { desc = "执行 opencode 操作…" })
    vim.keymap.set({ "n", "t" }, "<C-.>", function() require("opencode").toggle() end,                          { desc = "切换 opencode" })

    vim.keymap.set({ "n", "x" }, "go",  function() return require("opencode").operator("@this ") end,        { desc = "将范围添加到 opencode", expr = true })
    vim.keymap.set("n",          "goo", function() return require("opencode").operator("@this ") .. "_" end, { desc = "将行添加到 opencode", expr = true })

    vim.keymap.set("n", "<S-C-u>", function() require("opencode").command("session.half.page.up") end,   { desc = "向上滚动 opencode" })
    vim.keymap.set("n", "<S-C-d>", function() require("opencode").command("session.half.page.down") end, { desc = "向下滚动 opencode" })

    -- 如果您使用了上面带有偏好的 `<C-a>` 和 `<C-x>` 键位映射，可能需要这些设置；否则可以考虑使用 `<leader>o…`（并从 `toggle` 键位映射中移除终端模式）
    vim.keymap.set("n", "+", "<C-a>", { desc = "增加光标下的数值", noremap = true })
    vim.keymap.set("n", "-", "<C-x>", { desc = "减少光标下的数值", noremap = true })
  end,
}

nixvim

programs.nixvim = {
  extraPlugins = [
    pkgs.vimPlugins.opencode-nvim
  ];
};

[!TIP] 安装完成后运行 :checkhealth opencode。

⚙️ 配置

opencode.nvim 提供丰富且可靠的默认体验——所有可用选项及其默认值请参见此处。

上下文

opencode.nvim 会将提示中的占位符替换为相应的上下文：

占位符	上下文
@this	操作符范围或可视选区（如有），否则为光标位置
@buffer	当前缓冲区
@buffers	已打开的缓冲区
@visible	可见文本
@diagnostics	当前缓冲区的诊断信息
@quickfix	快速修复列表
@diff	Git 差异
@marks	全局标记
@grapple	grapple.nvim 标签

[!TIP] opencode 会从磁盘读取引用的文件——请保存您的更改！

提示

选择或引用提示来审查、解释并改进您的代码：

名称	提示
diagnostics	解释 @diagnostics
diff	审查以下 Git 差异是否存在正确性和可读性问题：@diff
document	为 @this 添加注释文档
explain	解释 @this 及其上下文
fix	修复 @diagnostics
implement	实现 @this
optimize	优化 @this 以提升性能和可读性
review	审查 @this 的正确性和可读性
test	为 @this 添加测试

服务器

你可以按自己的方式手动运行 opencode，opencode.nvim 会自动找到它们！

[!重要] 你必须使用 --port 标志来运行 opencode，以暴露其服务器。

如果 opencode.nvim 找不到现有的 opencode 实例，它会使用配置的服务器为你启动一个，默认情况下会在嵌入式终端中运行。

键位映射

opencode.nvim 在嵌入式终端中设置了以下普通模式键位映射，用于类似 Neovim 的消息导航：

键位映射	命令	描述
<C-u>	session.half.page.up	向上滚动半页
<C-d>	session.half.page.down	向下滚动半页
gg	session.first	跳转到第一条消息
G	session.last	跳转到最后一条消息
<Esc>	session.interrupt	中断

自定义

以下示例使用 snacks.terminal 替代默认行为：

local opencode_cmd = 'opencode --port'
---@type snacks.terminal.Opts
local snacks_terminal_opts = {
  win = {
    position = 'right',
    enter = false,
    on_win = function(win)
      -- 设置任意终端的键位映射并进行清理
      require('opencode.terminal').setup(win.win)
    end,
  },
}
---@type opencode.Opts
vim.g.opencode_opts = {
  server = {
    start = function()
      require('snacks.terminal').open(opencode_cmd, snacks_terminal_opts)
    end,
    stop = function()
      require('snacks.terminal').get(opencode_cmd, snacks_terminal_opts):close()
    end,
    toggle = function()
      require('snacks.terminal').toggle(opencode_cmd, snacks_terminal_opts)
    end,
  },
}

🚀 使用方法

提问 — require("opencode").ask()

输入一个提示给 opencode。

• 按 <Up> 可浏览最近的提问。
• 高亮显示并补全上下文和 opencode 子代理。
  • 按 <Tab> 触发内置补全。
• 使用 \n 结束提示以追加内容而非提交。
• 此外，当使用 snacks.input 时：
  • 按 <S-CR> 可追加内容而非提交。
  • 通过进程内 LSP 提供补全选项。

选择 — require("opencode").select()

从所有 opencode.nvim 功能中进行选择。

• 提示
• 命令
• 服务器控制

使用 snacks.picker 时，会高亮显示并预览各项内容。

提示 — require("opencode").prompt()

向 opencode 发出提示。

• 将命名引用解析为已配置的提示。
• 注入已配置的上下文。
• opencode 会解释 @ 引用的文件或子代理。

操作符 — require("opencode").operator()

将 prompt 包装为操作符，支持范围操作和点重复。

命令 — require("opencode").command()

执行 opencode 命令：

命令	描述
session.list	列出会话
session.new	开始一个新的会话
session.select	选择一个会话
session.share	分享当前会话
session.interrupt	中断当前会话
session.compact	整理当前会话（减少上下文大小）
session.page.up	向上滚动一页消息
session.page.down	向下滚动一页消息
session.half.page.up	向上滚动半页消息
session.half.page.down	向下滚动半页消息
session.first	跳转到会话中的第一条消息
session.last	跳转到会话中的最后一条消息
session.undo	撤销当前会话中的最后一步
session.redo	重做当前会话中被撤销的操作
prompt.submit	提交 TUI 输入
prompt.clear	清除 TUI 输入
agent.cycle	切换当前选中的代理

LSP

[!警告] 此功能目前处于实验阶段！请尝试设置 vim.g.opencode_opts.lsp.enabled = true 来体验。

opencode.nvim 提供了一个进程内 LSP，让你可以通过熟悉的 LSP 接口与 opencode 交互！

LSP 函数	opencode.nvim 处理程序
Hover	向 opencode 请求光标下的符号的简要说明
Code Actions	向 opencode 请求解释或修复光标下的诊断信息

👀 事件

opencode.nvim 会将 opencode 的服务器发送事件转发为 OpencodeEvent 自动命令：

-- 处理 `opencode` 事件
vim.api.nvim_create_autocmd("User", {
  pattern = "OpencodeEvent:*", -- 可选地过滤事件类型
  callback = function(args)
    ---@type opencode.server.Event
    local event = args.data.event
    ---@type number
    local port = args.data.port

    -- 查看可用的事件类型及其属性
    vim.notify(vim.inspect(event))
    -- 执行一些有用的操作
    if event.type == "session.idle" then
      vim.notify("`opencode` 已完成响应")
    end
  end,
})

编辑

当 opencode 编辑文件时，opencode.nvim 会自动重新加载对应的缓冲区。

权限

当 opencode 请求权限时，opencode.nvim 会等待空闲状态，然后提示你批准或拒绝该请求。

编辑

对于编辑请求，opencode.nvim 会在新标签页中打开目标文件，并使用 Neovim 的 :diffpatch 功能并排显示建议的更改。可参考 :h 'diffopt' 进行自定义。

键位映射	功能
da	接受整个编辑请求
dr	拒绝整个编辑请求
]c/[c	切换到下一个/上一个更改
dp	仅接受光标下的变更块，同时拒绝整个编辑请求
do	仅拒绝光标下的变更块，同时拒绝整个编辑请求
q	关闭差异对比窗口

状态栏

require("lualine").setup({
  sections = {
    lualine_z = {
      {
        require("opencode").statusline,
      },
    }
  }
})

🙏 致谢

• 灵感来源于 nvim-aider、neopencode.nvim 和 sidekick.nvim。
• 为保持简洁，使用了 opencode 的 TUI——有关 Neovim 前端，请参阅 sudo-tee/opencode.nvim。
• mcp-neovim-server 可能更适合您，但它缺乏自定义功能，且工具调用速度慢、稳定性不足。

opencode.nvim 快速上手指南

opencode.nvim 是一个强大的 Neovim 插件，旨在将 opencode AI 助手无缝集成到编辑器中。它支持共享编辑器上下文（缓冲区、选中内容、诊断信息等），提供类似 Vim 的操作符支持，并允许你通过 LSP 与 AI 进行交互。

环境准备

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

1. Neovim: 建议使用最新稳定版 (v0.9+)。
2. Opencode CLI: 必须预先安装 opencode 命令行工具。
   • 安装方式请参考 opencode 官方文档。
   • 重要: 运行 opencode 时必须携带 --port 参数以暴露服务端，插件会自动检测或启动该服务。
3. 依赖插件 (可选但推荐):
   • snacks.nvim: 用于增强输入框 (ask) 和选择器 (select) 的体验。
   • lazy.nvim: 推荐的插件管理器。

安装步骤

使用 lazy.nvim 安装

在你的 Neovim 配置文件中（例如 lua/plugins/opencode.lua），添加以下配置：

{
  "nickjvandyke/opencode.nvim",
  version = "*", -- 锁定最新稳定版本
  dependencies = {
    {
      -- 推荐集成 snacks.nvim 以获得更好的 UI 体验（可选）
      "folke/snacks.nvim",
      optional = true,
      opts = {
        input = {}, -- 增强 ask() 功能
        picker = { -- 增强 select() 功能
          actions = {
            opencode_send = function(...) return require("opencode").snacks_picker_send(...) end,
          },
          win = {
            input = {
              keys = {
                ["<a-a>"] = { "opencode_send", mode = { "n", "i" } },
              },
            },
          },
        },
      },
    },
  },
  config = function()
    ---@type opencode.Opts
    vim.g.opencode_opts = {
      -- 在此处添加自定义配置，留空则使用默认值
    }

    -- 必须开启 autoread 以支持编辑重载功能
    vim.o.autoread = true

    -- 推荐快捷键映射
    vim.keymap.set({ "n", "x" }, "<C-a>", function() require("opencode").ask("@this: ", { submit = true }) end, { desc = "Ask opencode…" })
    vim.keymap.set({ "n", "x" }, "<C-x>", function() require("opencode").select() end,                          { desc = "Execute opencode action…" })
    vim.keymap.set({ "n", "t" }, "<C-.>", function() require("opencode").toggle() end,                          { desc = "Toggle opencode" })

    -- 操作符映射 (支持范围选择和重复操作)
    vim.keymap.set({ "n", "x" }, "go",  function() return require("opencode").operator("@this ") end,        { desc = "Add range to opencode", expr = true })
    vim.keymap.set("n",          "goo", function() return require("opencode").operator("@this ") .. "_" end, { desc = "Add line to opencode", expr = true })

    -- 会话滚动映射
    vim.keymap.set("n", "<S-C-u>", function() require("opencode").command("session.half.page.up") end,   { desc = "Scroll opencode up" })
    vim.keymap.set("n", "<S-C-d>", function() require("opencode").command("session.half.page.down") end, { desc = "Scroll opencode down" })
  end,
}

使用 Nixvim 安装

如果你使用 Nix 管理配置：

programs.nixvim = {
  extraPlugins = [
    pkgs.vimPlugins.opencode-nvim
  ];
};

提示: 安装完成后，请在 Neovim 中运行 :checkhealth opencode 检查安装状态。

基本使用

安装完成后，你可以通过以下几种核心方式与 AI 交互：

1. 提问 (Ask)

按下 <C-a> (或在可视模式下选中代码后按 <C-a>) 唤起输入框。

• 上下文自动注入: 输入 @this 会自动替换为当前选区或光标所在行；输入 @buffer 代表当前文件内容。
• 智能补全: 输入 <Tab> 可触发上下文或子代理的自动补全。
• 示例: 选中一段代码，按 <C-a>，输入 解释 @this 的逻辑 并回车。

2. 选择预设动作 (Select)

按下 <C-x> 打开功能选择器。

• 你可以从库中选择预设的 Prompt（如 fix, review, test 等）。
• 也可以执行服务器控制命令（如新建会话、中断会话）。
• 若安装了 snacks.nvim，选择器将支持高亮预览。

3. 使用操作符 (Operator)

利用 Vim 原生的操作符逻辑调用 AI：

• 范围操作: 输入 go 然后移动光标选择范围（如 goj 选择下一行），AI 将自动处理该范围。
• 整行操作: 输入 goo 快速对当前行进行操作。
• 重复操作: 使用 . 键即可重复上一次的 AI 操作。

4. 查看与接受编辑

当 opencode 生成代码修改建议时：

• 插件会自动在新标签页打开差异对比视图 (diffpatch)。
• 接受修改: 按 da 接受所有更改。
• 拒绝修改: 按 dr 拒绝所有更改。
• 导航变更: 使用 ]c 和 [c 跳转到下一个或上一个变更点。

5. 常用上下文占位符

在输入 Prompt 时，可以使用以下占位符动态注入信息：

占位符	含义
@this	操作符范围、可视选区或光标位置
@buffer	当前缓冲区内容
@diagnostics	当前文件的错误/警告信息
@diff	Git 差异内容
@visible	屏幕上可见的文本

注意: opencode 会从磁盘读取引用的文件，因此在发送请求前请确保已保存文件 (:w)。