# 架构决策记录

## ADR-001: 使用 C++23 Modules 构建 LSP 服务器

**日期**: 2026-02-02
**状态**: 已采纳

### 决策

LSP 服务器核心使用 C++23 Modules (`.cppm` 文件) 而非传统头文件 (`.h/.hpp`)。

### 理由

- **编译性能**：Module 只需编译一次，后续增量编译更快
- **符号隔离**：避免头文件中的宏污染和符号冲突
- **依赖清晰**：显式 import 声明依赖关系更清晰
- **现代化**：跟进 C++ 现代化趋势

### 影响

- 需要 Clang 20+ 或 GCC 15+ 编译器
- CMake 需要 4.2+ 版本以支持 CXX_MODULE
- 第三方库需要通过 Bridge 模块封装

---

## ADR-002: 选择 Tree-sitter 作为解析器

**日期**: 2026-02-02
**状态**: 已采纳

### 决策

使用 Tree-sitter 作为 TSL 语法解析器，而非手写递归下降解析器或 ANTLR。

### 理由

- **增量解析**：Tree-sitter 原生支持增量更新，适合 IDE 场景
- **错误恢复**：能在语法错误时继续解析，提供最大可用性
- **高性能**：C 实现，解析速度快
- **生态**：被 GitHub、Neovim 等广泛使用，经过生产验证

### 影响

- 需要编写 Tree-sitter 语法文件 (`grammar.js`)
- 生成的 C 代码需要集成到构建系统
- 语法树结构受 Tree-sitter 约束

---

## ADR-003: 使用 Glaze 进行 JSON 序列化

**日期**: 2026-02-02
**状态**: 已采纳

### 决策

使用 Glaze 库处理 LSP 协议的 JSON 序列化，而非 nlohmann/json 或 rapidjson。

### 理由

- **零拷贝**：Glaze 支持零拷贝解析，性能最优
- **编译时反射**：使用 C++20 概念实现编译时序列化，无运行时开销
- **类型安全**：编译期检查 JSON 结构与 C++ 类型的匹配
- **简洁**：代码量少，维护成本低

### 影响

- 需要为 LSP 类型定义 `glz::meta` 或使用结构化绑定
- 依赖 C++20 特性

---

## ADR-004: 采用 Taskflow 实现异步处理

**日期**: 2026-02-02
**状态**: 已采纳

### 决策

使用 Taskflow 库实现请求的异步并行处理，而非 std::async 或自建线程池。

### 理由

- **任务图**：支持复杂的任务依赖关系
- **性能**：高效的工作窃取调度器
- **易用**：API 简洁，与 C++20 配合良好
- **成熟**：经过 HPC 场景验证

### 影响

- 需要正确管理任务生命周期
- 共享状态需要同步保护

---

## ADR-005: VSCode 扩展与 LSP 服务器分离

**日期**: 2026-02-02
**状态**: 已采纳

### 决策

VSCode 扩展作为纯客户端，通过 stdio 与独立的 LSP 服务器进程通信。

### 理由

- **标准协议**：遵循 LSP 标准，可复用于其他编辑器
- **独立开发**：C++ 和 TypeScript 代码库独立演进
- **调试方便**：服务器可独立启动调试
- **稳定性**：服务器崩溃不影响 VSCode 主进程

### 影响

- 需要处理进程管理和生命周期
- stdio 通信增加序列化开销
- 需要分发服务器二进制文件

---

## ADR-006: 使用 Conan 管理 C++ 依赖

**日期**: 2026-02-02
**状态**: 已采纳

### 决策

使用 Conan 2.x 作为 C++ 依赖管理工具。

### 理由

- **跨平台**：统一管理 Linux 和 Windows 依赖
- **二进制缓存**：避免重复编译第三方库
- **版本锁定**：精确控制依赖版本
- **CMake 集成**：生成 CMake 工具链文件

### 影响

- 开发者需要安装 Conan
- 需要维护 Conan profile 和配方

---

**最后更新**：2026-02-02