CodeCompass

CodeCompass

CodeCompass 帮助开发者应对遗留或现有代码库，为 AI 编码助手提供必要的上下文，从而给出精准的建议。遗留代码对 AI 来说很棘手——它们通常杂乱、过时，而且缺少清晰的文档。CodeCompass 通过 Qdrant Vector Store 分析代码库，并使用 Ollama（本地）或 DeepSeek 等云端 Agent 为 AI 提供支持，再借助其 Agentic RAG 功能，让建议更智能、更贴切。它就像为 AI 提供了一张代码路线图，让你轻松地进行 vibe coding。

---

功能

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

项目状态与路线图

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

• 使用 Qdrant Vector Store 分析代码库。
• 使用 Agentic RAG（检索增强生成）生成智能 AI 建议。
• 灵活集成本地大模型（通过 Ollama，例如 llama3.1:8b、nomic-embed-text:v1.5）和 DeepSeek 等云端大模型。

该项目正在积极维护，就目前的功能集而言已被认为稳定。

未来改进（考虑中）： 虽然核心功能稳健，但未来可能的方向包括：

• 支持更多大模型提供商（例如 OpenAI、Gemini、Claude）。
• 增强 Agent 能力并集成更多工具。
• 改进仓库索引技术，以实现更精准的上下文检索。
• 简化用户配置，进一步优化设置体验。
• 深入集成各类 IDE 和开发工作流。

我们欢迎社区为未来开发贡献力量并提出建议！请参阅我们的 CONTRIBUTING.md。

前置条件

• Node.js v20+（nodejs.org）
• Docker，用于运行 Qdrant（docker.com）
• Ollama（ollama.com）：用于本地大模型和嵌入功能。
  • 所需模型（可通过环境变量配置，详见“配置”部分）：
    • 嵌入模型：nomic-embed-text:v1.5（默认）
    • 建议模型（使用 Ollama 生成建议时）：llama3.1:8b（默认）
• DeepSeek API Key（可选，用于生成云端建议；可从 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  # Default embedding model
     ollama pull llama3.1:8b            # Default Ollama suggestion model
     

     你可以使用 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）。

示例：

# Start server for the current directory on the default port
codecompass

# Start server for a specific repository
codecompass /path/to/your/project

# Start server for the current directory on port 3005
codecompass --port 3005

启动后，CodeCompass 将开始为你的仓库建立索引（如果尚未建立）。MCP 通信主要通过 stdio 处理。实用 HTTP 服务也会在配置的端口（默认 3001）上运行，用于健康检查、索引状态查询，以及接收来自 Git hooks 的仓库更新通知。

实用 HTTP 服务的端口冲突： 如果配置的实用 HTTP 端口已被另一个 CodeCompass 实例占用，新实例将禁用自身的实用 HTTP 服务，并通过 stdio 运行 MCP。其实用 HTTP 相关的 MCP 工具（例如 get_indexing_status、trigger_repository_update）会自动将请求转发到现有实例的 HTTP 实用端点。如果端口被非 CodeCompass 服务占用，新实例将记录错误并退出。Git hooks 通常应指向主要运行中的 CodeCompass 实例所用的 HTTP 端口。

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

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

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": "How is user authentication handled?", "sessionId": "my-session-123"}'
  • 使用 JSON 输出：codecompass agent_query '{"query": "Show me user models"}' --json
• search_code <json_params>：执行语义代码搜索。
  • 示例：codecompass search_code '{"query": "database connection setup"}'
• 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": "optimize this database query"}'
• get_repository_context <json_params>：提供仓库上下文的高级摘要。
  • 示例：codecompass get_repository_context '{"query": "main API components"}'

常规 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 文件：为方便起见，尤其是在本地开发期间，可以将 .env 文件放在使用 CodeCompass 分析的仓库根目录中。CodeCompass 将从该文件加载变量。

下文将介绍如何直接在 shell 中或在系统范围内设置环境变量，随后列出常用变量。

设置环境变量

对于 Linux 和 macOS：

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

export VAR_NAME="value"

例如：

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

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

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

对于 Windows：

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

set VAR_NAME="value"

例如：

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

此设置仅对当前命令提示符会话有效。

使用 PowerShell：

$Env:VAR_NAME = "value"

例如：

$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 "value"

示例：

setx LLM_PROVIDER "deepseek"
setx DEEPSEEK_API_KEY "your_deepseek_api_key_here"

常见环境变量（参考）

以下是重要环境变量的列表。如果选择使用 .env 文件，可以复制此结构。

# --- General Configuration ---
# LOG_LEVEL: Logging level (e.g., error, warn, info, verbose, debug, silly). Default: info
# LOG_LEVEL=info

# --- Qdrant Configuration ---
# QDRANT_HOST: URL for the Qdrant vector store server.
QDRANT_HOST=http://localhost:6333
# COLLECTION_NAME: Name of the Qdrant collection for this repository.
# It's good practice to use a unique name per repository if you manage multiple.
# COLLECTION_NAME=codecompass_default_collection
# QDRANT_SEARCH_LIMIT_DEFAULT: Default number of results to fetch from Qdrant during standard searches. Default: 10
# QDRANT_SEARCH_LIMIT_DEFAULT=10

# --- Ollama Configuration (for local LLM and embeddings) ---
# OLLAMA_HOST: URL for the Ollama server.
OLLAMA_HOST=http://localhost:11434

# --- LLM Provider Configuration ---
# LLM_PROVIDER: Specifies the primary LLM provider for generating suggestions.
# Supported values: "ollama", "deepseek", "openai", "gemini", "claude". Default: "ollama"
LLM_PROVIDER=ollama

# SUGGESTION_MODEL: The specific model to use for suggestions.
# If LLM_PROVIDER="ollama", example: "llama3.1:8b", "codellama:7b"
# If LLM_PROVIDER="deepseek", example: "deepseek-coder"
# If LLM_PROVIDER="openai", example: "gpt-4-turbo-preview", "gpt-3.5-turbo"
# If LLM_PROVIDER="gemini", example: "gemini-pro"
# If LLM_PROVIDER="claude", example: "claude-2", "claude-3-opus-20240229"
# Default for Ollama: "llama3.1:8b"
SUGGESTION_MODEL=llama3.1:8b

# EMBEDDING_PROVIDER: Specifies the provider for generating embeddings.
# Currently, "ollama" is the primary supported embedding provider. Default: "ollama"
EMBEDDING_PROVIDER=ollama

# EMBEDDING_MODEL: The specific model to use for embeddings via Ollama.
# Default: "nomic-embed-text:v1.5"
EMBEDDING_MODEL=nomic-embed-text:v1.5

# --- Cloud Provider API Keys (only needed if using respective providers) ---
# DEEPSEEK_API_KEY: Your API key for DeepSeek.
# DEEPSEEK_API_KEY=your_deepseek_api_key_here

# OPENAI_API_KEY: Your API key for OpenAI.
# OPENAI_API_KEY=your_openai_api_key_here

# GEMINI_API_KEY: Your API key for Google Gemini.
# GEMINI_API_KEY=your_gemini_api_key_here

# CLAUDE_API_KEY: Your API key for Anthropic Claude.
# CLAUDE_API_KEY=your_claude_api_key_here

# --- DeepSeek Specific (Optional) ---
# DEEPSEEK_API_URL: Custom API URL for DeepSeek if not using the default.
# Default: "https://api.deepseek.com/chat/completions"
# DEEPSEEK_API_URL=https://api.deepseek.com/chat/completions
# DEEPSEEK_RPM_LIMIT: Requests per minute limit for DeepSeek. Default: 20
# DEEPSEEK_RPM_LIMIT=20

# --- Agent Configuration ---
# MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY: Maximum number of files to list directly in the generate_suggestion tool's context
# before attempting to summarize the file list using an LLM. Default: 15
# MAX_FILES_FOR_SUGGESTION_CONTEXT_NO_SUMMARY=15

# MAX_SNIPPET_LENGTH_FOR_CONTEXT_NO_SUMMARY: Maximum length of a code snippet to include in context without summarization.
# Snippets longer than this will be summarized by an LLM if available. Default: 1500
# MAX_SNIPPET_LENGTH_FOR_CONTEXT_NO_SUMMARY=1500

# MAX_DIFF_LENGTH_FOR_CONTEXT_TOOL: Maximum length of a git diff to include in context without summarization.
# Diffs longer than this will be summarized by an LLM if available. Default: 3000
# MAX_DIFF_LENGTH_FOR_CONTEXT_TOOL=3000

# AGENT_DEFAULT_MAX_STEPS: Default maximum number of steps (tool calls or LLM responses) the agent will take. Default: 10
# AGENT_DEFAULT_MAX_STEPS=10

# AGENT_ABSOLUTE_MAX_STEPS: Absolute maximum number of steps the agent can take, even if it requests more. Default: 15
# AGENT_ABSOLUTE_MAX_STEPS=15

# MAX_REFINEMENT_ITERATIONS: Maximum number of iterations for query refinement. Default: 3
# MAX_REFINEMENT_ITERATIONS=3

# FILE_INDEXING_CHUNK_SIZE_CHARS: Target size for chunks when indexing large files (in characters). Default: 1000
# FILE_INDEXING_CHUNK_SIZE_CHARS=1000

# FILE_INDEXING_CHUNK_OVERLAP_CHARS: Overlap between chunks when indexing large files (in characters). Default: 200
# FILE_INDEXING_CHUNK_OVERLAP_CHARS=200

# SUMMARIZATION_MODEL: LLM model to use for summarization tasks (e.g., long diffs, long snippets).
# If empty or not set, defaults to the SUGGESTION_MODEL.
# SUMMARIZATION_MODEL= # Example: llama3.1:8b or deepseek-coder

# REFINEMENT_MODEL: LLM model to use for LLM-powered query refinement.
# If empty or not set, defaults to the SUGGESTION_MODEL.
# REFINEMENT_MODEL= # Example: llama3.1:8b or deepseek-coder

# REQUEST_ADDITIONAL_CONTEXT_MAX_SEARCH_RESULTS: Number of search results to fetch when agent uses 'request_additional_context' with type 'MORE_SEARCH_RESULTS'. Default: 20
# REQUEST_ADDITIONAL_CONTEXT_MAX_SEARCH_RESULTS=20

# AGENT_QUERY_TIMEOUT: Timeout in milliseconds for agent's LLM reasoning steps. Default: 180000 (3 minutes)
# AGENT_QUERY_TIMEOUT=180000

注意：直接设置环境变量或通过 MCP 客户端配置设置时，无需创建 .env 文件。以上列表可供参考，列出了变量名称及其用途。对于使用 Ollama 的本地设置，默认设置通常无需配置许多环境变量即可使用，除非你想自定义模型或提供商。如果使用 DeepSeek 等云服务提供商，则必须设置相应的 API_KEY，并调整 LLM_PROVIDER 和 SUGGESTION_MODEL。 启动服务时，还可以通过 --port <number> CLI 参数设置 HTTP 端口；该参数优先于 HTTP_PORT 环境变量和默认值。

故障排除

• 未找到模型（Ollama）：

  • 确保已使用 ollama pull <model_name> 拉取正确的模型名称。
  • 使用 ollama list 验证已安装的模型。
  • 检查 OLLAMA_HOST 环境变量是否正确，以及 Ollama 服务是否可访问。
  • 确保 SUGGESTION_MODEL（如果使用 Ollama 生成建议）和 EMBEDDING_MODEL 环境变量与已拉取的模型一致。

• 连接被拒绝（Ollama/Qdrant）：

  • 确认 Ollama 服务正在运行（例如，运行 ollama serve 或启动 Ollama 应用）。
  • 确认 Qdrant Docker 容器正在运行（docker ps），并且可通过配置的主机/端口访问（默认为 http://localhost:6333）。
  • 如果防火墙设置可能阻止本地连接，请检查相关设置。

• API 密钥问题（DeepSeek、OpenAI、Gemini、Claude）：

  • 仔细检查相应的 API 密钥（例如 DEEPSEEK_API_KEY）是否已正确设置在环境变量或 .env 文件中。
  • 确保密钥有效、未过期且未达到配额上限。
  • 对于 DeepSeek，可以使用 npm run test-deepseek 脚本（如果你的设置中提供了该脚本）诊断连接问题。

• 提供方与模型不匹配：

  • 确保 LLM_PROVIDER 和 SUGGESTION_MODEL 环境变量相互兼容（例如，当 LLM_PROVIDER=deepseek 时，使用 deepseek-coder 这样的 DeepSeek 模型名称）。

• 一般问题：

  • 查看 CodeCompass 日志以获取更详细的错误信息。你可能需要将 LOG_LEVEL=debug 设置为更详细的输出级别。
  • 确保 Node.js 和 Docker 已正确安装并正在运行。

使用 Cursor 进行设置

1. 编辑 ~/.cursor/mcp.json：

   {
     "mcpServers": {
       "codecompass": {
         "command": "npx",
         "args": ["-y", "@alvinveroy/codecompass@latest", "/path/to/your/repo"],
         "env": {
           "DEEPSEEK_API_KEY": "your_deepseek_api_key"
         }
       }
     }
   }
   

2. 将 your_deepseek_api_key 替换为你的 DeepSeek API 密钥（使用 Ollama 时可省略）。你可以在此 env 块中设置“配置”部分列出的任意环境变量（例如 LLM_PROVIDER、SUGGESTION_MODEL），CodeCompass 将使用这些变量。
3. 重启 Cursor。

注意：对于 VSCode 中的 Cline，请在 cline_mcp_settings.json 中进行类似配置（参见 Cline 文档）。以这种方式设置的环境变量也会被 CodeCompass 识别。

参与贡献

Fork、创建分支并提交拉取请求。请参阅 CONTRIBUTING.md。

许可证

MIT 许可证。

审计