CodeCompanion CLI 交互指南:在 Neovim 内驱动 Claude Code 与 Codex 等终端 Agent

原创2026-10-10 23:23:081,658 阅读
文章标签:人工智能大模型AI 应用AI 插件MCP ClientsAI Agent开发工具

CodeCompanion CLI 交互指南:在 Neovim 内驱动 Claude Code 与 Codex 等终端 Agent

导读

CodeCompanion 的 CLI 交互(Command-Line Interface interaction)让你无需离开 Neovim,即可与 Claude Code、Codex 这类拥有命令行界面的 AI Agent 直接对话:把当前缓冲区、可视选区、LSP 诊断、终端输出等编辑器上下文,以按键级的速度共享给 CLI Agent,并直接在 Neovim 终端中查看与操作 Agent 的回复。读完本文,你将掌握 :CodeCompanionCLI 命令与 require("codecompanion").cli() Lua API 的完整用法、Agent 与 Provider 的配置方式、上下文注入(#{...})语法,以及 hooks 集成、自动提交等进阶工作流,并理解其底层在 CLI 交互模块 中的真实实现。

一、为什么需要 CLI 交互

与纯 API 对话不同,Claude Code、Codex 这类 Agent 以交互式 CLI 进程的形式运行。以往要给它共享上下文,你不得不切到终端、按 @ 搜索文件或触发斜杠命令;要分享一段代码,还得手动复制粘贴。CodeCompanion 的 CLI 交互将这一切压缩为几次按键:

  • 直接从 Neovim 缓冲区共享当前文件(#{buffer})、全部打开文件(#{buffers})、LSP 诊断(#{diagnostics})或最近终端输出(#{terminal});
  • 用可视选区或整行命令直接把代码与提示词一起送入 CLI Agent;
  • 在 Neovim 内的终端窗口查看 Agent 输出,无需离开编辑器;
  • 通过 hooks 让 CodeCompanion 的事件系统感知一轮对话的开始与结束(例如驱动代码评审等依赖“回合”边界的功能)。

其入口实现见 CodeCompanion.cli(),整体模块位于 interactions/cli。

二、发起一次 CLI 交互

2.1 基本命令

使用 :CodeCompanionCLI 即可启动一个新的 CLI 交互,CodeCompanion 会使用配置中 interactions.cli.agent 指定的默认 Agent。想要临时切换 Agent,可以在命令后追加 agent=<agent_name>:

:CodeCompanionCLI
:CodeCompanionCLI agent=codex

也可以像聊天缓冲区一样,用 require("codecompanion").toggle() 在“打开/隐藏”之间切换 CLI 窗口(内部实现为 CLI.toggle,若尚无实例则创建,否则在可见与隐藏间切换)。在 CLI 缓冲区中,{ 和 } 可以循环切换所有聊天与 CLI 交互(对应 keymaps 中的 next_chat / previous_chat,底层调用 registry.move)。

注意:若配置中没有任何 Agent,:CodeCompanionCLI 会失败并提示 CLI agent 'xxx' not found in config——详见 CLI.create。使用 CLI 交互前必须先定义至少一个 Agent(见下文“配置 CLI Agent”)。

2.2 命令的解析规则

:CodeCompanionCLI 由 commands/init.lua 注册,解析规则如下:

  • 形如 key=value 的参数会被提取为选项(目前支持 agent=),其余部分拼接为提示词;
  • 无提示词时:若处于可视模式('<,'> 范围)则把选区作为上下文发送,否则新建一个 CLI 交互实例;
  • 命令带 !(bang)时自动提交提示词(等价于 submit = true);
  • 输入 Ask 打开提示词输入缓冲区;输入 Install 触发 hooks 安装(见下文“Hooks 集成”)。

三、配置 CLI Agent

CLI 交互要求你在 setup 配置 中定义 Agent,完整示例见 doc/configuration/cli.md:

require("codecompanion").setup({
  interactions = {
    cli = {
      agent = "claude_code",          -- 默认 Agent
      agents = {
        claude_code = {
          cmd = "claude",             -- 启动命令
          args = {},                  -- 传给命令的参数
          description = "Claude Code CLI",
          provider = "terminal",      -- 默认即可
        },
      },
    },
  },
})

Agent 各字段说明:

Option Type Description
cmd string 要运行的命令(如 "claude"、"codex")
args table 传给命令的附加参数
description string 在 Action Palette 中显示的描述
provider string 使用的 Provider,默认 "terminal"

3.1 多 Agent 并存与切换

require("codecompanion").setup({
  interactions = {
    cli = {
      agent = "claude_code",
      agents = {
        claude_code = { cmd = "claude", args = {}, description = "Claude Code CLI" },
        codex = { cmd = "codex", args = {}, description = "OpenAI Codex CLI" },
      },
    },
  },
})

然后通过 :CodeCompanionCLI agent=codex <prompt> 使用指定 Agent。Lua API 侧则在 opts 中传 agent:require("codecompanion").cli({ agent = "codex" })。

从源码看,CLI.create 会根据 args.agent or config.interactions.cli.agent 查找 Agent 配置;当传入提示词时,CodeCompanion.cli() 优先复用该 Agent 的既有实例(find_by_agent),否则创建新实例,这一点与文档中 “reuses an existing instance of this agent if one exists” 的描述一致。相关测试见 tests/interactions/cli/test_cli.lua。

3.2 CLI 全局选项

require("codecompanion").setup({
  interactions = {
    cli = {
      opts = {
        auto_insert = true, -- 聚焦 CLI 终端时自动进入插入模式
        reload = true,      -- Agent 修改磁盘文件时重载缓冲区(执行 :checktime)
      },
    },
  },
})
Option Type Default Description
auto_insert boolean false(config 默认值) 聚焦 CLI 终端窗口时自动进入插入模式;文档配置页示例默认 true,以你配置为准
reload boolean true 监听 cwd 下文件变更,并运行 :checktime 重载缓冲区

auto_insert 在 CLI.create 中通过 BufEnter/BufLeave 自动命令实现 startinsert/stopinsert。

3.3 Provider:终端如何运行 Agent

Provider 决定 Agent 进程如何被启动。内置的 terminal Provider 使用 jobstart() 在 Neovim 终端缓冲区中运行 Agent,见 providers/terminal.lua:

require("codecompanion").setup({
  interactions = {
    cli = {
      providers = {
        terminal = {
          path = "interactions.cli.providers.terminal",
          description = "Terminal CLI provider",
        },
      },
    },
  },
})

你也可以注册自定义 Provider,path 可以是 CodeCompanion 内置模块、任意 Lua 模块或文件路径:

require("codecompanion").setup({
  interactions = {
    cli = {
      providers = {
        my_provider = {
          path = "my_custom.cli_provider",
          description = "My custom CLI provider",
        },
      },
      agents = {
        my_agent = {
          cmd = "my-cli",
          args = {},
          provider = "my_provider",
        },
      },
    },
  },
})

Provider 的分发逻辑在 providers/init.lua:优先使用 Agent 的 provider 字段,未匹配任何条目时回退到 terminal。

终端提供器的底层细节(对理解行为有帮助,无需配置):

  • 启动时把 Agent 的 cmd 作为首个元素、args 作为后续元素拼成命令数组,通过 jobstart(cmd, { term = true, cwd = getcwd() }) 启动,并注入 CODECOMPANION_CLI_BUFNR、CODECOMPANION_HOOK 等环境变量;
  • 通过轮询终端缓冲区输出的行数来判断 Agent 是否“就绪”(MAX_WAIT = 5000ms,输出稳定 500ms 视为就绪),就绪前所有输入进入队列;
  • 发送队列以 100ms 间隔消费;submit = true 时在文本后追加一个回车(\r)实现“按下回车自动执行”。

四、核心工作流:从 Neovim 向 Agent 发指令

下面这些工作流通过键位映射组合,把“共享上下文 + 发送提示词”压缩成一次按键。以下示例均基于 <LocalLeader> 前缀(默认通常是 \ 或空格,视你的 leader 配置而定)。

4.1 发送自定义提示词

-- [C]odeCompanion [P]rompt
vim.keymap.set({ "n", "v" }, "<LocalLeader>cp", function()
  return require("codecompanion").cli({ prompt = true })
end, { desc = "Prompt the CLI agent" })
  • 普通模式下:打开提示词输入缓冲区,可先补充编辑器上下文再发送;
  • 可视模式下:选区会作为上下文随提示词一并共享,省去手动指定上下文的步骤。

4.2 快速添加上下文(不打断思路)

-- [C]odeCompanion [A]dd
vim.keymap.set({ "n", "v" }, "<LocalLeader>ca", function()
  return require("codecompanion").cli("#{this}", { focus = false })
end, { desc = "Add context to the CLI agent" })

#{this} 是 CLI 交互独有的上下文:普通模式解析为当前缓冲区,可视模式解析为可视选区。focus = false 保证光标不跳到 CLI 缓冲区,你可以在多个缓冲区与代码间从容挑选要共享的上下文,而不会丢失当前编辑位置。

4.3 共享 LSP 诊断并请求修复

-- [C]odeCompanion [D]iagnostics
vim.keymap.set("n", "<LocalLeader>cd", function()
  return require("codecompanion").cli("#{diagnostics} Can you fix these?", { focus = false, submit = true })
end, { desc = "Send diagnostics to CLI agent" })

该键位把当前缓冲区的 LSP 诊断发送给 Agent,并借助 submit = true 自动提交(fire-and-forget),无需再手动按回车。

4.4 共享失败测试输出

-- [C]odeCompanion [T]erminal
vim.keymap.set("n", "<LocalLeader>ct", function()
  return require("codecompanion").cli("#{terminal} Sharing the output from the terminal. Can you fix it?", { focus = false, submit = true })
end, { desc = "Send terminal output to CLI agent" })

#{terminal} 会共享最近一次终端会话的输出,非常适合把失败测试的堆栈信息直接交给 Agent 排查;同样使用 submit = true 自动提交。

提示:这些键位只是示例,具体按键与动作可根据你的习惯调整,核心是理解 cli() 函数的入参语义(见下文 API 参考)。

五、发送上下文:更完整的用法

5.1 可视选区

可视选中一段代码后直接执行命令:

:CodeCompanionCLI Can you explain this code?

等价于 Lua:

require("codecompanion").cli({ prompt = true })

这会把可视选区传给提示词输入缓冲区,你再输入 “Can you explain this code?” 后发送。也可以硬编码提示词,跳过输入环节:

require("codecompanion").cli("Can you explain this code?")

5.2 编辑器上下文(#{...} 语法)

与 聊天缓冲区 一致,CLI 提示词同样支持编辑器上下文引用,用于共享当前 Neovim 会话的状态,例如当前缓冲区(#{buffer})、全部打开的缓冲区(#{buffers})、LSP 诊断(#{diagnostics})等。例如:

:CodeCompanionCLI Can you explain #{buffers}?

发送到 Agent CLI 后会被展开为:

❯ Can you explain the open buffers:
  @your_file_path
  @your_other_file_path?

Lua 侧等价写法:

require("codecompanion").cli("Can you explain #{buffers}?")

上下文的解析发生在 CLI.resolve_editor_context:它调用 editor_context:replace_cli(prompt, buffer_context) 完成替换,核心渲染逻辑分布在 interactions/shared/editor_context 下的各模块(如 buffers.lua 会把每个打开缓冲区渲染为 @相对路径)。

5.3 #{this}:CLI 独有的上下文

#{this} 是 CLI 交互特有的引用,普通模式解析为当前缓冲区路径,可视模式解析为选区代码块:

:CodeCompanionCLI What does #{this} do?

普通模式下解析为:

❯ What does @your_file_path do?

带可视选区时解析为:

❯ What does the selected code in @your_file_path do?

  - Selected code from @your_file_path (lines 3-4):
  ````lua
  local new_set = MiniTest.new_set
  local T = new_set()
  ````

#{this} 的分流逻辑见 editor_context/this.lua:可视模式下委托给选区渲染(selection.lua),否则委托给缓冲区渲染(buffer.lua)。

[!NOTE] @path 引用可被 Claude Code、Codex 等 CLI Agent 原生识别,Agent 会直接读取对应文件,这正是 CLI 交互能高效共享上下文的关键。

5.4 提示词输入缓冲区

需要发送复杂提示词时,除了 :CodeCompanionCLI <prompt> 直传,还可以打开专用的 codecompanion_input 缓冲区:

:CodeCompanionCLI Ask

或:

require("codecompanion").cli({ prompt = true })

在该输入缓冲区中:

  • 可使用全部可用的编辑器上下文(#{...})和部分斜杠命令;
  • 有更大的输入空间;
  • 用 :w 写入缓冲区发送提示词;用 :w! 强制写入则在发送后立即自动提交;
  • 用 <up> / <down> 键翻阅历史提示词。

输入缓冲区的实现在 interactions/cli/input.lua:提交回调中会先执行 resolve_editor_context 展开上下文,再复用最近实例或新建实例发送;submit_opts.bang 对应 :w! 的自动提交。

5.5 斜杠命令(Slash Commands)

提示词输入缓冲区还支持 buffer 与 file 斜杠命令,方便一次性共享大量上下文。在缓冲区中输入 / 即可调出所选 Provider 的补全菜单。

与聊天缓冲区“插入文件内容”不同,CLI 的斜杠命令插入的是 @path 引用。例如通过 /file 选择文件会插入:

@./lua/codecompanion/init.lua

选择多个文件时每个文件独占一行:

@./lua/codecompanion/init.lua
@./lua/codecompanion/config.lua

5.6 自动提交(Auto-Submit)

默认情况下,提示词会发送到 Agent 终端但不会自动按回车,文本出现在 CLI 中供你审阅后再手动回车执行。两种方式启用自动提交:

使用 bang 形式命令:

:CodeCompanionCLI! #{diagnostics} Can you fix these?

或传入 submit = true:

require("codecompanion").cli("#{diagnostics} Can you fix these?", { submit = true })

这在键位映射中尤其有用,可实现前述“诊断修复”“测试输出修复”这类 fire-and-forget 工作流。

六、Hooks:让事件系统感知 Agent 回合

CLI 交互可以与支持 hooks 的 Agent 集成,从而让 CodeCompanion 事件系统实时感知 Agent 回合的开始与结束。缺少它,依赖“回合边界”的功能(例如代码评审)将受到限制。目前 CodeCompanion 支持 Claude Code 的 hooks 集成(见 integrations/claude.lua)。

6.1 安装 hooks

在 Neovim 内执行:

:CodeCompanionCLI Install
  • 对 Claude Code,hooks 会被写入 ~/.claude/settings.json。

安装逻辑位于 interactions/cli/hooks.lua:它遍历配置中的所有 Agent,找到对应集成(按 cmd 名称匹配),确认其设置文件存在后弹出确认对话框,然后写入/合并 hooks 条目。Claude Code 集成会把 UserPromptSubmit、Stop、Notification、PermissionRequest、PostToolUse 等事件映射为 submitted、done、approval_requested、approval_finished 动作,并由 claude.sh 脚本通过 --remote-expr 回调 Neovim。

6.2 事件与钩子机制

这些事件经 CLI.hook 以 CodeCompanionCLISubmitted、CodeCompanionCLIDone、CodeCompanionCLIApprovalRequested、CodeCompanionCLIApprovalFinished 等形式广播,供状态栏集成、herdr 集成 等订阅使用;同时 RequestStarted / RequestFinished 事件让一次 CLI 回合在状态栏中呈现为“进行中”。需要明确的是:hooks 安装后,Agent 进程中还必须由 CODECOMPANION_HOOK 环境变量指向 hook 脚本(由 terminal Provider 注入),回调才能生效。

七、API 参考:require("codecompanion").cli()

cli() 是 CLI 交互的主要入口,具有多态签名(见 init.lua 中定义):

-- 无参数:创建新 CLI 实例并打开
require("codecompanion").cli()

-- opts 表:以选项创建新实例
require("codecompanion").cli({ agent = "claude_code" })

-- 字符串提示词:发送给最近实例(或新建一个)
require("codecompanion").cli("Can you explain this code?")

-- 字符串提示词 + 选项
require("codecompanion").cli("Fix #{diagnostics}", { submit = true, focus = false })

选项一览

Option Type Default Description
agent string config 默认 使用的 CLI Agent;发送提示词时,若存在该 Agent 的实例则复用
focus boolean true 是否打开 CLI 窗口并把光标移入;设为 false 可在后台发送上下文
submit boolean false 是否自动提交(按下回车)让 Agent 立即开始工作
prompt boolean false 是否打开提示词输入缓冲区而非直接发送;若同时提供字符串提示词,会预填输入框
width number config 默认 覆盖 CLI 窗口宽度
height number config 默认 覆盖 CLI 窗口高度

各选项的实际行为可从源码印证:

  • prompt = true 时直接走 input.toggle 打开输入缓冲区;
  • submit = true 时在发送文本后追加 \r(见 Terminal:send);
  • focus = false 时跳过 ui:open 与 focus(),实现后台静默发送(CodeCompanion.cli());
  • width / height 会透传给 UI:open 覆盖窗口尺寸。

八、窗口布局与显示定制

CLI 窗口默认继承 display.chat.window 的布局,并可用 display.cli.window 覆盖个别项(配置合并见 UI:resolve_window_config):

require("codecompanion").setup({
  display = {
    cli = {
      window = {
        layout = "vertical",
        width = 0.4,
        height = 0.6,
        opts = {
          list = false,
        },
      },
    },
  },
})

display.cli.window 中的设置会叠加在聊天窗口默认值之上,只需指定想修改的项。也可通过 Lua API 动态传入:

require("codecompanion").cli("fix the tests", {
  width = 0.5,
  height = 0.8,
})

九、典型使用场景小结

场景 推荐方式
启动/打开 CLI 窗口 :CodeCompanionCLI 或 require("codecompanion").toggle()
发送自定义提示词 :CodeCompanionCLI <prompt>,或用 <LocalLeader>cp 打开输入框
共享当前文件/选区 :CodeCompanionCLI What does #{this} do? 或 <LocalLeader>ca
修复 LSP 诊断 <LocalLeader>cd(#{diagnostics} + submit = true)
修复失败测试 <LocalLeader>ct(#{terminal} + submit = true)
一键自动提交 命令加 ! 或 Lua 传 submit = true
多 Agent 切换 :CodeCompanionCLI agent=<name> <prompt>
启用事件感知 :CodeCompanionCLI Install(写入 ~/.claude/settings.json)

十、进一步阅读

适用前提说明:CLI 交互要求你的机器上已安装对应 Agent(如 Claude Code、Codex),并已在 interactions.cli.agents 中完成配置;本文所述命令与行为以当前仓库源码为准。

登录后查看全文
codecompanion.nvim