企业官网建设流程全解析

Serena 如何用 query_project 工具查询外部项目的符号信息

【免费下载链接】serenaA powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent项目地址: https://gitcode.com/GitHub_Trending/ser/serena

在开发中经常遇到这种情况：你正在 Serena 中处理项目 A，却需要查看项目 B（比如一个被依赖的库）的符号信息——某个类定义在哪里、哪些引用指向它。直接激活项目 B 会打断当前会话的工作项目。Serena 的query_project工具就是为解决这个问题设计的：它让 agent 在不激活目标项目的前提下，查询另一个 Serena 项目中注册项目的文件与符号信息（见 Project Workflow 的 “Reading from External Projects” 一节）。

本文的目标路径是：把外部项目注册为 Serena 项目 → 激活query-projects模式 → 按语言后端满足资源条件（IDE 打开或启动 Project Server）→ 让 agent 用query_project发起只读符号查询。

准备条件：外部项目必须已被 Serena 认识

query_project只能查询“known to Serena”的项目，即已经按 Serena 的项目工作流创建过的项目。对每个想被查询的外部项目，先在其目录内执行显式项目创建：

serena project create [options] [project directory]

• 不指定目录时默认为当前目录；
• 对已有代码的项目，Serena 会基于源码文件检测编程语言并自动激活主语言，检测到多种语言时会提示你选择是否启用；
• 空项目可以用--language python --language typescript这类参数显式指定语言；
• 可以用--name my-name指定项目在 Serena 中的引用名，用--index在创建后立即索引。

创建后，建议对较大的项目执行一次索引，预缓存语言服务器提供的符号信息，避免首次符号查询时的延迟：

serena project index

索引只需执行一次；常规使用中文件变化时 Serena 会自动更新索引。

项目创建后，project_name、language_servers、added_modes等设置位于项目目录下的.serena/project.yml，可参考模板 project.template.yml 中的完整参数说明。

启用 query-projects 模式

query_project属于可选工具，默认不激活。启用方式是激活名为query-projects的模式。该模式的定义文件为 query-projects.yml，它会引入两个工具：

• query_project：在目标项目上下文中执行只读工具；
• list_queryable_projects：列出当前可以查询的项目（名称与根路径）。

模式可以在三个层面配置，最终激活的模式是三者取并集（base_modes+default_modes+added_modes，详见 Configuration 文档）：

1. 全局配置serena_config.yml：base_modes中的模式始终生效，default_modes可被项目或命令行覆盖；

2. 项目配置project.yml：设置added_modes为当前项目追加模式。模板文件注释里给出的示例正是本场景：

   # list of mode names to be activated additionally for this project, e.g. ["query-projects"] added_modes: ["query-projects"]

   注意：added_modes是“追加”，而default_modes是“覆盖全局默认模式”。只想在特定项目开启查询能力时，用added_modes即可，不影响其他模式。

3. 启动时命令行参数：传给start-mcp-server的参数可以覆盖默认模式（--mode）或在上面追加模式（--add-mode）。例如启动时为本次会话追加：

   --add-mode query-projects

配置变更后重启对应会话，工具才会出现在 agent 可用工具集中。

按语言后端满足查询条件

启用模式后，query_project对资源的管理取决于当前语言后端，两种后端的要求不同：

JetBrains 后端：确保每个希望被符号查询的项目都在一个 IDE 实例中打开。查询能力复用 IDE 中已有的项目实例，Serena 本身不会替你启动它们。

LSP 后端：通过query_project执行符号工具要求 Serena 的Project Server处于运行状态。它会自动为被查项目拉起所需的语言服务器。启动命令（见 070_security.md 也说明该服务只会在项目查询场景下显式启动）：

serena start-project-server

该命令启动一个监听127.0.0.1的 HTTP 服务（默认地址，可用--host/--port覆盖，见 cli.py 中start-project-server子命令的选项）。由于符号查询依赖它，保持该服务与查询会话同时运行。

发起查询并核对结果

条件就绪后，在对话中让 agent 对外部项目发起查询即可。核对顺序：

1. 先确认目标项目在可查询列表里：让 agent 调用list_queryable_projects。它返回项目名到根路径的映射；目标项目出现在结果中，说明注册（以及后端侧的条件）已满足。在 JetBrains 后端下，只有当前有打开 IDE 实例的项目才会被列出为可符号访问；LSP 后端下所有已注册项目都通过 Project Server 可查询（见 query_project_tools.py）。
2. 再执行符号查询：让 agent 用query_project在目标项目中执行只读符号工具，例如查询某符号的定义、引用或项目符号概览。query_project只允许执行只读工具——非只读工具会在断言处被拒绝，无法用于修改外部项目。

一次成功的查询返回的是对应只读工具在目标项目上下文中执行的结果（符号名、文件位置、代码片段等），与在当前项目中直接调用该工具的输出形态一致。若list_queryable_projects中看不到目标项目，回到前两步核对：项目是否已执行serena project create，以及 JetBrains 后端下 IDE 是否打开了该项目。

限制与边界

• query_project是纯只读通道：它不激活项目，也不能执行编辑类工具。要对外部项目做修改，仍需在该项目中正常激活它并工作。
• LSP 后端下，Project Server 是符号查询的前提；未启动时符号查询无法完成。
• 该工具在单项目类上下文中默认不出现（可选工具），必须显式通过上述任一模式配置启用。
• 全局配置、project.yml与命令行参数对模式的覆盖关系见 Configuration 文档的 Modes 一节；完整的工作流背景（项目创建、索引、激活）见 Project Workflow。

【免费下载链接】serenaA powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent项目地址: https://gitcode.com/GitHub_Trending/ser/serena