CodeCompass
CodeCompass通过为AI编码助手提供所需的上下文来提供即时建议，帮助开发人员处理遗留或现有的代码库。遗留代码对人工智能来说很难——它通常很混乱、过时，而且缺乏清晰的文档。CodeCompass通过Qdrant Vector Store分析您的代码库，并使用Ollama（本地）或DeepSeek等云代理为AI提供支持，利用其代理RAG功能使建议更智能、更相关，从而解决了这个问题。这就像给你的AI一个代码的路线图，这样你就可以毫不费力地感知代码。
______________________________________________________________________
特性
- 代码库分析：映射存储库的结构和依赖关系，现在支持通过自动分块对非常大的文件进行索引。
- 基于代理RAG的智能AI环境：采用复杂的检索增强生成（RAG）方法。中央银行
agent_query该工具智能地编排内部功能以收集全面的上下文。这包括分析git diff信息（如果很大，则进行汇总）、动态汇总大量文件列表或代码片段等，确保人工智能建议具有高度相关性。 - 智能代理编排：核心
agent_query该工具允许人工智能计划和执行多步骤任务。它可以主动使用一套内部功能来：
- 搜索代码(capability_searchCodeSnippets) - 检索完整文件内容(capability_getFullFileContent)，对大文件进行摘要。 - 列出目录内容(capability_listDirectory). - 获取相邻的代码块(capability_getAdjacentFileChunks). - 分析存储库概述，包括差异和相关片段(capability_getRepositoryOverview). - 请求更多搜索结果(capability_fetchMoreSearchResults)如果查询复杂，则需要更多的处理时间。
- 灵活的设置：在Ollama本地运行或连接到DeepSeek等云AI。
- 高度可配置性：提供广泛的环境变量来微调索引参数、代理行为（如循环步骤和细化迭代）、上下文处理限制以及用于摘要等任务的特定LLM模型。
项目状态和路线图
当前状态： CodeCompass已成功实现其核心功能，包括：
- 使用Qdrant矢量存储进行代码库分析。
- 用于智能人工智能建议的代理RAG（检索增强生成）。
- 通过Ollama与本地LLM灵活集成（例如。，
llama3.1:8b,nomic-embed-text:v1.5)以及基于云的LLM，如DeepSeek。
该项目因其当前的功能集而得到了积极的维护，并被认为是稳定的。
未来的增强功能（正在考虑中）： 虽然核心功能强大，但未来的潜在方向包括：
- 支持更广泛的LLM提供商（例如OpenAI、Gemini、Claude）。
- 更复杂的代理功能和额外的工具集成。
- 增强的存储库索引技术，可实现更精确的上下文检索。
- 简化的用户配置和更流畅的设置体验。
- 与各种IDE和开发工作流程进行更深入的集成。
我们欢迎社区为未来的发展做出贡献和建议！请查看我们的 贡献.md.
先决条件
- Node.js v20+()
- 码头工人 对于Qdrant()
- 奥拉马 (ollama.com)：用于本地LLM和嵌入功能。
- 所需型号（可通过环境变量配置，请参阅配置部分）： - 嵌入模型： nomic-embed-text:v1.5 （默认） - 建议模型（如果使用Olama提供建议）： llama3.1:8b （默认）
- DeepSeek API密钥 （可选，用于基于云的建议；从获取 深度求索)
安装
- 安装Ollama:
- Linux:
curl -fsSL https://ollama.com/install.sh | sh- macOS/Windows：从下载 ollama.com. - 确保Ollama应用程序正在运行（或正在运行 ollama serve 如果您安装了CLI版本，请在终端中安装）。 - 拉取默认模型（或您要配置的模型）：
ollama pull nomic-embed-text:v1.5 # Default embedding model
ollama pull llama3.1:8b # Default Ollama suggestion model您可以通过以下方式验证已安装的型号 ollama list.
- 安装Qdrant:
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant在以下位置验证 http://localhost:6333/dashboard.
- 安装CodeCompass:
npx -y @alvinveroy/codecompass@latest这将在全球范围内安装CodeCompass。然后，您可以从任何目录运行它。
用法
CodeCompass可以在两种主要模式下运行：作为服务器（默认）或作为客户端对正在运行的服务器执行特定工具。
1.运行CodeCompass服务器：
要启动CodeCompass服务器，请导航到git存储库的根目录并运行：
codecompass [repoPath] [--port ][repoPath]（可选）：要CodeCompass分析的存储库的路径。如果省略，则默认为当前目录(.).--port（可选）：指定服务器的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钩子接收存储库更新通知。
实用程序HTTP服务器的端口冲突： 如果配置的实用程序HTTP端口正被另一个CodeCompass实例使用，则新实例将禁用其自己的实用程序HTTP服务器，并使用 stdio MCP。其实用程序相关的MCP工具（如 get_indexing_status, trigger_repository_update)将自动将请求中继到现有实例的HTTP实用程序端点。如果端口被非CodeCompass服务占用，新实例将记录错误并退出。Git钩子通常应该针对主运行CodeCompass实例的HTTP端口。
2.通过CLI客户端模式执行工具：
为了执行特定的工具，CodeCompass CLI会生成一个专用的服务器实例，并通过以下方式与之通信 stdio 使用模型上下文协议（MCP）。
codecompass [json_parameters] [--repo
] [--json] [--port ]- ``：要执行的工具的名称（见下面的列表）。
[json_parameters]（可选）：包含工具参数的JSON字符串。对于不带参数的工具，可以省略此项或使用空JSON对象{}可以使用。- `--repo
或 -r （可选）：指定工具上下文的存储库路径。默认为当前目录(.`).生成的服务器将使用此存储库。
--json或-j（可选）：从工具中输出原始JSON响应。可用于脚本编写或调试。--port（可选）：为生成的服务器实例指定实用程序HTTP端口。这主要是为了在生成的服务器需要与其他实例交互或其实用程序端口需要特定时保持一致性，尽管该工具的核心MCP通信是通过stdio.
CLI客户端执行的可用工具：
agent_query：协调回答复杂查询的能力。
- 例子： 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：执行语义代码搜索。
- 例子： 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：切换建议模型/提供者。
- 例子： codecompass switch_suggestion_model '{"model": "deepseek-coder", "provider": "deepseek"}'
get_session_history：检索会话ID的历史记录。（需要sessionId在params中）。
- 例子： codecompass get_session_history '{"sessionId": "my-session-123"}'
generate_suggestion：生成代码建议。
- 例子： codecompass generate_suggestion '{"query": "optimize this database query"}'
get_repository_context：提供存储库上下文的高级摘要。
- 例子： 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提供支持的代理RAG功能可确保您的AI理解代码的上下文以获得精确的结果。CLI客户端模式提供了另一种直接与CodeCompass工具交互的方式。
配置
CodeCompass的配置依赖于环境变量。这些变量可以通过多种方式设置：
- 直接在你的壳里：用于当前会话或通过将它们添加到shell的配置文件脚本中来持久化。
- 全系统：在操作系统级别设置它们。
- 通过MCP客户端设置：如果您通过Cursor或Cline等MCP客户端使用CodeCompass，您通常可以在各自的配置文件中定义环境变量（例如。，
mcp.json光标）。这在“使用光标设置”一节中有详细介绍。 - 使用a
.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（常见默认值）：
~/.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上永久设置环境变量，请执行以下操作：
- 在“开始”菜单中搜索“环境变量”。
- 点击“编辑系统环境变量”。
- 在“系统属性”窗口中，单击“环境变量…”按钮。
- 您可以设置用户变量（针对当前用户）或系统变量（针对所有用户）。单击所需部分下的“新建…”。
- 输入变量名称（例如。，
LLM_PROVIDER)以及价值（例如。，deepseek). - 在所有窗口上单击“确定”。您可能需要重新启动命令提示符、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 是必要的。 HTTP端口也可以通过以下方式设置 --port 启动服务器时的CLI参数，其优先级高于 HTTP_PORT 环境变量和默认值。
故障排除
- 未找到型号（Ollama）：
- 确保您已使用以下命令提取了正确的型号名称 ollama pull . - 验证已安装的型号 ollama list. - 检查你的 OLLAMA_HOST 环境变量正确，Ollama服务器可访问。 - 确保 SUGGESTION_MODEL （如果使用Olama作为建议）和 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 环境变量是兼容的（例如，使用DeepSeek模型名称，如 deepseek-coder 当 LLM_PROVIDER=deepseek).
- 一般问题：
- 有关更详细的错误消息，请查看CodeCompass日志。您可能需要设置 LOG_LEVEL=debug 以获得更详细的输出。 - 确保Node.js和Docker已正确安装并正在运行。
使用光标进行设置
- 编辑
~/.cursor/mcp.json:
{
"mcpServers": {
"codecompass": {
"command": "npx",
"args": ["-y", "@alvinveroy/codecompass@latest", "/path/to/your/repo"],
"env": {
"DEEPSEEK_API_KEY": "your_deepseek_api_key"
}
}
}
}- 替换
your_deepseek_api_key使用您的DeepSeek API密钥（或省略Ollama）。您可以设置“配置”部分中列出的任何环境变量（例如。，LLM_PROVIDER,SUGGESTION_MODEL)在这个env块，CodeCompass将使用它们。 - 重新启动游标。
备注：对于VSCode中的Cline，在中进行类似配置 cline_mcp_settings.json （参见 Cline Docs).以这种方式设置的环境变量也将被CodeCompass识别。
贡献
分叉、分支并提交拉取请求。看 贡献.md.
