塞尔纳

• :rocket: Serena 是一个强大的编码代理工具包，能够将大型语言模型（LLM）转变为可以直接在您的代码库上工作的全功能代理。与大多数其他工具不同，它不依赖于特定的 LLM、框架或接口，因此可以以多种方式轻松使用。
• :wrench: Serena 提供了类似于 IDE 的语义代码检索和编辑工具，能够在符号级别提取代码实体并利用关系结构。当与现有的编码代理结合使用时，这些工具可以大大提高（令牌）效率。
• :free: Serena 是免费且开源的，可以增强您已经可以免费访问的 LLM 的能力。

您可以将 Serena 视为为您的 LLM/编码代理提供类似 IDE 的工具。有了它，代理不再需要读取整个文件、执行 grep 类似的搜索或字符串替换来查找和编辑正确的代码。相反，它可以使用以代码为中心的工具，如 find_symbol、find_referencing_symbols 和 insert_after_symbol。

LLM 集成

Serena 为编码工作流提供了必要的工具，但实际工作仍需 LLM 来协调工具的使用。

例如，通过一行 shell 命令来大幅提升 Claude Code 的性能。

一般来说，Serena 可以通过以下几种方式与 LLM 集成：

• 使用模型上下文协议 (MCP)。Serena 提供了一个 MCP 服务器，可以与
  • Claude Code 和 Claude Desktop，
  • 基于终端的客户端，如 Codex、Gemini-CLI、Qwen3-Coder、rovodev、OpenHands CLI 等，
  • 如 VSCode、Cursor 或 IntelliJ 等 IDE，
  • 如 Cline 或 Roo Code 等扩展，
  • 如 OpenWebUI、Jan、Agno 等本地客户端
• 使用 mcpo 将其连接到 ChatGPT 或其他不支持 MCP 但支持通过 OpenAPI 调用工具的客户端。
• 将 Serena 的工具集成到您选择的代理框架中，如这里所示。Serena 的工具实现与框架特定代码解耦，因此可以轻松适应任何代理框架。

Serena 实战

演示 1：在 Claude Code 中高效操作

演示了 Serena 在 Claude Code 中高效地检索和编辑代码，从而节省令牌和时间。高效的操不仅有助于节省成本，还能总体上提高生成代码的质量。这种效果在非常小的项目中可能不太明显，但在较大的项目中通常变得至关重要。

https://github.com/user-attachments/assets/ab78ebe0-f77d-43cc-879a-cc399efefd87

演示 2：在 Claude Desktop 中使用 Serena

演示了 Serena 在 Claude Desktop 中为自己实现一个小功能（更好的日志 GUI）。请注意，Serena 的工具如何使 Claude 能够找到并编辑正确的符号。### 编程语言支持与语义分析能力

Serena 的语义代码分析能力基于广泛实现的 语言服务器，使用语言服务器协议 (LSP)。LSP 提供了一组基于代码符号理解的多功能代码查询和编辑功能。借助这些功能，Serena 可以像经验丰富的开发人员利用 IDE 功能一样发现和编辑代码。即使在非常大且复杂的项目中，Serena 也能高效地找到正确的上下文并执行正确的操作！因此，它不仅免费且开源，还经常比那些收费的现有解决方案取得更好的结果。

语言服务器为广泛的编程语言提供支持。通过 Serena，我们提供了以下语言的直接、开箱即用的支持：

• Python
• TypeScript/Javascript
• PHP（使用 Intelephense LSP；设置 INTELEPHENSE_LICENSE_KEY 环境变量以启用高级功能）
• Go（需要安装 gopls）
• R（需要安装 languageserver R 包）
• Rust（需要 rustup - 使用来自工具链的 rust-analyzer）
• C/C++（查找引用时可能会遇到问题，我们正在解决中）
• Zig（需要安装 ZLS - Zig 语言服务器）
• C#
• Ruby（默认情况下，使用 ruby-lsp，指定 ruby_solargraph 作为您的语言以使用之前的 solargraph 基础实现）
• Swift
• Kotlin（使用预发布版 官方 kotlin LS，可能会出现一些问题）
• Java（注意：启动速度较慢，尤其是初次启动。在 macOS 和 Linux 上可能会遇到 Java 问题，我们正在解决中。）
• Clojure
• Dart
• Bash
• Lua（如果未安装，则会自动下载 lua-language-server）
• Nix（需要安装 nixd）
• Elixir（需要安装 NextLS 和 Elixir；不支持 Windows）
• Erlang（需要安装 beam 和 erlang_ls，实验性功能，可能运行缓慢或卡顿）
• AL

通过为新的语言服务器实现提供一个简单的适配器，可以轻松添加对更多语言的支持，请参阅 Serena 的 相关文档。

社区反馈

大多数用户报告称，即使在像 Claude Code 这样已经非常强大的代理中使用，Serena 对他们的编码代理的结果也有显著的积极影响。Serena 经常被描述为游戏规则改变者，提供了巨大的生产力提升。

Serena 在导航和操作复杂代码库方面表现出色，提供了在大型、结构化代码库存在的情况下支持精确代码检索和编辑的工具。然而，在处理仅涉及非常少或小文件的任务时，您可能不会从在现有编码代理之上包含 Serena 中受益。
特别是从头开始编写代码时，Serena 初始阶段提供的价值不大，因为 Serena 更优雅地处理的更复杂结构尚未创建。

关于 Serena 的一些视频和博客文章如下：

• YouTube:

  • AI Labs
  • Yo Van Eyck
  • JeredBlu

• 博客文章：

  • Serena 的设计原则
  • Serena 与 Claude Code（日语）* 将Claude代码转变为开发利器

目录

• 快速开始
  • 运行Serena MCP服务器
    • 用法
      • 使用uvx
        • 本地安装
      • 使用Docker（实验性）
    • SSE模式
    • 命令行参数
  • 配置
  • 项目激活与索引
  • Claude代码
  • Codex
  • 其他基于终端的客户端
  • Claude桌面版
  • MCP编码客户端（Cline, Roo-Code, Cursor, Windsurf等）
  • 本地GUI和框架
• 详细用法和建议
  • 工具执行
    • Shell执行和编辑工具
  • 模式和上下文
    • 上下文
    • 模式
    • 自定义
  • 入门和记忆
  • 准备您的项目
    • 组织您的代码库
    • 从干净的状态开始
    • 日志、代码检查和自动化测试
  • 提示策略
  • 代码编辑中的潜在问题
  • 超出上下文
  • 结合其他MCP服务器使用Serena
  • Serena的日志：仪表板和GUI工具
  • 故障排除
• 与其他编码代理的比较
  • 基于订阅的编码代理
  • 基于API的编码代理
  • 其他基于MCP的编码代理
• 致谢
• 自定义和扩展Serena
• 工具列表

快速开始

Serena可以以多种方式使用，下面是一些选定集成的说明。

• 对于使用Claude进行编码，我们推荐通过Claude代码或Claude桌面版来使用Serena。您也可以在大多数基于终端的客户端中使用Serena。
• 如果您希望在IDE之外获得GUI体验，您可以使用支持MCP服务器的许多本地GUI之一。
  您还可以使用mcpo将Serena连接到许多Web客户端（包括ChatGPT）。
• 如果您希望在IDE中集成使用Serena，请参阅其他MCP客户端部分。
• 您可以将Serena作为库来构建自己的应用程序。我们尽量保持公共API的稳定性，但仍然
  预期会有破坏性变更，如果您将其作为依赖项使用，请固定Serena版本。

Serena由uv管理，因此您需要安装它)。

运行Serena MCP服务器

您有几种运行MCP服务器的选项，这些将在以下小节中解释。

用法

典型的用法涉及客户端（如Claude代码、Claude桌面版等）作为子进程运行
MCP服务器（使用stdio通信），因此客户端需要提供运行MCP服务器的命令。(或者，您也可以在SSE模式下运行MCP服务器，并告诉您的客户端如何连接到它。)

请注意，无论您如何运行MCP服务器，Serena默认都会在本地主机上启动一个基于Web的小型仪表板，该仪表板将显示日志并允许关闭MCP服务器（因为许多客户端无法正确清理进程）。这些设置以及其他设置可以在配置中进行调整，和/或通过提供命令行参数。

使用uvx

uvx 可以用来直接从仓库运行最新版本的Serena，而无需显式地进行本地安装。

shell
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

探索CLI以查看Serena提供的一些自定义选项（更多信息见下文）。

本地安装

1. 克隆仓库并进入其中。

   shell
   git clone https://github.com/oraios/serena
   cd serena

2. 可选地编辑主目录中的配置文件：

   shell
   uv run serena config edit

   如果您只需要默认配置，则可以跳过此步骤，在首次运行Serena时会创建配置文件。

3. 使用 uv 运行服务器：

   shell
   uv run serena start-mcp-server

   当从Serena安装目录之外的位置运行时，请确保传递该目录，即使用

   shell
   uv run --directory /abs/path/to/serena serena start-mcp-server

使用Docker（实验性）

⚠️ Docker支持目前是实验性的，存在一些限制。请在使用前阅读Docker文档中的重要注意事项。

您可以直接通过docker运行Serena MCP服务器，假设您要处理的所有项目都位于 /path/to/your/projects 中：

shell
docker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena start-mcp-server --transport stdio

将 /path/to/your/projects 替换为您项目的绝对路径。Docker方法提供了：

• 更好的安全隔离，用于执行shell命令
• 无需在本地安装语言服务器和依赖项
• 在不同系统之间保持一致的环境

或者，可以使用仓库中提供的 compose.yml 文件来使用docker compose。

有关详细的设置说明、配置选项和已知限制，请参阅Docker文档。

使用Nix

如果您正在使用Nix并且启用了 nix-command 和 flakes 功能，则可以使用以下命令运行Serena：

bash
nix run github:oraios/serena -- start-mcp-server --transport stdio

您还可以通过引用此仓库 (github:oraios/serena) 并在Nix flake中使用它来安装Serena。该包被导出为 serena。

SSE 模式

ℹ️ 请注意，使用stdio作为协议的MCP服务器在客户端/服务器架构中有些不寻常，因为服务器必须由客户端启动才能通过服务器的标准输入/输出流进行通信。换句话说，您不需要自己启动服务器。客户端应用程序（例如Claude Desktop）负责这一点，因此需要配置一个启动命令。

当使用基于HTTP通信的SSE模式时，您可以自己控制服务器的生命周期，即您启动服务器并向客户端提供URL以连接到它。

只需向 start-mcp-server 提供 --transport sse 选项，并可选地提供端口。例如，要在端口9121上以SSE模式运行Serena MCP服务器，您可以从Serena目录中运行以下命令，

shell
uv run serena start-mcp-server --transport sse --port 9121

然后配置您的客户端以连接到 http://localhost:9121/sse。#### 命令行参数

Serena MCP 服务器支持广泛的额外命令行选项，包括以 SSE 模式运行以及适应各种上下文和操作模式的选项。

使用 --help 参数运行以获取可用选项列表。

配置

Serena 在配置方面非常灵活。对于大多数用户，默认配置已经足够使用，但您也可以通过编辑几个 YAML 文件来完全根据需要进行调整。您可以禁用工具、更改 Serena 的指令（我们称之为 system_prompt）、调整仅提供提示的工具的输出，甚至调整工具描述。

Serena 的配置在四个地方进行：

1. serena_config.yml 用于适用于所有客户端和项目的通用设置。
   它位于您的用户目录下的 .serena/serena_config.yml 中。
   如果您没有显式创建该文件，则在首次运行 Serena 时会自动生成。
   您可以直接编辑它，或者使用

   shell
   uvx --from git+https://github.com/oraios/serena serena config edit

   （或使用 --directory 命令版本）。

2. 在传递给 start-mcp-server 的参数中，在您的客户端配置中（见下文），这将应用于由相应客户端启动的所有会话。特别是，上下文参数应适当设置，以便 Serena 能够最好地适应现有工具和客户端的功能。
   有关详细说明，请参阅。您可以通过命令行参数覆盖 serena_config.yml 中的所有条目。

3. 在项目内的 .serena/project.yml 文件中。这将保存项目级别的配置，当激活该项目时使用。
   当您首次在该项目上使用 Serena 时，该文件将自动生成，但您也可以显式生成它，使用

   shell
   uvx --from git+https://github.com/oraios/serena serena project generate-yml

   （或使用 --directory 命令版本）。

4. 通过上下文和模式。请参阅 模式和上下文 部分以获取更多详细信息。

完成初始设置后，根据您希望如何使用 Serena 继续以下部分之一。

项目激活与索引

如果您主要在同一项目上工作，可以通过在客户端的 MCP 配置中的 start-mcp-server 命令中传递 --project <path_or_name> 来配置始终在启动时激活该项目。
这对于按项目配置 MCP 服务器的客户端（如 Claude Code）特别有用。

否则，推荐的方法是让 LLM 通过提供绝对路径或（如果项目过去已被激活）通过其名称来激活项目。默认项目名称是目录名称。

• "激活项目 /path/to/my_project"
• "激活项目 my_project"

所有已激活的项目将自动添加到您的 serena_config.yml 中，并且每个项目都会生成一个 .serena/project.yml 文件。您可以调整后者，例如通过更改名称（在激活期间引用）或其他选项。确保不要有两个不同但同名的项目。

ℹ️ 对于较大的项目，我们建议您对项目进行索引以加速 Serena 的工具；否则第一次应用工具可能会非常慢。
要执行此操作，请从项目目录运行（或传递项目路径作为参数）：

shell
uvx --from git+https://github.com/oraios/serena serena project index

（或使用 --directory 命令版本）。

Claude Code

Serena 是一种使 Claude Code 更便宜且更强大的好方法！

从您的项目目录，使用类似以下命令添加 serena，

shell
claude mcp add serena -- --context ide-assistant --project $(pwd)

其中 <serena-mcp-server> 是您运行 Serena MCP 服务器的方式。例如，当使用 uvx 时，您将运行

shell
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

ℹ️ Serena 自带了一份指令文本，Claude 需要读取它以正确使用 Serena 的工具。
从版本 v1.0.52 开始，Claude 代码会自动读取 MCP 服务器的指令，因此这是自动处理的。
如果您使用的是旧版本，或者 Claude 未能读取指令，您可以明确要求它“读取 Serena 的初始指令”，或运行 /mcp__serena__initial_instructions 来加载指令文本。
如果您想利用这一点，需要在配置文件中通过将 initial_instructions 添加到 included_optional_tools 来显式启用相应的工具。
请注意，在开始新的对话或执行任何压缩操作后，您可能需要让 Claude 再次读取指令，以确保其能够正确配置并使用 Serena 的工具。

Codex

Serena 开箱即用地支持 OpenAI 的 Codex CLI，但您必须使用 codex 上下文才能使其正常工作。（技术原因是 Codex 尚未完全支持 MCP 规范，因此需要对工具进行一些调整。）

与 Claude Code 不同，在 Codex 中，您需要全局添加 MCP 服务器而不是针对每个项目。请将以下内容添加到
~/.codex/config.toml（如果该文件不存在，请创建）：

toml
[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

Codex 启动后，您需要激活项目，可以通过说：

"使用 Serena 激活当前目录作为项目"

如果不激活项目，您将无法使用 Serena 的工具！

就这样！查看 ~/.codex/log/codex-tui.log 以检查是否发生了任何错误。

如果在配置中没有禁用，则 Serena 仪表板将会运行，但由于 Codex 的沙盒机制，浏览器可能不会自动打开。您可以手动访问 http://localhost:24282/dashboard/index.html（如果该端口已被占用，则可能是更高的端口）来打开它。

即使工具成功执行，Codex 也经常显示为 failed。这不是问题，似乎是 Codex 中的一个 bug。尽管有错误消息，一切仍按预期工作。

其他基于终端的客户端

有许多支持 MCP 服务器的基于终端的编码助手，如 Codex、Gemini-CLI、Qwen3-Coder、rovodev、OpenHands CLI 和 opencode。

它们通常可以从 Serena 提供的符号工具中受益。您可能希望通过编写自己的上下文、模式或提示来自定义 Serena 的某些方面，以适应您的工作流程、使用的其他 MCP 服务器以及客户端的内部能力。

Claude Desktop

对于 Claude Desktop（适用于 Windows 和 macOS），请转到 文件 / 设置 / 开发者 / MCP 服务器 / 编辑配置，这将允许您打开 JSON 文件 claude_desktop_config.json。
根据您的设置，使用 运行命令 添加 serena MCP 服务器配置。

• 本地安装：

  json
  {
  "mcpServers": {
  "serena": {
  "command": "/abs/path/to/uv",
  "args": ["run", "--directory", "/abs/path/to/serena", "serena", "start-mcp-server"]
  }
  }
  }

• uvx：

  json
  {
  "mcpServers": {
  "serena": {
  "command": "/abs/path/to/uvx",
  "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"]
  }
  }
  }* docker:

  json
  {
  "mcpServers": {
  "serena": {
  "command": "docker",
  "args": ["run", "--rm", "-i", "--network", "host", "-v", "/path/to/your/projects:/workspaces/projects", "ghcr.io/oraios/serena:latest", "serena", "start-mcp-server", "--transport", "stdio"]
  }
  }
  }

如果你在 Windows 上使用包含反斜杠的路径（请注意，你也可以只使用正斜杠），请确保正确转义它们（\\）。

就这样！保存配置，然后重启 Claude Desktop。你已经准备好激活你的第一个项目了。

ℹ️ 你可以使用额外的参数进一步自定义运行命令（参见上面）。

注意：在 Windows 和 macOS 上有 Anthropic 官方的 Claude Desktop 应用程序，对于 Linux 则有一个开源社区版本。

⚠️ 确保完全退出 Claude Desktop 应用程序，因为在 Windows 上关闭 Claude 只会将其最小化到系统托盘。

⚠️ 某些客户端可能会留下僵尸进程。你需要手动找到并终止这些进程。
使用 Serena，你可以激活仪表板以防止未注意到的进程，并且还可以使用仪表板来关闭 Serena。

重启后，你应该会在聊天界面中看到 Serena 的工具（注意小锤子图标）。

有关 Claude Desktop 中 MCP 服务器的更多信息，请参阅官方快速入门指南。

MCP 编码客户端（Cline、Roo-Code、Cursor、Windsurf 等）

作为 MCP 服务器，Serena 可以被任何 MCP 客户端包含。上述相同的配置，可能需要进行一些针对特定客户端的小修改，应该可以正常工作。大多数流行的现有编码助手（IDE 扩展或类似 VSCode 的 IDE）都支持连接到 MCP 服务器。建议为这些集成使用 ide-assistant 上下文，通过在 MCP 客户端配置中的 args 添加 "--context", "ide-assistant" 来实现。包含 Serena 通常可以通过提供符号操作工具来提升它们的性能。

在这种情况下，使用费用继续由你选择的客户端控制（与 Claude Desktop 客户端不同）。但你仍然可能希望通过这种方式使用 Serena，例如，出于以下原因之一：

1. 你已经在使用一个编码助手（比如 Cline 或 Cursor），只是想让它更强大。
2. 你在使用 Linux 并且不想使用社区创建的 Claude Desktop。
3. 你希望将 Serena 更紧密地集成到你的 IDE 中，并且不介意为此付费。

本地 GUI 和框架

在过去几个月中，出现了几种允许你运行强大的本地 GUI 并将其连接到 MCP 服务器的技术。它们开箱即用即可与 Serena 一起工作。一些领先的开源 GUI 技术包括 Jan、OpenHands、OpenWebUI 和 Agno。它们允许将 Serena 与几乎任何 LLM（包括本地运行的）结合，并提供各种其他集成。

详细用法和建议

工具执行

Serena 结合了语义代码检索工具、编辑功能和 shell 执行。Serena 的行为可以通过模式和上下文进一步定制。完整的工具列表见下方。

一般建议使用所有工具，因为这可以让 Serena 提供最大的价值：只有通过执行 shell 命令（特别是测试），Serena 才能自主识别并纠正错误。

Shell 执行和编辑工具然而，需要注意的是，execute_shell_command 工具允许任意代码执行。

当使用 Serena 作为 MCP 服务器时，客户端通常会在执行工具之前请求用户的许可，
因此只要用户事先检查执行参数，这应该不会成为问题。
但是，如果您有顾虑，可以在项目的 .yml 配置文件中选择禁用某些命令。
如果您只想使用 Serena 纯粹用于分析代码并提出实现建议
而不修改代码库，您可以通过在项目配置文件中设置 read_only: true 来启用只读模式。
这将自动禁用所有编辑工具，并防止对您的代码库进行任何修改，同时
仍然允许所有的分析和探索功能。

一般来说，请确保备份您的工作并使用版本控制系统以避免
丢失任何工作。

模式和上下文

Serena 的行为和工具集可以通过上下文和模式进行调整。
这些提供了高度的自定义性，以最好地适应您的工作流程和 Serena 所处的环境。

上下文

上下文定义了 Serena 运行的一般环境。
它影响初始系统提示和可用工具集。
上下文是在启动 Serena 时设置的（例如，通过 MCP 服务器的 CLI 选项或代理脚本），并且在活动会话期间不能更改。

Serena 提供了预定义的上下文：

• desktop-app: 专为与 Claude Desktop 等桌面应用程序一起使用而设计。这是默认设置。
• agent: 适用于 Serena 作为更自主代理的情况，例如与 Agno 一起使用时。
• ide-assistant: 优化了与 VSCode、Cursor 或 Cline 等 IDE 的集成，专注于编辑器内的编码辅助。
  选择最适合您所使用的集成类型的上下文。

启动 Serena 时，使用 --context <上下文名称> 指定上下文。
请注意，在指定了参数列表的情况下（例如 Claude Desktop），必须向列表中添加两个参数。

如果您使用的是需要您使用 OpenAI 兼容工具描述的本地服务器（如 Llama.cpp），请改用 oaicompat-agent 上下文而不是 agent。

模式

模式进一步细化了 Serena 在特定类型任务或交互风格下的行为。可以同时激活多个模式，从而结合它们的效果。模式影响系统提示，并且也可以通过排除某些工具来改变可用工具集。

内置模式的例子包括：

• planning: 使 Serena 专注于规划和分析任务。
• editing: 优化 Serena 以执行直接代码修改任务。
• interactive: 适合于对话式的来回交互风格。
• one-shot: 将 Serena 配置为单次响应完成的任务，常与 planning 结合使用以生成报告或初步计划。
• no-onboarding: 如果某个会话不需要初始引导过程，则跳过该过程。
• onboarding: （通常自动触发）专注于项目引导过程。

模式可以在启动时设置（类似于上下文），但也可以在会话期间_动态切换_。您可以指示 LLM 使用 switch_modes 工具来激活不同的模式集（例如，“切换到 planning 和 one-shot 模式”）。

启动 Serena 时，使用 --mode <模式名称> 指定模式；可以指定多个模式，例如 --mode planning --mode no-onboarding。

:warning: 模式兼容性：虽然您可以组合模式，但有些可能在语义上不兼容（例如 interactive 和 one-shot）。Serena 目前不会阻止不兼容的组合；用户需要自行选择合理的模式配置。

自定义

您可以通过两种方式创建自己的上下文和模式，以精确地根据需要定制 Serena：* 您可以使用Serena的CLI来管理模式和上下文。请查看

shell
uvx --from git+https://github.com/oraios/serena serena mode --help


和

shell
uvx --from git+https://github.com/oraios/serena serena context --help


_注意_: 自定义上下文/模式仅仅是`<home>/.serena`目录下的YAML文件，它们会自动注册并可以通过其名称（不带`.yml`扩展名的文件名）使用。如果您不想使用Serena的CLI，也可以以任何您认为合适的方式创建和管理这些文件。

• 使用外部YAML文件：启动Serena时，您还可以提供自定义.yml文件的绝对路径作为上下文或模式。

这种定制化允许Serena深度集成并适应特定项目需求或个人偏好。

入门与记忆

默认情况下，当Serena首次为某个项目启动时，它将执行一个入门过程。
入门的目标是让Serena熟悉该项目，并存储记忆，以便在未来的交互中引用。
如果LLM未能完成入门并且实际上没有将相应的记忆写入磁盘，您可能需要明确要求它这样做。

入门通常会从项目中读取大量内容，从而填充上下文。因此，在入门完成后切换到另一个对话可能是明智之举。
入门之后，我们建议您快速浏览一下记忆，并根据需要编辑或添加额外的记忆。

记忆是存储在项目目录下的.serena/memories/中的文件，代理可以选择在后续交互中读取这些文件。
您可以根据需要阅读和调整它们；也可以手动添加新的记忆。
.serena/memories/目录中的每个文件都是一个记忆文件。
每当Serena开始处理一个项目时，都会提供记忆列表，代理可以选择是否读取它们。
我们发现记忆可以显著改善用户与Serena的体验。

准备您的项目

结构化您的代码库

Serena利用代码结构来查找、读取和编辑代码。这意味着它在结构良好的代码上表现良好，但在完全无结构的代码（如包含巨大非模块化函数的“上帝类”）上可能表现不佳。
此外，对于非静态类型的语言，类型注解非常有益。

从干净的状态开始

最好从一个干净的git状态开始代码生成任务。这不仅会让您更容易检查更改，而且模型本身也有机会通过调用git diff看到它所做的更改，从而进行自我修正或在后续对话中继续工作。

:warning: 重要：由于Serena会使用系统原生的行尾符写入文件，并且它可能希望查看git差异，因此在Windows上设置git config core.autocrlf为true非常重要。
在Windows上将git config core.autocrlf设置为false时，您可能会因为行尾符而产生巨大的差异。通常建议在Windows上全局启用此git设置：

shell
git config --global core.autocrlf true

日志记录、代码检查和自动化测试

Serena可以在_代理循环_中成功完成任务，在该循环中它迭代地获取信息、执行操作并反思结果。
然而，Serena不能使用调试器；它必须依赖程序执行的结果、代码检查结果和测试结果来评估其操作的正确性。
因此，设计成能够产生有意义可解释输出（例如日志消息）并且具有良好测试覆盖率的软件对Serena来说更容易处理。

我们通常建议从所有代码检查和测试都通过的状态开始编辑任务。

提示策略我们发现，在实际实施任务之前，花一些时间对任务进行概念化和规划通常是个好主意，特别是对于非简单的任务。这有助于获得更好的结果，并增加控制感和保持在循环中的感觉。你可以在一个会话中制定详细的计划，Serena可能会阅读大量你的代码以建立上下文，然后在另一个会话中继续实施（可能是在创建了合适的记忆之后）。

代码编辑中的潜在问题

根据我们的经验，大语言模型不擅长计数，即它们在正确位置插入代码块时会有困难。大多数编辑操作可以在符号级别执行，这样可以克服这个问题。然而，有时行级别的插入也很有用。

Serena被指示要仔细检查它将要编辑的行号和任何代码块，但如果你遇到问题，明确告诉它如何编辑代码可能是有用的。
我们正在努力使Serena的编辑能力更加健壮。

上下文耗尽

对于长时间且复杂的任务，或者当Serena已经阅读了大量的内容时，你可能会接近上下文令牌的限制。在这种情况下，通常最好在一个新的对话中继续。Serena有一个专门的工具来总结当前进度状态以及所有相关信息以便继续。你可以请求创建这个摘要并将其写入记忆中。然后，在一个新的对话中，只需让Serena读取记忆并继续任务即可。根据我们的经验，这种方法效果非常好。此外，由于单个会话中不涉及总结，Serena通常不会迷失方向（不像某些其他代理那样在幕后进行总结），并且也被指示偶尔检查是否走在正确的轨道上。

另外，Serena被指示要节约使用上下文（例如，不要无必要地阅读代码符号的主体），但我们发现Claude在这方面并不总是表现得很好（Gemini似乎做得更好）。如果你知道不需要这样做，可以明确指示它不要阅读主体部分。

将Serena与其他MCP服务器结合使用

通过MCP客户端使用Serena时，可以将其与其他MCP服务器一起使用。但是，请注意工具名称冲突！有关此信息请参见上方。

目前，与流行的文件系统MCP服务器存在冲突。由于Serena也提供了文件系统操作，因此很可能没有必要同时启用这两个功能。

Serena的日志：仪表板和GUI工具

Serena提供了两种方便的方式来访问当前会话的日志：

• 通过基于Web的仪表板（默认启用）

  这在所有平台上都支持。
  默认情况下，它可以通过http://localhost:24282/dashboard/index.html访问，
  但如果默认端口不可用或运行了多个实例，则可能会使用更高的端口。

• 通过GUI工具（默认禁用）

  这主要支持Windows平台，但在Linux上也可能工作；macOS不支持。

这两种方式都可以在Serena的配置文件(serena_config.yml, 见上文)中启用、配置或禁用。
如果启用了这些功能，那么一旦启动Serena代理/MCP服务器，它们就会自动打开。
如果你在配置中设置了record_tool_usage_stats: True，则Web仪表板将显示Serena工具的使用统计信息。

除了查看日志外，这两种工具还允许关闭Serena代理。
提供此功能是因为像Claude Desktop这样的客户端在自身关闭时可能无法终止MCP服务器子进程。

故障排除

Claude Desktop对MCP服务器的支持以及各种MCP服务器SDK都是相对较新的发展，可能会表现出不稳定性。

MCP服务器的工作配置可能因平台而异平台之间以及客户端之间的路径。我们建议始终使用绝对路径，因为相对路径可能是错误的来源。语言服务器在单独的子进程中运行，并通过 asyncio 调用——有时客户端可能会导致其崩溃。如果你启用了 Serena 的日志窗口，并且它消失了，你就会知道发生了什么。

某些客户端可能无法正确终止 MCP 服务器，请注意挂起的 Python 进程，并在必要时手动终止它们。

与其他编码代理的比较

据我们所知，Serena 是第一个功能齐全的编码代理，其所有功能都通过 MCP 服务器提供，因此不需要 API 密钥或订阅。

基于订阅的编码代理

许多著名的基于订阅的编码代理是 IDE（如 Windsurf、Cursor 和 VSCode）的一部分。
Serena 的功能类似于 Cursor 的 Agent、Windsurf 的 Cascade 或 VSCode 的代理模式。

Serena 的优势在于不需要订阅。
潜在的缺点是它没有直接集成到 IDE 中，因此对新编写代码的检查不如其他工具无缝。

更多的技术差异包括：

• Serena 不绑定到特定的 IDE 或 CLI。
  Serena 的 MCP 服务器可以与任何 MCP 客户端（包括一些 IDE）一起使用，而基于 Agno 的代理提供了应用其功能的额外方式。
• Serena 不绑定到特定的大规模语言模型或 API。
• Serena 使用语言服务器导航和编辑代码，因此它具有代码的符号理解能力。
  基于 IDE 的工具通常使用 RAG 基础或纯文本基础的方法，这在处理大型代码库时往往不够强大。
• Serena 是开源的，代码量小，因此可以轻松扩展和修改。

基于 API 的编码代理

另一种替代基于订阅的代理的是基于 API 的代理，如 Claude Code、Cline、Aider、Roo Code 等，其使用成本直接映射到底层 LLM 的 API 成本。
其中一些（如 Cline）甚至可以作为扩展集成到 IDE 中。
它们通常非常强大，主要缺点是（可能非常高的）API 成本。

Serena 本身可以用作基于 API 的代理（参见上面关于 Agno 的部分）。
我们还没有为 Serena 编写 CLI 工具或专用的 IDE 扩展（后者可能没有必要，因为 Serena 已经可以与支持 MCP 服务器的任何 IDE 一起使用）。
如果有需求将 Serena 作为像 Claude Code 这样的 CLI 工具，我们会考虑编写一个。

Serena 与其他基于 API 的代理的主要区别在于，Serena 也可以用作 MCP 服务器，因此不需要 API 密钥并绕过了 API 成本。这是 Serena 的独特功能。

其他基于 MCP 的编码代理

还有其他设计用于编码的 MCP 服务器，如 DesktopCommander 和 codemcp。
然而，据我们所知，它们都没有提供语义代码检索和编辑工具；它们完全依赖于基于文本的分析。
正是语言服务器与 MCP 的集成使 Serena 在处理具有挑战性的编码任务时变得独特且强大，尤其是在大型代码库的上下文中。

致谢

我们在多个现有的开源技术基础上构建了 Serena，其中最重要的是：

1. multilspy。
   一个封装了语言服务器实现并使其能够通过 Python 进行交互的库，为我们 Solid-LSP 库（src/solidlsp）提供了基础。
   Solid-LSP 提供纯同步的 LSP 调用，并通过 Serena 所需的符号逻辑扩展了原始库。
2. Python MCP SDK
3. Agno 和
   相关的 agent-ui，我们使用这些项目来允许Serena与任何模型协同工作，而不仅仅是支持MCP的那些模型。
4. 通过Solid-LSP使用的所有的语言服务器。

没有这些项目，Serena将无法实现（或者构建起来会困难得多）。

自定义和扩展Serena

扩展Serena的AI功能以实现您自己的想法是相当直接的。只需通过继承serena.agent.Tool并根据工具的需求实现apply方法来创建一个新的工具即可。一旦实现，SerenaAgent将自动能够访问这个新工具。

添加对新编程语言的支持也相对简单。

我们期待看到社区能带来什么！有关贡献的详细信息，请参阅贡献指南。

工具列表

以下是Serena默认工具的列表及其简要说明（uv run serena tools list命令的输出）：

• activate_project: 按名称激活一个项目。
• check_onboarding_performed: 检查是否已经执行了项目的入门操作。
• create_text_file: 在项目目录中创建或覆盖文件。
• delete_memory: 从Serena特定于项目的记忆存储中删除一条记忆。
• execute_shell_command: 执行shell命令。
• find_file: 在给定的相对路径中查找文件。
• find_referencing_symbols: 查找引用给定位置符号的所有符号（可按类型过滤）。
• find_symbol: 对具有/包含给定名称/子字符串的符号进行全局（或局部）搜索（可按类型过滤）。
• get_symbols_overview: 获取给定文件中顶级符号定义的概览。
• insert_after_symbol: 在给定符号定义结束之后插入内容。
• insert_before_symbol: 在给定符号定义开始之前插入内容。
• list_dir: 列出给定目录中的文件和目录（可递归）。
• list_memories: 列出Serena特定于项目的记忆存储中的记忆。
• onboarding: 执行入门操作（识别项目结构和基本任务，例如测试或构建）。
• prepare_for_new_conversation: 提供为新的对话做准备的指示（以便继续必要的上下文）。
• read_file: 读取项目目录中的文件。
• read_memory: 从Serena特定于项目的记忆存储中读取指定名称的记忆。
• replace_regex: 使用正则表达式替换文件中的内容。
• replace_symbol_body: 替换符号的完整定义。
• search_for_pattern: 在项目中搜索模式。
• think_about_collected_information: 思考工具，用于考虑收集的信息是否完整。
• think_about_task_adherence: 思考工具，用于确定代理是否仍然在当前任务的轨道上。
• think_about_whether_you_are_done: 思考工具，用于确定任务是否真正完成。
• write_memory: 将命名记忆写入Serena特定于项目的记忆存储中，以备将来参考。

有几个工具默认是禁用的，需要显式启用，例如通过上下文或模式。请注意，我们的某些默认上下文确实启用了其中一些工具。例如，desktop-app上下文启用了execute_shell_command工具。

所有可选工具的完整列表如下（uv run serena tools list --only-optional命令的输出）：

• delete_lines: 删除文件中的某一行范围。
• get_current_config: 打印代理的当前配置，包括活动和可用的项目、工具、上下文和模式。
• initial_instructions: 获取当前项目的初始指令。仅应在无法设置系统提示的情况下使用。例如，在您无法控制的客户端中，如Claude Desktop。
• insert_at_line: 在文件的指定行插入内容。
• jet_brains_find_referencing_symbols: 查找引用给定符号的所有符号。
• jet_brains_find_symbol: 对具有/包含给定名称/子字符串的符号执行全局（或局部）搜索（可按类型过滤）。
• jet_brains_get_symbols_overview: 检索指定文件中的顶级符号概览。
• remove_project: 从Serena配置中移除一个项目。
• replace_lines: 用新内容替换文件中的某一行范围。
• restart_language_server: 重启语言服务器，当通过非Serena编辑发生时可能需要这样做。
• summarize_changes: 提供总结代码库更改的说明。
• switch_modes: 通过提供模式名称列表来激活这些模式。