CodeCompass

CodeCompass 帮助开发者处理遗留或现有代码库，通过提供AI编码助手所需的上下文来给出精准建议。遗留代码对AI来说很难处理——它通常混乱、过时且缺乏清晰的文档。CodeCompass 通过使用 Qdrant 向量存储分析代码库，并利用 Ollama（本地）或像 DeepSeek 这样的云代理（其Agentic RAG特性）来使建议更智能和相关。这就像给你的AI一个代码地图，让你可以轻松地与代码互动。

---

功能

• 代码库分析：映射仓库的结构和依赖关系，现在支持通过自动分块索引非常大的文件。
• 智能AI上下文与Agentic RAG：采用先进的检索增强生成（RAG）方法。核心的agent_query工具智能地协调内部能力以收集全面的上下文。这包括分析git diff信息（如果很大则进行总结），动态总结广泛的文件列表或代码片段等，确保AI建议高度相关。
• 智能代理编排：核心的agent_query工具允许AI规划并执行多步骤任务。它可以主动使用一系列内部能力：
  • 搜索代码（capability_searchCodeSnippets）
  • 获取完整文件内容（capability_getFullFileContent），对于大文件进行总结。
  • 列出目录内容（capability_listDirectory）。
  • 获取相邻代码块（capability_getAdjacentFileChunks）。
  • 分析仓库概览，包括差异和相关代码片段（capability_getRepositoryOverview）。
  • 请求更多搜索结果（capability_fetchMoreSearchResults）或更多处理时间，如果查询复杂。
• 灵活设置：本地运行Ollama或连接到如DeepSeek这样的云AI。
• 高度可配置：提供广泛的环境变量以微调索引参数、代理行为（如循环步骤和细化迭代）、上下文处理限制以及特定的任务如总结的LLM模型。

项目状态和路线图

当前状态： CodeCompass 已成功实现其核心功能，包括：

• 使用 Qdrant 向量存储进行代码库分析。
• 使用 Agentic RAG（检索增强生成）进行智能AI建议。
• 通过 Ollama（例如，llama3.1:8b，nomic-embed-text:v1.5）和基于云的LLM如DeepSeek进行灵活集成。

该项目正在积极维护，并认为其当前功能集是稳定的。

未来改进（考虑中）： 虽然核心功能已经很强大，但潜在的未来方向包括：

• 支持更广泛的LLM提供商（例如，OpenAI，Gemini，Claude）。
• 更复杂的代理能力和额外的工具集成。
• 提高仓库索引技术，以便更精确地检索上下文。
• 简化用户配置，提供更加流畅的设置体验。
• 与各种IDE和开发工作流程进行更深的集成。

我们欢迎社区贡献和对未来发展的建议！请参阅我们的CONTRIBUTING.md。

预备条件

• Node.js v20+ (nodejs.org)
• Docker 用于 Qdrant (docker.com)
• Ollama (ollama.com)：用于本地LLM和嵌入式能力。
  • 所需模型（可以通过环境变量配置，见配置部分）：
    • 嵌入模型：nomic-embed-text:v1.5（默认）
    • 建议模型（如果使用Ollama进行建议）：llama3.1:8b（默认）
• DeepSeek API密钥（可选，用于基于云的建议；从Deepseek获取）

安装

1. 安装Ollama：

   • Linux：

     curl -fsSL https://ollama.com/install.sh | sh
     

   • macOS/Windows：从ollama.com下载。
   • 确保Ollama应用程序正在运行（或者如果你安装了CLI版本，则在终端中运行ollama serve）。
   • 拉取默认模型（或你打算配置的模型）：

     ollama pull nomic-embed-text:v1.5  # 默认嵌入模型
     ollama pull llama3.1:8b            # 默认Ollama建议模型
     

     你可以使用ollama list验证已安装的模型。

2. 安装Qdrant：

   docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
   

   在http://localhost:6333/dashboard验证。

3. 安装CodeCompass：

   npx -y @alvinveroy/codecompass@latest
   

   这会全局安装CodeCompass。然后可以从任何目录运行它。

使用

CodeCompass 可以在两种主要模式下运行：作为服务器（默认）或作为客户端来针对正在运行的服务器执行特定工具。

1. 运行CodeCompass服务器：

要启动CodeCompass服务器，请导航到git仓库的根目录并运行：

codecompass [repoPath] [--port <number>]

• [repoPath]（可选）：CodeCompass要分析的仓库路径。如果省略，默认为当前目录（.）。
• --port <number>（可选）：指定服务器的HTTP端口。这会覆盖HTTP_PORT环境变量和默认端口（3001）。

示例：

# 在默认端口上启动当前目录的服务器
codecompass

# 启动特定仓库的服务器
codecompass /path/to/your/project

# 在端口3005上启动当前目录的服务器
codecompass --port 3005

一旦启动，CodeCompass将开始索引你的仓库（如果尚未索引）。MCP通信主要通过stdio处理。还会在配置的端口（默认3001）上运行一个实用HTTP服务器，用于健康检查、索引状态和接收来自Git钩子的仓库更新通知。

实用HTTP服务器端口冲突： 如果配置的实用HTTP端口被另一个CodeCompass实例占用，新实例将禁用自己的实用HTTP服务器并仅使用stdioMCP。其实用相关的MCP工具（如get_indexing_status，trigger_repository_update）将自动将请求转发到现有实例的HTTP实用端点。如果该端口被非CodeCompass服务占用，新实例将记录错误并退出。Git钩子应一般指向主运行CodeCompass实例的HTTP端口。

2. 通过CLI客户端模式执行工具：

要执行特定工具，CodeCompass CLI会启动一个专用服务器实例并通过stdio使用模型上下文协议（MCP）与其通信。

codecompass <tool_name> [json_parameters] [--repo <path>] [--json] [--port <number>]

• <tool_name>：要执行的工具名称（见下文列表）。
• [json_parameters]（可选）：包含工具参数的JSON字符串。对于不接受参数的工具，可以省略或使用空的JSON对象{}。
• --repo <path>或-r <path>（可选）：指定工具上下文的仓库路径。默认为当前目录（.）。启动的服务器将使用此仓库。
• --json或-j（可选）：输出工具的原始JSON响应。适用于脚本或调试。
• --port <number>（可选）：指定启动服务器实例的实用HTTP端口。主要用于一致性，如果启动的服务器需要与其他实例交互或其实用端口需要特定，尽管工具的核心MCP通信是通过stdio进行的。

可用于CLI客户端执行的工具：

• agent_query <json_params>：协调能力以回答复杂查询。
  • 示例：codecompass agent_query '{"query": "用户认证是如何处理的？", "sessionId": "my-session-123"}'
  • 带JSON输出：codecompass agent_query '{"query": "显示用户模型"}' --json
• search_code <json_params>：执行语义代码搜索。
  • 示例：codecompass search_code '{"query": "数据库连接设置"}'
• get_changelog：检索项目的CHANGELOG.md。
  • 示例：codecompass get_changelog
• get_indexing_status：获取仓库索引的当前状态。（如果另一个CC实例为主实例，可能会转发）
  • 示例：codecompass get_indexing_status --json
• trigger_repository_update：触发仓库的重新索引。（可能会转发）
  • 示例：codecompass trigger_repository_update
• switch_suggestion_model <json_params>：切换建议模型/提供商。
  • 示例：codecompass switch_suggestion_model '{"model": "deepseek-coder", "provider": "deepseek"}'
• get_session_history <json_params>：检索会话ID的历史记录。（需要参数中的sessionId）。
  • 示例：codecompass get_session_history '{"sessionId": "my-session-123"}'
• generate_suggestion <json_params>：生成代码建议。
  • 示例：codecompass generate_suggestion '{"query": "优化这个数据库查询"}'
• get_repository_context <json_params>：提供仓库上下文的高层次概述。
  • 示例：codecompass get_repository_context '{"query": "主要API组件"}'

通用CLI命令：

• codecompass --help 或 codecompass -h：显示帮助消息。
• codecompass --version 或 codecompass -v：显示CodeCompass版本。
• codecompass changelog [--verbose]：显示项目变更日志。

---

设置好CodeCompass后，可以在Cursor或其他AI工具中使用自然语言提示来与代码库直观互动。由Qdrant和Ollama/DeepSeek驱动的Agentic RAG特性确保AI理解代码的上下文以获得精确的结果。CLI客户端模式提供了另一种直接与CodeCompass工具互动的方式。

配置

CodeCompass依赖于环境变量进行配置。这些变量可以通过多种方式设置：

1. 直接在你的shell中：对于当前会话或持久化，通过将其添加到shell的配置脚本中。
2. 系统范围：在操作系统级别设置它们。
3. 通过MCP客户端设置：如果你通过像Cursor或Cline这样的MCP客户端使用CodeCompass，你通常可以在各自的配置文件（例如Cursor的mcp.json）中定义环境变量。这在“使用Cursor设置”部分中有详细说明。
4. 使用.env文件：为了方便，特别是在本地开发期间，你可以在使用CodeCompass分析的仓库根目录放置一个.env文件。CodeCompass将从该文件加载变量。

以下是直接在shell或系统范围内设置环境变量的说明，随后是一个常见变量的列表。

设置环境变量

对于Linux和macOS：

你可以在当前终端会话中使用export命令设置环境变量：

export VAR_NAME="值"

例如：

export LLM_PROVIDER="deepseek"
export DEEPSEEK_API_KEY="your_deepseek_api_key_here"

这些设置仅在当前会话中有效。要使其永久化，将这些export行添加到shell的配置文件中：

• 对于Bash（常见的默认值）：~/.bashrc或~/.bash_profile
• 对于Zsh（常见的macOS）：~/.zshrc 编辑完文件后，重新加载它（例如source ~/.bashrc或source ~/.zshrc）或打开一个新的终端。

对于Windows：

使用命令提示符（cmd.exe）：

set VAR_NAME="值"

例如：

set LLM_PROVIDER="deepseek"
set DEEPSEEK_API_KEY="your_deepseek_api_key_here"

这仅设置当前命令提示符会话中的变量。

使用PowerShell：

$Env:VAR_NAME = "值"

例如：

$Env:LLM_PROVIDER = "deepseek"
$Env:DEEPSEEK_API_KEY = "your_deepseek_api_key_here"

这仅设置当前PowerShell会话中的变量。

要在Windows上永久设置环境变量：

1. 在开始菜单中搜索“环境变量”。
2. 单击“编辑系统环境变量”。
3. 在系统属性窗口中，点击“环境变量...”按钮。
4. 你可以设置用户变量（针对当前用户）或系统变量（针对所有用户）。在所需部分下点击“新建...”。
5. 输入变量名（例如LLM_PROVIDER）和值（例如deepseek）。
6. 点击所有窗口上的“确定”。你可能需要重启命令提示符、PowerShell甚至计算机才能完全生效。

或者，要永久设置用户环境变量（从命令提示符需要新的命令提示符才能看到效果）：

setx VAR_NAME "值"

例如：

setx LLM_PROVIDER "deepseek"
setx DEEPSEEK_API_KEY "your_deepseek_api_key_here"

常见环境变量（参考）

这里是一些重要的环境变量列表。如果你选择使用.env文件，可以复制这种结构。

# --- 通用配置 ---
# LOG_LEVEL: 日志级别（例如，error，warn，info，verbose，debug，silly）。默认：info
# LOG_LEVEL=info

# --- Qdrant配置 ---
# QDRANT_HOST: Qdrant向量存储服务器的URL。
QDRANT_HOST=http://localhost:6333
# COLLECTION_NAME: 此仓库的Qdrant集合名称。
# 如果管理多个仓库，最好为每个仓库使用唯一名称。
# COLLECTION_NAME=codecompass_default_collection
# QDRANT_SEARCH_LIMIT_DEFAULT: 标准搜索期间从Qdrant获取的结果数量。默认：10
# QDRANT_SEARCH_LIMIT_DEFAULT=10

# --- Ollama配置（用于本地LLM和嵌入）---
# OLLAMA_HOST: Ollama服务器的URL。
OLLAMA_HOST=http://localhost:11434

# --- LLM提供商配置 ---
# LLM_PROVIDER: 指定生成建议的主要LLM提供商。
# 支持的值："ollama"，"deepseek"，"openai"，"gemini"，"claude"。默认："ollama"
LLM_PROVIDER=ollama

# SUGGESTION_MODEL: 用于建议的具体模型。
# 如果LLM_PROVIDER="ollama"，例如："llama3.1:8b"，"codellama:7b"
# 如果LLM_PROVIDER="deepseek"，例如："deepseek-coder"
# 如果LLM_PROVIDER="openai"，例如："gpt-4-turbo-preview"，"gpt-3.5-turbo"
# 如果LLM_PROVIDER="gemini"，例如："gemini-pro"
# 如果LLM_PROVIDER="claude"，例如："claude-2"，"claude-3-opus-20240229"
# 默认为Ollama："llama3.1:8b"
SUGGESTION_MODEL=llama3.1:8b

# EMBEDDING_PROVIDER: 指定生成嵌入的提供商。
# 目前，"ollama"是主要支持的嵌入提供商。默认："ollama"
EMBEDDING_PROVIDER=ollama

# EMBEDDING_MODEL: 通过Ollama使用的嵌入具体模型。
# 默认："nomic-embed-text:v1.5"
EMBEDDING_MODEL=nomic--embed-text:v1.5

# --- 云提供商API密钥（仅在使用相应提供商时需要）---
# DEEPSEEK_API_KEY: 你的DeepSeek API密钥。
# DEEPSEEK_API_KEY=your_deepseek_api_key_here

# OPENAI_API_KEY: 你的OpenAI API密钥。
# OPENAI_API_KEY=your_openai_api_key_here

# GEMINI_API_KEY: 你的Google Gemini API密钥。
# GEMINI_API_KEY=your_gemini_api_key_here

# CLAUDE_API_KEY: 你的Anthropic Claude API密钥。
# CLAUDE_API_KEY=your_claude_api_key_here

# --- DeepSeek特定（可选）---
# DEEPSEEK_API_URL: 如果不使用默认值，自定义DeepSeek API URL。
# 默认："https://api.deepseek.com/chat/completions"
# DEEPSEEK_API_URL=https://api.deepseek.com/chat/completions
# DEEPSEEK_RPM_LIMIT: DeepSeek的每分钟请求限制。默认：20
# DEEPSEEK_RPM_LIMIT=20

# --- 代理配置 ---
# MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY: 在尝试使用LLM总结文件列表之前，直接列出在generate_suggestion工具上下文中的最大文件数。默认：15
# MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY=1
# MAX_SNIPPET_LENGTH_FOR_CONTEXT_NO_SUMMARY: 包含在上下文中而不进行总结的最大代码片段长度。
# 超过此长度的片段将被LLM总结（如果可用）。默认：1500
# MAX_SNIPPET_LENGTH_FOR_CONTEXT_NO_SUMMARY=1500

# MAX_DIFF_LENGTH_FOR_CONTEXT_TOOL: 包含在上下文中而不进行总结的最大git diff长度。
# 超过此长度的diff将被LLM总结（如果可用）。默认：3000
# MAX_DIFF_LENGTH_FOR_CONTEXT_TOOL=3000

# AGENT_DEFAULT_MAX_STEPS: 代理将采取的默认最大步骤数（工具调用或LLM响应）。默认：10
# AGENT_DEFAULT_MAX_STEPS=10

# AG