greysquirr3l/coraline
GitHub: greysquirr3l/coraline
面向 AI 助手的本地代码图谱索引器，支持 28 种语言的语义搜索和符号级分析。
Stars: 3 | Forks: 0
# 🧵 Coraline
### 面向 AI 助手的快速本地代码智能工具
**语义代码索引 • 符号级编辑 • 100% Rust • MCP Server**
[](LICENSE-MIT)
[](https://www.rust-lang.org/)
## 🚀 什么是 Coraline？
**Coraline** 是一个 Rust 实现，结合了两个强大编码工具的最佳理念：
- **[CodeGraph](https://github.com/colbymchenry/codegraph)** - 用于高效 AI 探索的语义代码知识图谱
- **[Serena](https://github.com/oraios/serena)** - 符号级代码理解和编辑工具
Coraline 使用 Rust 从头构建，提供：
- ⚡ **原生性能** - 快速索引和查询，无 Node.js 开销
- 🧠 **语义搜索** - 使用向量嵌入按含义查找代码
- 🔧 **符号级工具** - 为 AI 助手提供 IDE 级别的精度
- 🔒 **100% 本地** - 所有处理均在您的机器上进行
- 🌐 **MCP 集成** - 适用于 Claude Desktop、Claude Code 和其他 MCP 客户端
## ✨ 关键特性
### 源自 CodeGraph
- **语义知识图谱** - 预索引的符号关系和调用图
- **多语言支持** - 支持 33 种语言，包括 TypeScript、Rust、Python、Go、C#、Java、C/C++、Ruby、Bash、PHP、Swift、Kotlin、Markdown、TOML
- **向量嵌入** - 使用本地 ONNX 模型进行语义代码搜索
- **影响分析** - 了解代码更改会带来什么影响
- **Git 集成** - 提交时自动同步以保持索引最新
### 源自 Serena
- **符号级操作** - 在函数/类/方法级别查找、读取和编辑代码
- **引用解析** - 在整个代码库中查找对符号的所有引用
- **精确编辑** - 在符号之前/之后插入，替换符号主体
- **项目记忆** - 为项目上下文提供持久化知识存储
- **智能上下文构建** - 高效地为 AI 助手收集相关代码
## 📦 安装
### 从 crates.io 安装（推荐）
```
cargo install coraline
```
这会将 `coraline` 二进制文件构建并安装到您的 Cargo bin 目录，并将其添加到您的 `PATH` 中。
| 平台 | 安装位置 |
|----------|-----------------|
| Linux / macOS | `~/.cargo/bin/coraline` |
| Windows | `%USERPROFILE%\.cargo\bin\coraline.exe` |
### 预编译二进制文件
从 [Releases 页面](https://github.com/greysquirr3l/coraline/releases) 下载适合您平台的最新版本压缩包：
| 平台 | 压缩包 |
|----------|---------|
| Linux x86\_64 | `coraline-linux-x86_64.tar.gz` |
| Linux ARM64 | `coraline-linux-aarch64.tar.gz` |
| macOS ARM64 (Apple Silicon) | `coraline-macos-aarch64.tar.gz` |
| Windows x86\_64 | `coraline-windows-x86_64.exe.zip` |
解压压缩包并将二进制文件移动到您的 `PATH` 中的某个位置：
```
# Linux / macOS
tar xzf coraline-*.tar.gz
sudo mv coraline /usr/local/bin/
# Windows (PowerShell)
Expand-Archive coraline-windows-x86_64.exe.zip .
# 将 coraline.exe 移动到您的 PATH 目录中，例如：
Move-Item coraline.exe "$env:USERPROFILE\.cargo\bin\"
```
### 从源码构建
```
git clone https://github.com/greysquirr3l/coraline.git
cd coraline
cargo install --path crates/coraline --force
```
### 启用 LLM / 语义搜索（可选）
默认情况下，Coraline 安装时**不包含** ONNX / 向量嵌入支持，以保持二进制文件小巧且无构建依赖。要启用语义搜索（`coraline_semantic_search` MCP 工具和 `embed`/`model` CLI 命令），请使用 `embeddings` 功能进行编译：
```
# 从 crates.io
cargo install coraline --features embeddings
# 从源代码
cargo install --path crates/coraline --features embeddings --force
```
`embeddings` 功能会引入 `ort` (ONNX Runtime)、`tokenizers` 和 `ndarray`。在生成嵌入之前必须下载兼容的模型：
```
# 从 HuggingFace 下载量化模型 (~25 MB)
coraline model download
# 为索引项目生成 embeddings
coraline embed
# 检查存在哪些模型文件
coraline model status
```
模型默认存储在 `~/.coraline/models/` 中，并在所有项目间共享。`embed` 命令也接受 `--download` 参数，可以将两个步骤合并为一步：
```
coraline embed --download
```
## 🚀 快速开始
### 1. 初始化项目
```
cd your-project
coraline init
```
这将创建一个 `.coraline/` 目录，其中包含：
- 用于代码图的 SQLite 数据库
- 配置文件
- 项目记忆
### 2. 索引您的代码
```
coraline index
```
Coraline 将：
- 使用 tree-sitter 解析源文件
- 提取符号（函数、类、方法、类型）
- 构建调用图和引用映射
### 3. 作为 MCP Server 使用
配置您的 MCP 客户端以使用 Coraline：
**对于 Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)：**
```
{
"mcpServers": {
"coraline": {
"command": "/path/to/coraline",
"args": ["serve", "--mcp"],
"env": {}
}
}
}
```
**对于 Claude Code (工作区中的 `.claude/mcp.json`)：**
```
{
"mcpServers": {
"coraline": {
"command": "coraline",
"args": ["serve", "--mcp"]
}
}
}
```
## 💻 CLI 使用
```
coraline init [path] # Initialize project
coraline index [path] # Build code graph
coraline sync [path] # Incremental update (git-diff based)
coraline status [path] # Show project status and paths
coraline stats [path] # Show index statistics
coraline query
# Search symbols
coraline context # Build AI context
coraline callers # Find what calls a symbol
coraline callees # Find what a symbol calls
coraline impact # Analyze change impact
coraline config [--set key=val] # Read or update configuration
coraline hooks install|remove # Manage git post-commit hook
coraline serve --mcp # Start MCP server
```
完整文档请参阅 [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)。
## 🔌 MCP 工具
作为 MCP server 运行时，Coraline 暴露了 **25 个工具**（启用向量嵌入时为 26 个），均以 `coraline_` 为前缀。
完整参考请参阅 [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)。
### 图谱工具
| 工具 | 描述 |
| ------ | ------------- |
| `coraline_search` | 按名称或模式查找符号 |
| `coraline_callers` | 查找调用某符号的代码 |
| `coraline_callees` | 查找某符号调用的代码 |
| `coraline_impact` | 分析变更影响范围 |
| `coraline_dependencies` | 从某个节点出发的传出依赖图 |
| `coraline_dependents` | 传入依赖图 —— 哪些代码依赖于某节点 |
| `coraline_path` | 查找两个节点之间的路径 |
| `coraline_stats` | 按语言、种类和边类型的详细统计 |
| `coraline_find_symbol` | 查找带有丰富元数据的符号 + 可选主体 |
| `coraline_get_symbols_overview` | 列出文件中的所有符号 |
| `coraline_find_references` | 查找对某符号的所有引用 |
| `coraline_node` | 获取完整的节点详细信息和源代码 |
### 上下文工具
| 工具 | 描述 |
| ------ | ------------- |
| `coraline_context` | 为 AI 任务构建结构化上下文 |
### 文件与配置工具
| 工具 | 描述 |
| ------ | ------------- |
| `coraline_read_file` | 读取文件内容 |
| `coraline_list_dir` | 列出目录内容 |
| `coraline_get_file_nodes` | 获取文件中的所有已索引节点 |
| `coraline_status` | 显示项目索引统计 |
| `coraline_sync` | 触发增量索引同步 |
| `coraline_get_config` | 读取项目配置 |
| `coraline_update_config` | 更新配置值 |
| `coraline_semantic_search` | 向量相似度搜索（需要嵌入支持） |
### 记忆工具
| 工具 | 描述 |
| ------ | ------------- |
| `coraline_write_memory` | 写入或更新项目记忆 |
| `coraline_read_memory` | 检索已存储的记忆 |
| `coraline_list_memories` | 列出所有记忆 |
| `coraline_delete_memory` | 删除记忆 |
| `coraline_edit_memory` | 通过字面量或正则替换编辑记忆 |
## 🏗️ 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ AI Assistant (MCP Client) │
│ (Claude, VS Code, etc.) │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Coraline MCP Server │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Graph Tools │ │ Symbol Tools │ │ Memory Tools │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ └──────────────────┼──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Core Engine (Rust) │ │
│ │ • tree-sitter parser │ │
│ │ • SQLite database │ │
│ │ • Vector embeddings │ │
│ │ • Reference resolver │ │
│ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 数据流
1. **解析**：tree-sitter 提取 AST 和符号
2. **存储**：节点和边存储在 SQLite 中
3. **解析**：引用被解析为定义
4. **嵌入**：符号被嵌入以进行语义搜索 (ONNX)
5. **查询**：图遍历 + 向量相似度
6. **服务**：通过 MCP 协议返回结果
## 🌐 支持的语言
Coraline 使用 tree-sitter 进行快速、准确的代码解析。当前支持：
### ✅ 已完全实现
| 语言 | 解析器 | 状态 | 备注 |
| ---------- | -------- | -------- | ------- |
| TypeScript | tree-sitter-typescript | ✅ Full | 函数、类、方法、接口 |
| JavaScript | tree-sitter-javascript | ✅ Full | ES6+, JSX 支持 |
| Rust | tree-sitter-rust | ✅ Full | 完整符号提取 |
| Python | tree-sitter-python | ✅ Full | 类、函数、方法 |
| Go | tree-sitter-go | ✅ Full | 包、函数、结构体 |
| Java | tree-sitter-java | ✅ Full | 类、方法、接口 |
| C | tree-sitter-c | ✅ Full | 函数、结构体、类型定义 |
| C++ | tree-sitter-cpp | ✅ Full | 类、模板、命名空间 |
| C# (.NET) | tree-sitter-c-sharp | ✅ Full | ASP.NET Core, Blazor, .razor 文件 |
| Ruby | tree-sitter-ruby | ✅ Full | 类、模块、方法 |
| Bash | tree-sitter-bash | ✅ Full | Shell 脚本、函数 |
| Dart | tree-sitter-dart | ✅ Full | 类、函数、Widget |
| Elixir | tree-sitter-elixir | ✅ Full | 模块、函数、宏 |
| Elm | tree-sitter-elm | ✅ Full | 函数、类型、模块 |
| Erlang | tree-sitter-erlang | ✅ Full | 模块、函数 |
| Fortran | tree-sitter-fortran | ✅ Full | 子程序、函数、模块 |
| Groovy | tree-sitter-groovy | ✅ Full | 类、方法、闭包 |
| Haskell | tree-sitter-haskell | ✅ Full | 函数、类型、类型类 |
| Julia | tree-sitter-julia | ✅ Full | 函数、类型、模块 |
| Kotlin | tree-sitter-kotlin-ng | ✅ Full | 类、函数、对象 |
| Lua | tree-sitter-lua | ✅ Full | 函数、表、模块 |
| Markdown | tree-sitter-markdown-fork | ✅ Full | 文档、标题、列表 |
| MATLAB | tree-sitter-matlab | ✅ Full | 函数、脚本 |
| Nix | tree-sitter-nix | ✅ Full | Derivations、函数 |
| Perl | tree-sitter-perl | ✅ Full | 包、子程序 |
| PHP | tree-sitter-php | ✅ Full | 类、函数、方法 |
| PowerShell | tree-sitter-powershell | ✅ Full | 函数、cmdlet、脚本 |
| R | tree-sitter-r | ✅ Full | 函数、脚本 |
| Scala | tree-sitter-scala | ✅ Full | 类、对象、特质 |
| Swift | tree-sitter-swift | ✅ Full | 类、结构体、函数 |
| TOML | tree-sitter-toml-ng | ✅ Full | 配置、表、键 |
| YAML | tree-sitter-yaml | ✅ Full | 结构、映射 |
| Zig | tree-sitter-zig | ✅ Full | 函数、结构体 |
### 🔄 进行中
| 语言 | 状态 | 备注 |
| ---------- | -------- | ------- |
| Liquid | ⏸️ Pending | 解析器 API 兼容性问题 |
## ⚙️ 配置
配置文件位于 `.coraline/config.toml`。`coraline init` 会创建一个带注释的模板。
```
[indexing]
max_file_size = 1048576 # 1 MB
batch_size = 100
[context]
max_nodes = 20
max_code_blocks = 5
max_code_block_size = 1500
traversal_depth = 1
[sync]
git_hooks_enabled = true
[vectors]
enabled = false # ONNX embedding support (pending stable ort 2.0)
```
完整参考请参阅 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
## 📊 测试
```
# 运行所有测试
cargo test --all-features
# 运行并输出
cargo test --all-features -- --nocapture
# 运行特定集成测试文件
cargo test --test context_test
```
当前状态：**38/38 测试通过**
完整测试结构请参阅 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。
## 📚 文档
| 文档 | 描述 |
|---|---|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 系统设计和数据模型 |
| [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | 完整 MCP 工具参考 |
| [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | 所有 CLI 命令和参数 |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | 配置指南 |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | 构建、测试和贡献 |
## 🤝 贡献
欢迎贡献！有关构建设置、代码风格以及如何添加新工具和语言解析器，请参阅 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。
## 📄 许可证
根据以下任一许可证授权：
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) 或 )
- MIT ([LICENSE-MIT](LICENSE-MIT) 或 )
由您选择。
## 🙏 致谢
Coraline 的灵感来源于并基于以下项目的思想构建：
- **[CodeGraph](https://github.com/colbymchenry/codegraph)** 作者 Colby McHenry - 用于 AI 的语义代码图
- **[Serena](https://github.com/oraios/serena)** 作者 Oraios AI - 符号级代码智能
- **[tree-sitter](https://tree-sitter.github.io/)** - 快速、增量式解析库
## 🔗 参考资料
- CodeGraph:
- Serena:
- MCP:
- tree-sitter:
**用 🦀 Rust 为 AI 编程社区构建**
[报告 Bug](https://github.com/greysquirr3l/coraline/issues) · [请求功能](https://github.com/greysquirr3l/coraline/issues)
标签：AI 辅助编程, CNCF毕业项目, Graph RAG, IDE 插件, IPv6支持, MCP Server, Rust, SQLite, Tree-sitter, 云安全监控, 代码搜索, 代码理解, 代码索引, 可视化界面, 向量嵌入, 多语言支持, 大模型工具, 威胁情报, 安全测试框架, 开发者工具, 影响分析, 本地代码智能, 符号编辑, 网络流量审计, 语义搜索, 通知系统, 静态分析