实用提示：Serena MCP——为你的AI编程工具赋予IDE级功能
《实用笔记》操作指南：Serena MCP——为人工智能编程工具赋予 IDE 级功能：针对采用该模式的团队提供的契约、校验机制以及可直接插入的代码模块。
可将此内容视为《Serena MCP：为你的 AI 编程工具赋予 IDE 级的智能功能》中理念面向操作员的优化版本：清晰的阶段划分、有序的代码模块以及能在交接过程中保留的恢复说明。在扩大范围之前，最好先将“概览”阶段视为一个可量化的基准，记录一份最佳操作案例、一个故障实例以及对应的回滚说明。同时记录正常流程与异常恢复路径，重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。
什么是 Serena MCP？
对于“什么是 Serena MCP 阶段”这一问题，在修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。应在网关处进行身份验证，在数据层再次授权——仅凭承载令牌并不足以界定租户边界。
问题所在：当前 AI 工具如何处理代码
在“AI面临的问题”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，并拒绝默许的半完成状态。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
+----------------------------+-------------------------------------+--------------------------------------------+
| Task | Without Serena | With Serena |
+============================+=====================================+============================================+
| **Semantic search** | Text match on "auth" - returns | Returns `authenticateUser()`, |
| "find auth functions" | false positives, misses functions | `login()`, `verifyCredentials()` |
| | named `verifyCredentials` | with file locations and line numbers |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Go to definition** | Searches files for "User" and | Jumps directly to the `User` |
| "show me the User schema" | "schema" - returns every reference | class/interface definition with |
| | | full import tree |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Find references** | Text search for "PaymentProcessor" | Returns all usages with context: |
| "where is | - misses dynamic usages | imports, instantiations, method calls |
| PaymentProcessor used?" | | |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Cross-file refactoring** | Text search and replace - misses | Semantic rename via LSP - updates |
| "rename UserService | string interpolations or aliased | every reference correctly across |
| to AccountService" | imports, breaks things | the entire codebase |
+----------------------------+-------------------------------------+--------------------------------------------+
Serena如何改变游戏规则
在实施“Serena如何改变工作流程”这一方案时，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解这些成本信息，可避免在流程从演示环境转向共享环境时出现意外费用。应在网关处进行身份验证，并在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。在实施“Serena如何改变工作流程”这一方案时，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。需同时记录正常流程和故障恢复流程的详细信息。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的功能。
内存系统
在处理“内存系统”阶段时，首先写下相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤出错时，错误应指向单一责任模块，而非复杂的流程链。 需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。没有这些记录，调试过程将会浪费大量时间。
管理控制面板
在处理“管理控制台”阶段时，首先写下相关契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合约定。 将此阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。 需记录每次调用的工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无休止的循环，耗费大量时间。
场景选择：为你的客户端挑选合适的模式
在“选择合适上下文”阶段工作时，首先需写下接口规范：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。 为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试循环将会耗费大量时间。 在“选择合适上下文”阶段工作时，首先需写下接口规范：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。
+---------------------+------------------------------+------------------------------------------------+
| Context | Designed for | What it does |
+=====================+==============================+================================================+
| `desktop-app` | Claude Desktop, general use | **Full toolset** - everything Serena offers. |
| | | Use this when the client has no built-in |
| | | coding capabilities. This is also the right |
| | | choice for a shared Docker instance serving |
| | | multiple different clients. |
+---------------------+------------------------------+------------------------------------------------+
| `claude-code` | Claude Code | Disables tools that overlap with Claude |
| | | Code's built-in capabilities (file edits, |
| | | shell commands, etc.) to avoid conflicts. |
| | | Single-project context. |
+---------------------+------------------------------+------------------------------------------------+
| `ide` | VS Code, Cursor, Cline, Kilo | Generic IDE augmentation - focuses on |
| | | semantic tools, assumes the IDE already |
| | | handles basic file operations. |
| | | Single-project context. |
+---------------------+------------------------------+------------------------------------------------+
| `agent` | Agno, autonomous agents | Broader autonomy for agents that drive the |
| | | full workflow independently. |
+---------------------+------------------------------+------------------------------------------------+
| `codex` | OpenAI Codex | Optimized for Codex's tool calling format. |
+---------------------+------------------------------+------------------------------------------------+
| NOTE: The `claude-code` and `ide` contexts are **single-project**: when you pass a project |
| path at startup, those contexts lock down to only the tools relevant to that project and |
| disable the project-switching tool entirely (since you won't need it). |
+---------------------+------------------------------+------------------------------------------------+
安装
将安装阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向具体的责任主体，而非复杂的流程链。 使用结构清晰、带有明确副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变状态。
标准安装
将标准安装阶段视为可度量的对象最为有效。在扩大范围之前，需记录一份成功的案例、一个失败案例以及回滚说明。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，绝不允许默许部分完成的情况。 使用具有严格结构定义和明确副作用标识的工具。主机需要在自动批准之前知晓哪些操作会改变状态。
uv tool install -p 3.13 serena-agent@latest --prerelease=allow
serena init
claude mcp add --scope user serena -- serena start-mcp-server \
--context claude-code --project-from-cwdlaude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
{
"servers": {
"serena": {
"type": "stdio",
"command": "serena",
"args": [
"start-mcp-server",
"--context", "ide",
"--project", "${workspaceFolder}"
]
}
}
}
{
"mcpServers": {
"serena": {
"command": "serena",
"args": ["start-mcp-server", "--context", "desktop-app"]
}
}
}
Docker安装
将 Docker 安装阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，需记录一份理想的操作流程、一个故障案例以及回滚说明。 在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。 应使用结构清晰且带有明确副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。 将 Docker 安装阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，需记录一份理想的操作流程、一个故障案例以及回滚说明。 需同时文档化正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品的一部分，而非后续需要补充的内容。
services:
serena:
image: ghcr.io/oraios/serena:latest
container_name: myproject-serena
restart: unless-stopped
environment:
- SERENA_DOCKER=1
ports:
- "10121:9121" # SSE endpoint
- "34282:24282" # Web dashboard
volumes:
- .:/workspace/myproject
command: >
serena start-mcp-server
--transport sse
--port 9121
--host 0.0.0.0
--context desktop-app
--project /workspace/myproject
gui_log_window: false
web_dashboard_listen_address: "0.0.0.0"
web_dashboard_open_on_launch: false
docker compose up -d serena
连接你的 AI 工具
在“连接你的 AI 工具”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。在网关处进行身份验证，在数据层再次授权——仅凭承载令牌并不足以界定租户边界。
Claude Code
在 Claude Code 阶段，修改代码之前需先定义输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功判定标准，并拒绝默许的半完成状态。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
claude mcp add serena --transport sse --url http://localhost:10121/sse
{
"mcpServers": {
"serena": {
"type": "sse",
"url": "http://localhost:10121/sse"
}
}
}
VS Code / Cursor / Windsurf
在 VS Code Cursor Windsurf 阶段，修改代码之前需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 在功能结果旁记录执行时间以及令牌或查询成本。提前显示成本可避免在流程从演示环境转向共享环境时出现意外费用。 在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。 在 VS Code Cursor Windsurf 阶段，修改代码之前需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都是产品的一部分，而非后续需要补充的功能。
{
"servers": {
"serena": {
"type": "sse",
"url": "http://localhost:10121/sse"
}
}
}
OpenCode
在处理OpenCode阶段时，首先需明确合同规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 建议使用小型、可测试的单元而非庞大的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。 需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。没有这些记录，调试过程将会浪费大量时间。
{
"mcp": {
"serena": {
"type": "remote",
"url": "http://localhost:10121/sse",
"enabled": true
}
}
}
项目配置
在处理项目配置阶段时，首先写下相关约定：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合约定。 将此阶段视为输入与验证后输出之间的契约。为相关成果命名，明确成功判定标准，杜绝无声的半完成状态。 需记录每次调用的工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。
project_name: "myproject"
languages:
- typescript # uses typescript-language-serverencoding: "utf-8"
ignore_all_files_in_gitignore: trueignored_paths:
- "node_modules"
- "dist"
- "build"
- "coverage"
- ".next"
- "out"
- ".cache"
.serena/project.yml ← commit this (shared config)
.serena/memories/ ← commit this (AI-generated project notes, useful for everyone)
.serena/cache/ ← gitignore (rebuilt per machine)
.serena/project.local.yml ← gitignore (per-developer overrides)
使用体验
在体验阶段工作时，首先需写下接口规范：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外账单。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试循环将会耗费大量时间。 在体验阶段工作时，首先需写下接口规范：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。
make serena-up # Start the Serena container
make serena-stop # Stop it
make serena-logs # Tail logs
make serena-index # Force re-index after big changes
make serena-health # Health check the workspace
总结
“最终思考”阶段若被视为可度量的工作面，效果最佳。在扩大范围之前，先记录一份优秀的处理方案、一个失败案例以及回滚说明。相比庞大的脚本，应优先选择小型且可测试的单元。当某一步骤失败时，故障应指向单一责任点，而非复杂的流程链。需使用结构明确的工具，并标注清晰的副作用信息。主机需要在自动批准之前知道哪些调用会修改状态。
运营检查清单
在处理运营检查清单阶段时，首先明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。
将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。
记录每次调用的工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试过程将会浪费大量时间。
锁定依赖版本的数值，并记录用于运行演示的镜像摘要。可重复性远比个人经验更重要。
同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都是产品不可或缺的部分，而非后续才需要补充的功能。
记录每次调用的工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试过程将会浪费大量时间。
在推广该技术栈之前，应先冻结版本，为关键流程保存标准操作记录，并明确回滚步骤。共享环境需要设置速率限制、进行租户身份验证，同时要指定专人负责密钥轮换工作。与其追求华而不实的临时演示，不如注重扎实可靠的稳定性。
关于1c6261938c06的批处理说明：不要将提供者密钥放入仓库中，设定每会话的令牌上限，并将转录内容存储在评估测试用例旁边，以便后续更换模型时仍能保持可比性。