Ace-Tool & Serena 协作指南
两个 MCP 工具的协作流程，用于高效理解和导航代码库。
工具定位
工具 核心能力 适用场景
Ace-Tool 语义搜索、自然语言查询 不知道代码在哪、探索性搜索
Serena 符号级精确定位、LSP 集成 知道符号名、需要精确引用
核心约束（MUST）
-
Serena 仅用于检索/定位，严禁修改代码
-
Ace-Tool 的 search_context 用于语义搜索
-
两个工具都是只读工具，不执行任何写操作
协作流程
场景 1：探索未知代码
用户："用户认证是怎么实现的？"
-
Ace-Tool search_context → 语义搜索 "用户认证实现" → 获取相关文件和代码片段
-
Serena find_symbol (可选) → 对搜索结果中的关键符号深入分析 → 获取精确的符号定义和引用
场景 2：定位已知符号
用户："找到 AuthService 类的所有引用"
-
Serena find_symbol → 直接定位 AuthService → 获取定义位置
-
Serena find_referencing_symbols → 查找所有引用该符号的位置
场景 3：混合搜索
用户："数据库连接池是怎么配置的？"
-
Ace-Tool search_context → 语义搜索 "数据库连接池配置" → 获取相关配置文件和代码
-
Serena (如果需要深入) → 对发现的配置类进行符号分析
工具选择决策树
需要理解代码？ ├── 不知道在哪 → Ace-Tool search_context ├── 知道符号名 → Serena find_symbol └── 需要引用关系 → Serena find_referencing_symbols
搜索类型？ ├── 自然语言描述 → Ace-Tool ├── 精确符号名 → Serena └── 模糊 + 精确 → Ace-Tool → Serena
工具调用规范
Ace-Tool search_context
参数：
- project_root_path: 项目根目录绝对路径
- query: 自然语言查询（支持中英文）
示例查询：
- "用户登录流程的实现"
- "API 错误处理机制"
- "数据库事务管理"
Serena 常用工具
工具 用途
find_symbol
查找符号定义
find_referencing_symbols
查找符号引用
get_symbol_definition
获取符号完整定义
list_symbols_in_file
列出文件中的所有符号
详细参数见 references/serena-tools.md
最佳实践
-
先广后深：Ace-Tool 广泛搜索 → Serena 精确定位
-
语义优先：不确定时先用 Ace-Tool 语义搜索
-
符号追踪：需要引用关系时用 Serena
-
只读原则：两个工具都不修改代码，修改使用 Edit/Write 工具