wehub-resource-sync
e260b46b98
13 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
为你的编程 Agent 打造的 IDE
- Serena 提供必不可少的语义化代码检索、编辑、重构与调试工具，能力堪比 IDE， 在符号层面运行，并充分利用代码的关系结构。
- 它通过模型上下文协议（MCP，Model Context Protocol）与任何客户端/LLM 集成。
Serena 的面向 Agent 优先的工具设计采用稳健的高层抽象，有别于 依赖行号或原始搜索模式等底层概念的做法。
practically，这意味着你的 Agent 能够更快、更高效、更可靠地运行，尤其是在更大、 更复杂的代码库中。
Important
请勿通过 MCP 或插件市场安装 Serena！其中的安装命令已过时且并非最优。 请改按我们的快速开始说明操作。
Quick Demo
https://github.com/user-attachments/assets/8d11646e-b80e-4723-b9d7-32d6101b5f58
📺 更长视频：5 分钟了解 Serena（YouTube）
我们的「最终用户」怎么说
虽然下载和配置 Serena 的是人类，但我们的最终用户本质上是 AI Agent。 作为实际使用 Serena 工具的一方，他们最有资格评价 Serena。
我们设计了一套无偏见的评估提示，引导 Agent 完成约 20 项日常开发中的常规编码任务， 以估算在与自身内置能力配合使用时，Serena 工具所带来的价值。
以下是 Agent 们的一句话总结：
Claude Code 中 Opus 4.6 (high)，大型 Python 代码库：
"Serena 基于 IDE 的语义化工具是我工具箱里影响最大的一项补充——跨文件重命名、移动和引用查找， 原本需要我花 8–12 步小心翼翼、易出错的操作，现在一次原子调用就能完成；我绝对会请与我合作的任何开发者都配置上它们。"
Codex CLI 中 GPT 5.4 (high)，Java 代码库：
"作为编程 AI Agent，我会请我的使用者添加 Serena，因为它补上了我在符号、引用和重构方面缺失的 IDE 级理解， 把脆弱的文本手术变成更从容、更快、更有把握的语义化代码修改。"
Copilot CLI 中 GPT 5.4 (medium)，大型多语言 monorepo：
"作为编程 Agent，我绝对会请我的使用者添加 Serena，因为它让我在真实代码上明显更敏锐、更从容—— 尤其是符号感知导航、跨文件重构和 monorepo 依赖跳转——同时我仍会用内置能力处理细小文本编辑和非代码工作。"
不同 Agent 在不同场景下，不约而同地得出相同结论。
给你的 Agent 它一直想要的工具，把 Serena MCP 加到你的客户端吧！
请参阅我们的文档 了解完整方法论及更详细的评估结果，或在你自选的项目上自行运行评估。
Serena 如何工作
Serena 为编码工作流提供必要的工具， 但实际工作仍需 LLM 来编排工具使用。
Serena 可通过**模型上下文协议（MCP）**扩展你现有 AI 客户端的功能。 大多数现代 AI 聊天客户端直接支持 MCP，包括
- 终端类客户端，如 Claude Code、Codex、OpenCode 或 Gemini-CLI，
- VSCode、Cursor 和 JetBrains IDE 的 IDE 及 IDE 助手插件（Copilot、Junie、JetBrains AI Assistant 等），
- 桌面与 Web 客户端，如 Claude Desktop、Codex App 或 OpenWebUI。
要将 Serena MCP 服务器连接到你的客户端，你可以
- 向客户端提供启动命令，由其启动 MCP 服务器，或
- 自行以 HTTP 模式启动 Serena MCP 服务器，并向客户端提供 URL。
请参阅下方快速开始章节了解如何上手。
编程语言支持与语义分析能力
Serena 基于对代码的符号化理解，提供一套灵活的代码查询与编辑功能。 借助这些能力，你的 Agent 能像资深开发者利用 IDE 能力一样发现和编辑代码。 即使在非常大且复杂的项目中，Serena 也能高效找到正确上下文并做出正确操作！
支撑这些能力的技术有两套可选方案：
- 实现语言服务器协议（LSP，Language Server Protocol）的语言服务器——免费/开源方案，默认使用。
- Serena JetBrains 插件，利用 JetBrains IDE 强大的代码分析与编辑能力（付费插件；提供免费试用）。
你可按偏好与需求任选其一作为后端。
Language Servers
Serena 为集成实现语言服务器协议（LSP）的语言服务器提供了强大的抽象层。 底层语言服务器通常是开源项目，或至少可免费使用。
使用 Serena 的语言服务器后端时，我们支持 40 多种编程语言，包括 Ada / SPARK、AL、Angular、Ansible、Bash、BSL、C#、C/C++、Clojure、Crystal、CUE、Dart、Elixir、Elm、Erlang、Fortran、F#、GDScript、GLSL、Go、Groovy、Haskell、Haxe、HLSL、HTML、Java、JavaScript、JSON、Julia、Kotlin、LaTeX、Lean 4、Lua、Luau、Markdown、MATLAB、mSL、Nix、OCaml、Perl、PHP、PowerShell、Python、R、Ruby、Rust、Scala、SCSS / Sass / CSS、Solidity、Svelte、Swift、TOML、TypeScript、WGSL、YAML 和 Zig。
Serena JetBrains 插件
付费的 Serena JetBrains 插件（提供免费试用） 利用 JetBrains IDE 强大的代码分析能力。 该插件天然支持 JetBrains IDE 所支持的所有编程语言与框架， 包括 IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、RubyMine、GoLand 等（Rider 和 CLion 暂不支持）。
请参阅我们的文档页面 了解进一步详情及插件应用说明。
功能
Serena 提供广泛的工具，用于高效代码检索、编辑与重构， 以及面向长期 Agent 工作流的记忆系统。
鉴于功能范围广泛，Serena 通过多层配置系统适配你的需求。
详情
Retrieval
Serena 的检索工具让 Agent 在符号层面探索代码库，理解结构与关系， 而无需阅读整个文件。
| Capability | Language Servers | JetBrains Plugin |
|---|---|---|
| find symbol | yes | yes |
| symbol overview (file outline) | yes | yes |
| find referencing symbols | yes | yes |
| search in project dependencies | -- | yes |
| type hierarchy | -- | yes |
| find declaration | yes* | yes |
| find implementations | yes** | yes |
| query external projects | yes | yes |
| diagnostics/inspections | yes | yes |
*: 通常不适用于外部依赖中的声明。
**：仅部分语言可用，受语言服务器（language server）功能限制。
重构
若没有精确的重构工具，智能体（agent）只能被迫依赖不可靠且成本高昂的搜索替换操作。
| 能力 | Language Servers | JetBrains Plugin |
|---|---|---|
| rename | 是（仅符号） | 是（符号、文件、目录） |
| move（符号、文件、目录） | -- | 是 |
| inline | -- | 是 |
| propagate deletions（删除未使用代码） | -- | 是 |
符号化编辑
Serena 的符号化编辑工具比常见替代方案更少出错，且 token 效率更高。
| 能力 | Language Servers | JetBrains Plugin |
|---|---|---|
| replace symbol body | 是 | 是 |
| insert after symbol | 是 | 是 |
| insert before symbol | 是 | 是 |
| safe delete | 是 | 是 |
交互式调试
此项为 JetBrains 插件独有。Serena 提供一款高度通用的调试工具，智能体可通过持久的 REPL 风格界面设置断点、检查变量、求值表达式并控制执行流程。
基础功能
除语义能力外，Serena 还包含一组基础工具以保障完整性。当 Serena 在 Claude Code 或 Codex 等智能体宿主（agentic harness）中使用时，这些工具通常默认禁用，因为外围宿主已提供重叠的文件、搜索和 shell 能力。
search_for_pattern– 在整个代码库中进行灵活的 regex 搜索replace_content– 面向智能体优化的、基于 regex 的字面量文本替换list_dir/find_file– 目录列表与文件搜索read_file– 读取文件或文件片段execute_shell_command– 运行 shell 命令（例如构建、测试、linter）
记忆管理
记忆系统是长期运行的智能体工作流的基础组件，尤其在知识需要在会话、用户和项目之间共享时更是如此。尽管设计简洁，我们仍收到许多用户的积极反馈——他们倾向于将 Serena 的记忆管理系统与其智能体的内部系统（例如 AGENTS.md 文件）结合使用。若你更愿使用其他方案，也可轻松禁用该功能。
可配置性
Serena 的活跃工具、工具描述、提示词（prompts）、语言后端细节等诸多方面，只需调整几行 YAML 即可按场景灵活配置。为此，Serena 提供多层（可组合的）配置：
- 全局配置
- MCP 启动命令（CLI）配置
- 按项目配置（支持本地覆盖）
- 执行上下文相关配置（例如针对特定客户端）
- 可动态组合的配置片段（modes）
快速开始
前置条件。Serena 由 uv 管理，安装 uv 是唯一必需的前置条件。
Note
使用语言服务器后端时，可能需要安装一些额外依赖以支持特定语言； 详情请参阅 Language Support 页面。
安装 Serena。通过 uv 安装 Serena 的步骤如下：
uv tool install -p 3.13 serena-agent
安装成功后，命令 serena 应可在 shell 中使用。
初始化 Serena。要初始化 Serena 并验证配置是否正确，只需运行：
serena init
默认情况下，这将把 Serena 配置为使用语言服务器后端。若要改用 JetBrains 后端，请添加参数 -b JetBrains
（更多用法请参阅 JetBrains Plugin documentation page）。
无论哪种方式，你都应收到表明 Serena 已成功初始化的成功消息。
配置客户端。要将 Serena 连接到首选的 MCP 客户端，通常需要在客户端中 配置启动命令. 请按链接查看如何在 Claude Code、Codex、Claude Desktop、支持 MCP 的 IDE 及其他客户端（如本地与基于 Web 的 GUI）中设置 Serena 的具体说明。
Tip
快速上手很容易，但 Serena 是功能丰富、配置项众多的强大工具包。 我们强烈建议阅读 user guide，以充分发挥 Serena 的价值。
尤其建议了解……
用户指南
有关如何有效使用 Serena 的详细说明，请参阅 user guide。
致谢
Serena 的很大一部分，尤其是多种语言的支持，来自开源社区的贡献。我们非常感谢众多贡献者——他们的付出使这一切成为可能，并在塑造如今的 Serena 方面发挥了重要作用。