AI 编码代理工具包
一个强大的开源编码代理工具包，通过语义检索和编辑能力，将 LLM 转化为能够直接操作代码库的完整功能代理。 支持 30+ 种编程语言，基于语言服务器协议（LSP）提供 IDE 级别的代码智能。
理解这个革命性的编码代理工具包
Serena 不是一个特定的 AI 模型或 IDE 插件，而是一个工具包框架。 它为大语言模型（LLM）提供了一套强大的工具，使其能够像人类开发者使用 IDE 一样， 以语义级别理解和操作代码，而不仅仅是将代码视为文本字符串。
不再需要阅读整个文件或进行字符串搜索。Serena 提供 find_symbol、
find_referencing_symbols、insert_after_symbol 等工具，
让 AI 能够精确定位和修改代码符号。
通过 LSP（语言服务器协议）集成，支持 Python、JavaScript、TypeScript、Rust、Go、 Java、C++、C# 等超过 30 种编程语言，适用于几乎任何项目。
不绑定特定的 LLM、框架或接口。支持 MCP（Model Context Protocol）、OpenAPI、 以及自定义集成，可以与 Claude、ChatGPT、VSCode、Cursor 等多种工具配合使用。
构建在成熟的语言服务器协议之上，复用现有的语言服务器基础设施， 提供可靠的代码分析、导航和重构能力。
在复杂代码库中发挥最大价值。通过利用代码的关系结构， 即使在包含数千个文件的项目中也能高效工作，显著提升生产力。
开发者可以通过继承 serena.agent.Tool 类添加自定义功能，
工具会自动集成到 SerenaAgent 中，轻松扩展能力。
深入理解 Serena 的技术架构
Claude Desktop、Claude Code、VSCode、Cursor、ChatGPT 等 AI 编程助手
MCP (Model Context Protocol): 用于 Claude 系列工具
OpenAPI: 通过 mcpo 适配器支持非 MCP 客户端
自定义协议: 可集成到任何 AI 框架
SerenaAgent: 主要代理类，管理工具和会话
工具集: find_symbol、find_referencing_symbols、insert_after_symbol 等
Python MCP SDK: MCP 协议实现
Solid-LSP: 对 multilspy 的扩展
Multilspy: 多语言 LSP 客户端库
Pyright (Python)、TypeScript Language Server、rust-analyzer、 gopls (Go)、Java Language Server、clangd (C/C++) 等 30+ 语言服务器
1. AI 客户端发送请求 ↓ 2. 通过 MCP/OpenAPI 协议传递到 Serena ↓ 3. SerenaAgent 选择合适的工具（如 find_symbol） ↓ 4. 工具通过 Solid-LSP 与对应的语言服务器通信 ↓ 5. 语言服务器分析代码库，返回语义信息 ↓ 6. Serena 格式化结果并返回给 AI ↓ 7. AI 理解代码结构，执行精确操作
LSP（Language Server Protocol）是微软开发的一个开放协议，最初用于 VSCode。 它将语言特定的功能（如代码补全、跳转定义、查找引用等）与编辑器分离。 Serena 利用这一成熟技术栈，无需为每种语言重新实现分析器，就能提供强大的代码理解能力。
覆盖主流和小众语言的广泛支持
只要有对应的 LSP 语言服务器，Serena 就能支持该语言
灵活的集成选项适配不同需求
| 集成方式 | 适用场景 | 支持的工具 | 设置难度 |
|---|---|---|---|
| MCP 协议 | 原生支持 MCP 的客户端 | Claude Code、Claude Desktop、VSCode、Cursor、Codex | ⭐⭐ 简单 |
| OpenAPI（通过 mcpo） | 不支持 MCP 的工具 | ChatGPT、自定义 GPT、其他 OpenAPI 兼容客户端 | ⭐⭐⭐ 中等 |
| 自定义框架 | 深度集成到自己的 AI 系统 | 任何自定义 AI 代理框架 | ⭐⭐⭐⭐ 需要开发 |
从零开始：在 Claude Code 中使用 Serena
首先需要安装 uv，这是一个快速的 Python 包管理器
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # 验证安装 uv --version
在 Claude Code 设置中添加 Serena MCP 服务器
# 编辑 ~/.claude/settings.json 或通过 Claude Code 设置界面
{
"mcpServers": {
"serena": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server"
]
}
}
}
💡 提示：也可以添加额外参数如 --debug 来启用调试模式
关闭并重新打开 Claude Code，让配置生效。Serena 服务器将自动启动并连接。
✓ 在 Claude Code 的工具列表中应该能看到 Serena 提供的工具
在 Claude Code 中打开一个代码项目，Serena 会自动检测项目类型并启动对应的语言服务器
# 在终端中进入项目目录 cd ~/projects/my-awesome-app # 启动 Claude Code claude-code .
📁 Serena 会在项目根目录创建 .serena/ 配置目录
现在可以向 Claude 提出代码相关的请求，它会自动使用 Serena 的工具
你: "找到 UserService 类的定义"
Claude: 使用 find_symbol(symbol_name="UserService")
→ 返回: src/services/user_service.py:15
你: "哪些地方调用了 authenticate 方法？"
Claude: 使用 find_referencing_symbols(symbol_name="authenticate")
→ 返回所有调用该方法的位置列表
你: "在 process_payment 函数后添加一个新函数 refund_payment"
Claude: 使用 insert_after_symbol(symbol_name="process_payment", code="...")
→ 精确在指定位置插入代码
让我们看一个真实的重构场景
场景：你的团队决定将所有的日志记录从 print 改为使用 logging 模块 传统方式： 1. 全局搜索 print( 2. 手动检查每个结果是否是调试输出 3. 逐个文件修改 4. 容易遗漏或误改 使用 Serena： 你: "找到所有使用 print 的地方，并帮我改为使用 logging" Claude 会: 1. 使用 find_referencing_symbols 找到所有 print 调用 2. 分析上下文判断是否是日志输出 3. 使用 insert_after_symbol 在文件开头添加 import logging 4. 使用 replace_symbol_code 替换 print 为 logging.info 5. 保持代码格式和缩进一致 结果： ✓ 精确定位所有相关代码 ✓ 智能判断替换上下文 ✓ 自动处理导入语句 ✓ 几分钟完成原本需要几小时的工作
find_symbol 定位再操作，比直接搜索文件更高效
find_referencing_symbols 了解影响范围再修改代码
Serena 在实际开发中的价值体现
快速理解陌生代码库的结构。"这个类在哪里定义？"、"谁在使用这个函数？"、 "这个变量的作用域是什么？" - 让 AI 帮你快速定位和理解。
重命名符号、修改函数签名、迁移 API - Serena 能够找到所有相关引用， 确保重构的完整性和正确性，避免遗漏导致的运行时错误。
追溯 bug 的影响范围。通过查找符号引用，了解问题代码在哪里被调用， 帮助你评估修复的影响面和潜在风险。
升级依赖库版本时，找到所有使用旧 API 的地方并批量更新。 Serena 的语义理解确保不会误改相似但无关的代码。
让 AI 遍历代码符号，自动生成准确的 API 文档。基于实际代码结构， 而不是简单的文本分析，确保文档与代码保持同步。
检查代码中的模式和潜在问题。"找到所有未处理异常的数据库调用"、 "哪些函数没有类型注解？" - 让 AI 进行系统性的代码检查。
为什么 Serena 能够改变游戏规则
| 任务 | 传统 AI 编程助手 | 使用 Serena |
|---|---|---|
| 找到函数定义 | 需要阅读多个文件或依赖正则搜索 | 直接使用 find_symbol 精确定位 |
| 重命名变量 | 文本替换可能误改同名但不相关的代码 | 语义级重命名，只影响相关引用 |
| 了解依赖关系 | 手动追踪 import 语句和调用链 | find_referencing_symbols 自动构建调用图 |
| 在大型项目中定位 | 需要提供完整文件或大量上下文 | 基于符号索引，即时响应 |
| 跨文件重构 | 容易遗漏某些文件或引用 | 系统性覆盖所有相关位置 |
Serena 提供的主要工具及其用法
查找代码符号的定义位置（类、函数、变量等）
# 用法示例
find_symbol(
symbol_name="UserService",
symbol_type="class" # 可选: class, function, variable
)
返回： 符号定义的文件路径和行号
查找所有引用某个符号的位置
# 用法示例
find_referencing_symbols(
symbol_name="authenticate",
file_path="src/auth/service.py", # 可选：限定搜索范围
line_number=42
)
返回： 所有引用该符号的位置列表
在指定符号后插入代码
# 用法示例
insert_after_symbol(
symbol_name="process_payment",
code="""
def refund_payment(transaction_id: str) -> bool:
\"\"\"处理退款\"\"\"
# 实现退款逻辑
return True
""",
preserve_indentation=True
)
作用： 在语义合适的位置插入新代码，保持项目结构
替换符号的实现代码
# 用法示例
replace_symbol_code(
symbol_name="validate_email",
new_code="""
def validate_email(email: str) -> bool:
import re
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
return bool(re.match(pattern, email))
"""
)
获取符号的详细信息（类型、签名、文档等）
# 用法示例
get_symbol_info(
symbol_name="UserService.create_user"
)
# 返回示例
{
"name": "create_user",
"type": "method",
"signature": "(self, username: str, email: str) -> User",
"docstring": "创建新用户",
"file": "src/services/user_service.py",
"line": 25
}
三种主要集成方式的详细配置
{
"mcpServers": {
"serena": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/oraios/serena",
"serena",
"start-mcp-server"
]
}
}
}
# 1. 安装 mcpo pip install mcpo # 2. 启动 OpenAPI 适配器 mcpo \ --mcp-server uvx \ --from git+https://github.com/oraios/serena \ serena start-mcp-server # 3. 在 ChatGPT 中添加 Actions # 使用生成的 OpenAPI schema
# Python 示例
from serena import SerenaAgent
from serena.tools import FindSymbol
# 创建代理
agent = SerenaAgent(
project_path="/path/to/project"
)
# 使用工具
result = agent.use_tool(
FindSymbol,
symbol_name="MyClass"
)
print(result)
开发者如何评价 Serena
"Serena 是一个真正的游戏改变者。在我们有 50+ 个微服务的代码库中， 它让 AI 能够准确定位和修改代码，节省了大量时间。"
- 资深后端工程师
"对于大型重构任务，Serena 的语义理解能力让我放心地让 AI 进行批量修改。 它知道什么该改，什么不该改。"
- 技术架构师
"刚开始使用时觉得配置有点复杂，但一旦运行起来，效率提升是显而易见的。 现在已经离不开它了。"
- 全栈开发者
了解何时使用以及何时不使用 Serena
深入学习和获取支持