oraios/serena · 上手攻略

  • 仓库：oraios/serena
  • 链接：https://github.com/oraios/serena
  • 分类：skill
  • 作者：Tom
  • 更新：2026-07-08

这是什么

Serena 是一个面向 AI 编程 Agent 的 MCP 工具包，为 Agent 提供 IDE 级别的语义代码检索、编辑、重构和调试能力。它的核心定位是"Agent 的专属 IDE"——让 Agent 能像资深开发者使用 IDE 那样，在符号（symbol）层面理解代码结构，而不是逐文件逐行地猜。

简而言之：没有 Serena，Agent 只能靠"grep 搜索 + 文本替换"在代码库里摸索；有了 Serena，Agent 能直接查符号引用、跨文件重命名、找实现、查类型层次。

两种后端可选：

后端 费用 支持语言数
语言服务器（LSP） 免费，开源 40+（Ada/AL/Angular/Bash/C#/C++/Clojure/Dart/Elixir/Erlang/Fortran/Go/Haskell/Java/JavaScript/Kotlin/Lua/MATLAB/Nix/OCaml/Perl/PHP/Python/R/Ruby/Rust/Scala/Swift/TypeScript/Zig 等）
JetBrains 插件 付费，有免费试用 JetBrains 全家桶支持的所有语言（IntelliJ/PyCharm/WebStorm/GoLand 等）

解决什么问题

主流 Agent（Claude Code、Codex、Copilot CLI 等）在处理代码时，本质上是在做"文本手术"：搜索关键字、替换字符串。这种方式在大型代码库里极容易出错——同名变量、跨文件引用、字符串误匹配，都会让 Agent 输出错误的修改。

Serena 通过 LSP 或 JetBrains 插件，把代码的符号语义暴露给 Agent：

  • 符号引用查找：某函数在哪些地方被调用？
  • 声明定位：某个符号在哪里定义？
  • 跨文件重命名：改一个函数名，所有引用同步更新
  • 移动/重构：符号、文件、目录的整体搬迁
  • 类型层次：查看接口的实现类

实测数据（官方评估，Claude Code + 大型 Python 代码库）：

"Serena's IDE-backed semantic tools are the single most impactful addition to my toolkit – cross-file renames, moves, and reference lookups that would cost me 8–12 careful, error-prone steps collapse into one atomic call."

GPT 5.4（高）/ Codex CLI 在 Java 代码库上的评价：

"It gives me the missing IDE-level understanding of symbols, references, and refactorings, turning fragile text surgery into calmer, faster, more confident code changes."

快速安装

唯一前提：安装 uv

Serena 通过 uv 管理，不需要 pip/conda：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或
pip install uv

安装 Serena：

uv tool install -p 3.13 serena-agent

⚠️ 官方明确提示：不要从 MCP marketplace 或插件市场安装，那些版本往往过时且非最优。请务必使用上面的命令。

初始化（使用 LSP 后端）：

serena init

成功后会看到初始化完成的提示。此时 Serena 会自动在项目目录下生成配置。

初始化（使用 JetBrains 后端）：

serena init -b JetBrains

然后在 IDE 里安装对应插件（免费试用）：https://plugins.jetbrains.com/plugin/28946-serena/

为客户端配置 MCP 连接：

不同的 Agent 客户端有不同的配置方式，完整指南见官方文档：https://oraios.github.io/serena/02-usage/030_clients.html

典型思路是：将 serena 命令作为 MCP 服务器启动，客户端通过命令行参数或 HTTP 模式连接。

核心用法

Serena 通过 MCP 协议暴露以下工具类别（以 LSP 后端为例）：

检索类

工具 功能
find_symbol 在项目中按名称找符号（函数/类/变量）
symbol_overview 查看文件的符号大纲（类结构、函数列表）
find_referencing_symbols 找所有引用了某符号的地方
find_declaration 跳转到符号声明位置
find_implementations 找接口/抽象类的所有实现
query_external_projects 查外部依赖中的符号（需要源码）
diagnostics 获取代码诊断信息（lint/类型错误）

编辑/重构类

工具 功能
rename 符号重命名（影响所有引用，自动原子化）
replace_symbol_body 替换符号的函数体
insert_after_symbol 在符号后插入代码
insert_before_symbol 在符号前插入代码
safe_delete 安全删除（先确认无引用）

⚠️ rename（跨文件重命名）和 move（移动符号/文件/目录）是 JetBrains 插件独有功能，LSP 后端 rename 仅支持符号级。

实用工具类

当 Serena 独立使用（非 Claude Code 等自带文件工具的 Agent）时，这些工具可用：

  • search_for_pattern — 正则搜索
  • replace_content — 基于正则的内容替换
  • list_dir / find_file — 目录浏览与文件搜索
  • read_file — 读取文件片段
  • execute_shell_command — 运行构建/测试/lint 命令

在 Claude Code / Codex 环境中，这些通常被禁用，避免功能重叠。

内存系统

Serena 自带一个轻量内存系统，支持跨会话、跨用户、跨项目共享知识，适合和 Agent 的 AGENTS.md 配合使用：

# serena.yaml 配置示例
memory:
  enabled: true
  backend: file  # 或 other-backed
  path: .serena/memory

配置层级

Serena 支持多层级可组合配置（从全局到执行上下文）：

# 全局配置 ~/.serena/config.yaml
global:
  backend: LSP
  language: en

# 项目本地配置 ./serena.yaml（覆盖全局）
project:
  backend: JetBrains

# MCP 启动命令级配置
serena --config-mode=strict

典型适用场景

1. 大型代码库维护（万人开源项目、企业 monorepo）

当代码库有上百个文件、复杂的模块依赖时，Agent 如果只靠 grep 搜索，很容易改错或漏改。Serena 让 Agent 精确理解符号关系，跨文件重构安全可靠。

2. 多语言 monorepo 开发

Serena 的 LSP 后端支持 40+ 语言，适合多语言项目（前端 TypeScript + 后端 Go + Python 混写），无需切换工具。

3. 持续集成的 AI 代码审查

Agent 可用 diagnostics 工具批量检查代码质量，配合 CI pipeline 自动输出报告。

4. JetBrains 用户的深度重构

如果团队使用 IntelliJ / PyCharm，JetBrains 插件后端提供 rename（符号+文件+目录）、move、inline 等高级重构，能力最完整。

坑与注意

  1. 不要从 MCP marketplace 安装：官方明确警告 marketplace 版本过时。请务必用 uv tool install 手动安装。

  2. LSP 后端的 rename 有局限：仅支持符号级rename，不支持文件/目录 rename；JetBrains 插件无此限制。如需完整重构能力，请用 JetBrains 后端。

  3. 语言支持因后端而异：LSP 后端对部分语言（如 Kotlin、Ruby）的 find_implementations 支持有限，具体见：https://oraios.github.io/serena/01-about/020_programming-languages.html

  4. 磁盘空间消耗：Serena 在初始化时可能需要为语言服务器下载索引，建议确保 5GB+ 可用空间。

  5. JetBrains 插件需要付费：免费试用可用，但长期使用需购买 JetBrains 许可证。

  6. uv 最低 Python 版本：要求 Python 3.13，使用前确认版本：python --version。

  7. find_declaration 对外部依赖支持有限：声明在外部包里的符号，LSP 通常无法定位。

与同类对比

工具 定位 后端 多语言 特色
Serena Agent 的 IDE（符号级） LSP / JetBrains 40+ 专为 Agent 设计，符号语义最完整
Cody (Sourcegraph) 代码智能 自有 LLM 任意 强在代码解释和问答，非重构
Continue (VS Code) IDE 插件 多模型 任意 通用代码助手，非专注 Agent 场景
Aider 终端 AI 编程 多模型 任意 专注 humans，弱符号语义
Claude Code 内置工具 Agent 基础 — — 有文件/Rename，但无符号级引用理解

核心差异：Serena 是目前唯一一个专门为 AI Agent 设计、以符号语义操作为核心的 MCP 工具包；其他工具主要面向人类开发者，Agent 使用时效率和准确性均不如 Serena。

一句话推荐结论

如果你用 Claude Code / Codex / Copilot CLI 处理超过 10 个文件的代码库，Serena 是目前最值得安装的 MCP 工具，它把 Agent 的"文本替换"升级为真正的"符号重构"，实测可以将复杂重构的 token 消耗和错误率大幅降低。