# 系统模式与约束

## 模块边界

### 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