Serena：开源编码代理工具包，让AI直接在你的代码库上工作

在软件开发领域，我们经常需要处理复杂的代码库，寻找特定的函数或类，进行代码重构或实现新功能。传统方法往往需要开发者手动搜索、阅读和修改大量代码，效率低下且容易出错。今天，我要向大家介绍一款革命性的开源工具——Serena，它能够将大语言模型（LLM）转变为直接在你的代码库上工作的全功能编码代理。

什么是Serena？

Serena是一个强大的编码代理工具包，它通过语义代码检索和编辑工具，让AI能够像使用IDE一样操作你的代码库。与传统基于文本的代码助手不同，Serena能够：

• 直接理解代码的符号结构（函数、类、变量等）
• 精确定位和修改代码片段
• 执行命令行操作和测试
• 管理项目上下文和记忆系统

Serena完全免费开源，能够显著提升你现有LLM的编码能力，无需额外付费订阅。

Serena的核心功能

1. 语义代码检索与编辑

Serena的核心优势在于其符号级代码操作能力。它不像传统工具那样仅处理文本，而是真正理解代码结构：

• 全局符号搜索：快速查找项目中特定名称的函数、类或变量
• 引用分析：找出所有引用特定符号的代码位置
• 精准编辑：直接替换整个符号定义或插入代码片段
• 上下文感知：自动识别当前编辑位置的作用域

2. 多语言支持

Serena通过语言服务器协议（LSP）支持多种编程语言：

3. 项目记忆系统

Serena能够为每个项目创建记忆存储（.serena/memories/），保存项目特定的上下文信息，如：

• 项目架构描述
• 关键业务逻辑说明
• 常见问题解决方案
• 测试策略

这些记忆会在后续会话中被自动读取，让AI能够持续理解项目背景。

安装与配置

前置要求

• Python 3.8+
• uv（Python包管理工具）

安装方式

方式一：使用uvx（推荐）

# Serena：开源编码代理工具包，让AI直接在你的代码库上工作
在软件开发领域，我们经常需要处理复杂的代码库，寻找特定的函数或类，进行代码重构或实现新功能。传统方法往往需要开发者手动搜索、阅读和修改大量代码，效率低下且容易出错。今天，我要向大家介绍一款革命性的开源工具——Serena，它能够将大语言模型（LLM）转变为直接在你的代码库上工作的全功能编码代理。
## 什么是Serena？
Serena是一个强大的**编码代理工具包**，它通过语义代码检索和编辑工具，让AI能够像使用IDE一样操作你的代码库。与传统基于文本的代码助手不同，Serena能够：
- 直接理解代码的符号结构（函数、类、变量等）
- 精确定位和修改代码片段
- 执行命令行操作和测试
- 管理项目上下文和记忆系统
![Serena Logo](https://sfile.chatglm.cn/chatglm4/file/44/4432635157.md/resources/serena-logo.svg#gh-light-mode-only)
Serena完全免费开源，能够显著提升你现有LLM的编码能力，无需额外付费订阅。
## Serena的核心功能
### 1. 语义代码检索与编辑
Serena的核心优势在于其**符号级代码操作**能力。它不像传统工具那样仅处理文本，而是真正理解代码结构：
- **全局符号搜索**：快速查找项目中特定名称的函数、类或变量
- **引用分析**：找出所有引用特定符号的代码位置
- **精准编辑**：直接替换整个符号定义或插入代码片段
- **上下文感知**：自动识别当前编辑位置的作用域
### 2. 多语言支持
Serena通过语言服务器协议（LSP）支持多种编程语言：
| 语言类型 | 支持状态 | 备注 |
|---------|---------|------|
| **直接支持** |  |  |
| Python | ✅ | 开箱即用 |
| TypeScript/JavaScript | ✅ | 当前存在不稳定性问题 |
| PHP | ✅ |  |
| Go | ✅ | 需先安装Go和gopls |
| Rust | ✅ |  |
| C# | ✅ | 需安装.NET，近期切换了底层语言服务器 |
| Java | ✅ | 启动较慢，macOS/Linux可能有兼容性问题 |
| Elixir | ✅ | 需安装NextLS和Elixir，不支持Windows |
| Clojure | ✅ |  |
| C/C++ | ✅ | 可能存在引用查找问题 |
| **间接支持** |  |  |
| Ruby | ⚠️ | 未充分测试 |
| Kotlin | ⚠️ | 未充分测试 |
| Dart | ⚠️ | 未充分测试 |
### 3. 项目记忆系统
Serena能够为每个项目创建**记忆存储**（.serena/memories/），保存项目特定的上下文信息，如：
- 项目架构描述
- 关键业务逻辑说明
- 常见问题解决方案
- 测试策略
这些记忆会在后续会话中被自动读取，让AI能够持续理解项目背景。
## 安装与配置
### 前置要求
- Python 3.8+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)（Python包管理工具）
### 安装方式
#### 方式一：使用uvx（推荐）
```bash
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

方式二：本地安装

# 克隆仓库
git clone https://github.com/oraios/serena
cd serena
# 可选：编辑配置文件
uv run serena config edit
# 启动服务器
uv run serena start-mcp-server

方式三：Docker（实验性）

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

配置文件说明

Serena使用四个层级的配置：

1. 全局配置（~/.serena/serena_config.yml）

   • 所有项目和客户端共享的默认设置
   • 可通过 uv run serena config edit 编辑
2. 项目配置（项目目录下的.serena/project.yml）

   • 项目特定设置
   • 自动生成或手动创建：

     uv run serena project generate-yml
     

3. 命令行参数

   • 覆盖配置文件设置
   • 例如：--context ide-assistant --mode planning
4. 运行模式

   • 动态调整行为（详见后文）

使用指南

项目激活与索引

激活项目

通过自然语言指令激活项目：

# 使用绝对路径
"Activate the project /path/to/my_project"
# 使用项目名称（需先激活过）
"Activate the project my_project"

索引项目（可选）

对于大型项目，建议先索引以加速工具响应：

uv run serena project index

与不同LLM集成

Claude Desktop

1. 打开设置：File > Settings > Developer > MCP Servers > Edit Config
2. 添加配置：

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

3. 重启Claude Desktop

Claude Code

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

Agno Agent（支持任意LLM）

1. 安装Agent UI：

   npx create-agent-ui@latest
   cd agent-ui
   pnpm install
   pnpm dev
   

2. 安装Serena：

   uv pip install --all-extras -e .
   

3. 启动代理：

   uv run python scripts/agno_agent.py
   

4. 连接UI并开始使用

工具使用示例

Serena提供了丰富的工具集，以下是常用工具：

高级用法

运行模式与上下文

Serena通过**上下文（Context）和模式（Mode）**调整行为：

上下文（Context）

• desktop-app：桌面应用（Claude Desktop默认）
• agent：独立代理（Agno使用）
• ide-assistant：IDE集成（VSCode/Cursor等）

模式（Mode）

• planning：专注规划与分析
• editing：专注代码修改
• interactive：对话式交互
• one-shot：单次完成任务
• no-onboarding：跳过项目引导
  示例命令：

uv run serena start-mcp-server --context ide-assistant --mode planning --mode no-onboarding

项目准备最佳实践

1. 代码结构化

   • 避免巨型类和超长函数
   • 使用类型注解（特别是动态语言）
2. Git状态管理

   • 从干净状态开始任务
   • Windows用户设置：

     git config --global core.autocrlf true
     

3. 测试与日志

   • 确保有自动化测试
   • 使用有意义的日志输出

提示策略

1. 分阶段任务

   • 先规划：要求Serena分析需求并制定详细计划
   • 后实现：在新的会话中基于计划实现
2. 上下文管理

   • 长任务时使用summarize_changes创建记忆摘要
   • 新会话时读取记忆继续工作
3. 精确指令

   • 明确指定修改位置（符号名或行号）
   • 要求解释修改原因

常见问题解答

Q1: Serena与Cursor等IDE内置AI有何区别？

A: Serena是开源免费的，通过语义理解操作代码（而非文本匹配），支持任意LLM，且可跨IDE使用。

Q2: 如何确保代码修改的安全性？

A: 1) 使用版本控制 2) 在测试环境验证 3) 可配置read_only: true模式禁用编辑功能 4) 检查修改前确认命令参数。

Q3: 支持Windows系统吗？

A: 完全支持。除Elixir语言（NextLS无Windows版本）外，其他语言均可正常使用。

Q4: 如何解决TypeScript/JavaScript的不稳定性？

A: 当前团队正在修复此问题，建议关注更新日志获取进展。

Q5: 项目索引需要多长时间？

A: 取决于项目大小，首次索引可能需要几分钟。大型项目建议提前索引。

Q6: 可以同时使用多个MCP服务器吗？

A: 可以，但需注意工具名称冲突（如避免同时使用Filesystem MCP Server）。

Q7: 如何查看Serena的执行日志？

A: 默认启动Web仪表盘（http://localhost:24282），或启用GUI工具（Windows/Linux支持）。

Q8: Agno Agent支持哪些模型？

A: 理论上支持所有Agno兼容模型，包括：

• Anthropic Claude
• Google Gemini
• OpenAI GPT系列
• 本地模型（Ollama/Together/Anyscale）

Q9: 如何自定义Serena的行为？

A: 1) 创建自定义上下文/模式（YAML文件） 2) 修改配置文件 3) 使用命令行参数覆盖。

Q10: 遇到语言服务器问题如何处理？

A: 尝试重启语言服务器：

restart_language_server

或查看日志排查问题。

总结

Serena代表了AI辅助开发的新范式，它通过语义理解能力让AI真正成为开发团队的智能成员。其开源特性、多语言支持和灵活的集成方式，使其成为替代昂贵商业IDE插件和API服务的理想选择。
无论你是：

• 需要增强Claude/Cursor等工具的开发者
• 希望使用本地模型进行编码的隐私保护者
• 寻求免费替代方案的小团队
• 研究AI辅助开发的学者
  Serena都能提供专业级的代码理解与操作能力。随着项目持续迭代（见Roadmap），其功能将不断完善，为开发者带来更强大的AI伙伴。

“Serena让我们终于摆脱了多个IDE订阅和API费用的困扰。它不仅免费，在很多场景下甚至比付费工具表现更好。”
— Oraios AI开发团队
立即体验Serena，开启你的AI驱动开发之旅！