内容
# Cortex 索引 — 本地优先的 AI 代码智能引擎
> 为您的代码提供持久的语义操作系统。Cortex 索引将原始源代码转换为高密度、token 优化的知识图谱 (`cortex_build_context`)，为 AI 代理（Claude、Cursor、Antigravity）提供精确的文件间 AST 智能。
---
## ⚡ 主要功能
- 🧠 **上下文构建器 (`cortex_build_context`)**: 生成紧凑、token 优化的上下文包（目标符号 + 调用者 + 被调用者 + 风险评分 + 架构建议），而不是转储数千行原始代码。
- ⚡ **本地优先和高性能**: 纯 Go SQLite WAL 数据库 (`modernc.org/sqlite`)。索引时间 < 150ms，查询延迟 < 0.3ms。零外部依赖。
- 🔌 **22 种本地 MCP 工具**: 与模型上下文协议（MCP v1.0）完全兼容，支持 **Stdio** 和 **HTTP JSON-RPC 2.0**。
- 🔍 **多语言 AST 支持**: Go、TypeScript / JavaScript、Python 和 Rust AST 解析器。
- 🔄 **增量和 Git 感知**: 实时 `fsnotify` 文件监视器（300ms 防抖）和 Git 分支比较器 (`cortex_compare_branches`)。
- 📊 **可视化 Web UI 仪表盘**: 由 **Bun**、Vite、React 19 和 Tailwind CSS 驱动的现代暗黑模式仪表盘。
- 🚀 **CLI 守护进程控制**: 后台守护进程管理 (`cortex start -d`，`cortex stop`)，带有 PID 跟踪。
---
## 🏗️ 架构概述
```
┌─────────────────────────────────────────────────────────────┐
│ AI 代理（Claude / Cursor / IDE） │
└──────────────────────────────┬──────────────────────────────┘
│ JSON-RPC 2.0 (Stdio / HTTP)
┌──────────────────────────────▼──────────────────────────────┐
│ Cortex Index MCP & API 服务器 │
├─────────────────────────────────────────────────────────────┤
│ • 上下文构建引擎 • 图引擎（BFS/DFS） │
│ • 查询规划器和 LRU 缓存 • AST 解析器 v2 │
├─────────────────────────────────────────────────────────────┤
│ 纯 Go SQLite WAL 仓库（index.db） │
└──────────────────────────────▲──────────────────────────────┘
│ 实时索引
┌──────────────────────────────┴──────────────────────────────┐
│ 增量索引器和文件监视器 │
│ Go AST │ TypeScript AST │ Python AST │ Rust AST │
└─────────────────────────────────────────────────────────────┘
```
---
## 🚀 快速入门
### 先决条件
- **Go 1.22+**
- **Bun 1.0+** （用于 UI 仪表盘）
### 1. 全局构建和安装
克隆仓库并运行:
```bash
# 构建 Go 二进制文件（bin/cortex）和 UI 包
make build
# 将 cortex 二进制文件全局安装到 /usr/local/bin（可全局访问）
make install
```
---
## 🛠️ 运行方式
### 选项 A: 在开发模式下同时运行后端和 UI
在 `http://localhost:8080` 上启动 Go API 后端，在 `http://localhost:3000` 上启动 Bun React UI:
```bash
make dev
```
### 选项 B: 运行后台服务器守护进程（PID 模式）
在后台以守护进程运行服务器:
```bash
# 在后台启动服务器守护进程（输出 PID）
cortex start -d
# 输出: ✓ Cortex Index 守护进程已在后台启动 [PID: 14101]
# 检查守护进程运行状态和指标
cortex status
# 停止后台服务器守护进程 PID
cortex stop
# 输出: ✓ Cortex Index 守护进程已停止 [PID: 14101]
```
### 选项 C: 在前台运行服务器
```bash
cortex serve
```
---
## 🪝 自动 Git 钩子和实时文件监视器
在编写代码、切换分支或提交时，保持知识图谱自动同步:
```bash
# 安装 Git 钩子（post-commit、post-checkout、post-merge）
cortex hooks install
# 输出: ✓ 已安装 Cortex Index Git 钩子（post-commit、post-checkout、post-merge）
# 启动实时文件更改监视器（300ms 防抖）
cortex watch
# 删除 Git 钩子时需要
cortex hooks remove
```
---
## 🔌 连接到 MCP（模型上下文协议）
Cortex Index 公开 **22 种本地 MCP 工具**，用于 AI 助手（Claude Desktop、Cursor IDE、Antigravity、Windsurf）。
### 1. 通过 Kilo AI 连接（`~/.config/kilo/kilo.json`）
将 `cortex-index` 添加到 `~/.config/kilo/kilo.json`:
```json
{
"mcp": {
"cortex-index": {
"type": "local",
"command": [
"cortex",
"mcp",
"stdio"
]
}
}
}
```
### 2. 通过 Stdio 连接（Claude Desktop / Antigravity / Cursor）
将 Cortex Index 添加到您的 MCP 客户端配置文件中（例如 `claude_desktop_config.json`）:
```json
{
"mcpServers": {
"cortex-index": {
"command": "cortex",
"args": ["mcp", "stdio"]
}
}
}
```
### 3. 通过 HTTP 传输连接
如果在端口 `8080` 上运行 `cortex serve` 或 `cortex start -d`:
```json
{
"mcpServers": {
"cortex-http": {
"url": "http://localhost:8080/mcp"
}
}
}
```
---
## 🛠️ 22 种本地 MCP 工具参考
| 类别 | MCP 工具名称 | 描述 |
| :--- | :--- | :--- |
| **高级智能** | `cortex_build_context` | 为目标符号生成 token 优化的 AI 上下文包 |
| | `cortex_find_entry_points` | 查找主要入口点、API 路由和处理程序 |
| | `cortex_find_dead_code` | 确定具有零调用者的未引用符号 |
| | `cortex_get_diagnostics` | 深度系统健康、解析错误和未解析符号 |
| | `cortex_compare_branches` | 与 Git 目标分支进行架构差异比较 |
| **代码智能** | `cortex_find_symbol` | 在工作区中按名称搜索符号 |
| | `cortex_get_definition` | 检索符号定义和文件行位置 |
| | `cortex_find_references` | 查找文件中对符号的所有引用 |
| | `cortex_find_callers` | 查找调用目标符号的所有调用者函数 |
| | `cortex_find_callees` | 查找目标符号调用的所有函数 |
| **结构导航** | `cortex_get_file` | 检索文件元数据和包含的符号 |
| | `cortex_get_module` | 检索模块文件和目录包 |
| | `cortex_get_package` | 检索包详细信息和包含的文件 |
| | `cortex_list_symbols` | 列出特定文件中的所有符号 |
| | `cortex_explore_directory` | 探索目录结构和跟踪文件 |
| **架构** | `cortex_get_architecture` | 高级模块架构图 |
| | `cortex_get_dependency_graph` | 依赖关系图（`IMPORTS` 和 `DEPENDS_ON`） |
| | `cortex_get_call_graph` | 符号的层次调用图树 |
| | `cortex_get_type_graph` | 类型层次图（结构体、接口、类） |
| **搜索** | `cortex_search_symbol` | 按查询字符串搜索符号 |
| | `cortex_search_text` | 搜索符号文档注释或函数文本 |
| | `cortex_search_path` | 按相对文件路径搜索文件 |
| **项目智能** | `cortex_get_project_summary` | 工作区统计摘要 |
| | `cortex_get_stats` | 总文件数、符号数、节点数、边数和健康度 |
| | `cortex_get_health` | 健康状态检查 |
| | `cortex_get_recent_changes` | 最近的 Git 分支更改和脏文件 |
---
## 🧪 测试和验证
```bash
# 运行 Go 单元测试套件和 UI 类型检查
make test
```
---
## 📄 许可证
MIT License © 2026 Cortex Index Team.
