Home
Login
oraios/serenaPlease refer to the latest official releases for information GitHub Homepage

Serena 是一个强大的编码代理工具包，能够将大型语言模型（LLM）转变为一个功能完备的代理，直接在您的代码库上工作。

MITPython 2.9koraiosserena Last Updated: 2025-06-25

Serena 项目详细介绍

项目概述

Serena 是一个强大的编程智能体工具包，能够将大语言模型（LLM）转换为功能齐全的编程智能体，直接在您的代码库上进行工作。该项目由 Oraios AI 开发并开源贡献给开发者社区。

核心特性

🚀 核心能力

  • 语义代码检索和编辑功能：提供类似 IDE 的能力，在符号级别提取代码实体并利用关系结构
  • 完全开源免费：增强您已有 LLM 的能力，无需额外费用
  • 多种集成方式：支持 MCP 服务器、Agno 框架和自定义智能体框架集成

🔧 技术优势

  • 基于语言服务器协议（LSP）：通过广泛实现的 LSP 提供多种代码查询和编辑功能
  • 符号级理解：基于代码的符号理解进行发现和编辑，就像经验丰富的开发者使用 IDE 一样
  • 高效精准：即使在大型复杂项目中也能高效找到正确的上下文并执行正确的操作

支持的编程语言

直接支持（开箱即用）

  • Python
  • Java（注意：启动较慢，首次启动尤为明显）
  • TypeScript

这些语言通过 Serena 底层使用的 multilspy 语言服务器库支持。

集成方式

1. 模型上下文协议（MCP）

Serena 提供 MCP 服务器，可与以下客户端集成：

  • Claude Desktop
  • IDE（如 VSCode、Cursor、IntelliJ）
  • 扩展（如 Cline、Roo Code）
  • Goose（提供良好的 CLI 体验）
  • 以及许多其他客户端，包括即将支持的 ChatGPT 应用

2. Agno 框架

通过 Agno（模型无关的智能体框架），Serena 可以将几乎任何 LLM 转换为编程智能体，支持：

  • Google、OpenAI、Anthropic 提供的付费 API 模型
  • Ollama、Together、Anyscale 提供的免费模型

3. 自定义智能体框架

Serena 的工具实现与框架特定代码解耦，可以轻松适配到任何智能体框架。

使用场景

Serena 可用于任何编程任务，包括：

  • 代码分析
  • 项目规划
  • 设计新组件
  • 重构现有代码
  • 从初始分析到实现、测试，最终到版本控制系统提交的完整自主编程任务

快速开始

基本安装

  1. 安装 uv（安装说明参见官方文档）
  2. 克隆仓库到 /path/to/serena
  3. 复制 serena_config.template.yml 为 serena_config.yml 并调整设置
  4. 复制 myproject.template.yml 为 myproject.yml 并调整项目特定设置
  5. 如需动态切换项目，将所有项目文件添加到 serena_config.yml 的 projects 列表中

Claude Desktop 集成

  1. 创建项目配置文件 myproject.yml
  2. 在 Claude Desktop 中配置 MCP 服务器：
    • 打开 File / Settings / Developer / MCP Servers / Edit Config
    • 在 claude_desktop_config.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"]
    }
  }
}
  3. 保存配置并重启 Claude Desktop

Goose CLI 使用

  1. 安装 goose
  2. 使用 goose configure 添加扩展
  3. 选择 "Command-line Extension"，命名为 "Serena"
  4. 添加命令：/abs/path/to/uv run --directory /abs/path/to/serena serena-mcp-server /optional/abs/path/to/project.yml
  5. 禁用默认的 developer 扩展

Agno GUI 使用

  1. 下载 agent-ui 代码：npx create-agent-ui@latest
  2. 安装 Serena：uv pip install --all-extras -r pyproject.toml -e .
  3. 复制 .env.example 为 .env 并填入 API 密钥
  4. 启动 Agno 智能体：uv run python scripts/agno_agent.py
  5. 启动 UI：cd agent-ui && pnpm dev

工具和配置

主要工具类别

  • 语义代码检索工具：查找符号、引用、代码片段
  • 代码编辑工具：插入、替换、删除代码
  • 文件系统操作：读取、创建、列出文件和目录
  • Shell 执行：执行 shell 命令
  • 项目管理：激活项目、入门引导、内存管理

安全考虑

  • 所有工具的使用通常都是推荐的，以提供最大价值
  • execute_shell_command 工具允许任意代码执行，需要谨慎使用
  • 可以在项目配置文件中禁用特定命令
  • 支持只读模式（read_only: true），只允许分析和建议，不修改代码库

与其他编程智能体的比较

相比基于订阅的智能体（Windsurf、Cursor、VSCode）

优势：

  • 无需订阅费用
  • 不绑定特定 IDE
  • 不绑定特定大语言模型或 API
  • 使用语言服务器进行符号级代码理解
  • 开源且代码库小，易于扩展和修改

劣势：

  • 不直接集成到 IDE 中，检查新代码不如 IDE 内置工具无缝

相比基于 API 的智能体（Claude Code、Cline、Aider）

优势：

  • 可作为 MCP 服务器使用，无需 API 密钥，避免 API 费用
  • 这是 Serena 的独特功能

相似点：

  • 都可以作为 API 基础智能体使用
  • 都很强大，主要缺点是潜在的高 API 费用

相比其他 MCP 服务器

  • 据了解，其他编程相关的 MCP 服务器（如 DesktopCommander、codemcp）都不提供语义代码检索和编辑工具
  • 它们依赖纯基于文本的分析
  • Serena 集成语言服务器和 MCP 的特性使其在处理大型代码库的挑战性编程任务时独特且强大

入门引导和记忆系统

入门引导

  • 默认情况下，Serena 在首次为项目启动时会执行入门引导过程
  • 目标是让 Serena 熟悉项目并存储记忆，供未来交互使用

记忆系统

  • 记忆文件存储在项目目录的 .serena/memories/ 中
  • 智能体可以选择读取这些文件
  • 用户可以根据需要阅读和调整记忆文件，也可以手动添加新的记忆文件
  • 记忆系统显著改善了用户使用 Serena 的体验

使用建议

模型选择

  • 非思考版本的 Claude 3.7 似乎比思考版本效果更好
  • Gemini 在初步实验中表现很好，但尚不支持 MCP
  • Gemini 相对便宜且可以处理巨大的上下文长度

最佳实践

  1. 版本控制：最好从干净的 git 状态开始代码生成任务
  2. Windows 配置：在 Windows 上设置 git config --global core.autocrlf true
  3. 代码结构：使用结构良好、模块化和有类型注解的代码
  4. 测试和日志：包含详细的日志信息和有意义的测试
  5. 规划优先：对于复杂任务，先进行概念化和规划
  6. 上下文管理：长任务时可以创建摘要并在新对话中继续

完整工具列表

以下是 Serena 所有工具的完整列表：

  • 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_symbols_overview: 获取文件或目录中顶级符号的概览
  • insert_after_symbol: 在符号定义结束后插入内容
  • insert_at_line: 在文件的给定行插入内容
  • insert_before_symbol: 在符号定义开始前插入内容
  • list_dir: 列出目录中的文件和目录
  • list_memories: 列出内存存储中的记忆
  • onboarding: 执行入门引导
  • prepare_for_new_conversation: 为新对话做准备
  • read_file: 读取项目目录中的文件
  • read_memory: 读取指定名称的记忆
  • replace_lines: 用新内容替换文件中的行范围
  • replace_symbol_body: 替换符号的完整定义
  • restart_language_server: 重启语言服务器
  • search_for_pattern: 在项目中搜索模式
  • summarize_changes: 提供代码库更改摘要说明
  • think_about_collected_information: 思考工具，用于考虑收集信息的完整性
  • think_about_task_adherence: 思考工具，用于确定智能体是否仍在当前任务的正确轨道上
  • think_about_whether_you_are_done: 思考工具，用于确定任务是否真正完成
  • write_memory: 将命名记忆写入内存存储以供将来参考

总结

Serena 是一个功能强大、完全开源的编程智能体工具包，通过语义代码理解和多种集成方式，为开发者提供了一个免费且强大的 AI 编程助手解决方案。无论是通过 MCP 服务器与 Claude Desktop 集成，还是通过 Agno 框架使用各种 LLM，Serena 都能显著提升编程效率和代码质量。

Star History Chart