nexus/wiki/concepts/Semantic-Index-Infrastructure.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
Semantic Index Infrastructure	concept	indexing code-intelligence persistence	lsp-index-engineer	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

{"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 流式推送图谱差异