Multilspy: 用于构建基于语言服务器的应用程序的 Python LSP 客户端库

简介

本仓库托管 multilspy，这是一个作为 NeurIPS 2023 论文《使用仓库上下文的静态分析引导代码语言模型解码》（“使用监控器通过全局上下文引导代码语言模型”）研究工作的一部分而开发的库。该论文提出了一种用于代码生成的语言模型引导解码方法——监控引导解码（MGD）。在此方法中，监控器利用静态分析来指导解码过程，确保生成的代码符合各种正确性属性，例如不存在幻觉符号名、方法调用顺序有效等。有关监控引导解码的更多详细信息，请参阅论文及 GitHub 仓库 microsoft/monitors4codegen。

multilspy 是一个跨平台库，旨在简化创建语言服务器客户端的过程，以便查询并从多种通过 语言服务器协议 进行通信的语言服务器获取各类静态分析结果。它易于扩展，可支持任何拥有语言服务器的语言，并且我们计划持续增加对更多语言服务器和语言的支持。

语言服务器 是一种工具，可在代码仓库上执行多种静态分析，并通过 语言服务器协议 (LSP) 提供有用的信息，例如基于类型的代码补全建议、符号定义位置、符号引用等。由于 LSP 具有语言无关性，multilspy 可以通过统一的接口提供不同语言代码的静态分析结果。

multilspy 旨在简化语言服务器的使用流程，通过处理使用语言服务器时的多个步骤来实现这一目标：

• 自动下载特定于操作系统的服务器二进制文件，并完成语言服务器的启动与关闭；
• 处理客户端与服务器之间的 JSON-RPC 通信；
• 维护并传递经过精心调整的服务器及语言特定配置参数；
• 向用户提供简单的 API，同时自动执行服务器特定协议中的所有步骤以完成查询或请求。

multilspy 可以提供的部分分析结果包括：

• 查找函数或类的定义（textDocument/definition）
• 查找函数的调用者或类的实例化位置（textDocument/references）
• 提供基于类型的引用补全（textDocument/completion）
• 获取悬停在符号上时显示的信息，如方法签名（textDocument/hover）
• 获取给定文件中定义的所有符号列表/树结构，以及符号类型，如类、方法等（textDocument/documentSymbol）
• 如需其他未列出的 LSP 请求，请提交问题或拉取请求。

安装

建议使用 python>=3.10 创建一个新的虚拟环境。使用 conda 创建并激活虚拟环境的命令如下：

conda create -n multilspy_env python=3.10
conda activate multilspy_env

关于 Python 虚拟环境的更多详细信息和创建说明，请参阅 官方文档。此外，我们也推荐用户使用 Miniconda，作为上述创建虚拟环境步骤的替代方案。

使用 pip 安装 multilspy 的命令如下：

pip install multilspy

支持的语言

目前，multilspy 支持以下语言：

编程语言	语言服务器
Java	Eclipse JDTLS
Python	jedi-language-server
Rust	Rust Analyzer
C#	OmniSharp / RazorSharp
TypeScript	TypeScriptLanguageServer
JavaScript	TypeScriptLanguageServer
Go	gopls
Dart	Dart
Ruby	Solargraph
Kotlin	KotlinLanguageServer

使用方法

使用示例：

from multilspy import SyncLanguageServer
from multilspy.multilspy_config import MultilspyConfig
from multilspy.multilspy_logger import MultilspyLogger
...
config = MultilspyConfig.from_dict({"code_language": "java"}) # 同样支持 "python", "rust", "csharp", "typescript", "javascript", "go", "dart", "ruby"
logger = MultilspyLogger()
lsp = SyncLanguageServer.create(config, logger, "/abs/path/to/project/root/")
with lsp.start_server():
    result = lsp.request_definition(
        "relative/path/to/code_file.java", # 发起请求的代码文件路径
        163, # 请求符号所在的行号
        4 # 请求符号所在的列号
    )
    result2 = lsp.request_completions(
        ...
    )
    result3 = lsp.request_references(
        ...
    )
    result4 = lsp.request_document_symbols(
        ...
    )
    result5 = lsp.request_hover(
        ...
    )
    ...

multilspy 还提供了基于 asyncio 的 API，可用于异步上下文中。异步使用示例：

from multilspy import LanguageServer
...
lsp = LanguageServer.create(...)
async with lsp.start_server():
    result = await lsp.request_definition(
        ...
    )
    ...

文件 src/multilspy/language_server.py 提供了 multilspy 的 API。位于 tests/multilspy/ 中的多个测试用例提供了 multilspy 的详细使用示例。可通过运行以下命令执行这些测试：

pytest tests/multilspy

multilspy 在 AI4Code 场景中的应用，如监控引导解码

multilspy 提供了语言服务器协议为 VSCode 等 IDE 所提供的所有功能。它对于开发能够与大型语言模型（LLM）等 AI 系统交互的工具集非常有用。

监控引导解码

其中一个用例就是监控引导解码（MGD），其中 multilspy 被用来获取诸如类型导向补全之类的静态分析结果，以指导使用大语言模型逐标记生成代码。这样可以确保所有生成的标识符和方法名在仓库上下文中都是有效的，从而显著提高生成代码的可编译性。MGD 还展示了如何利用 multilspy 创建监控器，以保证大语言模型生成的代码中所有函数调用都接收正确数量的参数，并且对象的方法调用遵循正确的协议顺序（例如，在文件对象上不会先调用“read”再调用“open”）。

Multilspy 在其他用例中的应用

• "修复测试：通过静态收集器和神经重排序器增强大语言模型以修复测试用例"，载于 2024 年 IEEE 第 35 届软件可靠性工程国际研讨会 (ISSRE)
• 使用 multilspy 获取 Python 补全的教程
• 收集并利用仓库级别的上下文信息，用于构建仓库级编码智能体

常见问题解答 (FAQ)

执行 MGD 测试时出现与 asyncio 相关的运行时错误

如果您遇到以下错误：

RuntimeError: Task <Task pending name='Task-2' coro=<_AsyncGeneratorContextManager.__aenter__() running at
    python3.8/contextlib.py:171> cb=[_chain_future.<locals>._call_set_state() at
    python3.8/asyncio/futures.py:367]> got Future <Future pending> attached to a different loop python3.8/asyncio/locks.py:309: RuntimeError

请确保您创建了一个 Python 版本 >=3.10 的新环境。更多详细信息，请参阅 StackOverflow 讨论。

引用 Multilspy

如果您在研究或应用中使用了 Multilspy，请使用以下 BibTeX 格式引用：

@inproceedings{NEURIPS2023_662b1774,
 author = {Agrawal, Lakshya A and Kanade, Aditya and Goyal, Navin and Lahiri, Shuvendu and Rajamani, Sriram},
 booktitle = {Advances in Neural Information Processing Systems},
 editor = {A. Oh and T. Naumann and A. Globerson and K. Saenko and M. Hardt and S. Levine},
 pages = {32270--32298},
 publisher = {Curran Associates, Inc.},
 title = {基于仓库上下文静态分析的代码大语言模型监控引导解码},
 url = {https://proceedings.neurips.cc/paper_files/paper/2023/file/662b1774ba8845fc1fa3d1fc0177ceeb-Paper-Conference.pdf},
 volume = {36},
 year = {2023}
}

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议 (CLA)，声明您有权并将您的贡献权利授予我们。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记 PR（例如状态检查、评论）。只需按照机器人提供的说明操作即可。对于使用我们 CLA 的所有仓库，您只需执行一次此操作。

本项目已采用 微软开源行为准则。更多信息请参阅 行为准则常见问题解答 或发送电子邮件至 opencode@microsoft.com 提出任何其他问题或意见。

商标

本项目可能包含项目、产品或服务的商标或徽标。未经授权使用微软商标或徽标须遵守并遵循 微软商标与品牌指南。在本项目的修改版本中使用微软商标或徽标不得造成混淆或暗示微软的赞助。任何第三方商标或徽标的使用均受其各自政策的约束。

Multilspy 快速上手指南

Multilspy 是一个基于 Python 的跨平台 LSP（语言服务器协议）客户端库，旨在简化与各类语言服务器的交互，帮助开发者轻松获取代码静态分析结果（如定义跳转、引用查找、自动补全等），特别适用于构建 AI 辅助编程工具。

环境准备

• 操作系统：支持 Windows、macOS 和 Linux（跨平台）
• Python 版本：必须使用 Python 3.10 或更高版本（低版本可能导致 asyncio 运行时错误）
• 包管理工具：推荐使用 pip 或 conda
• 网络建议：若下载语言服务器二进制文件较慢，可配置国内镜像源加速 pip 安装，但语言服务器本身需从官方源下载（暂无官方中国镜像）

💡 建议创建独立的虚拟环境以避免依赖冲突。

安装步骤

方式一：使用 Conda（推荐）

conda create -n multilspy_env python=3.10
conda activate multilspy_env
pip install multilspy

方式二：使用 venv + pip

python3.10 -m venv multilspy_env
source multilspy_env/bin/activate  # Windows 用户请使用：multilspy_env\Scripts\activate
pip install multilspy

✅ 安装完成后，库会自动在首次运行时按需下载对应语言的服务器二进制文件（如 Java 的 JDTLS、Python 的 jedi-language-server 等）。

基本使用

以下是最简单的同步调用示例，以 Java 项目为例：

from multilspy import SyncLanguageServer
from multilspy.multilspy_config import MultilspyConfig
from multilspy.multilspy_logger import MultilspyLogger

# 配置目标语言（支持：java, python, rust, csharp, typescript, javascript, go, dart, ruby, kotlin）
config = MultilspyConfig.from_dict({"code_language": "java"})
logger = MultilspyLogger()

# 初始化语言服务器（传入项目根目录绝对路径）
lsp = SyncLanguageServer.create(config, logger, "/abs/path/to/project/root/")

# 启动服务器并执行查询
with lsp.start_server():
    # 获取某符号的定义位置
    result = lsp.request_definition(
        "src/main/java/com/example/App.java",  # 文件相对路径
        25,   # 行号（从 0 开始）
        10    # 列号（从 0 开始）
    )
    print(result)

    # 获取自动补全建议
    completions = lsp.request_completions(
        "src/main/java/com/example/App.java",
        25,
        10
    )
    print(completions)

如需在异步场景中使用（例如集成到 async AI 服务中），可使用 asyncio 接口：

from multilspy import LanguageServer

lsp = LanguageServer.create(config, logger, "/abs/path/to/project/root/")

async with lsp.start_server():
    result = await lsp.request_definition(
        "src/main/java/com/example/App.java",
        25,
        10
    )

📌 提示：更多用法请参考 tests/multilspy/ 目录下的测试用例，运行 pytest tests/multilspy 可验证本地环境是否正常。