78 lines
3.1 KiB
Markdown
78 lines
3.1 KiB
Markdown
# 系统模式与约束
|
||
|
||
## 模块边界
|
||
|
||
### Core / Protocol
|
||
|
||
- **职责**：处理 stdio 生命周期、LSP 消息路由、协议类型定义与序列化入口
|
||
- **输入**：编辑器发来的原始 LSP 请求、通知、初始化参数
|
||
- **输出**：分发后的 provider 调用、协议响应和服务端事件
|
||
- **不应负责**：语义分析、符号计算、解析缓存管理
|
||
|
||
### Provider / Manager
|
||
|
||
- **职责**：Provider 负责 capability 级编排；
|
||
Manager 负责文档、解析结果、符号等共享状态
|
||
- **输入**：已解析的协议请求、文档状态、语言分析结果
|
||
- **输出**：LSP 返回值、workspace edit、内部状态更新
|
||
- **不应负责**：跨层直接操作第三方库细节，或绕过 manager 持久化共享状态
|
||
|
||
### Language / Bridge
|
||
|
||
- **职责**：Language 负责 AST、语义、符号逻辑；
|
||
Bridge 负责 Tree-sitter、Glaze、Taskflow、spdlog 等第三方封装
|
||
- **输入**：语法树、节点访问请求、共享分析上下文
|
||
- **输出**：AST 结构、语义结论、符号信息、桥接后的库接口
|
||
- **不应负责**：LSP 协议路由、编辑器生命周期管理
|
||
|
||
## 关键数据流
|
||
|
||
1. 编辑器请求进入 `core/server.cppm`，由 `dispatcher.cppm`
|
||
解析 method 并路由到对应 provider
|
||
2. Provider 通过 `manager/` 获取文档、语法树和符号状态，
|
||
需要深入分析时再调用 `language/` 能力
|
||
3. 结果经 `protocol/` 与 `codec/` 序列化后返回客户端；
|
||
异步任务由 `scheduler/async_executor.cppm` 承载
|
||
|
||
## 核心不变量
|
||
|
||
- LSP 线协议必须稳定，能力扩展优先新增 provider 而不是改现有报文结构
|
||
- 文档和解析缓存由 manager 统一持有，其他层不各自维护第二份真相
|
||
- Tree-sitter 生成物、AST 访问逻辑和测试夹具必须同步演进
|
||
- Bridge 模块只做库封装，不夹带 TSL 业务分支
|
||
|
||
## 常见实现模式
|
||
|
||
### 新增 LSP 能力
|
||
|
||
- **适用场景**：新增 `textDocument/*`、`workspace/*`、
|
||
`callHierarchy/*` 等协议能力
|
||
- **推荐做法**：先补 protocol 类型，再在 `src/provider/`
|
||
新增或扩展对应 provider，最后在 dispatcher 注册并补测试
|
||
- **避免事项**：把协议分发、共享状态和语义逻辑揉进一个模块里
|
||
|
||
### 调整语法或 AST
|
||
|
||
- **适用场景**：关键字、表达式、声明、节点结构发生变化
|
||
- **推荐做法**：先改 Tree-sitter 与 parser/scanner，同步 AST /
|
||
semantic / symbol 访问点，再补 `test_tree_sitter`、
|
||
`test_ast`、相关 provider 测试
|
||
- **避免事项**：只改生成物不改测试，或只改 AST 不回溯语法源
|
||
|
||
## 扩展路径
|
||
|
||
1. 协议功能扩展优先从 `src/protocol/`、`src/provider/`、
|
||
`src/core/dispatcher.cppm` 这一条链路进入
|
||
2. 语言分析扩展优先从 `src/language/` 进入，
|
||
需要共享缓存时再通过 `src/manager/` 暴露给 provider
|
||
|
||
## 禁止破坏的约束
|
||
|
||
- 不破坏现有分层边界，不跨层绕过 manager 直接操作底层解析状态
|
||
- 不引入与现有 C++23 Modules 组织方式冲突的头文件式拼装
|
||
- 不在 playbook 对齐任务里修改产品 README 或业务实现
|
||
|
||
---
|
||
|
||
**最后更新**：2026-05-24
|