tsl-devkit/lsp-server/框架.md

📡 CORE & PROTOCOL LAYER core/ server.hpp/.cpp dispatcher.hpp/.cpp 连接管理 请求路由 响应处理 protocol/ protocol.hpp

transform/ common.hpp facade.hpp/.inl transformer.*

LSP类型定义 类型转换 Position/Range 序列化/反序列化

scheduler/ async_executor.hpp/.cpp 异步任务执行 线程池管理 🔌 PROVIDER LAYER (LSP Handlers) provider/

base/ (注册&接口) bootstrap. interface.

核心功能模块: initialize/ text_document/ workspace/ call_hierarchy/

completion_item/ code_action/ code_lens/ ...

20+ LSP请求处理器

text_document/ (核心功能) completion.* hover.* definition.* implementation.* did_open.* did_change.*

→ Symbol → Symbol → Symbol → Symbol → Document → Document

调用 service/ 层进行实际处理

⚙️ SERVICE LAYER (业务逻辑 + 三区域符号存储) service/symbol/ symbol.hpp/.cpp 符号服务主接口

detail/symbol/ symbol_types.hpp PositionKey, RangeKey SymbolSignature

三区域仓库:

system_repo.* ~50KB/文件 系统库轻量索引 workspace_repo.* ~100KB/文件 工作区文件索引 editing_repo.* (?) ~1MB/文件 完整符号表 ⚠️ 需新增! service/parser/ parser.hpp/.cpp

• Tree-sitter语法解析 • 增量解析优化 • 触发DocumentParsed事件 • ParseTsfFile() 完整解析

service/document/ document.hpp/.cpp

• 文档内容管理 • 版本控制 • OpenDocument() • UpdateDocument()

service/base/ (事件驱动) event_bus.hpp events.hpp bootstrap.*

DocumentOpened → Parser → DocumentParsed → Symbol构建

service/utils/ text_coordinates.*

• 位置计算 • 行列转换 • 范围处理

🧬 LANGUAGE LAYER (语言语义分析) language/ast/ node_types.hpp AST节点定义(variant) UnitDef, ClassDef, FunctionDef, VarDecl... deserializer.hpp/.cpp TSTree → AST 转换

核心数据结构示例: struct UnitDef { std::string name; Location location; std::optional<UsesClause> uses; vector<ASTNode> interface_stmts; vector<ASTNode> impl_stmts; }; using ASTNode = variant< UnitDef, ClassDef, FunctionDef... >;

language/symbol/ symbol.hpp/.cpp 符号类层次 table.hpp/.cpp 符号表 + GlobalTable builder.hpp/.cpp AST → Symbol构建器

符号类型体系: Symbol (base) ├─ Variable (变量/参数) ├─ Function (函数 + body_scope) └─ Method (继承Function) ├─ Class (类 + members Table) ├─ Constant (常量) └─ Unit (interface + impl Tables)

完整语义信息 ~1MB/文件

language/keyword/ types.hpp 关键字类型枚举 repo.hpp/.cpp 关键字仓库

用途: • 语法验证 (识别保留字) • 补全过滤 (避免建议关键字) • 高亮支持 (提供关键字列表)

示例关键字: begin, end, if, then, else class, function, procedure var, const, type unit, interface, implementation uses, private, public, published

🌳 TREE-SITTER LAYER (C语法解析引擎) tree-sitter/ grammar.json parser.c node-types.json

→ 生成CST (Concrete Syntax Tree) → 增量解析 | 错误恢复 | 高性能

调用服务 构建符号表 解析触发 AST→Symbol TSTree 📋 图例 普通模块 服务模块 轻量存储 完整表 调用关系 数据流转

⚠️ 红色部分需新增文件

💡 架构要点 1️⃣ 三层数据流: 源代码 → TSTree (tree-sitter) → AST (language/ast) → Symbol (language/symbol) → 索引 (service/symbol) 2️⃣ 三区域存储: SystemRepo(50KB) + WorkspaceRepo(100KB) + EditingRepo(1MB) = 分层节省内存 3️⃣ 事件驱动: Document变化 → Parser解析 → Symbol构建 → Provider响应LSP 4️⃣ 职责分离: Provider处理协议 | Service管理业务 | Language执行语义 | Tree-sitter负责语法

事件类型: DocumentOpened, DocumentChanged, DocumentClosed DocumentParsed, SymbolTableBuilt

service/document/ DocumentService (服务类) void OpenDocument(TextDocumentItem) void UpdateDocument(uri, changes) void CloseDocument(uri) TextDocument (实体类) void ApplyChange(change) const string& GetContent() integer GetVersion() 私有成员: TextDocumentItem item_ service/parser/ ParserService (服务类) ParseResult Parse(uri, source) ParseResult ParseIncremental(uri, old_tree) FileSymbolIndex ParseLight(file) ParseResult ParseFull(file) 返回: AST + TSTree + Errors incremental.hpp (可选) • 增量解析优化逻辑 • 变更范围计算 service/symbol/ SymbolService (核心服务) void LoadSystemSymbols(folder) SymbolQueryResult FindSymbol(name, ctx) SymbolQueryResult FindSymbolAt(uri, pos) SymbolResolutionContext BuildContext(uri) types.hpp • PositionKey / RangeKey • SymbolSignature • SymbolQueryResult context.hpp/cpp • 上下文构建 • 可见单元计算 • 可见性规则 service/symbol/repository/ - 三区域符号存储 system_repo.hpp/cpp ~50KB/文件

void LoadFromFolder(folder) SymbolSignature FindSymbol(unit, name) SystemSymbolIndex FindUnit(unit) GlobalTable* LoadFullSymbolTable(file)

存储结构: • index_: unit_name → SystemSymbolIndex • global_symbols_: symbol → unit_name 只存 public/published 符号

workspace_repo.hpp/cpp ~100KB/文件

void LoadFromFolder(folder) void AddOrUpdate(file, FileSymbolIndex) SymbolSignature FindSymbol(unit, name) vector<string> GetDependencies(file)

存储结构: • files_: file_path → FileSymbolIndex • units_: unit_name → file_path • dependencies_: 依赖图

editing_repo.hpp/cpp ⚠️ 需新增 ~1MB/文件

void AddOrUpdate(uri, GlobalTable, AST) Symbol* FindSymbolAt(uri, position) Symbol* FindSymbolByName(uri, name) GlobalTable* GetSymbolTable(uri)

存储结构 (EditingSymbolTable): • symbol_table: 完整 GlobalTable • name_index_: 名称快速查找 • position_index_: 位置快速查找

service/utils/ - 工具类 position.hpp/cpp 位置计算、行列转换、范围处理 conversion.hpp (可选) 类型转换: Position ↔ PositionKey 触发事件 DocumentOpened DocumentParsed DocumentParsed 查找顺序: 1.Editing → 2.Workspace → 3.System 关键设计说明 1. 服务接口统一命名: DocumentService, ParserService, SymbolService (后缀 *Service) 2. 分层存储策略: SystemRepo(轻量50KB) + WorkspaceRepo(索引100KB) + EditingRepo(完整1MB) 3. 事件驱动流程: DocumentOpened → Parse → DocumentParsed → BuildSymbol → SymbolTableBuilt 4. 查找优先级: EditingRepo (当前文档) → WorkspaceRepo (项目) → SystemRepo (系统库) 5. 按需加载: 优先使用轻量级SymbolSignature，需要时才load_full_symbol()加载完整GlobalTable 6. 职责分离: Document管理内容 | Parser负责解析 | Symbol处理语义 | Repository存储索引 服务类 实体类 仓库 基础 事件流 调用