nexus/wiki/concepts/Semantic-Index.md

title, type, tags, last_updated

title	type	tags	last_updated
Semantic Index	concept	index code-intelligence navigation	2026-04-20

Definition

Semantic Index（语义索引）是存储代码符号定义、引用关系和悬停文档的持久化数据结构，支持快速代码导航和文档查询。

Navigation Index Format (nav.index.jsonl)

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

Index Schema

Field	Description
symId	符号唯一标识符，格式：sym:<name>
def	定义位置（文件 URI + 行号 + 列号）
refs	引用位置数组
hover	悬停文档内容（Markdown 格式）

Storage Backends

• JSONL：流式写入，适合大规模索引
• SQLite：支持快速随机访问和复杂查询
• LSIF：Language Server Index Format，用于预计算数据导入/导出

Performance Requirements

• 定义查找：<20ms（缓存），<60ms（未缓存）
• 支持 100k+ 符号规模
• 增量更新，不重建整个索引

Connections

• graphd ← 维护 ← Semantic Index
• LSIF (Language Server Index Format) ← 导入/导出 ← Semantic Index