---
title: "Semantic Index Infrastructure"
type: concept
tags: [indexing, code-intelligence, persistence]
sources: [lsp-index-engineer]
last_updated: 2026-04-25
---

## Definition

语义索引基础设施（Semantic Index Infrastructure）是 LSP/Index Engineer 构建的核心数据管道——将 LSP 语义数据（符号定义、引用、悬停文档）持久化为标准化索引格式，支持快速启动、增量更新和跨语言统一查询。

## Core Components

- **nav.index.jsonl**：导航索引行格式，存储符号 ID、定义位置、引用列表、悬停内容
- **LSIF 导入/导出**：Language Server Index Format，支持预计算语义数据的标准化交换
- **SQLite/JSON 缓存层**：持久化层，支持快速启动和低延迟查询
- **WebSocket 实时推送**：图谱变更通过 WebSocket 实时推送至客户端

## nav.index.jsonl Format

```jsonl
{"symId":"sym:AppController","def":{"uri":"file:///src/controllers/app.php","l":10,"c":6}}
{"symId":"sym:AppController","refs":[
  {"uri":"file:///src/routes.php","l":5,"c":10},
  {"uri":"file:///tests/app.test.php","l":15,"c":20}
]}
{"symId":"sym:AppController","hover":{"contents":{"kind":"markdown","value":"```php\nclass AppController extends BaseController\n```\nMain application controller"}}}
```

## Design Principles

- **原子性更新**：从不将图谱置于不一致状态
- **增量构建**：通过文件监视器和 Git hooks 触发增量更新
- **零重启启动**：缓存层确保热启动无需重新索引
- **可序列化**：支持 WebSocket 流式推送图谱差异