CodeCompanion.nvim 工具 API 升级指南：从 v18 位置参数到 v19 结构化 meta 表的全面迁移-北京尧图网络

CodeCompanion.nvim 工具 API 升级指南从 v18 位置参数到 v19 结构化 meta 表的全面迁移【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim导读CodeCompanion.nvim 在 v19 版本中对自定义工具Tools的 API 做了系统性重构所有工具函数与回调的位置参数被替换为结构化 tableopts/meta。本指南以仓库内置升级提示词 tools.md 为主体结合 orchestrator.lua、runner.lua、cmd_tool.lua 等源码实现带你逐项完成cmds、output、handlers三类函数签名的迁移。读完本文你将能把任何基于 v18 签名编写的自定义工具平滑升级到 v19 API且不改变任何业务逻辑。一、升级背景与核心原则该文档是 CodeCompanion.nvim 内置提示词库prompt library中的一个升级提示词Upgrade Tools定位是让 LLM 帮助用户把自定义工具从 v18 迁移到 v19。其 frontmatter 定义了关键元数据--- name: Upgrade Tools interaction: chat description: Upgrade Tools from v18 to v19 opts: is_slash_cmd: false stop_context_insertion: true ---从 markdown.lua 的解析逻辑可知interaction: chat表示它作为聊天交互提示词加载description会展示在提示词库选择器中opts.stop_context_insertion: true则指示在插入该提示词时不自动注入额外的编辑器上下文。当前仓库版本号为 version.txt 中的19.22.0正好落在 v19 系列。迁移的核心原则只有一句话位置参数被结构化 table 取代。凡是原来通过第 3、4 个位置参数传递的input、cb、tools、cmd、stdout、stderr、opts现在都收纳进opts或meta表迁移时只改函数签名与参数访问方式不改动任何业务逻辑原来写tools.chat的地方一律改为meta.tools.chat。二、cmds函数签名迁移cmds表中的每一项可以是命令数组基于vim.system的异步命令也可以是函数型工具。函数型工具在执行时由 runner.lua 统一以tool_cmd(self, args, opts)的形式调用其中opts由 Runner 注入三个字段{ input args.input, -- 上一个命令/函数传递下来的输出 output_cb output_handler, -- 异步回调提交结果给 Orchestrator register_job function(job) end, -- 注册 vim.SystemObj 以便取消 }2.1 同步工具签名变化仅属美观同步工具直接return一个结果表v19 中签名的第三个参数从input改为opts。对于不使用input与output_cb的同步工具这只是参数重命名-- OLD: function(self, args, input) -- NEW同步工具保持不变: function(self, args, opts) -- opts 包含: { input any, output_cb fun(msg: table) } -- 返回: { status success|error, data string }例如 doc/extending/tools.md 中的计算器工具同步函数体完全不变只是参数名从input换成optscmds { function(self, args, opts) local num1 tonumber(args.num1) local num2 tonumber(args.num2) -- ... 校验与计算逻辑不变 ... return { status success, data result } end, },2.2 异步工具必须从回调迁移到opts.output_cb异步工具原来通过第 4 个位置参数拿到回调函数v19 中回调统一从opts.output_cb获取-- OLD: function(self, args, _, cb) cb({ status success, data result }) end -- NEW: function(self, args, opts) local cb opts.output_cb cb({ status success, data result }) end从源码看runner.lua 的output_handler有两条硬性约束迁移后依然适用output_cb只能被调用一次第二次调用会被tool_finished标记直接丢弃一个工具函数要么同步return结果表要么调用opts.output_cb二者不可同时使用——同时使用的结果是未定义的因为无法保证哪个输出先被处理。2.3 连续命令Consecutive cmdscmds中多个函数会串行执行前一个的输出会作为下一个函数的输入。v18 中前一个输出通过第 3 个位置参数传入v19 中改从opts.input读取-- OLD: 第二个函数收到前一个输出作为第 3 个位置参数 function(self, args, input) -- NEW: 前一个输出在 opts.input 中 function(self, args, opts) local input opts.input end这条链路在源码中由 Runner 维护Runner:go_to_next_tool(output)会把上一个函数的输出透传给下一个 Runner 实例的input见 runner.lua。三、output回调签名迁移output表负责在每次命令/函数执行后格式化并回写结果。Orchestrator 在 orchestrator.lua 中统一包装这些回调迁移后回调参数结构如下回调OLD 签名NEW 签名meta 内容success(self, tools, cmd, stdout)(self, stdout, meta){ tools, cmd }error(self, tools, cmd, stderr)(self, stderr, meta){ tools, cmd }rejected(self, tools, cmd, opts)(self, meta){ tools, cmd, opts }prompt(self, tools)(self, meta){ tools }cmd_string(self, tools)(self, meta){ tools }cancelled(self, tools, cmd)(self, meta){ tools, cmd }3.1success与errorstdout/stderr从第 4 个位置参数提前到第 2 个参数原来用于取 chat 引用的tools收敛进meta.tools-- OLD: success function(self, tools, cmd, stdout) local chat tools.chat -- NEW: success function(self, stdout, meta) local chat meta.tools.chat -- meta.cmd 在需要时也可用-- OLD: error function(self, tools, cmd, stderr) local chat tools.chat -- NEW: error function(self, stderr, meta) local chat meta.tools.chat注意 Orchestrator 在调用success/error时若stdout/stderr为空表会传入nil见 orchestrator.lua 与#L244-L249迁移后应保留对空值的防御处理。3.2rejected变化最大rejected是迁移中差异最明显的回调v18 需要自行拼装{ tools, message }传给helpers.rejectedv19 中meta已经天然携带{ tools, cmd, opts }只需把自定义message合并进 meta 再转发-- OLD: rejected function(self, tools, cmd, opts) helpers.rejected(self, { tools tools, message ... }) -- NEW: rejected function(self, meta) -- meta 已经包含 { tools, cmd, opts } local message The user rejected ... meta vim.tbl_extend(force, { message message }, meta or {}) helpers.rejected(self, meta) end这套新写法在仓库内置工厂 cmd_tool.lua 中就是标准实现rejected function(self, meta) local message fmt(The user rejected the execution of the %s tool, spec.name) meta vim.tbl_extend(force, { message message }, meta or {}) helpers.rejected(self, meta) endhelpers.rejected本身在 v19 中的签名是(self, opts)其中opts { tools, message, reason }。Orchestrator 在用户拒绝时会把用户填写的拒绝理由通过opts.reason传入output.rejected(self.tool, { cmd cmd, tools self.tools, opts opts })见 orchestrator.lua因此meta.opts.reason可以在迁移后用于携带拒绝理由。3.3prompt与cmd_string这两个回调原来只接收tools一个位置参数现在统一接收meta { tools }-- OLD: prompt function(self, tools) -- NEW: prompt function(self, meta) -- meta 包含 { tools }-- OLD: cmd_string function(self, tools) -- NEW: cmd_string function(self, meta) -- meta 包含 { tools }prompt的返回值用于审批弹窗文案——Orchestrator 在_prompt_for_approval中调用self.output.prompt()若返回空则回退到默认文案Run the %q tool?见 orchestrator.lua。cmd_string则用于审批与 YOLO 模式下的命令展示及命令级审批缓存 key。3.4cancelled-- OLD: cancelled function(self, tools, cmd) local chat tools.chat -- NEW: cancelled function(self, meta) local chat meta.tools.chat -- meta.cmd 也可用 end该回调在用户取消执行、取消待执行队列cancel_pending_tools以及工具被中断时触发见 orchestrator.lua。若工具未定义cancelledOrchestrator 会向 chat 写入默认文案The user cancelled the execution of the %s tool。四、handlers回调签名迁移handlers表控制工具生命周期setup在cmds/output执行之前调用常用来动态生成cmdson_exit在之后调用prompt_condition用于决定是否需要弹出审批。三者统一从(self, tools)迁移为(self, meta)-- OLD: setup function(self, tools) -- NEW: setup function(self, meta) -- meta 包含 { tools }-- OLD: on_exit function(self, tools) -- NEW: on_exit function(self, meta) -- meta 包含 { tools }-- OLD: prompt_condition function(self, tools) -- NEW: prompt_condition function(self, meta) -- meta 包含 { tools }源码侧Orchestrator 在_setup_handlers中正是以{ tools self.tools }作为 meta 调用这三个回调见 orchestrator.lua。setup在setup_next_tool中会提前调用以便run_command、cmd_tool这类工具在真正执行前动态填充cmds——这也是迁移后setup必须能访问meta.tools以读写工具状态的原因。五、迁移模式速查升级提示词在结尾给出了完整的模式总结这是迁移任何工具时可直接对照的清单cmds函数(self, args, opts)其中opts { input, output_cb }output.success/output.error(self, stdout_or_stderr, meta)其中meta { tools, cmd }output.rejected(self, meta)其中meta { tools, cmd, opts }output.prompt/output.cmd_string(self, meta)其中meta { tools }output.cancelled(self, meta)其中meta { tools, cmd }handlers.setup/handlers.on_exit/handlers.prompt_condition(self, meta)其中meta { tools }helpers.rejected(self, opts)其中opts { tools, message, reason }全局规则任何原来访问tools.chat的地方迁移后统一写成meta.tools.chat。六、源码视角迁移后的调用链长什么样结合源码可以完整还原 v19 的调用链帮助你验证迁移是否正确解析与入队tools/init.lua 的Tools:execute解析 LLM 返回的工具调用经_resolve_and_prepare_tool深度拷贝工具定义、解析args字符串参数会经vim.json.decode转为 Lua 表、合并opts然后压入 Orchestrator 队列生命周期回调Orchestrator 依次执行handlers.setup()可能动态改写cmds→ 审批流程output.prompt/cmd_string必要时rejected/cancelled→Runner逐条执行cmds执行与回写runner.lua 以(self, args, { input, output_cb, register_job })调用每个函数型cmd同步return或异步output_cb的结果进入output.success/output.error最终通过meta.tools.chat:add_tool_output(...)写回聊天缓冲收尾所有cmds执行完毕后调用handlers.on_exit()触发ToolFinished/ToolsFinished事件。仓库内置的 cmd_tool.lua 是一个完全采用 v19 新签名的参考实现它的handlers.setup(self, meta)在 setup 阶段调用spec.build_cmd(self.args)动态构造命令output.cmd_string(self, meta)供审批展示output.rejected(self, meta)采用vim.tbl_extend(force, ...)合并 message 后转发给helpers.rejected。迁移自定义工具时对照它的写法即可确认签名是否正确。七、如何使用这份升级提示词该文件是提示词库的 Markdown 格式会被 markdown.lua 解析YAML frontmatter 提供元数据## user之后的正文作为用户消息注入聊天。其中#{buffer}是运行时占位符会被替换为当前缓冲区的引用——即提示词所指向的待升级工具所在文件。使用流程无需手动修改本仓库文件在 CodeCompanion chat buffer 中打开提示词库选择器leaderap调出 Action Palette 后选择 Prompt Library或通过 prompt-library 文档描述的方式调用选择Upgrade Toolsv18 → v19提示词将你的自定义工具代码粘贴进当前缓冲区或确保#{buffer}指向包含工具定义的文件发送消息让 LLM 仅修改函数签名与参数访问方式保持业务逻辑不变对照上文第五节速查表人工复核改动。八、迁移检查清单最后整理一份可直接执行的迁移自检清单cmds中所有函数第 3 个参数统一为opts使用异步回调的改为opts.output_cb连续命令中读取前置输出的位置改为opts.inputoutput.success/output.error改为(self, stdout/stderr, meta)内部改用meta.tools.chatoutput.rejected改为(self, meta)用vim.tbl_extend(force, { message ... }, meta or {})合并后调用helpers.rejectedoutput.prompt/output.cmd_string/output.cancelled改为(self, meta)handlers.setup/on_exit/prompt_condition改为(self, meta)全文搜索tools.chat确认已全部替换为meta.tools.chat确认opts.output_cb只调用一次且不与同步return混用业务逻辑除参数访问方式外零改动完成以上检查后你的自定义工具即可在 v19 系列当前仓库为 19.22.0上正常运行进一步了解工具的结构、schema 与审批机制可继续阅读工具扩展指南与 Agent 与工具使用说明。【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

CodeCompanion.nvim 工具 API 升级指南：从 v18 位置参数到 v19 结构化 meta 表的全面迁移

相关推荐

小吃生意冷清怎么办？低谷期的调整动作与心态

Flower (flwr) 开发版本安装指南：uv、pip 与本地构建的完整实践

在 Ember 应用中运行 tsParticles 粒子动画 Demo：安装、启动与源码解析

更多资讯

OpenProject 9.0 新版本特性解读：看板视图、工作包模板与源码实现剖析

高质量SKILL.md写作指南：claude-plugins-community四大插件案例研究

Matter 制造数据流程指南：NXP 平台的证书生成、Provisioning 数据写入与 DAC 私钥安全存储

Newton 多世界（Worlds）机制详解：在单个 Model 中组织、隔离与并行仿真多个独立场景

FastF1 变更日志全解读：从 v3.8.0 到 v3.9.0 的 API 演进、弃用清理与数据可靠性修复

TruckSim重载汽车侧翻控制联合仿真与LTR参数标定

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？