Sync: add semantic index and lsp notes
This commit is contained in:
32
wiki/concepts/Incremental-Graph-Update.md
Normal file
32
wiki/concepts/Incremental-Graph-Update.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: "Incremental Graph Update"
|
||||
type: concept
|
||||
tags: [graph, real-time, file-watching]
|
||||
sources: [lsp-index-engineer]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
增量图谱更新（Incremental Graph Update）是 LSP/Index Engineer 维护代码语义图谱的核心策略——通过文件监视器（File Watchers）和 Git hooks 检测变更，仅更新受影响的图谱子图，而非全量重建，从而实现亚秒级增量同步。
|
||||
|
||||
## Trigger Mechanisms
|
||||
|
||||
- **文件监视器**：监听文件系统变更，触发相关符号的重新索引
|
||||
- **Git hooks**：在提交前后执行图谱增量更新，确保版本控制集成
|
||||
- **WebSocket 推送**：将图谱差异实时推送至连接的客户端
|
||||
|
||||
## Consistency Guarantees
|
||||
|
||||
LSP/Index Engineer 的原子性保证：图谱更新必须是原子性的——从不将图谱置于不一致状态。具体约束：
|
||||
- 每个符号有且仅有一个定义节点
|
||||
- 所有边必须引用有效节点 ID
|
||||
- 文件节点必须在符号节点之前创建
|
||||
- 导入边必须解析到实际文件/模块节点
|
||||
|
||||
## Performance Impact
|
||||
|
||||
增量更新使得图谱在 100k+ 符号规模下依然保持亚秒级响应：
|
||||
- 文件保存后 → 图谱更新传播至客户端 <500ms
|
||||
- 单个文件变更 → 仅更新受影响子图，而非全量重建
|
||||
- WebSocket 推送延迟 <50ms
|
||||
36
wiki/concepts/LSP-317-Specification.md
Normal file
36
wiki/concepts/LSP-317-Specification.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: "LSP 3.17 Specification"
|
||||
type: concept
|
||||
tags: [protocol, language-server, standardization]
|
||||
sources: [lsp-index-engineer]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
Language Server Protocol 3.17（LSP 3.17）是 Microsoft 发起的语言服务器协议的最新版本，定义了编辑器/IDE 与语言服务器之间的标准化 JSON-RPC 通信规范，使得不同语言可以有统一的方式提供代码智能功能（跳转到定义、查找引用、悬停文档等）。
|
||||
|
||||
## Core Components
|
||||
|
||||
- **JSON-RPC 2.0**：基于 JSON 的远程过程调用协议
|
||||
- **Server Capabilities**：服务器声明其支持的功能（如 definitionProvider、referencesProvider）
|
||||
- **Client Capabilities**：客户端声明其支持的功能
|
||||
- **Lifecycle**：initialize → initialized → shutdown → exit
|
||||
- **textDocument/* 请求**：textDocument/definition、textDocument/references、textDocument/hover 等
|
||||
|
||||
## Why LSP 3.17
|
||||
|
||||
LSP/Index Engineer 严格遵循 LSP 3.17 规范进行所有客户端通信，正确处理每个语言服务器的能力协商。LSP 3.17 相比早期版本增加了：
|
||||
- 增量同步（Incremental同步）
|
||||
- Call Hierarchy 和 Type Hierarchy
|
||||
- 更完整的诊断能力
|
||||
- 更好的多根工作区支持
|
||||
|
||||
## Implementation Note
|
||||
|
||||
LSP/Index Engineer 的核心约束：**永远不要假设能力，必须始终检查服务器能力响应**。这确保了 graphd 能与任何符合 LSP 规范的服务器协作。
|
||||
|
||||
## Aliases
|
||||
- LSP
|
||||
- Language Server Protocol
|
||||
- LSP 3.17
|
||||
40
wiki/concepts/Performance-Contracts.md
Normal file
40
wiki/concepts/Performance-Contracts.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "Performance Contracts"
|
||||
type: concept
|
||||
tags: [performance, latency, engineering]
|
||||
sources: [lsp-index-engineer]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
性能契约（Performance Contracts）是 LSP/Index Engineer 定义的量化性能约束体系，为 graphd 系统的每个关键操作设定明确的延迟、吞吐量和资源上限，作为所有实现决策的北极星指标。
|
||||
|
||||
## Contract Table
|
||||
|
||||
| Operation | Constraint | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| `/graph` endpoint | <100ms | 数据集 <10k 节点 |
|
||||
| `/nav/:symId` (cached) | <20ms | 缓存命中 |
|
||||
| `/nav/:symId` (uncached) | <60ms | 缓存未命中 |
|
||||
| WebSocket event stream | <50ms latency | 端到端推送延迟 |
|
||||
| Memory usage | <500MB | 典型项目 |
|
||||
| Go-to-definition | <150ms | 任意符号 |
|
||||
| Hover documentation | <60ms | 悬停响应 |
|
||||
| Graph update propagation | <500ms | 文件保存后 |
|
||||
| Symbol scale | 100k+ symbols | 无性能降级 |
|
||||
|
||||
## Measurement Strategy
|
||||
|
||||
- **基准测试**：每次提交后运行基准测试套件
|
||||
- **Profiling**：识别性能瓶颈并优先处理
|
||||
- **P99 监控**：关注 P99 而非平均值，确保长尾性能
|
||||
|
||||
## Optimization Techniques
|
||||
|
||||
- 内存映射文件（Memory-mapped files）
|
||||
- 零拷贝网络传输（io_uring）
|
||||
- 无锁数据结构（Lock-free data structures）
|
||||
- SIMD 优化图操作
|
||||
- 批量 LSP 请求以减少往返开销
|
||||
- 主动缓存 + 精确失效
|
||||
36
wiki/concepts/Semantic-Index-Infrastructure.md
Normal file
36
wiki/concepts/Semantic-Index-Infrastructure.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
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 流式推送图谱差异
|
||||
Reference in New Issue
Block a user