diff --git a/memory-bank/architecture.md b/memory-bank/architecture.md index c65e2f5..042fe9b 100644 --- a/memory-bank/architecture.md +++ b/memory-bank/architecture.md @@ -1,43 +1,169 @@ # 架构设计 - - ## 整体架构 - +```mermaid +graph TB + subgraph Clients["编辑器客户端"] + VSCode["VSCode Extension"] + Vim["Vim Plugin"] + Other["其他 IDE"] + end -```txt -{{ARCHITECTURE_DIAGRAM}} + VSCode & Vim & Other -->|"LSP (JSON-RPC over stdio)"| Core + + subgraph Server["LSP Server (C++23)"] + subgraph Core["Core Layer"] + ServerMain["Server\n主循环"] + Dispatcher["Dispatcher\n请求分发"] + AsyncExecutor["AsyncExecutor\n异步调度"] + ServerMain --- Dispatcher --- AsyncExecutor + end + + subgraph Manager["Manager Layer"] + DocumentMgr["Document\nManager"] + ParserMgr["Parser\nManager"] + SymbolMgr["Symbol\nManager"] + EventBus["EventBus"] + end + + subgraph Provider["Provider Layer"] + Completion["Completion"] + CodeAction["CodeAction"] + CodeLens["CodeLens"] + Definition["Definition"] + InlayHint["InlayHint"] + More["..."] + end + + subgraph Language["Language Layer"] + AST["AST\n语法树"] + Semantic["Semantic\n语义分析"] + Symbol["Symbol\n符号表"] + end + + subgraph Bridge["Bridge Layer"] + Glaze["Glaze"] + Spdlog["spdlog"] + Taskflow["Taskflow"] + TreeSitter["Tree-sitter"] + Win32Stdio["win32_stdio"] + end + + Core --> Manager + Core --> Provider + Provider --> Manager + Provider --> Language + Manager --> Language + Language --> Bridge + Manager --> Bridge + end ``` ## 核心模块 - +### Core - 核心服务 -### {{MODULE_1}} +**职责**：处理 LSP 协议通信，分发请求，管理服务器生命周期 -**职责**：{{MODULE_1_DESC}} +**关键文件**： + +- `src/core/server.cppm` - 服务器主循环，stdio 读写 +- `src/core/dispatcher.cppm` - 请求分发器，路由到对应 Provider + +### Manager - 状态管理 + +**职责**：管理文档、符号、解析结果等核心状态 + +**关键文件**： + +- `src/manager/document.cppm` - 文档管理，维护打开的文件内容 +- `src/manager/parser.cppm` - 解析管理，维护语法树缓存 +- `src/manager/symbol.cppm` - 符号管理，维护符号索引 +- `src/manager/event_bus.cppm` - 事件总线，模块间解耦通信 +- `src/manager/manager_hub.cppm` - 管理器集线器，统一访问入口 + +### Provider - LSP 功能提供者 + +**职责**：实现具体的 LSP 功能（补全、跳转、悬停等） + +**关键目录**： + +- `src/provider/completion_item/` - 代码补全 +- `src/provider/code_action/` - 代码操作 +- `src/provider/code_lens/` - 代码透镜 +- `src/provider/text_document/` - 文档相关 (悬停、跳转定义、引用等) +- `src/provider/inlay_hint/` - 内联提示 +- `src/provider/document_link/` - 文档链接 +- `src/provider/call_hierarchy/` - 调用层次 +- `src/provider/type_hierarchy/` - 类型层次 +- `src/provider/workspace_symbol/` - 工作区符号搜索 + +### Language - 语言分析 + +**职责**：TSL 语言的语法和语义分析 + +**关键目录**： + +- `src/language/ast/` - 抽象语法树访问和遍历 +- `src/language/semantic/` - 语义分析 +- `src/language/symbol/` - 符号定义和类型 +- `src/language/keyword/` - 关键字定义 + +### Bridge - 第三方库桥接 + +**职责**：封装第三方库，提供 C++ Module 接口 + +**关键文件**： + +- `src/bridge/glaze.cppm` - JSON 序列化 +- `src/bridge/spdlog.cppm` - 日志 +- `src/bridge/taskflow.cppm` - 并行任务 +- `src/bridge/tree_sitter.cppm` - 语法解析 +- `src/bridge/win32_stdio.cppm` - Windows stdio 支持 + +### Protocol - LSP 协议 + +**职责**：定义 LSP 协议的类型和序列化 + +**关键文件**： + +- `src/protocol/types.cppm` - 基础类型定义 +- `src/protocol/protocol.cppm` - 协议聚合模块 ## 关键约束 - - -- {{CONSTRAINT_1}} +- **C++ Modules**：使用 `.cppm` 文件，需要 Clang 20+ 或 GCC 15+ +- **异步处理**：所有耗时操作必须通过 `AsyncExecutor` 异步执行 +- **增量解析**：使用 Tree-sitter 保证编辑时的响应性能 +- **JSON 序列化**：使用 Glaze 库实现零拷贝 JSON 解析 ## 扩展点 - - -### {{EXTENSION_1}} +### 添加新的 LSP Provider **步骤**： -1. {{STEP_1}} +1. 在 `src/provider/` 下创建新目录 +2. 继承 `ProviderBase` 基类 +3. 实现 `handle()` 方法处理请求 +4. 在 `Dispatcher` 中注册路由 + +### 添加新的语义分析 + +**步骤**： + +1. 在 `src/language/semantic/` 添加分析模块 +2. 定义访问 AST 的逻辑 +3. 在 `SymbolManager` 中集成 + +### 添加新的代码补全类型 + +**步骤**： + +1. 在 `src/provider/completion_item/` 添加新的补全源 +2. 实现补全逻辑，返回 `CompletionItem` 列表 +3. 在主 completion provider 中注册 --- diff --git a/memory-bank/decisions.md b/memory-bank/decisions.md index 598101e..1c2afbd 100644 --- a/memory-bank/decisions.md +++ b/memory-bank/decisions.md @@ -1,32 +1,143 @@ # 架构决策记录 - +## ADR-001: 使用 C++23 Modules 构建 LSP 服务器 -## ADR 模板 - -```markdown -## ADR-XXX: 决策标题 - -**日期**: YYYY-MM-DD -**状态**: 已采纳 / 已废弃 / 待讨论 +**日期**: 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 和配方 --- diff --git a/memory-bank/progress.md b/memory-bank/progress.md index 559d39b..1374270 100644 --- a/memory-bank/progress.md +++ b/memory-bank/progress.md @@ -1,3 +1,64 @@ +# 项目进度 + +## 已完成功能 + +### LSP 服务器核心 + +- [x] JSON-RPC 通信框架 (stdio) +- [x] 请求分发器 (Dispatcher) +- [x] 异步任务执行器 (AsyncExecutor) +- [x] 文档管理器 (DocumentManager) +- [x] 解析管理器 (ParserManager) +- [x] 符号管理器 (SymbolManager) +- [x] 事件总线 (EventBus) + +### LSP 功能 (Provider) + +- [x] `initialize` / `shutdown` / `exit` +- [x] `textDocument/didOpen` / `didChange` / `didClose` +- [x] `textDocument/completion` - 代码补全 +- [x] `textDocument/hover` - 悬停信息 +- [x] `textDocument/definition` - 跳转定义 +- [x] `textDocument/references` - 查找引用 +- [x] `textDocument/documentSymbol` - 文档符号 +- [x] `textDocument/codeAction` - 代码操作 +- [x] `textDocument/codeLens` - 代码透镜 +- [x] `textDocument/inlayHint` - 内联提示 +- [x] `textDocument/documentLink` - 文档链接 +- [x] `callHierarchy/incomingCalls` / `outgoingCalls` +- [x] `typeHierarchy/supertypes` / `subtypes` +- [x] `workspace/symbol` - 工作区符号搜索 + +### VSCode 扩展 + +- [x] 语法高亮 (TextMate) +- [x] 代码片段 (Snippets) +- [x] LSP 客户端集成 +- [x] 扩展打包 (`.vsix`) + +### 构建与部署 + +- [x] CMake 构建系统 +- [x] Conan 依赖管理 +- [x] Linux (Clang) 构建 +- [x] Windows 交叉编译 +- [x] Gitea CI/CD 流水线 + +## 进行中 + +- [ ] 语义高亮 (`textDocument/semanticTokens`) +- [ ] 重命名 (`textDocument/rename`) +- [ ] 格式化 (`textDocument/formatting`) + +## 待规划 + +- [ ] 诊断 (`textDocument/publishDiagnostics`) +- [ ] 签名帮助 (`textDocument/signatureHelp`) +- [ ] 折叠范围 (`textDocument/foldingRange`) +- [ ] 选择范围 (`textDocument/selectionRange`) + +--- + # Plan 状态 diff --git a/memory-bank/project-brief.md b/memory-bank/project-brief.md index edf39c6..d1623d6 100644 --- a/memory-bank/project-brief.md +++ b/memory-bank/project-brief.md @@ -1,47 +1,47 @@ # tsl-devkit 项目简介 - - ## 项目定位 - +**核心目标**：为 TSL (TinySoft Language) 提供完整的 IDE 开发体验 -**核心目标**：{{PROJECT_GOAL}} - -**一句话描述**：{{PROJECT_DESCRIPTION}} +**一句话描述**：基于 LSP 标准的 TSL 语言服务器及编辑器扩展套件 ## 项目边界 - - ### 做什么 -- {{DO_1}} +- 实现 LSP (Language Server Protocol) 服务器，提供标准语言服务 +- 提供 VSCode 扩展，集成语法高亮、代码补全、诊断等功能 +- 提供 Vim 语法支持 +- 支持跨平台运行 (Linux / Windows) ### 不做什么 - - -- {{DONT_1}} +- 不实现 TSL 语言的编译器/解释器 +- 不实现 TSL 语言的运行时环境 +- 不提供 TSL 语言的调试功能 (Debugger) ### 约束条件 - - -- {{CONSTRAINT_1}} +- 必须遵循 LSP 3.17+ 协议标准 +- LSP 服务器必须支持增量解析以保证响应性能 +- 必须同时支持 Linux 和 Windows 平台 ## 核心概念 - +| 术语 | 说明 | +| --------------- | ------------------------------------------------ | +| **TSL** | TinySoft Language，天软公司的领域特定脚本语言 | +| **LSP** | Language Server Protocol，微软定义的语言服务协议 | +| **Tree-sitter** | 增量解析框架，用于构建语法树 | +| **Provider** | LSP 功能提供者，处理特定类型的请求 | +| **Manager** | 管理器，负责文档、符号、解析等核心状态管理 | ## 参考资料 - +- [LSP 规范](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) +- [Tree-sitter 文档](https://tree-sitter.github.io/tree-sitter/) +- [VSCode 扩展 API](https://code.visualstudio.com/api) --- diff --git a/memory-bank/tech-stack.md b/memory-bank/tech-stack.md index 9e90979..08b71c4 100644 --- a/memory-bank/tech-stack.md +++ b/memory-bank/tech-stack.md @@ -1,63 +1,122 @@ # 技术栈与工具链 - - ## 核心技术 - +**主语言**：C++23 (LSP 服务器) + TypeScript (VSCode 扩展) -**主语言**：cpp - -**文件类型**：{{FILE_TYPES}} +**文件类型**：`.cppm` (C++ Module), `.cc`, `.ts`, `.json` ## 项目结构 - - ```text tsl-devkit/ -├── {{DIR_1}}/ # {{DIR_1_DESC}} -└── memory-bank/ # 项目上下文 +├── lsp-server/ # LSP 服务器 (C++23) +│ ├── src/ # 源代码 +│ │ ├── bridge/ # 第三方库桥接 +│ │ ├── cli/ # 命令行接口 +│ │ ├── codec/ # 编解码器 +│ │ ├── core/ # 核心服务 +│ │ ├── language/ # 语言分析 +│ │ ├── manager/ # 状态管理器 +│ │ ├── protocol/ # LSP 协议定义 +│ │ ├── provider/ # LSP 功能提供者 +│ │ ├── scheduler/ # 异步调度 +│ │ ├── tree-sitter/ # 解析器绑定 +│ │ └── utils/ # 工具函数 +│ ├── test/ # 单元测试 +│ └── conan/ # Conan 配置 +├── vscode/ # VSCode 扩展 +│ ├── src/ # TypeScript 源码 +│ ├── syntaxes/ # TextMate 语法 +│ └── snippets/ # 代码片段 +├── vim/ # Vim 支持 +├── test/ # 集成测试用例 +├── docs/ # 文档 +│ ├── prompts/ # AI 编码提示 +│ └── standards/ # 代码标准 +└── memory-bank/ # 项目上下文 ``` ## 开发环境 - - **必需工具**： -- {{TOOL_1}} +- CMake 4.2+ +- Clang 20+ (推荐) 或 GCC 15+ +- Conan 2.x (包管理) +- Node.js 18+ (VSCode 扩展开发) +- ninja (构建) + +**构建 LSP 服务器 (Linux)**： + +```bash +# 安装依赖 +CONAN_HOME=/tmp/conan-home conan install lsp-server \ + -pr:h=lsp-server/conan/profiles/linux-x86_64-clang \ + -pr:b=lsp-server/conan/profiles/linux-x86_64-clang \ + -of lsp-server/build/clang-linux --build=missing + +# 配置 +cmake -S lsp-server -B lsp-server/build/clang-linux/Release \ + -DCMAKE_TOOLCHAIN_FILE=$PWD/lsp-server/build/clang-linux/Release/generators/conan_toolchain.cmake \ + -DBUILD_TESTS=ON + +# 构建 +cmake --build lsp-server/build/clang-linux/Release --target tsl-server +``` + +**构建 LSP 服务器 (Windows 交叉编译)**： + +```bash +CONAN_HOME=/tmp/conan-home conan install lsp-server \ + -pr:b=lsp-server/conan/profiles/linux-x86_64-clang \ + -pr:h=lsp-server/conan/profiles/windows-x86_64-clang-cross \ + -of lsp-server/build/clang-cross --build=missing + +cmake -S lsp-server -B lsp-server/build/clang-cross \ + -DCMAKE_TOOLCHAIN_FILE=$PWD/lsp-server/build/clang-cross/Release/generators/conan_toolchain.cmake \ + -DBUILD_TESTS=OFF + +cmake --build lsp-server/build/clang-cross --target tsl-server +``` **运行测试**： ```bash -{{TEST_CMD}} +# C++ 单元测试 +ctest --test-dir lsp-server/build/clang-linux/Release --output-on-failure + +# VSCode 扩展 +cd vscode && npm test ``` ## 依赖管理 - +**C++ 依赖 (Conan)**： -**外部依赖**： +| 包 | 版本 | 用途 | +| ----------- | ------ | ------------------ | +| glaze | 6.4.0 | 高性能 JSON 序列化 | +| spdlog | 1.17.0 | 日志库 | +| fmt | 12.1.0 | 格式化库 | +| taskflow | 3.10.0 | 并行任务执行 | +| tree-sitter | 0.25.9 | 增量语法解析 | -- {{EXTERNAL_DEP_1}} +**VSCode 扩展依赖 (npm)**： + +| 包 | 用途 | +| --------------------- | ---------- | +| vscode-languageclient | LSP 客户端 | ## 测试策略 - - **测试类型**： -- {{TEST_TYPE_1}} +- LSP JSON 测试：Python 脚本驱动的协议交互测试 (`run_lsp_json_tests.py`) **验证标准**： -- {{PASS_CONDITION_1}} +- 所有 LSP JSON 测试通过 ---