# 塞琳娜编码代理 ## 基本信息 - Slug: `oraios-serena` - Source: modelscope - Publisher: @oraios/serena - Categories: developer-tools / version-control - Hosted: No - License: MIT License - Source URL: https://www.modelscope.cn/mcp/servers/@oraios/serena ## 简介 一个功能齐全的编码代理，它使用符号操作（由语言服务器启用），即使在大型代码库中也能很好地工作。本质上是 Cursor 和 Windsurf Agents、Cline、Roo Code 等的免费替代品。 ## 安装提示 ```bash :info: 如果你在配置中设置了 `enable_project_activation`，则传递项目文件是可选的， 因为这样你可以简单地指示 Claude 激活你想要工作的项目。 如果你在 Windows 上使用包含反斜杠的路径 （请注意，你也可以只使用正斜杠），请确保正确转义它们（`\\`）。 就这样！保存配置，然后重新启动 Claude 桌面版。 注意：在 Windows 和 macOS 上有 Anthropic 提供的官方 Claude 桌面应用程序，对于 Linux 有一个 [开源社区版本](https://github.com/aaddrick/claude-desktop-debian)。 ⚠️ 确保完全退出 Claude 桌面应用程序，因为关闭 Claude 只会将其最小化到系统托盘——至少在 Windows 上是这样。 重新启动后，你应该会在聊天界面中看到 Serena 的工具（注意小锤子图标）。 ⚠️ 工具名称：Claude 桌面版（以及大多数 MCP 客户端）不会解析服务器的名称。因此你不应该说“使用 Serena 的工具”之类的话。相反，你可以指示 LLM 使用符号工具或通过引用其名称来使用特定工具。此外，如果你使用多个 MCP 服务器，可能会出现**工具名称冲突**，导致未定义的行为。例如，由于工具名称冲突，Serena 目前与 [文件系统 MCP 服务器](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) 不兼容。 ℹ️ 请注意，使用 stdio 作为协议的 MCP 服务器在客户端/服务器架构中是相对不常见的，因为为了通过服务器的标准输入/输出流进行通信，客户端必须启动服务器。换句话说，您不需要自己启动服务器。客户端应用程序（例如 Claude Desktop）会负责这一点，因此需要配置一个启动命令。 有关 Claude Desktop 的 MCP 服务器的更多信息，请参阅[官方快速入门指南](https://modelcontextprotocol.io/quickstart/user)。 ### 其他 MCP 客户端 - Cline, Roo-Code, Cursor, Windsurf 等 作为一个 MCP 服务器，Serena 可以被任何 MCP 客户端包含。与上述相同的配置，可能加上一些特定于客户端的小修改即可工作。大多数流行的现有编码助手（IDE 扩展或类似 VSCode 的 IDE）都支持连接到 MCP 服务器。包括 Serena 通常可以通过提供符号操作工具来提高它们的性能。 在这种情况下，使用的计费继续由您选择的客户端控制（不像使用 Claude Desktop 客户端那样）。但您仍然可能希望通过这种方式使用 Serena，例如出于以下原因之一： 1. 您已经在使用一个编码助手（比如 Cline 或 Cursor），只是想让它更强大。 2. 您使用的是 Linux 并且不想使用[社区创建的 Claude Desktop](https://github.com/aaddrick/claude-desktop-debian)。 3. 您希望将 Serena 更紧密地集成到您的 IDE 中，并且不介意为此付费。 这里同样适用使用 Claude Desktop 的 Serena 时的注意事项（特别是工具名称冲突问题）。 当在内置有 AI 编码交互功能的 IDE 或扩展中使用时（实际上，所有这些都有），Serena 的全套工具可能会导致与您作为用户无法控制的客户端内部工具发生不必要的交互。这尤其适用于编辑工具，您可能需要为此目的禁用这些工具。随着我们在各种流行客户端中使用 Serena 积累更多经验，我们将收… ``` ## MCP Server 详情

* :rocket: Serena 是一个强大的 **编码代理工具包**，能够将大型语言模型（LLM）转变为可以直接在您的代码库上工作的全功能代理。 * :wrench: Serena 提供了类似于 IDE 功能的基本 **语义代码检索和编辑工具**，能够在符号级别提取代码实体并利用关系结构。 * :free: Serena 是 **免费且开源的**，可以增强您已经可以免费访问的 LLM 的能力。 ### 演示 这里是一个使用 Claude Desktop 的 Serena 实现一个小功能（更好的日志 GUI）的演示。请注意 Serena 的工具如何使 Claude 能够找到并编辑正确的符号。 [https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753](https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753) ### LLM 集成 Serena 为编码工作流程提供了必要的 [工具](#full-list-of-tools)，但需要 LLM 来实际执行任务，并协调工具的使用。 Serena 可以通过以下几种方式与 LLM 集成： * 通过使用 **模型上下文协议 (MCP)**。 Serena 提供了一个 MCP 服务器，可以与 * Claude Desktop， * 如 VSCode、Cursor 或 IntelliJ 等 IDE， * 如 Cline 或 Roo Code 等扩展， * Goose（用于良好的 CLI 体验） * 以及许多其他工具集成，包括 [即将支持的 ChatGPT 应用程序](https://x.com/OpenAIDevs/status/1904957755829481737) * 通过使用 **Agno——模型无关的代理框架**。 基于 Agno 的 Serena 代理可以让您几乎将任何 LLM 转变为编码代理，无论是由 Google、OpenAI 或 Anthropic（需付费 API 密钥）提供的 还是由 Ollama、Together 或 Anyscale 提供的免费模型。 * 通过将 Serena 的工具整合到您选择的代理框架中。 Serena 的工具实现与特定框架的代码是解耦的，因此可以轻松适应任何代理框架。 ### 编程语言支持与语义分析能力 Serena 的语义代码分析能力基于广泛实现的 **语言服务器** 和语言服务器协议 (LSP)。LSP 提供了一组基于对代码的符号理解的多功能代码查询和编辑功能。 配备了这些功能后，Serena 发现和编辑代码就像一位经验丰富的开发人员利用 IDE 的能力一样。 即使在非常大且复杂的项目中，Serena 也能高效地找到正确的上下文并做出正确的操作！因此，它不仅免费且开源，还经常比现有的收费解决方案取得更好的结果。 语言服务器支持广泛的编程语言。借助 Serena，我们提供 * 直接开箱即用的支持： * Python * Java (_注意_：启动较慢，初次启动尤其如此) * TypeScript * 间接支持（可能需要一些代码更改/手动安装）： * Ruby（未测试） * Go（未测试） * C#（未测试） * Rust（未测试） * Kotlin（未测试） * Dart（未测试） * C/C++（未测试） 这些语言由语言服务器库 [multilspy](https://github.com/microsoft/multilspy) 支持，Serena 在幕后使用该库。但我们没有明确测试这些语言的支持是否实际有效。 原则上，通过为新的语言服务器实现提供一个浅层适配器，可以轻松支持更多语言。 ## 目录 - [我能用 Serena 做什么？](#我能用-serena-做什么) - [使用 Serena 的免费编码代理](#使用-serena-的免费编码代理) - [快速开始](#快速开始) * [设置与配置](#设置与配置) * [MCP 服务器 (Claude Desktop)](#mcp-服务器-claude-desktop) * [其他 MCP 客户端 - Cline, Roo-Code, Cursor, Windsurf 等](#其他-mcp-客户端---cline-roo-code-cursor-windsurf-等) * [Goose](#goose) * [Agno 代理](#agno-代理) * [其他代理框架](#其他代理框架) - [Serena 的工具和配置](#serena-的工具和配置) - [与其他编码代理的比较](#与其他编码代理的比较) * [基于订阅的编码代理](#基于订阅的编码代理) * [基于 API 的编码代理](#基于-api-的编码代理) * [其他基于 MCP 的编码代理](#其他基于-mcp-的编码代理) - [入门和记忆](#入门和记忆) - [与其他 MCP 服务器的组合](#与其他-mcp-服务器的组合) - [使用 Serena 的建议](#使用-serena-的建议) * [选择哪个模型？](#选择哪个模型) * [入门](#入门-1) * [在编辑代码之前](#在编辑代码之前) * [代码编辑中可能出现的问题](#代码编辑中可能出现的问题) * [超出上下文限制](#超出上下文限制) * [控制工具执行](#控制工具执行) * [组织你的代码库](#组织你的代码库) * [日志、代码检查和测试](#日志-代码检查和测试) * [一般建议](#一般建议) - [故障排除](#故障排除) * [Serena 日志](#serena-日志) - [致谢](#致谢) - [自定义 Serena](#自定义-serena) - [工具完整列表](#工具完整列表) ## 我能用 Serena 做什么？ 你可以使用 Serena 完成任何编码任务——无论是专注于分析、规划、设计新组件还是重构现有组件。 由于 Serena 的工具允许大语言模型（LLM）闭合认知感知-行动循环，基于 Serena 的代理可以从头到尾自主地执行编码任务——从最初的分析到实现、测试，最后到版本控制系统提交。 Serena 可以读取、编写和执行代码，阅读日志和终端输出。 虽然我们不一定鼓励这样做，“随性编程”当然是可能的，如果你想几乎感觉“代码不再存在”， 你可能会发现 Serena 比 IDE 内部的代理更适合随性编程（因为你将有一个独立的图形用户界面，真的可以让你忘记这一切）。 ## 使用 Serena 的免费编码代理 即使是 Anthropic 的 Claude 的免费层级也支持 MCP 服务器，因此你可以免费使用 Claude 与 Serena。 预计一旦添加了对 MCP 服务器的支持，很快也可以通过 ChatGPT Desktop 实现相同功能。 通过 Agno，你还有选项可以使用一个免费/开放权重模型来使用 Serena。 Serena 是 [Oraios AI](https://oraios-ai.de/) 对开发者社区的贡献。 我们自己也经常使用它。 我们厌倦了不得不支付多个基于 IDE 的订阅费用（如 Windsurf 或 Cursor），这些费用迫使我们在已经存在的聊天订阅成本之外还要购买更多的令牌。 像 Claude Code、Cline、Aider 等基于 API 的工具所产生的高额 API 费用同样不吸引人。 因此，我们构建了 Serena，希望能够取消大部分其他订阅。 ## 快速开始 Serena 可以以多种方式使用，下面是一些选定集成的说明。 - 如果你只想将 Claude 转变为一个免费使用的编码代理，我们建议通过 Claude Desktop 使用 Serena。 - 如果你想使用 Gemini 或任何其他模型，并且想要一个图形用户界面体验，你应该使用 [Agno](#agno-agent)。在 macOS 上，你还可以使用 [goose](#goose) 的图形用户界面。 - 如果你更喜欢通过命令行界面使用 Serena，可以使用 [goose](#goose)。在那里几乎任何模型都是可能的。 - 如果你想在你的 IDE 中使用集成的 Serena，请参阅关于 [其他 MCP 客户端](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc) 的部分。 ### 设置和配置 1. 安装 `uv`（安装说明[在这里](https://docs.astral.sh/uv/getting-started/installation/)） 2. 将仓库克隆到 `/path/to/serena`。 3. 将 `serena_config.template.yml` 复制为 `serena_config.yml` 并调整设置。 4. 将 `myproject.template.yml` 复制为 `myproject.yml` 并根据你的项目调整特定设置。 （对于每个希望 Serena 工作的项目，都添加这样一个文件。） 5. 如果希望 Serena 动态切换项目，在 `serena_config.yml` 中的 `projects` 列表里添加上一步创建的所有项目文件列表。 > ⚠️ **注意：** Serena 正在积极开发中。我们持续添加功能、改进稳定性和用户体验。 > 因此，配置可能会以破坏性的方式更改。如果你的配置无效， > MCP 服务器或基于 Serena 的代理可能无法启动（在这种情况下，请检查 MCP 日志）。 > 在更新 Serena 时，请查看 [变更日志](CHANGELOG.md) > 并根据需要调整你的配置。 完成初始设置后，根据你想要如何使用 Serena，继续以下部分之一。 ### MCP 服务器 (Claude 桌面版) 1. 为你的项目创建一个配置文件，例如 `myproject.yml`，基于 [myproject.template.yml](myproject.template.yml) 模板。 2. 在客户端中配置 MCP 服务器。 对于 [Claude 桌面版](https://claude.ai/download)（适用于 Windows 和 macOS），请转到 文件 / 设置 / 开发者 / MCP 服务器 / 编辑配置， 这将允许你打开 JSON 文件 `claude_desktop_config.json`。添加以下内容（并调整路径）以启用 Serena： ```json { "mcpServers": { "serena": { "command": "/abs/path/to/uv", "args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server", "--project-file", "/abs/path/to/myproject.yml"] } } } ``` :info: 如果你在配置中设置了 `enable_project_activation`，则传递项目文件是可选的， 因为这样你可以简单地指示 Claude 激活你想要工作的项目。 如果你在 Windows 上使用包含反斜杠的路径 （请注意，你也可以只使用正斜杠），请确保正确转义它们（`\\`）。 就这样！保存配置，然后重新启动 Claude 桌面版。 注意：在 Windows 和 macOS 上有 Anthropic 提供的官方 Claude 桌面应用程序，对于 Linux 有一个 [开源社区版本](https://github.com/aaddrick/claude-desktop-debian)。 ⚠️ 确保完全退出 Claude 桌面应用程序，因为关闭 Claude 只会将其最小化到系统托盘——至少在 Windows 上是这样。 重新启动后，你应该会在聊天界面中看到 Serena 的工具（注意小锤子图标）。 ⚠️ 工具名称：Claude 桌面版（以及大多数 MCP 客户端）不会解析服务器的名称。因此你不应该说“使用 Serena 的工具”之类的话。相反，你可以指示 LLM 使用符号工具或通过引用其名称来使用特定工具。此外，如果你使用多个 MCP 服务器，可能会出现**工具名称冲突**，导致未定义的行为。例如，由于工具名称冲突，Serena 目前与 [文件系统 MCP 服务器](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) 不兼容。 ℹ️ 请注…