---
url: /wave-agent/specs/core/lsp-integration.md
description: Language Server Protocol 代码智能（定义跳转、引用查找、悬停信息）
---

# 功能规格说明：LSP 集成支持

**创建日期**：2025-12-24

## 用户场景与测试 *（必填）*

### 用户故事：代码导航（优先级：P1）

作为 AI agent，我希望找到符号的定义，以便我可以在不手动搜索文件的情况下了解其实现方式。

**为什么是这个优先级**：对于代码理解和导航至关重要，尤其是在大型代码库中。

**独立测试**：在已知符号上调用 `lsp` 工具的 `goToDefinition` 操作并验证它返回正确的文件路径和行号。

**验收场景**：

1. **假设**支持的语言中的有效符号，**当** agent 调用 `goToDefinition` 时，**则**系统必须返回定义的位置（文件和范围）。
2. **假设**具有多个定义的符号（如重载方法），**当** agent 调用 `goToDefinition` 时，**则**系统应该返回所有相关位置。

***

### 用户故事：类型和文档检查（优先级：P1）

作为 AI agent，我希望获取符号的悬停信息，以便我可以看到其类型签名和文档。

**为什么是这个优先级**：帮助 agent 正确使用 API 并理解变量和函数的用途。

**独立测试**：在函数上调用 `lsp` 工具的 `hover` 操作并验证它返回文档字符串和类型信息。

**验收场景**：

1. **假设**有文档的符号，**当** agent 调用 `hover` 时，**则**系统必须返回文档和类型信息。

***

### 用户故事：调用层次探索（优先级：P2）

作为 AI agent，我希望看到哪些函数调用了特定方法，以便我可以了解更改它的影响。

**为什么是这个优先级**：对于重构和理解执行流程至关重要。

**独立测试**：调用 `prepareCallHierarchy` 然后调用 `incomingCalls` 并验证它返回调用者函数列表。

**验收场景**：

1. **假设**一个被其他函数调用的函数，**当** agent 调用 `incomingCalls` 时，**则**系统必须返回所有调用位置的列表。

***

### 边界情况

* **未配置服务器**：如果文件扩展名没有映射的 LSP 服务器，工具应该返回清晰的错误。
* **服务器崩溃**：如果 LSP 服务器进程死亡，`LspManager` 应该优雅地处理并可能重启它。
* **大型响应**：某些 LSP 响应（如 `findReferences`）可能非常大；工具必须将结果截断为最多 1000 项和 100 个文件，以防止过多的 token 使用，同时在头部报告总数。
* **慢速服务器**：实现超时以防止 agent 无限等待慢速语言服务器。

## 假设

* 用户的系统上已安装必要的语言服务器可执行文件。
* 如果需要自定义 LSP 服务器，项目包含 `.lsp.json` 文件。
* 终端环境允许生成子进程。