# serena
**Repository Path**: kaitoops/serena
## Basic Information
- **Project Name**: serena
- **Description**: https://github.com/oraios/serena
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-08-04
- **Last Updated**: 2025-08-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Serena 项目介绍
* :rocket: Serena 是一个强大的**代码代理工具包**，能够将大型语言模型（LLM）转化为可以直接在代码库上工作的全功能代理。
* :wrench: Serena 提供了类似 IDE 功能的**语义代码检索和编辑工具**，能够在符号级别提取代码实体，并利用关系结构。
* :free: Serena 是**免费且开源**的，可以免费增强你已经拥有的 LLM 的能力。
### 演示
这里有一个演示，展示 Serena 如何为自身实现一个小功能（更好的日志 GUI），使用的是 Claude Desktop。
请注意 Serena 的工具如何让 Claude 找到并编辑正确的符号。
[演示视频链接](https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753)
Serena 正在积极开发中！查看最新更新、即将推出的功能和经验教训，以保持最新。
### LLM 集成
Serena 提供了编码工作流所需的工具，但实际工作（工具的使用）需要由 LLM 来协调。
例如，可以通过**一行 Shell 命令**来增强 Claude Code 的性能（见[此处](#claude-code)）。
Serena 可以通过以下方式与 LLM 集成：
* 使用**模型上下文协议（MCP）**。
Serena 提供了一个 MCP 服务器，可以与以下工具集成：
* Claude Code 和 Claude Desktop，
* IDE（如 VSCode、Cursor 或 IntelliJ），
* 插件（如 Cline 或 Roo Code）
* 以及其他许多工具，包括即将支持的 [ChatGPT 应用](https://x.com/OpenAIDevs/status/1904957755829481737)
* 使用**Agno – 模型无关的代理框架**。
Serena 的基于 Agno 的代理可以将几乎任何 LLM 转化为编码代理，无论它是由 Google、OpenAI 或 Anthropic 提供的（需要付费 API 密钥），
还是由 Ollama、Together 或 Anyscale 提供的免费模型。
* 将 Serena 的工具集成到你选择的代理框架中。
Serena 的工具实现与框架特定代码解耦，因此可以轻松适应任何代理框架。
### 编程语言支持与语义分析能力
Serena 的语义代码分析能力基于**语言服务器**，使用广泛实现的语言服务器协议（LSP）。LSP 提供了一组基于代码符号理解的多功能代码查询和编辑功能。
Serena 利用这些能力，像经验丰富的开发人员使用 IDE 功能一样发现和编辑代码。
即使在非常大和复杂的项目中，Serena 也能高效地找到正确的上下文并执行正确的操作！Serena 不仅免费且开源，而且在许多情况下，其结果比收费的现有解决方案更好。
语言服务器支持多种编程语言。Serena 提供以下语言的直接支持：
* Python
* TypeScript/Javascript（目前存在一些稳定性问题，我们正在修复）
* PHP
* Go（需要先安装 Go 和 gopls）
* Rust
* C#（需要安装 dotnet。我们最近更换了底层语言服务器，请报告你遇到的任何问题）
* Java（_注意_：启动速度较慢，尤其是首次启动。在 macOS 和 Linux 上可能存在 Java 问题，我们正在修复）
* Elixir（需要安装 NextLS 和 Elixir；**不支持 Windows**，因为 Next LS 没有提供 Windows 二进制文件）
* Clojure
* C/C++（你可能会遇到查找引用的问题，我们正在修复）
Serena 还提供以下语言的间接支持（可能需要一些代码更改/手动安装）：
* Ruby（未测试）
* Kotlin（未测试）
* Dart（未测试）
这些语言由语言服务器库支持，但我们尚未明确测试这些语言的支持是否完全无误。
原则上，通过为新语言服务器实现提供一个简单的适配器，可以轻松支持更多语言。
---
## 目录
- [Serena 的用途](#serena的用途)
- [使用 Serena 的免费编码代理](#使用-serena-的免费编码代理)
- [快速开始](#快速开始)
* [运行 Serena MCP 服务器](#运行-serena-mcp-服务器)
+ [使用方法](#使用方法)
* [本地安装](#本地安装)
- [使用 uvx](#使用-uvx)
- [使用 Docker（实验性）](#使用-docker-实验性)
+ [SSE 模式](#sse-模式)
+ [命令行参数](#命令行参数)
* [配置](#配置)
* [项目激活与索引](#项目激活与索引)
* [Claude Code](#claude-code)
* [Claude Desktop](#claude-desktop)
* [其他 MCP 客户端（Cline、Roo-Code、Cursor、Windsurf 等）](#其他-mcp-客户端-cline-roo-code-cursor-windsurf-等)
* [Agno 代理](#agno-代理)
* [其他代理框架](#其他代理框架)
- [详细使用方法和建议](#详细使用方法和建议)
* [工具执行](#工具执行)
+ [Shell 执行和编辑工具](#shell-执行和编辑工具)
* [模式和上下文](#模式和上下文)
+ [上下文](#上下文)
+ [模式](#模式)
+ [自定义](#自定义)
* [入职和记忆](#入职和记忆)
* [准备你的项目](#准备你的项目)
+ [结构化你的代码库](#结构化你的代码库)
+ [从干净状态开始](#从干净状态开始)
+ [日志、检查和自动化测试](#日志-检查和自动化测试)
* [提示策略](#提示策略)
* [代码编辑中的潜在问题](#代码编辑中的潜在问题)
* [上下文溢出](#上下文溢出)
* [与其他 MCP 服务器结合使用](#与其他-mcp-服务器结合使用)
* [Serena 的日志：仪表板和 GUI 工具](#serena-的日志-仪表板和-gui-工具)
* [故障排除](#故障排除)
- [与其他编码代理的比较](#与其他编码代理的比较)
* [订阅制编码代理](#订阅制编码代理)
* [API 基础的编码代理](#api-基础的编码代理)
* [其他基于 MCP 的编码代理](#其他基于-mcp-的编码代理)
- [致谢](#致谢)
- [自定义和扩展 Serena](#自定义和扩展-serena)
- [完整工具列表](#完整工具列表)
---
## Serena 的用途
你可以使用 Serena 进行任何编码任务，无论是分析、规划、设计新组件还是重构现有组件。
由于 Serena 的工具允许 LLM 完成认知感知 - 行动循环，基于 Serena 的代理可以自主地从头到尾完成编码任务——从初始分析到实现、测试，最后提交到版本控制系统。
Serena 可以读取、写入和执行代码，读取日志和终端输出。
虽然我们不一定鼓励，但“氛围编码”是完全可能的，如果你想要几乎感觉“代码不再存在”，你可能会发现 Serena 比 IDE 中的代理更适合“氛围编码”（因为你将拥有一个单独的 GUI，让你真正忘记代码的存在）。
## 使用 Serena 的免费编码代理
即使使用免费的 Anthropic Claude 层级，也支持 MCP 服务器，因此你可以免费将 Claude 与 Serena 结合使用。
预计不久后，ChatGPT Desktop 也将支持 MCP 服务器。
通过 Agno，你还可以选择将 Serena 与免费/开源权重模型结合使用。
Serena 是 [Oraios AI](https://oraios-ai.de/) 对开发者社区的贡献。
我们自己也经常使用它。
我们厌倦了不得不支付多个基于 IDE 的订阅费用（例如 Windsurf 或 Cursor），这些订阅还强迫我们继续购买代币，而我们已经支付了聊天订阅费用。
像 Claude Code、Cline、Aider 等基于 API 的工具所产生的大量 API 费用同样不具吸引力。
因此，我们开发了 Serena，希望能够取消大多数其他订阅。
## 快速开始
Serena 可以以多种方式使用，以下是针对选定集成的说明。
- 如果你只想将 Claude 转化为免费的编码代理，我们建议通过 [Claude Code](#claude-code) 或 [Claude Desktop](#claude-desktop) 使用 Serena。
- 如果你想使用 Gemini 或其他模型，并且希望有 GUI 体验，你可以使用 [Agno](#agno-代理) 或其他支持 MCP 服务器的 GUI。
- 如果你想将 Serena 集成到你的 IDE 中，请参阅 [其他 MCP 客户端](#其他-mcp-客户端---cline-roo-code-cursor-windsurf-等) 部分。
Serena 由 `uv` 管理，因此你需要 [安装它](https://docs.astral.sh/uv/getting-started/installation/)。
### 运行 Serena MCP 服务器
运行 MCP 服务器有几种选项，以下小节将分别说明。
#### 使用方法
典型用法是客户端（如 Claude Code、Claude Desktop 等）将 MCP 服务器作为子进程运行（使用标准输入/输出流通信），
因此客户端需要提供运行 MCP 服务器的命令。
（或者，你也可以在 SSE 模式下运行 MCP 服务器，并告诉客户端如何连接到它。）
无论你如何运行 MCP 服务器，Serena 默认会启动一个小型的基于 Web 的仪表板，显示日志并允许关闭 MCP 服务器（因为许多客户端无法正确清理进程）。
此设置和其他设置可以通过 [配置](#配置) 和/或提供 [命令行参数](#命令行参数) 进行调整。
###### 本地安装
1. 克隆仓库并进入其中。
```shell
git clone https://github.com/oraios/serena
cd serena
```
2. 可选地在你的用户目录中创建配置文件，例如：
* Linux 和 macOS 下的 `~/.serena/serena_config.yml`，或
* Windows 下的 `%USERPROFILE%\.serena\serena_config.yml`。
通过复制模板并根据需要进行调整来完成：
```shell
mkdir ~/.serena
cp src/serena/resources/serena_config.template.yml ~/.serena/serena_config.yml
```
如果你只想使用默认配置，可以跳过这一步，首次运行 Serena 时会自动生成配置文件。
3. 使用 `uv` 运行服务器：
```shell
uv run serena-mcp-server
```
如果从 Serena 安装目录之外运行，请确保传递正确的路径，例如：
```shell
uv run --directory /abs/path/to/serena serena-mcp-server
```
##### 使用 uvx
`uvx` 可以直接从仓库运行 Serena 的最新版本，无需显式本地安装。
* Windows：
```shell
uvx --from git+https://github.com/oraios/serena serena-mcp-server.exe
```
* 其他操作系统：
```shell
uvx --from git+https://github.com/oraios/serena serena-mcp-server
```
##### 使用 Docker（实验性）
⚠️ Docker 支持目前是实验性的，存在一些限制。请在使用之前仔细阅读 [Docker 文档](DOCKER.md) 以了解重要注意事项。
你可以直接通过 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-mcp-server --transport stdio
```
将 `/path/to/your/projects` 替换为你的项目目录的绝对路径。使用 Docker 的方式提供了：
- 更好的 Shell 命令执行安全隔离
- 无需在本地安装语言服务器和依赖项
- 在不同系统上提供一致的环境
请参阅 [Docker 文档](DOCKER.md) 以获取详细的设置说明、配置选项和已知限制。
#### SSE 模式
ℹ️ 注意，使用 stdio 作为协议的 MCP 服务器在客户端/服务器架构中较为罕见，因为服务器必须由客户端启动，以便通过服务器的标准输入/输出流进行通信。
换句话说，你无需自己启动服务器。客户端应用程序（例如 Claude Desktop）会处理这些，并且需要配置启动命令。
如果改为使用 SSE 模式（基于 HTTP 的通信），你可以自己控制服务器的生命周期，
即你可以启动服务器，并向客户端提供连接的 URL。
只需为 `serena-mcp-server` 提供 `--transport sse` 选项，并可选地指定端口。
例如，如果你想在本地安装的情况下以 SSE 模式运行 Serena MCP 服务器，并使用端口 9121，
你可以从 Serena 目录运行以下命令：
```shell
uv run serena-mcp-server --transport sse --port 9121
```
然后将客户端配置为连接到 `http://localhost/sse:9121`。
#### 命令行参数
Serena MCP 服务器支持一系列额外的命令行选项，包括运行在 SSE 模式下以及适应各种 [上下文和操作模式](#模式和上下文)。
运行时带上参数 `--help`，可以获取可用选项的列表。
### 配置
Serena 的行为（激活的工具和提示，以及日志配置等）可以在以下四个地方进行配置：
1. `serena_config.yml` 文件，用于适用于所有客户端和项目的通用设置。
它位于你的用户目录下的 `.serena/serena_config.yml`。
如果你没有显式创建该文件，首次运行 Serena 时会自动生成一个。
2. 在传递给客户端配置中的 `serena-mcp-server` 的参数中（见下文），
这些设置将适用于该客户端启动的所有会话。特别是 [上下文](#上下文) 参数，
应适当设置，以便 Serena 能够最好地适应现有工具和客户端的能力。
你可以通过命令行参数覆盖 `serena_config.yml` 中的所有条目。
3. 在项目目录中的 `.serena/project.yml` 文件中。这将保存项目级别的配置，
每次激活该项目时都会使用。
4. 通过当前激活的 [模式](#模式) 集。
> ⚠️ **注意：** Serena 正在积极开发中。我们不断添加功能、改进稳定性和用户体验。
> 因此，配置可能会以破坏性的方式发生变化。如果你的配置无效，
> MCP 服务器或基于 Serena 的代理可能无法启动（在前一种情况下，请检查 MCP 日志）。
> 在更新 Serena 时，请检查 [更新日志](CHANGELOG.md)
> 和配置模板，相应地调整你的配置。
完成初始设置后，请根据你希望使用 Serena 的方式，继续阅读以下部分之一。
你可以直接让 LLM 显示你的会话配置，Serena 提供了一个工具来完成这个操作。
### 项目激活与索引
推荐的方式是让 LLM 通过提供项目的绝对路径或名称来激活项目。
如果项目之前已经被激活过，可以通过名称来激活。默认的项目名称是目录名称。
* “激活项目 /path/to/my_project”
* “激活项目 my_project”
所有被激活的项目都会被自动添加到你的 `serena_config.yml` 文件中，并且每个项目都会生成一个 `.serena/project.yml` 文件。
你可以调整后者，例如通过更改名称（在激活时引用它）或其他选项。确保不要有两个不同项目使用相同的名称。
如果你主要使用同一个项目，你也可以配置在启动时自动激活项目，通过在客户端的 `serena-mcp-server` 命令中添加 `--project ` 参数。
ℹ️ 对于较大的项目，我们建议你对项目进行索引，以加快 Serena 的工具运行速度；否则，首次使用工具可能会非常慢。
为此，请在项目目录中运行以下命令，或者将项目路径作为参数传递：
* 如果使用本地安装：
```shell
uv run --directory /abs/path/to/serena index-project
```
* 如果使用 uvx：
```shell
uvx --from git+https://github.com/oraios/serena index-project
```
### Claude Code
Serena 是让 Claude Code 更便宜且更强大的绝佳方式！
从你的项目目录中，使用类似以下的命令添加 Serena：
```shell
claude mcp add serena -- --context ide-assistant --project $(pwd)
```
其中 `` 是你 [运行 Serena MCP 服务器](#运行-the-serena-mcp-服务器) 的方式。
例如，如果你使用 `uvx`，则运行：
```shell
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project $(pwd)
```
ℹ️ 在 Claude Code 中，你应该首先让 Claude “阅读初始指令”，作为你的第一个提示，这样它将获得如何使用 Serena 工具的信息。
每次开始新对话时，以及可能在压缩操作之后，都应该提供这个提示，以便 Claude 始终能够正确地使用 Serena 的工具。
### Claude Desktop
对于 [Claude Desktop](https://claude.ai/download)（适用于 Windows 和 macOS），转到文件 / 设置 / 开发者 / MCP 服务器 / 编辑配置，
这将允许你打开 `claude_desktop_config.json` 文件。
添加 `serena` MCP 服务器配置，使用一个 [运行命令](#运行-the-serena-mcp-服务器)，具体取决于你的设置。
* 本地安装：
```json
{
"mcpServers": {
"serena": {
"command": "/abs/path/to/uv",
"args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server"]
}
}
}
```
* 使用 uvx：
```json
{
"mcpServers": {
"serena": {
"command": "/abs/path/to/uvx",
"args": ["--from", "git+https://github.com/oraios/serena", "serena-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-mcp-server", "--transport", "stdio"]
}
}
}
```
如果你在 Windows 上使用包含反斜杠的路径（注意你也可以直接使用正斜杠），请确保正确转义它们（`\\`）。
完成配置后，保存文件并重新启动 Claude Desktop。你就可以激活你的第一个项目了。
ℹ️ 你可以通过添加额外的参数（见 [上文](#命令行参数)）来自定义运行命令。
注意：在 Windows 和 macOS 上有官方的 Claude Desktop 应用程序，对于 Linux，有一个 [开源社区版本](https://github.com/aaddrick/claude-desktop-debian)。
⚠️ 确保完全退出 Claude Desktop 应用程序，因为关闭 Claude 只会将其最小化到系统托盘——至少在 Windows 上是这样。
⚠️ 当前，包括 Claude Desktop 在内的某些客户端可能会留下僵尸进程。你可能需要手动找到并终止它们。
使用 Serena 时，你可以激活 [仪表板](#serena-的日志-仪表板和-gui-工具) 来防止未注意到的进程，并且还可以使用仪表板关闭 Serena。
重新启动后，你应该会在聊天界面中看到 Serena 的工具（注意小锤子图标）。
有关 Claude Desktop 中 MCP 服务器的更多信息，请参阅 [官方快速入门指南](https://modelcontextprotocol.io/quickstart/user)。
### 其他 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](https://github.com/aaddrick/claude-desktop-debian)。
3. 你希望将 Serena 更紧密地集成到你的 IDE 中，并且不介意为此付费。
### Agno 代理
Agno 是一个模型无关的代理框架，允许你将 Serena 转化为一个代理
（独立于 MCP 技术），并使用大量底层 LLM。Agno 目前
是运行带有你选择的 LLM 的 Serena 的最简单方式。
尽管 Agno 还没有完全稳定，但我们选择了它，因为它带有自己的开源 UI，
使得你可以通过聊天界面直接使用代理。通过 Agno，Serena 被转化为一个代理
（不再是 MCP 服务器），因此它可以以编程方式使用（例如用于基准测试或在你的应用程序中）。
以下是操作方法（也可以参阅 [Agno 文档](https://docs.agno.com/introduction/playground)）：
1. 使用 npx 下载 agent-ui 代码
```shell
npx create-agent-ui@latest
```
或者，手动克隆它：
```shell
git clone https://github.com/agno-agi/agent-ui.git
cd agent-ui
pnpm install
pnpm dev
```
2. 安装带有可选依赖项的 Serena：
```shell
# 你也可以只选择 agno,google 或 agno,anthropic 而不是 all-extras
uv pip install --all-extras -r pyproject.toml -e .
```
3. 将 `.env.example` 复制为 `.env` 并填写你打算使用的提供商的 API 密钥。
4. 启动 Agno 代理应用：
```shell
uv run python scripts/agno_agent.py
```
默认情况下，该脚本使用 Claude 作为模型，但你可以选择 Agno 支持的任何模型（基本上是现有的任何模型）。
5. 在新终端中，启动 Agno UI：
```shell
cd agent-ui
pnpm dev
```
将 UI 连接到上面启动的代理，并开始聊天。你将拥有与 MCP 服务器版本相同的工具。
这里有一个简短的演示，展示 Serena 使用最新的 Gemini 模型执行一个小的分析任务：
[演示视频链接](https://github.com/user-attachments/assets/ccfcb968-277d-4ca9-af7f-b84578858c62)
⚠️ **重要提示：** 与 MCP 服务器方法不同，Agno UI 中的工具执行
不会询问用户的许可。Shell 工具尤其关键，因为它可以执行任意代码。
尽管我们在使用 Claude 进行测试时从未遇到过任何问题，但允许这种操作可能并不完全安全。
你可以选择在你的 Serena 项目的配置文件（`.yml`）中禁用某些工具。
### 其他代理框架
将 Serena 集成到任何
代理框架（如 [pydantic-ai](https://ai.pydantic.dev/)、[langgraph](https://langchain-ai.github.io/langgraph/tutorials/introduction/) 或其他框架）中应该相当简单。
通常，你只需要为 Serena 的工具编写一个适配器，以适配你选择的框架中的工具表示，
就像我们为 Agno 编写了 [SerenaAgnoToolkit](/src/serena/agno.py) 一样。
## 详细使用方法和建议
### 工具执行
Serena 结合了语义代码检索工具、编辑能力和 Shell 执行功能。
Serena 的行为可以通过 [模式和上下文](#模式和上下文) 进一步定制。
完整的工具列表见 [下方](#完整工具列表)。
通常建议使用所有工具，因为这样可以让 Serena 提供最大的价值：
只有通过执行 Shell 命令（特别是测试），
Serena 才能自主地识别并纠正错误。
#### Shell 执行和编辑工具
然而，需要注意的是，`execute_shell_command` 工具允许执行任意代码。
当使用 Serena 作为 MCP 服务器时，客户端通常会在执行工具之前询问用户许可，
只要用户事先检查执行参数，这应该不会有问题。
但是，如果你有顾虑，你可以选择在你的项目的 `.yml` 配置文件中禁用某些命令。
如果你只想使用 Serena 纯粹用于分析代码和建议实现
而不修改代码库，你可以在你的项目配置文件中设置 `read_only: true`。
这将自动禁用所有编辑工具，并防止对你的代码库进行任何修改，同时仍然
允许所有分析和探索功能。
一般来说，确保备份你的工作并使用版本控制系统，以避免
丢失任何工作。
### 模式和上下文
Serena 的行为和工具集可以通过上下文和模式进行调整。
这些允许高度定制，以最好地适应你的工作流程和 Serena 所在的环境。
#### 上下文
上下文定义了 Serena 所在的通用环境。
它影响初始系统提示和可用工具集。
上下文在启动时设置（例如，通过 CLI 选项启动 MCP 服务器或在代理脚本中），并且在一个活跃会话中不能更改。
Serena 提供了预定义的上下文：
* `desktop-app`：适用于与桌面应用程序（如 Claude Desktop）一起使用。这是默认上下文。
* `agent`：适用于 Serena 作为更自主代理的场景，例如与 Agno 一起使用。
* `ide-assistant`：针对集成到 IDE（如 VSCode、Cursor 或 Cline）进行了优化，专注于编辑器内的编码辅助。
选择最适合你所使用的集成类型的上下文。
在启动 Serena 时，使用 `--context ` 指定上下文。
注意，对于参数列表中指定的上下文（例如 Claude Desktop），你必须在列表中添加两个参数。
#### 模式
模式进一步细化 Serena 在特定类型的任务或交互风格中的行为。多个模式可以同时激活，允许你组合它们的效果。模式影响系统提示，并且也可以通过排除某些工具来改变可用工具集。
内置的模式示例包括：
* `planning`：专注于规划和分析任务。
* `editing`：优化直接代码修改任务。
* `interactive`：适用于对话式、来回交互的风格。
* `one-shot`：配置 Serena 用于应在单次响应中完成的任务，通常与 `planning` 一起用于生成报告或初始计划。
* `no-onboarding`：如果特定会话不需要，则跳过初始入职过程。
* `onboarding`：（通常自动触发）专注于项目的入职过程。
模式可以在启动时设置（类似于上下文），但也可以在会话过程中 *动态切换*。你可以指示 LLM 使用 `switch_modes` 工具激活不同的模式集（例如，“切换到规划和一次性模式”）。
在启动 Serena 时，使用 `--mode ` 指定模式；可以指定多个模式，例如 `--mode planning --mode no-onboarding`。
:warning: **模式兼容性**：虽然你可以组合模式，但某些模式可能在语义上不兼容（例如，`interactive` 和 `one-shot`）。Serena 当前不会阻止不兼容的组合；由用户选择合理的模式配置。
#### 自定义
你可以通过以下两种方式创建自己的上下文和模式，以精确地调整 Serena 以满足你的需求：
* **添加到 Serena 的配置目录**：在你的本地 Serena 仓库的 `config/contexts/` 或 `config/modes/` 目录中创建新的 `.yml` 文件。这些自定义上下文/模式将自动注册并可以通过它们的名称（文件名去掉 `.yml` 扩展名）使用。它们也会出现在上下文/模式的列表中。
* **使用外部 YAML 文件**：在启动 Serena 时，你可以提供一个自定义 `.yml` 文件的绝对路径，用于上下文或模式。
上下文或模式 YAML 文件通常定义以下内容：
* `name`：（如果使用文件名则可选）上下文/模式的名称。
* `prompt`：将被纳入 Serena 系统提示的字符串。
* `description`：（可选）简要描述。
* `excluded_tools`：当此上下文/模式激活时要禁用的工具名称列表（字符串）。
这种自定义允许深度集成和调整 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 可能会读取大量代码来构建上下文，
然后在另一个会话中继续进行实现（可能在创建了合适记忆之后）。
### 代码编辑中的潜在问题
在我们的经验中，LLM 在计数方面表现不佳，即它们在
将代码块插入正确位置时存在问题。大多数编辑操作可以在符号级别进行，这允许解决这个问题。然而，有时，
行级插入是有用的。
Serena 被指示要双重检查它将编辑的行号和任何代码块，但如果你遇到问题，你可能会发现明确告诉它如何编辑代码是有用的。
我们正在努力使 Serena 的编辑能力更加稳健。
### 上下文溢出
对于长且复杂的任务，或者 Serena 已经读取了大量内容的任务，你
可能会接近上下文令牌的限制。在这种情况下，通常最好在新对话中继续。Serena 有一个专用工具来创建当前进度的摘要
以及继续任务所需的所有相关信息。你可以请求创建这个摘要并
将其写入记忆。然后，在新对话中，你只需让 Serena 读取记忆并
继续任务。在我们的经验中，这效果很好。优点是，在单个会话中通常没有总结涉及，Serena 通常不会迷失方向（与其他一些在底层进行总结的代理不同），并且它还被指示偶尔检查是否
在正确的轨道上。
此外，Serena 被指示要节省上下文
（例如，不要不必要地读取代码符号的主体），
但我们发现 Claude 在节省上下文方面并不总是很好（Gemini 在这方面似乎表现更好）。
你可以明确指示它不要读取主体，如果你知道这是不必要的。
### 与其他 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 服务器启动时自动打开。
除了查看日志外，这两种工具都允许关闭 Serena 代理。
提供此功能是因为像 Claude Desktop 这样的客户端可能无法正确终止 MCP 服务器子进程
当它们自己关闭时。
### 故障排除
在 Claude Desktop 和各种 MCP 服务器 SDK 中对 MCP 服务器的支持是相对较新的发展，可能会出现不稳定。
MCP 服务器的可用配置可能因平台而异，也因客户端而异。我们建议始终使用绝对路径，因为相对路径可能是错误的来源。
语言服务器以单独的子进程运行，并通过 asyncio 调用——有时
客户端可能会导致它崩溃。如果你启用了 Serena 的日志窗口，并且它消失了，你就会知道发生了什么。
有些客户端可能无法正确终止 MCP 服务器，请注意是否有挂起的 Python 进程并手动终止它们，如果需要的话。
## 与其他编码代理的比较
据我们所知，Serena 是第一个完全功能的编码代理，其
所有功能都通过 MCP 服务器提供，因此不需要 API 密钥或
订阅。
### 订阅制编码代理
最著名的订阅制编码代理是 IDE 的一部分，如
Windsurf、Cursor 和 VSCode。
Serena 的功能与 Cursor 的代理、Windsurf 的 Cascade 或
VSCode 即将推出的 [代理模式](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode) 类似。
Serena 的优势在于不需要订阅。
一个潜在的劣势是它
不是直接集成到 IDE 中的，因此检查新编写的代码
没有那么无缝。
更技术性的差异如下：
* Serena 不绑定于特定的 IDE。
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 与其他基于 API 的代理的主要区别在于，Serena 还可以作为 MCP 服务器使用，因此不需要 API 密钥，从而绕过了 API 成本。这是 Serena 的独特功能。
### 其他基于 MCP 的编码代理
还有其他为编码设计的 MCP 服务器，例如 [DesktopCommander](https://github.com/wonderwhy-er/DesktopCommanderMCP) 和 [codemcp](https://github.com/ezyang/codemcp)。然而，据我们所知，这些工具中没有一个提供语义代码检索和编辑工具；它们完全依赖于基于文本的分析。正是语言服务器与 MCP 的集成，使得 Serena 在处理大型代码库中的复杂编码任务时如此独特且强大。
## 致谢
我们基于多种现有的开源技术构建了 Serena，其中最重要的是：
1. [multilspy](https://github.com/microsoft/multilspy)。
这是一个封装语言服务器实现的库，并将其适配为通过 Python 进行交互。它为我们的 Solid-LSP 库（src/solidlsp）提供了基础。
Solid-LSP 提供了纯同步的 LSP 调用，并扩展了原始库，增加了 Serena 所需的符号逻辑。
2. [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
3. [Agno](https://github.com/agno-agi/agno) 和相关的 [agent-ui](https://github.com/agno-agi/agent-ui)，
我们使用它们让 Serena 能够与任何模型一起工作，而不仅仅是支持 MCP 的模型。
4. 我们通过 Solid-LSP 使用的所有语言服务器。
没有这些项目，Serena 将无法实现（或者构建难度会大大增加）。
## 自定义和扩展 Serena
扩展 Serena 的 AI 功能非常简单。只需通过继承 `serena.agent.Tool` 创建一个新工具，并实现符合工具要求的 `apply` 方法。一旦实现，`SerenaAgent` 将自动获得对新工具的访问权限。
添加对新编程语言的支持也相对简单。
我们期待社区的贡献！关于如何贡献的详细信息，请参阅 [这里](/CONTRIBUTING.md)。
## 完整工具列表
以下是 Serena 的完整工具列表及其简要描述（由 `uv run serena-list-tools` 输出）：
* `activate_project`：通过名称激活项目。
* `check_onboarding_performed`：检查项目入职是否已经完成。
* `create_text_file`：在项目目录中创建/覆盖文件。
* `delete_lines`：删除文件中的一段行。
* `delete_memory`：从 Serena 的项目特定存储中删除记忆。
* `execute_shell_command`：执行 Shell 命令。
* `find_referencing_code_snippets`：查找在给定位置引用的符号所在的代码片段。
* `find_referencing_symbols`：查找引用给定位置符号的符号（可选按类型过滤）。
* `find_symbol`：执行全局（或局部）搜索，查找包含给定名称/子字符串的符号（可选按类型过滤）。
* `get_active_project`：获取当前激活的项目名称（如果有），并列出现有项目。
* `get_current_config`：打印当前代理的配置，包括激活的模式、工具和上下文。
* `get_symbols_overview`：获取给定文件或目录中定义的顶级符号的概览。
* `initial_instructions`：获取当前项目的初始指令。
仅应在无法设置系统提示的环境中使用，例如在你无法控制的客户端（如 Claude Desktop）中。
* `insert_after_symbol`：在给定符号定义的末尾插入内容。
* `insert_at_line`：在文件的指定行插入内容。
* `insert_before_symbol`：在给定符号定义的开头插入内容。
* `list_dir`：列出给定目录中的文件和目录（可选递归）。
* `list_memories`：列出 Serena 的项目特定存储中的记忆。
* `onboarding`：执行入职流程（识别项目结构和基本任务，例如测试或构建）。
* `prepare_for_new_conversation`：为新对话准备指令（以便继续必要的上下文）。
* `read_file`：读取项目目录中的文件。
* `read_memory`：从 Serena 的项目特定存储中读取指定名称的记忆。
* `replace_lines`：用新内容替换文件中的一段行。
* `replace_symbol_body`：替换符号的完整定义。
* `restart_language_server`：重启语言服务器，当非通过 Serena 的编辑发生时可能需要。
* `search_for_pattern`：在项目中搜索模式。
* `summarize_changes`：提供总结对代码库所做更改的指令。
* `switch_modes`：通过提供模式名称列表激活模式。
* `think_about_collected_information`：思考工具，用于思考收集到的信息是否完整。
* `think_about_task_adherence`：思考工具，用于判断代理是否仍在按当前任务进行。
* `think_about_whether_you_are_done`：思考工具，用于判断任务是否真正完成。
* `write_memory`：将命名的记忆（供将来参考）写入 Serena 的项目特定存储。