CodeCompanion.nvim 插件开发指南

CodeCompanion.nvim 插件开发指南

codecompanion.nvim ✨ A Copilot Chat experience in Neovim. Supports Anthropic, Ollama and OpenAI LLMs 项目地址: https://gitcode.com/gh_mirrors/co/codecompanion.nvim

项目概述

CodeCompanion.nvim 是一个功能强大的 Neovim 插件，旨在为开发者提供智能代码辅助功能。该项目采用模块化设计，包含约 9000 行 Lua 代码，支持多种大语言模型(LLM)提供商的适配，为开发者提供聊天式编程、内联代码编辑等创新功能。

开发准备

环境要求

1. 基础环境：

   • Neovim 0.10.0 或更高版本
   • Lua 语言服务器(lua-language-server)提供 LSP 支持和类型注解
   • Stylua 工具用于代码格式化

2. 开发工具链：

   • 推荐使用 lazy.nvim 作为包管理器
   • 需要安装 nvim-treesitter 和 plenary.nvim 作为基础依赖

项目结构解析

lua/codecompanion/
├── adapters/        # 不同LLM提供商的适配器
├── strategies/      # 核心功能实现
│   ├── chat/        # 聊天缓冲区实现
│   ├── inline/      # 内联代码编辑
│   └── cmd/         # 命令行编辑
├── providers/       # 外部工具集成
├── utils/           # 工具函数
doc/                 # 文档资源
queries/             # Tree-sitter 查询文件
tests/               # 测试套件

开发流程详解

1. 项目初始化

配置本地开发环境时，建议使用以下 lazy.nvim 配置模板：

{
  dir = "/项目本地路径/codecompanion.nvim",
  dev = true,
  dependencies = {
    { "nvim-treesitter/nvim-treesitter", build = ":TSUpdate" },
    { "nvim-lua/plenary.nvim" },
  },
  opts = {
    log_level = "DEBUG",  -- 开发时启用详细日志
    -- 其他自定义配置
  }
}

2. 调试技巧

日志系统

CodeCompanion 采用分级日志系统，支持以下级别：

• ERROR
• WARN
• INFO
• DEBUG
• TRACE

日志文件默认存储在 Neovim 的日志目录，可通过 :checkhealth codecompanion 命令查看具体位置。

代理调试

使用 mitmproxy 可以拦截和分析与 LLM 提供商的通信：

1. 安装并启动 mitmproxy：

   mitmweb --set listen_port=4141
   

2. 配置插件使用代理：

   opts = {
     adapters = {
       opts = {
         allow_insecure = true,
         proxy = "http://127.0.0.1:4141",
       },
     }
   }
   

聊天调试

在聊天缓冲区中按 gd 可打开调试窗口，查看完整的消息历史记录和适配器设置。

测试体系

测试框架

项目采用 Mini.Test 测试框架，测试覆盖率较高(约 200 个测试用例)。测试不仅是质量保证手段，也是理解代码行为的重要文档。

测试执行

• 运行全部测试：

  make test
  

• 运行单个测试文件：

  FILE=tests/adapters/test_openai.lua make test_file
  

测试开发建议

1. 将 test 工作区加载到聊天缓冲区，让 LLM 辅助理解测试框架
2. 参考现有测试用例(如 test_openai.lua)的结构和模式
3. 新功能必须包含相应的测试用例

代码规范

1. 格式化：

   • 使用 Stylua 进行代码格式化
   • 提交前执行 make format 确保格式统一
   • 配置参考项目根目录的 stylua.toml 文件

2. 类型注解：

   • 鼓励使用类型注解
   • 类型定义参考 lua/codecompanion/types.lua
   • 遵循 LuaCATS 注解规范

3. 文档：

   • 使用 panvimdoc 生成文档
   • 执行 make docs 构建文档

开发最佳实践

1. 利用项目自身功能：

   • 使用 CodeCompanion 的聊天功能辅助开发
   • 加载工作区让 LLM 理解项目上下文

2. 代码索引工具：

   • 推荐使用 VectorCode 建立代码索引
   • 执行 vectorcode vectorise -r 索引项目代码
   • 索引后可实现智能代码片段共享

3. 模块化设计：

   • 新功能应遵循现有模块划分
   • 避免破坏性 API 变更(项目遵循语义化版本)

4. 性能考量：

   • 注意控制插件体积
   • 新功能应提供明显价值，避免功能膨胀

文档构建

项目文档采用 panvimdoc 构建系统，包含：

• 在线文档网站
• Vim 内置帮助文档

构建命令：

make docs

通过遵循这些指南，开发者可以高效地为 CodeCompanion.nvim 贡献代码，同时保持项目的一致性和质量。

codecompanion.nvim ✨ A Copilot Chat experience in Neovim. Supports Anthropic, Ollama and OpenAI LLMs 项目地址: https://gitcode.com/gh_mirrors/co/codecompanion.nvim