企业官网建设流程全解析

Serena CLI实战指南：3步跑通AI代码助手

【免费下载链接】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 是一个面向编程的 MCP 工具包，serena 命令行负责在一行命令里把 MCP 服务器拉起来，让 AI 助手能检索、修改你项目里的代码符号。本文从第一次启动讲起，把启动、行为微调、代码索引三件事一次跑通。

30秒认识：它负责什么，不负责什么

上手前先划清边界，避免用错地方：

一条命令启动MCP服务器

想把 AI 接入你的项目，这是最短路径。装好uv tool install -p 3.13 serena-agent并执行serena init生成全局配置后，在项目根目录启动：

serena start-mcp-server --project .

默认走 stdio 传输、desktop-app上下文。启动后命令会一直阻塞（stdio 在等客户端接入），这是正常的。怎么确认它真的起来了？看两点：

• 终端 stderr 会打印Initializing Serena MCP server、Starting MCP server …之类的行
• 启动时会提示日志文件位置：~/.serena/logs/<日期>/mcp_<时间>_<pid>.txt，打开它看到持续写入的日志即工作正常

若浏览器或第三方应用要远程接入，换 HTTP 传输：

serena start-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000

按任务目标微调AI行为

默认行为覆盖多数场景，遇到具体问题再落一份自定义 YAML。

收紧工具集：只读代码审查

代码审查时不该给 AI 改文件的权力。复制内置 editing 模式再剔除编辑工具：

serena mode create --from-internal editing --name readonly

执行完打印新文件路径并自动打开编辑器。把~/.serena/modes/readonly.yml改成：

prompt: null excluded_tools: - replace_symbol_body - replace_content

启动时带上：serena start-mcp-server --mode readonly --project .。如果写错模式名，启动会直接报错——这就是最直接的校验方式。

让AI回答更严谨

AI 回答发散时，给它一个严格的自定义上下文（context 管整体行为，mode 管工具集，两者互补）：

serena context create --name strict

在~/.serena/contexts/strict.yml里加：

prompt: | You are a strict code reviewer. Cite symbol names in every answer; if not found, say so.

随后serena start-mcp-server --context strict --mode readonly --project .。不想起服务器也能验证拼装结果：serena print-system-prompt --context strict --only-instructions .会直接打印系统提示词。

按客户端匹配现成上下文

不同 AI 客户端的用法习惯不一样，Serena 内置了一批现成上下文：

serena context list

输出是名称加存储位置列表，内置的标注(internal)（以实际输出为准）。挑一个用：serena start-mcp-server --context claude-code --project .。

让Serena读懂你的代码：生成配置、索引、体检

符号索引是 AI"认识代码"的地基——它经语言服务器收集类、函数等符号并缓存。

① 生成项目配置：

serena project create . --ls python

输出形如 "Generated project with language servers {python} at ..."，文件落在项目根目录的.serena/project.yml，同时把项目注册进全局配置。

② 跑索引：

serena project index

有进度条，结束后按语言汇总文件数。符号缓存存在项目的.serena/目录下，具体缓存路径会在命令结尾打印。若有失败文件，错误清单写在.serena/logs/indexing.txt。

③ 健康检查：

serena project health-check

它会真实执行符号检索、引用查找等工具验证语言服务器是否可用，报告写入.serena/logs/health-checks/。AI 找不到符号时先跑这个。

调试单个文件：serena project index-file src/main.py -v，会逐条打印符号名、行号与类型，并说明保存到了哪个缓存目录。

任务卡：三个高频场景

卡片1 新项目接入目标：把新仓库交给 AI

serena project create . --ls python serena project index serena start-mcp-server --project .

预期结果：.serena/project.yml生成，索引汇总打印，服务器阻塞运行并在日志里持续输出。

卡片2 代码审查目标：AI 只读不写

serena mode list # 确认 readonly 在列 serena start-mcp-server --mode readonly --context strict --project .

预期结果：AI 没有编辑类工具，回答受 strict 上下文约束。

卡片3 故障排查目标：确认是不是项目配置的问题

serena project health-check serena project is_ignored_path venv/

预期结果：体检报告写入.serena/logs/health-checks/；第二条命令直接告诉你这个路径是否被项目配置忽略。

排障速查表

进阶方向

1. 看 mode/context 的加载与覆盖规则：src/serena/config/context_mode.py
2. 看工作流工具的实现：src/serena/tools/workflow_tools.py
3. 完整配置项说明：docs/02-usage/050_configuration.md

现在到你的项目根目录执行serena project create . --ls python，索引跑完后 AI 才算真正认识你的代码。

【免费下载链接】serenaA powerful MCP toolkit for coding, providing semantic retrieval and editing capabilities - the IDE for your agent项目地址: https://gitcode.com/GitHub_Trending/ser/serena