CodeCompanion.nvim 源码贡献指南从开发环境搭建到 Mini.Test 测试与调试实战【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim导读CodeCompanion.nvim 是一个采用 Omakase主厨精选哲学开发的 Neovim AI 编程插件本指南以仓库 CONTRIBUTING.md 为主线完整讲解如何为其提交 PR、搭建本地开发环境Docker/lazy.nvim 两种方式、利用分层日志与 mitmproxy 代理调试请求、使用 Mini.Test 编写并运行测试以及遵循 stylua 与 panvimdoc 完成代码格式化和文档构建。读完本文你将掌握一套可复用的 Neovim 插件级开发工作流能够独立向该项目贡献高质量功能或修复。贡献前的三个原则先讨论再动手贡献 PR 之前请先通过 GitHub Discussions 发起讨论。项目维护者明确表示欢迎改进插件的贡献但拒绝低价值、高臃肿的功能——插件本体已接近 9,000 行 Lua 代码任何新增功能都必须经过权衡。同时项目采用语义化版本Semantic Versioning任何破坏现有 API 的 PR 都极不可能被合并因此贡献前务必检查你的改动是否影响公开接口的兼容性。Omakase精选而非堆砌项目将产品哲学概括为日料中的 omakase交给你了——食客让主厨精心挑选每一道菜。映射到 LLM 插件领域意味着Intentional over exhaustive每个新功能都要放到整个菜单功能全景中权衡而非只看它自身Complementary新功能应当与既有功能相得益彰而不是一个多余的小菜Maintainable每一行新增代码都是维护者承诺长期维护的债务。从源码结构看这一哲学直接体现在目录组织上lua/codecompanion/下的adapters/LLM 提供商适配、interactions/chat/inline/cmd 三大交互、providers/Snacks、Telescope 等集成与utils/分工清晰新功能应当落位到对应模块而非另起炉灶。AI 辅助贡献的红线CodeCompanion 本身就是 AI 辅助开发的工具但维护者明确拒绝vibe-coded式贡献——即用 LLM 生成代码但提交者自己并不理解的内容。需要警惕的红旗信号包括无法解释实现决策、代码与既有架构模式不符、测试看似全面但没有真正覆盖边界情况、出现过度防御式编程与冗长注释等通用 LLM 模式。相反期待的贡献者画像应是先理解代码库再动手用 rules、读测试、探索架构、为自己的每一行代码负责、写出能证明你理解该功能的测试、基于反馈持续迭代PR 是对话而非一次性投递。文档给出的经验法则值得记住用 LLM 创建一个功能或者一个测试但永远不要同时用 LLM 生成两者。标准贡献流程按以下 6 步操作即可打开 discussion 提出想法先确认该功能契合项目目标Fork 仓库从main分支切出你的开发分支在分支上实现功能或修复确保代码遵循项目的编码风格与约定保证代码有充分的测试覆盖与良好文档以清晰的标题和描述提交 Pull Request。高效上手的两个捷径Rules 与测试即文档用内置 Rules 让 LLM 理解架构在 CodeCompanion 仓库内工作时你可以加载内置的 rules 文件让 LLM 掌握插件某个方面的实现方式——这是确保新功能遵循既有实践、让 AI 真正理解架构与设计决策的最佳途径。加载方式有两种通过 Action Palette 选择加载 rules在聊天缓冲区中直接使用/rules斜杠命令。仓库中与 rules 相关的实现位于 lua/codecompanion/interactions/shared/rules/对应的测试位于 tests/interactions/shared/rules/可以对照阅读了解规则解析器的工作机制。把测试当作第二份文档项目拥有约 800 个精心编写的测试它们既是覆盖率保障也是第二来源文档。官方建议直接参照 tests/adapters/test_openai.lua 这类真实测试文件来学习测试写法具体测试运行方式见下文Testing章节。项目结构速览理解仓库布局是贡献的第一步lua/codecompanion/插件核心adapters/不同 LLM 提供商的适配层OpenAI、Anthropic、Gemini、Ollama 等interactions/三大交互形态——chat/聊天缓冲区、inline/行内代码编辑、cmd/命令行编辑providers/与 Snacks.nvim、Telescope.nvim 等外部组件的集成utils/通用工具函数含日志、异步、文件操作等。doc/CodeCompanion 站点文档与 Neovim 帮助文档doc/codecompanion.txtqueries/面向多语言的 Tree-sitter 查询文件cc_symbols.scm等tests/插件各类测试。开发环境搭建前置依赖Neovim 0.11.0测试与运行的最低版本tree-sitter测试所需Tree-sitter 解析器lua-language-serverLSP 支持与类型注解检查styluaLua 代码格式化pandoc文档生成配合 panvimdoc。方式一使用项目内置 Dockerfile仓库根目录提供 Dockerfile可构建包含make工具链含测试的容器# 构建容器镜像 docker build -t codecompanion.nvim . # 拉取依赖并运行测试挂载当前目录、以当前用户身份运行 docker run --rm -ti -u $(id -u):$(id -g) -v $(pwd):/cc -w /cc codecompanion.nvim:latest make deps test方式二lazy.nvim 本地开发配置以下以 lazy.nvim 为例也可使用任意包管理器。核心思路是让插件指向你的本地 Fork{ dir /full/path/to/local/codecompanion.nvim, dev true, dependencies { { nvim-lua/plenary.nvim }, -- 按需补充开发所需的可选依赖 }, opts { opts { log_level DEBUG, -- 开发期间开启详细日志 }, -- 其余配置 } }dev true会让 lazy.nvim 直接使用本地目录而不去拉取远程版本配合log_level DEBUG即可进入开发态。调试与日志分层日志系统CodeCompanion 采用分层日志系统源码见 lua/codecompanion/utils/log.lua。从实现看日志器支持file、notify、echo三种 handler按级别过滤输出并采用非阻塞异步写入async_writer批量落盘避免影响 Neovim 性能。日志级别对应 Neovim 的vim.log.levels共五档ERROR、WARN、INFO、DEBUG、TRACE。默认级别为ERROR见 lua/codecompanion/config.lua开发时可调高require(codecompanion).setup({ opts { log_level DEBUG, -- Options: ERROR, WARN, INFO, DEBUG, TRACE } })日志文件位于 Neovim 的 log 目录stdpath(log)默认文件名codecompanion.logM.get_logfile()即返回该路径。运行:checkhealth codecompanion可查看日志目录位置。gd调试聊天消息历史开发聊天功能时在聊天缓冲区按gd即可打开调试窗口展示当前消息历史你和 LLM 的消息以及适配器设置。其实现位于 lua/codecompanion/interactions/chat/debug.lua调试窗口支持保存与关闭等操作。用代理抓取 LLM 请求/响应当需要排查发给 LLM 提供商的请求与响应时可启用proxy选项将请求转发到代理服务器。底层实现上proxy与allow_insecure定义于 lua/codecompanion/config.lua 的adapters.http.opts下并被 lua/codecompanion/http.lua 及多个适配器Ollama、HuggingFace、Novita、OpenAI Compatible、Copilot 等读取。以 mitmproxy 为例的完整流程安装 mitmproxy启动带 Web 界面的代理并监听 4141 端口mitmweb --set listen_port4141配置 CodeCompanion 指向该代理{ dir /full/path/to/local/codecompanion.nvim, -- 其余配置 ... opts { adapters { opts { allow_insecure true, proxy http://127.0.0.1:4141, }, } -- 其余配置 ... } }此后所有请求都会转发到代理。mitmproxy 的能力远不止查看流量——你可以用自定义脚本/hooks 模拟慢速连接、篡改请求等参考其官方插件addons文档即可。测试体系Mini.Test 实战运行测试项目全部测试基于Mini.Testminiprox 生态的测试框架。在 Makefile 中测试命令封装如下# 运行完整测试套件 make test # 运行指定测试文件 FILEtests/adapters/test_openai.lua make test_file底层实现分别调用MiniTest.run()与MiniTest.run_file($(FILE))并通过scripts/minimal_init.lua在 headless Neovim 中启动测试环境见 scripts/minimal_init.lua。该环境有两点值得注意会安装并编译lua、make、markdown、markdown_inline、yaml等 Tree-sitter 解析器保证渲染一致性强制禁用网络测试中任何真实 HTTP 请求都会直接报错plenary.curl的各方法被替换为抛错函数确保测试确定性——需要响应的测试必须 mock 其调用层。新增功能时请在 tests/ 下对应的测试文件中补充用例。Windows 原生运行测试[!Note] 以下为原生 Windows 指南不适用于 WSL、MSYS2、Cygwin 等 POSIX 模拟环境。需要满足的前置条件git在%PATH%中某种make在%PATH%中C/C 编译器在路径中用于引导 Tree-sitter定义%HOME%环境变量指向%HOMEDRIVE%%HOMEPATH%或%USERPROFILE%在 CodeCompanion 根目录创建deps目录若不存在。make与编译器可来自 Visual Studio Community 2022 的x64 Native Tools Command Prompt提供 NMake 与 Visual C 编译器。在 cmd.exe 中REM 设置环境 IF NOT EXIST deps MD deps SET HOME%HOMEDRIVE%%HOMEPATH% SET PATH%PATH%;C:\Program Files\Git\bin C:\Program Files (x86)\Microsoft Visual Studio\2022\VC\Auxiliary\Build\vcvars64.bat REM 运行全部测试 nmake test REM 运行单个测试套件 nmake FILEtests/interactions/chat/tools/runtime/tests_cmd.lua test_file另外仓库提供 Make.ps1 PowerShell 脚本可执行与make相同的命令format/docs/test/test_file单独运行Make.ps1则一次执行all。注意传给test_file的参数中斜杠必须使用/反斜杠会导致 MiniTest 工作异常。测试技巧让 LLM 帮你写测试面对约 800 个测试的代码库学习成本不低。官方建议把testrules 加载进聊天缓冲区让 LLM 先了解 Mini.Test 的写法同时把 tests/adapters/test_openai.lua 这样的真实测试文件分享给 LLM 作为范例。从 tests/helpers.lua 可以看到测试基建的用心setup_plugin会 mock Copilot 适配器的外部 HTTP 调用mock_http/queue_mock_http_response/get_mock_http_requests提供了一套完整的请求-响应 mock 管线create_mock_adapter可在子 Neovim 实例中构建测试适配器——这些工具都值得在编写新测试时复用。代码风格与规范使用stylua格式化 Lua 代码配置见 stylua.tomlcolumn_width 120、2 空格缩进、Unix 换行、双引号优先等提交 PR 前运行make format实际执行stylua tests/ lua/ -f ./stylua.toml鼓励类型注解参见 lua/codecompanion/types.lua 与 LuaCATS 注解规范这能让 lua-language-server 提供更好的 LSP 支持。构建文档文档使用panvimdoc从 Markdown 源生成。运行make docs从 Makefile 的实现看该命令以 pandoc 驱动、加载 panvimdoc 的 Lua filtersinclude-files.lua、skip-blocks.lua及仓库自带的 scripts/panvimdoc-cleanup.lua把 scripts/vimdoc.md 转换为doc/codecompanion.txtNeovim 帮助文件同时生成带目录toc:true与 Tree-sitter 高亮的文档。此外doc/目录下的 Markdown 源也是站点文档含 doc/usage、doc/configuration、doc/extending 等子模块的输入修改功能时务必同步更新对应文档。贡献检查清单提交 PR 前请逐项确认已在 discussion 中与维护者对齐方向符合 Omakase 哲学未破坏现有 API语义化版本约束功能与测试分别清晰可控功能与测试二选一由 LLM 生成的经验法则代码通过make format遵循 stylua.toml 规范并带类型注解在 tests/ 对应文件补充测试并确认make test全绿同步更新 doc/ 文档并验证make docs可正常生成。遵循这套流程你就能以维护者认可的方式为 CodeCompanion.nvim 贡献代码同时借助其 Rules 与测试体系让 AI 辅助开发真正服务于插件质量的提升。【免费下载链接】codecompanion.nvim✨ AI Coding, Vim Style项目地址: https://gitcode.com/GitHub_Trending/co/codecompanion.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考