Serena 项目源码地图基于 MCP 的编码 Agent 工具集核心架构解析【免费下载链接】serenaA powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent项目地址: https://gitcode.com/GitHub_Trending/ser/serena本文基于仓库记忆文档 .serena/memories/project_structure.md 展开系统梳理 SerenaPyPI 包名serena-agent的源码布局、核心模块职责与项目级不变量。读者将掌握Serena 各入口点CLI / MCP 服务器 / 项目服务器 / 钩子如何接线、工具层与配置层的实现位置、LSP 客户端框架与测试体系的组织方式以及贡献代码或二次开发时应遵守的约束。一、Serena 是什么Serena 是一个基于MCPModel Context Protocol的“编码 Agent IDE”它以语言服务器Language Server为驱动为编程 Agent 提供语义级代码检索、编辑与重构能力。与普通基于文本搜索/字符串替换的工具不同Serena 借助各语言官方语言服务器获得符号级symbol-level的代码理解从而支持“按符号名定位定义、按符号引用批量改名、按函数体位置插入/替换代码”等结构化操作。从其核心描述见 pyproject.toml可以看到项目定位A powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent整个仓库是一个monorepo式布局wheel 打包时同时包含三个顶层 Python 包serenaAgent 与工具核心、interprompt提示词模板库、solidlspLSP 客户端框架见 pyproject.toml 的 hatch 构建配置[tool.hatch.build.targets.wheel] packages [src/serena, src/interprompt, src/solidlsp]二、源码地图逐模块导航记忆文档给出了一张“Source map”下面结合源码逐一展开说明每个目录的真实职责。2.1src/serena/—— Agent、MCP 服务器、工具与项目/配置层这是 Serena 的主包所有面向用户的编排逻辑都在这里。入口与接线entrypoints/wiring文件职责agent.py核心SerenaAgent持有工具集ToolSet、活动项目、活动模式modes负责系统提示词生成、项目激活、任务调度与工具调用记录mcp.pyMCP 服务器封装将内部Tool实例转换为 MCP 工具并注册到 FastMCP支持 stdio / sse / streamable-http 三种传输project_server.py本地 HTTP 项目服务器供其他进程按“项目名 工具名 JSON 参数”远程调用工具query_project接口cli.pyClick 命令行入口serena init/setup/start-mcp-server/...等子命令hooks.pyClaude Code 等客户端的钩子命令serena-hooks入口见hook_commands这些文件正是记忆文档中所说的“entrypoints/wiring”——它们本身不含具体功能实现而是把底层能力组装成对外可用的服务。工具层src/serena/tools/工具是 Agent 与底层能力之间的薄封装每个工具类都继承自 tools_base.py 中的Tool基类第 142 行class Tool(Component)。基类提供了统一的名字推导get_name、工具描述与 docstring 提取get_tool_description/get_apply_docstring、max_answer_chars截断、参数别名get_param_aliases以及 MCP 兼容的apply_ex执行入口。按功能划分工具模块包括memory_tools.py —— 记忆读写write_memory/read_memory/ 列表 / 重命名 / 编辑symbol_tools.py —— 符号级检索与编辑按name_path查找符号、查引用、查实现、替换函数体、重命名符号file_tools.py —— 文件读写、多文件正则/字面量替换含occurrence_ids精确指定替换点workflow_tools.py —— 工作流编排完成任务、会话查询等query_project_tools.py —— 跨进程项目查询经由 project_serverconfig_tools.py —— 配置读取与项目注册cmd_tools.py —— 执行 shell 命令jetbrains_tools.py —— 当语言后端为 JetBrains 插件时替代部分 LSP 工具配置层src/serena/config/文件职责serena_config.py全局SerenaConfig与项目级ProjectConfig/RegisteredProject配置加载、默认值、项目注册表持久化、语言后端LSP vs JetBrains判定context_mode.pySerenaAgentContext上下文与SerenaAgentMode模式的 YAML 加载与注册表管理client_setup.py各客户端Claude Code、Codex、Copilot 等的 MCP 服务器一键配置serena setup的后端实现记忆文档提到的resources/config/contexts/*.yml与resources/config/modes/*.yml在本仓库中对应 src/serena/resources/config/contexts/ 与 src/serena/resources/config/modes/。实测该目录下包含 16 个内置上下文定义agent.yml、claude-code.yml、codex.yml、chatgpt.yml、vscode.yml、ide.yml等以及context.template.yml模板和 10 个内置模式定义editing.yml、planning.yml、interactive.yml、one-shot.yml、no-memories.yml等以及mode.template.yml模板。目录路径常量定义在 constants.py默认上下文为desktop-app同文件第 24 行。符号编辑与 LS 生命周期code_editor.py —— 符号编辑执行器包含三种实现基于文件系统的CodeEditor、基于 LSP 文本编辑的LanguageServerCodeEditor、基于 JetBrains 插件的JetBrainsCodeEditor。支持按符号替换函数体replace_body、符号前后插入insert_after_symbol/insert_before_symbol、按行插入/删除、符号删除与重命名。symbol.py —— 符号数据模型与检索器。核心是LanguageServerSymbolRetriever提供find/find_unique/find_referencing_symbols/find_implementing_symbols/get_symbol_overview/get_symbol_diagnostics等语义查询以及符号的分组GroupedSymbolDict与name_path匹配NamePathPattern支持子串匹配。ls_manager.py —— 语言服务器生命周期管理LanguageServerManager负责创建、启动、重启、停止各语言的SolidLanguageServer按文件后缀路由到合适的 LS并支持缓存保存与文件系统变更同步sync_file_system_changes。辅助设施dashboard.py —— 基于 Flask 的 Web 仪表盘日志查看、工具调用统计、配置概览、记忆管理、语言服务器增删、新闻公告等 REST 接口另含 pywebview 桌面查看器与系统托盘tray管理。gui_log_viewer.py —— GUI 日志查看器与MemoryLogHandler内存环形日志缓冲供仪表盘拉取。prompt_factory.py 与 generated/generated_prompt_factory.py —— 提示词工厂前者是手写入口后者是从模板自动生成的代码由 scripts/gen_prompt_factory.py 重新生成。从generated_prompt_factory.py的类定义可看到其产物形态create_system_prompt、create_connection_prompt、create_onboarding_prompt、create_cc_system_prompt_override等。analytics.py —— token 估算tiktoken / Claude API / 平均字符数三种估算器与工具调用用量统计。task_executor.py —— 任务队列执行器支持超时、取消与完成回调。agno.py —— 可选的 agno Agent 集成agnoextra 依赖把 Serena 工具包装成 agno 的Function。jetbrains/ —— JetBrains 语言后端jetbrains_plugin_client.py与 IDEA 插件通信的 HTTP 客户端含符号查找/引用/类型层级/重命名/内联/安全检查等、jetbrains_types.pyDTO 类型、launch_coordinator.py启动并等待插件服务器就绪。memories/ —— 记忆子系统memory_manager.py记忆文件的读写、列表、重命名、引用传播、memory_reference_analysis.py记忆间引用完整性校验与自动加前缀修复。2.2src/solidlsp/—— LSP 客户端框架solidlsp是 Serena 的语言服务器基础设施与具体的 Agent 逻辑解耦ls.py / ls_process.py / ls_request.py —— 语言服务器的进程启动、请求/响应模型ls_config.py ——LanguageServerId枚举与服务器配置注册lsp_protocol_handler/ —— 基于 pygls 的 LSP 协议处理器server.py、lsp_requests.py、lsp_types.py、lsp_constants.pylanguage_servers/ ——78 个按语言拆分的服务器适配模块每个文件对应一门语言/工具链clangd_language_server.py、gopls.py、rust_analyzer.py、pyright_server.py、basedpyright_server.py、ruby_lsp.py、typescript_language_server.py、omnisharp.py、scala_language_server.py等dependency_provider.py / settings.py —— 语言服务器依赖下载/路径解析与运行时设置util/ ——subprocess_util.py跨平台子进程参数、cache.py、zip.py等通用工具。2.3src/interprompt/—— 提示词模板库interprompt是一个独立的提示词模板库jinja 模板 多语言提示词 prompt 工厂代码注释及.syncCommitId.*文件仓库中存在 src/interprompt/.syncCommitId.remote 与 src/interprompt/.syncCommitId.this表明它从外部仓库同步而来并用提交 ID 记录同步点。generated_prompt_factory.py实际上就是把interprompt的模板渲染成 Python 函数。2.4 测试与脚本test/serena/ —— Agent 核心的 pytest 套件test_symbol_editing.py符号编辑配套 syrupy 快照 test/serena/snapshots/test_symbol_editing.ambr、test_file_tools.py、test_memories_manager.py、test_mcp.py、test_dashboard.py等。test/solidlsp/ —— 按语言划分的 LSP 集成测试每个语言一个目录ada/、go/、rust/、typescript/…。这些测试由 pytest 标记marker按语言门控[tool.pytest.ini_options].markers在 pyproject.toml 中定义了 clojure / crystal / python / go / java / rust / typescript / cpp / scala / solidity 等 50 个语言标记每个标记说明对应语言服务器的运行前提。test/resources/repos/ /—— 语言服务器测试所用的固定夹具项目fixture repos例如typescript/test_repo。注意该目录被 ty 类型检查与 codespell 明确排除见 pyproject.toml 与 L390因为其中包含第三方锁定文件与压缩代码。scripts/ —— 开发工具脚本gen_prompt_factory.py重新生成提示词工厂、print_tool_overview.py打印工具总览、profile_tool_call.py工具调用性能剖析、agno_agent.py、build_news_json.py、mcp_server.py、memory_graph.py等。docs/ —— Jupyter Book 文档源构建命令为poe doc-build定义于 pyproject.toml内部串联 autogen_docs → create_toc → jupyter-book config → sphinx-build。三、项目级不变量Project-wide invariants记忆文档最后一部分给出了三条必须遵守的“不变量”它们与源码/配置一一对应是理解打包与运行方式的关键。3.1 PyPI 包名与 wheel 内容PyPI 包名为serena-agent版本当前为1.7.1.dev0见 pyproject.tomlwheel 包含serena、interprompt、solidlsp三个包hatchpackages配置。3.2 Python 版本范围与精确锁依赖要求3.11, 3.15pyproject.tomlclassifier 声明了 3.11–3.14所有依赖在pyproject.toml中精确固定版本。其原因是uvx从 git 安装时会忽略 lockfile因此必须把版本精确 pin 在 pyproject 中才能保证可复现。这一注释直接出现在依赖块里第 43-44 行Exact pins because uvx installs from git, ignoring the lock file.。例如mcp1.28.1、pydantic2.12.5、anthropic0.117.0、pygls2.1.1、flask3.1.3等。可选 extradevpytest、ruff、ty、sphinx/jupyter-book 文档链等、agno、google。3.3 命令行入口点[project.scripts]pyproject.toml注册了三个可执行命令[project.scripts] serena serena.cli:top_level serena-agent serena.cli:top_level serena-hooks serena.hooks:hook_commandsserena/serena-agent→ cli.py 的top_level。实测该 Click 应用包含以下子命令族init初始化可选--language-backend lsp|jetbrainssetup为指定客户端配置 MCP 服务器start-mcp-server启动 MCP 服务器支持--transport stdio|sse|streamable-http、--context、--default-modes/--added-modes、--host/--port、--enable-web-dashboard、--open-web-dashboard、--log-level、--trace-lsp-communication、--tool-timeout等print-system-prompt打印系统提示词--only-instructions、--modesstart-project-server启动项目服务器--host/--port/--log-leveldashboard-viewer以独立窗口打开仪表盘modes list/create/edit/delete与contexts list/create/edit/delete管理自定义模式与上下文 YAMLprojects create/index/is-ignored-path/index-file/health-check注册项目、索引、健康检查tools list/description列出工具与查看工具描述memories initialize/list/read/write/delete/rename/edit/check/auto-prefix-references完整记忆管理prompts list/create-override/edit-override/list-overrides/delete-override/print-prompt-template/print-cc-system-prompt-override提示词模板覆盖管理。serena-hooks→ hooks.py 的hook_commands为支持钩子的客户端提供activate/cleanup/remind/auto-approve/reset等操作钩子内部会基于工具调用频率在“符号化工具优先”与普通工具之间做提醒/放行决策见 hooks.py 中PreToolUseHook相关实现。四、从源码结构看 Serena 的分层架构综合上述源码地图可以推断出 Serena 的整体分层┌─ 对外接口层 ─────────────────────────────┐ │ CLI (cli.py) │ MCP Server (mcp.py) │ │ Project Server (project_server.py) │ │ Hooks (hooks.py) │ Web Dashboard │ └───────────────┬────────────────────────┘ ┌───────────────▼────────────────────────┐ │ Agent 编排层 (agent.py) │ │ ToolSet / Modes / 系统提示词 / 项目激活 │ └───────────────┬────────────────────────┘ ┌───────────────▼────────────────────────┐ │ 工具层 tools/ (继承 tools_base.Tool) │ │ 记忆 / 符号 / 文件 / 配置 / 命令 / 查询 │ └───────────────┬────────────────────────┘ ┌───────────────▼────────────────────────┐ │ 能力实现层 │ │ symbol.py 检索 │ code_editor.py 编辑 │ │ ls_manager.py │ memories/ │ jetbrains/ │ └───────────────┬────────────────────────┘ ┌───────────────▼────────────────────────┐ │ solidlsp 语言服务器框架78 个适配器 │ └────────────────────────────────────────┘其中值得注意的几个“职责单一”设计点工具类只做参数校验与结果格式化真正的语义能力符号查找、文本替换、诊断获取都在symbol.py、code_editor.py、text_utils.py等实现层工具层是薄封装。例如file_tools.py中的多文件替换最终调用text_utils.MultiFileContentReplacer见 text_utils.py完成 occurrence 匹配与 diff 渲染。编辑后诊断回读tools_base.py中存在DiagnosticsContext之类的上下文管理器从EditingToolWithDiagnostics推断配合 ls_diagnostics.py 在符号编辑前后对比诊断快照让 Agent 知道一次编辑是否引入了新的编译错误——这体现了“语义编辑 校验闭环”的设计。双语言后端抽象LanguageBackend枚举LSP / JetBrains定义于serena_config.py决定同一套工具名映射到哪种实现——LSP 后端走solidlspLanguageServerSymbolRetrieverJetBrains 后端走jetbrains_plugin_client.py的 HTTP 接口工具层通过get_lsp_tool_class_replacements做替换。这让“IDE 中的 Agent”既能独立工作LSP也能深度融入 JetBrains IDE插件。五、给贡献者与二次开发者的实践指引结合记忆文档与仓库实况参与本项目的正确姿势如下定位代码先对照本篇文章的源码地图找到所属层。改工具行为 → src/serena/tools/改符号检索 → symbol.py改语言服务器适配 → src/solidlsp/language_servers/改提示词模板 →src/interprompt/或重新生成generated_prompt_factory.py运行 scripts/gen_prompt_factory.py。写测试核心逻辑测试放 test/serena/语言服务器集成测试放test/solidlsp/ /并给测试打上对应语言的 pytest 标记marker 注册见 pyproject.toml。符号编辑类快照测试使用 syrupy--snapshot-update更新快照。跑检查poe testpytest、poe lint/poe formatruff、poe type-checkty。注意 poe 的 executor 被显式配置为simple而非uv——注释说明这是因为 Serena MCP 服务器运行时会占用 Python 环境用uv执行器会尝试重建环境导致失败pyproject.toml。遵守设计不变量不要在配置中放宽 Python 版本范围、不要引入未 pin 的依赖版本、新增工具类时继承tools_base.Tool并在对应工具模块注册新增语言时在solidlsp/language_servers/添加适配器并在ls_config.py注册LanguageServerId。六、总结.serena/memories/project_structure.md本质上是 Serena 的“项目核心速查表”它用一张源码地图 三条不变量把 78 个语言服务器适配器、数十个工具、三层 MCP/CLI/钩子入口组织进一个清晰的认知框架。本文在此基础上逐文件验证并补充了模块职责、关键类与配置路径可作为阅读源码、提交贡献或基于 Serena 构建二次开发方案时的第一份索引。若要继续深入推荐从 agent.py编排核心与 symbol.py语义检索核心读起并结合 test/solidlsp/ 下的语言级测试理解端到端行为。【免费下载链接】serenaA powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent项目地址: https://gitcode.com/GitHub_Trending/ser/serena创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
