/ 目錄 / 演練場 / Serena
● 社群 oraios ⚡ 即開即用

Serena

作者 oraios · oraios/serena

Serena 將語言伺服器支援的語義搜尋和符號編輯附加到您的代理上 - 因此重命名/重構/查找引用實際上可以跨巨大的程式碼庫工作。

Serena 是「您的代理商的 IDE」。 它不再是 grep 檔案和祈禱,而是使用 40 多種語言的真正 LSP 後端來回答符號級問題:“這個函數在哪裡調用?”,“類型層次結構是什麼?”,“在使用該符號的所有地方重命名它”。 然後,它提供符號編輯工具,以便代理可以替換函數體、安全刪除符號或插入與 AST 節點相關的程式碼。 記憶系統會在整個會話中保留上下文——克勞德從上週中斷的地方繼續。

為什麼要用

核心特性

即時演示

實際使用效果

serena.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "serena",
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "serena": {
      "command": {
        "path": "uvx",
        "args": [
          "--from",
          "serena-agent",
          "serena",
          "start-mcp-server",
          "--context=claude-desktop"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add serena -- uvx --from serena-agent serena start-mcp-server --context=claude-desktop

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: Serena

在 1M 行程式碼庫中尋找函數的每個呼叫者

👤 在成熟的大型倉庫中工作的工程師 ⏱ ~10 min intermediate

何時使用: 您需要一個完整、正確的呼叫者清單 - grep 會給出誤報(註解、字串、其他作用域中類似名稱的函數)並錯過重載。

前置條件
  • 紫外線安裝 — 捲曲-LsSf https://astral.sh/uv/install.sh |噓
  • 專案以 Serena 的 LSP 支援的語言打開 — 大多數主流語言都是開箱即用的
步驟
  1. 打開專案
    使用 Serena 開啟 /abs/path/to/repo。 確認LSP索引建立。✓ 已複製
    → Serena 報告專案根目錄和載入的 LSP
  2. 尋找符號參考
    尋找“PaymentService.chargeCustomer”的每個呼叫站點。 包括重載和覆蓋,排除測試。✓ 已複製
    → 精確的文件:行列表,註解/字串沒有誤報
  3. 總結影響
    按模組對呼叫站點進行分組。 對於每個群組,請告訴我呼叫者如何處理返回值。✓ 已複製
    → 模組分組的敘述,而不是平面列表

結果: 在你接觸改變之前,你就清楚知道它會影響什麼。

注意事項
  • 一些多語言儲存庫需要多個 LSP — 如果語言不共享伺服器,則按子項目啟動 Serena
搭配使用: filesystem · github

重新命名公共 API 符號而不破壞依賴項

👤 庫/框架維護者 ⏱ ~15 min intermediate

何時使用: 您要重新命名可能在文件外部使用的函數或類別 - 您需要 LSP 精確的重命名,而不是文字替換。

前置條件
  • 清理 git 樹 — git status clean 這樣你就可以在提交之前查看差異
步驟
  1. 試運行重命名
    在 src/api/users.ts 中將 getUser 重新命名為 fetchUserById。 使用 Serena 的符號重新命名。 預覽差異 - 尚未套用。✓ 已複製
    → 每個受影響文件的差異預覽
  2. 審查並申請
    應用重命名。 告訴我 Serena 標記為不明確的任何文件。✓ 已複製
    → 已套用重新命名、歧義清單(如果有)
  3. 運行套件
    運行測試並報告失敗,重點是引用舊名稱的任何內容。✓ 已複製
    → 測試綠色,或精確的失敗列表

結果: 整個儲存庫的重命名都是乾淨的,包括公共重新匯出、index.ts 桶和過時的 JSDoc 引用。

注意事項
  • LSP 重新命名不會捕獲動態存取 (obj['getUser']) — 符號重命名後,對舊名稱字串執行一次 grep; Serena 會顯示任何無法靜態解析的內容
搭配使用: filesystem · git

替換函數體而不影響周圍程式碼

👤 工程師在大文件中進行外科手術編輯 ⏱ ~10 min intermediate

何時使用: 您希望重寫“calculatePrice”的實現,但要準確保留其簽名和 JSDoc。 整個文件重新生成是錯誤的工具。

步驟
  1. 瞄準符號
    在 src/billing/pricing.ts 中,找到「calculatePrice」。 僅顯示目前正文(不顯示簽名或文件)。✓ 已複製
    → 僅正文片段
  2. 更換本體
    僅將主體替換為處理免稅情況的版本。 保持簽名和 JSDoc 完整。✓ 已複製
    → 使用瑟琳娜的替換身體工具; diff 中的簽名未更改

結果: 最小的、可審查的差異—沒有偶然的空格/格式變化。

注意事項
  • 代理回退到全文件寫入 — 明確指示“使用 Serena 的符號替換,而不是 write_file”
搭配使用: filesystem

一小時內進入不熟悉的程式碼庫

👤 新進員工、承包商或 OSS 貢獻者 ⏱ ~60 min beginner

何時使用: 您剛剛克隆了一個包含 500 個檔案的儲存庫,並且需要一張心智圖才能做出貢獻。

步驟
  1. 取得架構
    使用 Serena 開啟此儲存庫。 建構地圖:頂級模組、它們的公共導出和主要入口點。 以「arch_overview」的形式儲存到 Serena 記憶體中。✓ 已複製
    → 結構化概覽;建立記憶筆記
  2. 遵循用戶請求
    追蹤使用者點擊 POST /orders 時發生的情況。 讓我按順序瀏覽每個文件。✓ 已複製
    → 請求 → 處理程序 → 服務 → 儲存庫跟踪,以及 Serena 的參考查找
  3. 注意陷阱
    將任何看起來不尋常的模式(自訂裝飾器、魔術常數)作為「陷阱」儲存到記憶體中。✓ 已複製
    → 為下一次會話保存記憶筆記

結果: 在下一次課程中,克勞德已經熟悉了地圖——無需重新加入成本。

搭配使用: filesystem · github

組合

與其他 MCP 搭配,撬動十倍槓桿

serena + filesystem

Serena 用於符號感知導航 + 用於任意 I/O 的檔案系統

使用 Serena 尋找身份驗證模組,然後使用檔案系統為該資料夾編寫新的自述文件。✓ 已複製
serena + github

使用 Serena 進行本地重構;透過 GitHub MCP 推送分支並開啟 PR

使用 Serena 重新命名 ApiClient → HttpClient,然後開啟一個標題為「refactor(api): rename ApiClient」的 PR。✓ 已複製
serena + git

在提交之前查看 Serena 生成的 diff

顯示 Serena 重新命名後的 git diff。 如有任何可疑之處,請在我們提交之前​​標記出來。✓ 已複製
serena + context7

庫感知重構 - Serena 用於本地移動,Context7 用於匹配 v-next API

將此檔案遷移到 Next.js 15 模式。 使用新 API 的 Context7 和 Serena 以符號方式套用變更。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
find_symbol name: str, scope?: str 透過名稱以 LSP 精度定位類別/函數/var free (local)
find_references symbol: ref 符號的所有呼叫者/用法;比 grep 好得多 free
get_symbols_overview path: str 在決定閱讀內容之前文件/模組大綱 free
rename_symbol symbol: ref, new_name: str, dryRun?: bool 整個專案的安全重命名 free
replace_symbol_body symbol: ref, new_body: str 在不觸及簽名的情況下交換函數/方法體 free
insert_before_symbol / insert_after_symbol symbol: ref, code: str 新增錨定到 AST 節點的裝飾器、導入或同級聲明 free
move_file / move_dir src: str, dst: str 重新定位程式碼並讓 LSP 修復每個導入器 free
write_memory / read_memory key: str, value?: str 跨會話保留專案上下文(架構圖、陷阱) free
search_pattern regex: str, path: str 當目標不是命名符號(字串文字、模式)時的回退 free

成本與限制

運行它的成本

API 配額
無 — 本地 LSP
每次呼叫 Token 數
小 - Serena 返回符號範圍的片段,而不是整個文件
費用
自由的
提示
在大文件上,優先使用 get_symbols_overview + find_symbol 而不是 read_text_file — 您花費的令牌數量減少了 10 倍,並且獲得了更好的信號

安全

權限、密鑰、影響範圍

憑證儲存: 無 — 一切都在本地運行
資料出站: 預設情況下無。 Serena 可以執行 shell 指令(停用);在授予 Claude 寫入權限之前,請先查看工具清單。
切勿授予: Access to directories outside your project

故障排查

常見錯誤與修復

LSP 啟動失敗/未找到符號

檢查專案語言的語言伺服器是否已安裝(例如,Python 的 Pyright,TS 的 TypeScript-Language-Server)。 Serena 日誌列出了它正在使用的 LSP。

驗證: Run Serena in verbose mode; confirm LSP handshake succeeded
重命名跳過了一些文件

通常表示文件不在 LSP 的工作區。 確認專案根目錄是 monorepo 根目錄,而不是子包。

驗證: Ask Serena to list its workspace roots
代理退回到原始檔案寫入而不是 Serena 工具

在 CLAUDE.md 中明確規定:「對於符號操作,請務必使用 Serena 的工具;切勿在現有 .py/.ts 檔案上 write_file'

驗證: Re-run the task; inspect tool_use calls in the trace
uvx:未找到指令

先安裝uv:curl -LsSf https://astral.sh/uv/install.sh |噓;然後重新開啟你的終端

驗證: uvx --version

替代方案

Serena 對比其他方案

替代方案何時用它替代權衡
JetBrains MCP您已經使用 JetBrains IDE 並希望代理程式驅動其重構工具需要開放的IDE進程;較重
filesystem您不需要符號意識 - 只需讀取/寫入文件沒有語義搜尋或安全重命名
mcp-language-server您想要一個更小的僅 LSP 包裝器,而不是 Serena 的內存 + 外殼層進階工具較少;您自己編寫工作流程

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills