# 快速开始
<cite>
**本文档中引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [autodev-config.json](file://autodev-config.json)
- [src/cli/args-parser.ts](file://src/cli/args-parser.ts)
- [src/cli/tui-runner.ts](file://src/cli/tui-runner.ts)
- [src/mcp/server.ts](file://src/mcp/server.ts)
- [src/mcp/http-server.ts](file://src/mcp/http-server.ts)
- [src/code-index/config-manager.ts](file://src/code-index/config-manager.ts)
- [src/code-index/embedders/ollama.ts](file://src/code-index/embedders/ollama.ts)
- [src/code-index/embedders/openai-compatible.ts](file://src/code-index/embedders/openai-compatible.ts)
- [src/code-index/embedders/openai.ts](file://src/code-index/embedders/openai.ts)
- [src/code-index/interfaces/config.ts](file://src/code-index/interfaces/config.ts)
</cite>
## 目录
1. [简介](#简介)
2. [安装依赖](#安装依赖)
3. [启动MCP服务器](#启动mcp服务器)
4. [连接到IDE](#连接到ide)
5. [使用交互式TUI](#使用交互式tui)
6. [执行API语义搜索](#执行api语义搜索)
7. [配置文件详解](#配置文件详解)
8. [端到端示例](#端到端示例)
9. [故障排除](#故障排除)
## 简介
`@autodev/codebase` 是一个平台无关的代码分析库，提供语义搜索能力和MCP（模型上下文协议）服务器支持。本指南将引导您完成从安装到首次搜索的完整流程，帮助您快速上手使用该工具。
**Section sources**
- [README.md](file://README.md#L1-L340)
## 安装依赖
要使用 `@autodev/codebase`，您需要先安装并启动以下三个核心服务：Ollama、ripgrep 和 Qdrant。
### 1. 安装和启动 Ollama
Ollama 用于提供嵌入模型服务。
```bash
# 安装 Ollama (macOS)
brew install ollama
# 启动 Ollama 服务
ollama serve
# 在新终端中拉取嵌入模型
ollama pull dengcao/Qwen3-Embedding-0.6B:Q8_0
```
### 2. 安装 ripgrep
ripgrep 用于快速代码库索引。
```bash
# 安装 ripgrep (macOS)
brew install ripgrep
# 或在 Ubuntu/Debian 上
sudo apt-get install ripgrep
# 或在 Arch Linux 上
sudo pacman -S ripgrep
```
### 3. 安装和启动 Qdrant
Qdrant 是向量数据库，用于存储和检索代码嵌入。
```bash
# 使用 Docker 启动 Qdrant 容器
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
```
### 4. 验证服务运行状态
确保所有服务都已正确启动。
```bash
# 检查 Ollama
curl http://localhost:11434/api/tags
# 检查 Qdrant
curl http://localhost:6333/collections
```
### 5. 安装 Autodev-codebase
通过 npm 全局安装 `@autodev/codebase`。
```bash
npm install -g @autodev/codebase
```
**Section sources**
- [README.md](file://README.md#L37-L134)
## 启动MCP服务器
MCP（Model Context Protocol）服务器允许IDE通过HTTP协议与代码库进行交互。
### 启动MCP服务器
在您的项目目录中启动MCP服务器：
```bash
cd /my/project
codebase mcp-server
```
您也可以指定自定义端口和主机：
```bash
codebase mcp-server --port=3002 --host=localhost
```
### MCP服务器选项
| 选项 | 描述 | 默认值 |
|------|------|-------|
| `--port=<port>` | HTTP服务器端口 | 3001 |
| `--host=<host>` | HTTP服务器主机 | localhost |
启动后，您将看到类似以下的输出：
```
🔍 Codebase MCP Server running at http://localhost:3001
📁 Workspace: /my/project
🌐 MCP endpoint: http://localhost:3001/mcp
```
**Section sources**
- [README.md](file://README.md#L145-L158)
- [src/cli/args-parser.ts](file://src/cli/args-parser.ts#L1-L160)
- [src/mcp/http-server.ts](file://src/mcp/http-server.ts#L1-L517)
## 连接到IDE
配置您的IDE以连接到MCP服务器。以Claude Desktop为例：
### 配置IDE
在IDE的配置文件中添加以下内容：
```json
{
"mcpServers": {
"codebase": {
"url": "http://localhost:3001/mcp"
}
}
}
```
对于不支持SSE MCP的客户端，可以使用以下配置：
```json
{
"mcpServers": {
"codebase": {
"command": "codebase",
"args": [
"stdio-adapter",
"--server-url=http://localhost:3001/mcp"
]
}
}
}
```
### MCP服务器功能
- **主页**: `http://localhost:3001` - 服务器状态和配置
- **健康检查**: `http://localhost:3001/health` - JSON状态端点
- **MCP端点**: `http://localhost:3001/mcp` - StreamableHTTP MCP协议端点
**Section sources**
- [README.md](file://README.md#L288-L318)
- [src/mcp/http-server.ts](file://src/mcp/http-server.ts#L1-L517)
## 使用交互式TUI
交互式TUI（文本用户界面）模式提供了一个丰富的终端界面来探索代码库。
### 启动TUI模式
```bash
# 基本用法：索引当前目录作为代码库
codebase
# 带自定义选项
codebase --demo
codebase --path=/my/project
codebase --path=/my/project --log-level=info
```
### CLI选项
| 选项 | 描述 | 默认值 |
|------|------|-------|
| `--path=<path>` | 工作空间路径 | 当前目录 |
| `--demo` | 在工作空间中创建演示文件 | false |
| `--force` | 忽略缓存强制重新索引 | false |
| `--log-level=<level>` | 日志级别 | error |
**Section sources**
- [README.md](file://README.md#L161-L175)
- [src/cli/args-parser.ts](file://src/cli/args-parser.ts#L1-L160)
- [src/cli/tui-runner.ts](file://src/cli/tui-runner.ts#L1-L379)
## 执行API语义搜索
通过MCP服务器的API进行语义搜索。
### 可用MCP工具
- **`search_codebase`** - 通过语义向量搜索代码库
- 参数: `query` (字符串), `limit` (数字), `filters` (对象)
- 返回: 格式化的搜索结果，包含文件路径、分数和代码块
### 搜索示例
```bash
# 使用curl进行搜索
curl -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "callTool",
"params": {
"name": "search_codebase",
"arguments": {
"query": "如何实现用户认证"
}
}
}'
```
**Section sources**
- [README.md](file://README.md#L319-L334)
- [src/mcp/server.ts](file://src/mcp/server.ts#L1-L309)
## 配置文件详解
`@autodev/codebase` 使用分层配置系统，优先级从高到低为：CLI参数 > 项目配置文件 > 全局配置文件 > 内置默认值。
### 配置文件位置
- 全局: `~/.autodev-cache/autodev-config.json`
- 项目: `./autodev-config.json`
- CLI: 直接传递参数
### 配置文件结构
```json
{
"isEnabled": true,
"isConfigured": true,
"embedder": {
"provider": "ollama",
"model": "dengcao/Qwen3-Embedding-0.6B:Q8_0",
"dimension": 1024,
"baseUrl": "http://localhost:11434"
},
"qdrantUrl": "http://localhost:6333"
}
```
### 配置选项
| 选项 | 类型 | 描述 | 默认值 |
|------|------|------|-------|
| `isEnabled` | boolean | 启用/禁用代码索引功能 | `true` |
| `embedder.provider` | string | 嵌入提供者 (`ollama`, `openai`, `openai-compatible`) | `ollama` |
| `embedder.model` | string | 嵌入模型名称 | `dengcao/Qwen3-Embedding-0.6B:Q8_0` |
| `embedder.dimension` | number | 向量维度大小 | `1024` |
| `embedder.baseUrl` | string | 提供者API基础URL | `http://localhost:11434` |
| `embedder.apiKey` | string | API密钥（用于OpenAI/兼容提供者） | - |
| `qdrantUrl` | string | Qdrant向量数据库URL | `http://localhost:6333` |
| `qdrantApiKey` | string | Qdrant API密钥（如果启用身份验证） | - |
| `searchMinScore` | number | 搜索结果的最小相似度分数 | `0.4` |
**Section sources**
- [README.md](file://README.md#L181-L287)
- [autodev-config.json](file://autodev-config.json#L1-L10)
- [src/code-index/config-manager.ts](file://src/code-index/config-manager.ts#L1-L335)
- [src/code-index/interfaces/config.ts](file://src/code-index/interfaces/config.ts#L1-L61)
## 端到端示例
从初始化项目到执行第一次搜索的完整示例。
### 1. 初始化项目
```bash
# 创建新项目
mkdir my-project
cd my-project
# 初始化npm项目
npm init -y
```
### 2. 安装依赖
```bash
# 安装autodev-codebase
npm install -g @autodev/codebase
```
### 3. 创建配置文件
创建 `autodev-config.json` 文件：
```json
{
"isEnabled": true,
"embedder": {
"provider": "ollama",
"model": "dengcao/Qwen3-Embedding-0.6B:Q8_0",
"dimension": 1024,
"baseUrl": "http://localhost:11434"
},
"qdrantUrl": "http://localhost:6333"
}
```
### 4. 启动MCP服务器
```bash
# 启动MCP服务器
codebase mcp-server --port=3001
```
### 5. 执行第一次搜索
在另一个终端中，使用curl执行搜索：
```bash
curl -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "callTool",
"params": {
"name": "search_codebase",
"arguments": {
"query": "hello world"
}
}
}'
```
**Section sources**
- [README.md](file://README.md#L37-L340)
- [autodev-config.json](file://autodev-config.json#L1-L10)
- [src/mcp/server.ts](file://src/mcp/server.ts#L1-L309)
- [src/mcp/http-server.ts](file://src/mcp/http-server.ts#L1-L517)
## 故障排除
### 常见问题
1. **服务未启动**: 确保Ollama和Qdrant服务已正确启动。
2. **配置验证失败**: 检查配置文件中的`baseUrl`和`apiKey`是否正确。
3. **索引失败**: 使用`--force`参数强制重新索引。
### 调试信息
- 查看日志输出，使用`--log-level=info`或`--log-level=debug`获取更多详细信息。
- 检查网络连接，确保MCP服务器端口未被占用。
**Section sources**
- [README.md](file://README.md#L37-L340)
- [src/cli/tui-runner.ts](file://src/cli/tui-runner.ts#L1-L379)
- [src/mcp/http-server.ts](file://src/mcp/http-server.ts#L1-L517)
