内容
# Delfos
Delfos 是一个用于代码库的图内存 **MCP 服务器**。Delfos 在代码仓库上实现了主动重建模型，并将其作为工具暴露给任何兼容 MCP 的代理（Claude Code、Cursor 等）使用，无需了解图内部的实现。
内存访问是一种迭代的、由 LLM 驱动的遍历持久的 **线索 → 标签 → 内容** 图，而不是一次性检索。有关架构概述，请参阅 [`ARCHITECTURE.md`](ARCHITECTURE.md)，有关设计决策和原理，请参阅 [`docs/decisions.md`](docs/decisions.md)。
## 快速入门
### 1. 安装
```bash
pip install delfos # 或：uv add delfos
```
Delfos 为 Python 3.12+ 提供了预编译的轮，因此无需 C++ 工具链。要启用 SCIP 交叉引用工具（`references`、`implementations`、`type_definition`），还需要安装 [`scip-python`](https://github.com/sourcegraph/scip-python)：
```bash
npm install -g @sourcegraph/scip-python
```
### 2. 配置凭证
Delfos 需要一个嵌入端点（和用于 `reconstruct` 的聊天端点）。在您要索引的仓库根目录下创建一个 `.env` 文件，它将在启动时自动加载。复制 [`.env.example`](.env.example) 并编辑。
对于 **托管 OpenAI**，API 密钥是唯一必需的设置（模型和维度默认为 `nomic-embed-text` / 768，或索引时使用的任何值）：
```bash
DELFOS_EMBED_API_KEY=sk-...
```
对于 **本地 OpenAI 兼容服务器**（llama.cpp、Ollama、LM Studio），请将基本 URL 设置为它 - 有关完整的 llama.cpp 演练，请参阅 [`.env.example`](.env.example)。`DELFOS_*` 变量的完整列表及其优先级在下面的 [配置](#配置) 中。
### 3. 索引您的仓库
```bash
delfos index /path/to/repo # 构建 .delfos/ 工作空间
delfos doctor --repo /path/to/repo # 验证工作空间 + 工具链
delfos status --repo /path/to/repo # 检查清单和存储
```
索引写入一个 `.delfos/` 工作空间，位于仓库内：图存储快照、`index.scip` 和一个 `manifest.json`，记录了索引时使用的嵌入模型和维度。查询它只需要凭证 - 模型和维度来自清单。
### 4. 从代理（MCP）使用它
使用 Delfos 的主要方式是作为 MCP 服务器。将您的代理指向 `delfos-mcp` 控制台脚本，并将 `DELFOS_REPO` 设置为已索引的仓库。对于 Claude Code / Cursor，请将其添加到您的 `mcpServers` 配置中：
```json
{
"mcpServers": {
"delfos": {
"command": "delfos-mcp",
"env": { "DELFOS_REPO": "/absolute/path/to/repo" }
}
}
}
```
服务器通过 stdio 以只读模式运行，并暴露了遍历工具（`search`、`traverse_forward`、`traverse_reverse`、`fetch`）、SCIP 工具和 `reconstruct` 提示，教导深度优先遍历规则。凭证可以位于仓库的 `.env` 中（自动加载），而不是在上面的配置中。
### 5. 或从终端查询
您也可以直接在终端中探索图，而无需代理：
```bash
delfos search "如何删除边"
delfos reconstruct "过时的文件重新索引流程" --budget 3
```
`search` 返回语义种子线索；`reconstruct` 运行 LLM 驱动的深度优先遍历（需要配置 `DELFOS_LLM_*` 聊天端点）。
## 架构
两个层在单个边界相遇 - `GraphStore` 抽象基类。没有组件直接接触 C++ 引擎。下面是简要概述；完整的贡献者演练在 [`ARCHITECTURE.md`](ARCHITECTURE.md) 中。
- **`libdelfos/`** - C++ 存储引擎：内存中的 CSR 有向属性图（`graph.hpp`）、USearch 上的 HNSW 矢量索引（`vector_index.hpp`）和通过 FlatBuffers + USearch 原生格式的安全快照持久性（`snapshot.hpp`）。通过 nanobind 绑定公开为 Python 的 `delfos._delfos` 扩展。
- **`delfos.schema`** - 特定于代码的线索-标签-内容模式，作为 Pydantic 模型（`CueNode`、`TagNode`、`ContentNode`）、`Edge` 模型和封闭枚举词汇表。线索和内容节点携带 `source_file` + `git_sha` 来源（用于删除和重新索引；标签在文件之间共享，不携带任何信息），以及可选的嵌入元数据（`embedding_model`）用于嵌入版本控制。
- **`delfos.store`** - `GraphStore` 抽象基类（所有其他组件经过的单个数据库边界）和 `NativeGraphStore`，即 C++ 引擎上的具体后端。
- **`delfos.indexer`** - 构建管道（`parser`、`extractor`、`embedder`、`pipeline`），将仓库转换为图节点和边。
## 配置
Delfos 通过 `DELFOS_*` 环境变量进行配置，按以下优先级（从高到低）解析：
1. 真实环境变量
2. 传递给 `--repo` / `DELFOS_REPO` 的 `.env` 文件 - 在启动时显式加载（复制 `.env.example` 到 `.env` 并编辑）
3. `.delfos/config.toml`（仅限非机密设置 - 将 API 密钥排除在外）
4. `.delfos/manifest.json`，在索引时记录（`embed.model` / `embed.dim` 仅 - 这些必须与索引时使用的匹配）
5. 内置默认值（`nomic-embed-text`，维度 768）
| 变量 | 目的 |
|---|---|
| `DELFOS_EMBED_MODEL` | 嵌入模型名称 |
| `DELFOS_EMBED_DIM` | 嵌入输出维度（必须与模型匹配） |
| `DELFOS_EMBED_BASE_URL` | OpenAI 兼容的嵌入端点（未设置 = OpenAI） |
| `DELFOS_EMBED_API_KEY` | 嵌入端点 API 密钥（当 `DELFOS_EMBED_BASE_URL` 未设置时需要） |
| `DELFOS_LLM_MODEL` | 用于 `reconstruct` 跳跃规划器的聊天模型 |
| `DELFOS_LLM_BASE_URL` | OpenAI 兼容的聊天端点（未设置 = OpenAI） |
| `DELFOS_LLM_API_KEY` | 聊天端点 API 密钥 |
| `DELFOS_REPO` | 要服务的仓库的 `.delfos/` 工作空间（仅限 `delfos-mcp`） |
| `DELFOS_VERBOSE` | `1` 表示每个文件的 DEBUG 日志记录 |
对已索引仓库的查询只需要凭证 - 模型和维度来自清单。`DELFOS_EMBED_BASE_URL` 和 `DELFOS_LLM_BASE_URL` 分别独立指向其自己的端点；它们之间没有回退。
## 开发
该项目使用 [uv](https://docs.astral.sh/uv/)。
```bash
uv sync # 安装 Python 依赖项 + 开发工具
uv pip install -e . # 构建 + 安装 _delfos C++ 扩展
uv run ruff check . # 校验
uv run ruff format . # 格式化
uv run pyright # 类型检查（严格）
uv run pytest # 运行测试
```
### C++ 引擎
独立的 C++ 构建/测试流程使用 Ninja 生成器（`brew install ninja`）：
```bash
cmake --preset debug # 配置（ASan + UBSan）
cmake --build build/debug
ctest --test-dir build/debug --output-on-failure
```
> **注意：** CMake 4.x 放弃了与 `cmake_minimum_required < 3.5` 的兼容性，而源自 USearch 依赖项仍声明该兼容性。构建通过 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`（连接到 `pyproject.toml` 和 CMake 预设）进行配置，以便在现代 CMake 下工作。
