oraios--serena
wehub-resource-sync
e260b46b98
Tests / native (windows-latest) (push) Has been cancelled
Tests / niche (ubuntu-latest) (push) Has been cancelled
Tests / other-langs (macos-latest) (push) Has been cancelled
Tests / other-langs (ubuntu-latest) (push) Has been cancelled
Tests / other-langs (windows-latest) (push) Has been cancelled
Tests / catch-all (macos-latest) (push) Has been cancelled
Tests / catch-all (ubuntu-latest) (push) Has been cancelled
Tests / catch-all (windows-latest) (push) Has been cancelled
Tests / jvm (macos-latest) (push) Has been cancelled
Tests / jvm (ubuntu-latest) (push) Has been cancelled
Tests / jvm (windows-latest) (push) Has been cancelled
Tests / native (macos-latest) (push) Has been cancelled
Tests / native (ubuntu-latest) (push) Has been cancelled
Codespell / Check for spelling errors (push) Has been cancelled
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
CodeQL Advanced / Analyze (javascript-typescript) (push) Has been cancelled
CodeQL Advanced / Analyze (python) (push) Has been cancelled
Build and Push Docker Images / build-and-push (push) Has been cancelled
Docs Build / build (push) Has been cancelled
Docs Build / deploy (push) Has been cancelled
253 行
13 KiB
Markdown
253 行
13 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/oraios/serena) · [上游 README](https://github.com/oraios/serena/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<p align="center" style="text-align:center;">
|
||
<img src="resources/serena-logo.svg#gh-light-mode-only" style="width:500px">
|
||
<img src="resources/serena-logo-dark-mode.svg#gh-dark-mode-only" style="width:500px">
|
||
</p>
|
||
|
||
<h3 align="center">
|
||
为你的编程 Agent 打造的 IDE
|
||
</h3>
|
||
|
||
<div align="center">
|
||
<a href="https://discord.com/invite/cVUNQmnV4r"><img src="https://img.shields.io/badge/discord-join-5865F2?style=flat-square&labelColor=0a0e14&logo=discord&logoColor=5865F2" alt="discord"></a>
|
||
<a href="https://github.com/oraios/serena/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-b0e8ff?style=flat-square&labelColor=0a0e14" alt="license"></a>
|
||
</div>
|
||
<br>
|
||
|
||
|
||
* Serena 提供必不可少的**语义化代码检索、编辑、重构与调试工具**，能力堪比 IDE，
|
||
在符号层面运行，并充分利用代码的关系结构。
|
||
* 它通过模型上下文协议（**MCP**，Model Context Protocol）与任何客户端/LLM 集成。
|
||
|
||
Serena 的**面向 Agent 优先的工具设计**采用稳健的高层抽象，有别于
|
||
依赖行号或原始搜索模式等底层概念的做法。
|
||
|
||
practically，这意味着你的 Agent 能够**更快、更高效、更可靠**地运行，尤其是在更大、
|
||
更复杂的代码库中。
|
||
|
||
> [!IMPORTANT]
|
||
> 请勿通过 MCP 或插件市场安装 Serena！其中的安装命令已过时且并非最优。
|
||
> 请改按我们的[快速开始](#quick-start)说明操作。
|
||
|
||
## Quick Demo
|
||
|
||
https://github.com/user-attachments/assets/8d11646e-b80e-4723-b9d7-32d6101b5f58
|
||
|
||
:tv: 更长视频：[5 分钟了解 Serena（YouTube）](https://www.youtube.com/watch?v=5QN7gN1KYLA)
|
||
|
||
## 我们的「最终用户」怎么说
|
||
|
||
虽然下载和配置 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 加到你的客户端吧！_
|
||
|
||
请参阅我们的[文档](https://oraios.github.io/serena/04-evaluation/000_evaluation-intro.html) 了解完整方法论及更详细的评估结果，或在你自选的项目上自行运行评估。
|
||
|
||
|
||
## Serena 如何工作
|
||
|
||
Serena 为编码工作流提供必要的[工具](https://oraios.github.io/serena/01-about/035_tools.html)，
|
||
但实际工作仍需 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。
|
||
|
||
<img src="resources/serena-block-diagram.svg">
|
||
|
||
:tv: 另见：[5 分钟了解 Serena（YouTube）](https://www.youtube.com/watch?v=5QN7gN1KYLA)
|
||
|
||
要将 Serena MCP 服务器连接到你的客户端，你可以
|
||
* 向客户端提供启动命令，由其启动 MCP 服务器，或
|
||
* 自行以 HTTP 模式启动 Serena MCP 服务器，并向客户端提供 URL。
|
||
|
||
请参阅下方[快速开始](#quick-start)章节了解如何上手。
|
||
|
||
## 编程语言支持与语义分析能力
|
||
|
||
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 暂不支持）。
|
||
|
||
<a href="https://plugins.jetbrains.com/plugin/28946-serena/"><img src="docs/_static/images/jetbrains-marketplace-button.png"></a>
|
||
|
||
请参阅我们的[文档页面](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html) 了解进一步详情及插件应用说明。
|
||
|
||
## 功能
|
||
|
||
Serena 提供广泛的工具，用于高效代码检索、编辑与重构，
|
||
以及面向长期 Agent 工作流的记忆系统。
|
||
|
||
鉴于功能范围广泛，Serena 通过多层配置系统适配你的需求。
|
||
|
||
<details>
|
||
<summary>详情</summary>
|
||
|
||
### 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 |
|
||
|
||
*: 通常不适用于外部依赖中的声明。<br>
|
||
**：仅部分语言可用，受语言服务器（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）
|
||
|
||
</details>
|
||
|
||
## 快速开始
|
||
|
||
**前置条件**。Serena 由 *uv* 管理，[安装 uv](https://docs.astral.sh/uv/getting-started/installation/) 是唯一必需的前置条件。
|
||
|
||
> [!NOTE]
|
||
> 使用语言服务器后端时，可能需要安装一些额外依赖以支持特定语言；
|
||
> 详情请参阅 [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) 页面。
|
||
|
||
**安装 Serena**。通过 uv 安装 Serena 的步骤如下：
|
||
|
||
```bash
|
||
uv tool install -p 3.13 serena-agent
|
||
```
|
||
|
||
安装成功后，命令 `serena` 应可在 shell 中使用。
|
||
|
||
**初始化 Serena**。要初始化 Serena 并验证配置是否正确，只需运行：
|
||
|
||
```bash
|
||
serena init
|
||
```
|
||
|
||
默认情况下，这将把 Serena 配置为使用语言服务器后端。若要改用 JetBrains 后端，请添加参数 `-b JetBrains`
|
||
（更多用法请参阅 [JetBrains Plugin documentation page](https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html)）。
|
||
无论哪种方式，你都应收到表明 Serena 已成功初始化的成功消息。
|
||
|
||
**配置客户端**。要将 Serena 连接到首选的 MCP 客户端，通常需要在客户端中 [配置启动命令](https://oraios.github.io/serena/02-usage/030_clients.html).
|
||
请按链接查看如何在 Claude Code、Codex、Claude Desktop、支持 MCP 的 IDE 及其他客户端（如本地与基于 Web 的 GUI）中设置 Serena 的具体说明。
|
||
|
||
> [!TIP]
|
||
> 快速上手很容易，但 Serena 是功能丰富、配置项众多的强大工具包。
|
||
> 我们强烈建议阅读 [user guide](https://oraios.github.io/serena/02-usage/000_intro.html)，以充分发挥 Serena 的价值。
|
||
>
|
||
> 尤其建议了解……
|
||
> * [Serena's project-based workflow](https://oraios.github.io/serena/02-usage/040_workflow.html)，以及
|
||
> * [configuring Serena](https://oraios.github.io/serena/02-usage/050_configuration.html).
|
||
|
||
## 用户指南
|
||
|
||
有关如何有效使用 Serena 的详细说明，请参阅 [user guide](https://oraios.github.io/serena/02-usage/000_intro.html)。
|
||
|
||
## 致谢
|
||
|
||
Serena 的很大一部分，尤其是多种语言的支持，来自开源社区的贡献。我们非常感谢众多贡献者——他们的付出使这一切成为可能，并在塑造如今的 Serena 方面发挥了重要作用。
|
||
|
||
<!-- mcp-name: io.github.oraios/serena -->
|