📝 docs(memory-bank): sync templates

2026-02-02 17:21:21 +08:00 · 2026-02-02 17:21:21 +08:00 · fe4183314e
parent 73f01c3ca4
commit fe4183314e
5 changed files with 442 additions and 85 deletions
--- 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 中注册

 ---

--- a/memory-bank/decisions.md
+++ b/memory-bank/decisions.md
@ -1,32 +1,143 @@
 # 架构决策记录

-<!--
-填写指南：
- 本文件记录重要架构决策，使用 ADR 格式
- 初始可为空，遇到重要决策时由 AI 或人工添加
- 每个决策使用下方模板
-->
+## 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 和配方

 ---

--- 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 状态

 <!-- plan-status:start -->
--- 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)

 ---

--- 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 测试通过

 ---