SuperAPI AI 工具集

Serena Usage

编程与开发

查看项目

更新于 10-16 05:58

技能介绍

用途

Serena Usage 技能用于在用户要求“使用 serena”“语义搜索”“符号分析”“查找引用”“代码导航”,或需要 Serena MCP 时,指导如何正确使用 Serena 的代码智能能力。其核心思路是:代码智能操作优先使用 Serena 的符号工具,文件系统导航则使用 Glob、Grep、ls 等标准工具。

主要能力

该技能覆盖以下符号级操作:

  • 文件结构概览:get_symbols_overview(建议先 depth=0,再 depth=1)。
  • 符号查找:find_symbol,支持 name_path_pattern,可用 include_body=true 获取实现体,可用 substring_matching=true 扩大匹配。
  • 引用查找:find_referencing_symbols,用于查找调用方并递归构建依赖图。
  • 符号替换与插入:replace_symbol_body、insert_before_symbol、insert_after_symbol。
  • 重命名:rename_symbol,用于一致地更新引用。
  • 声明与实现查找:find_declaration(配合正则捕获符号名)、find_implementations。
  • 安全删除:safe_delete_symbol,若被阻止则检查返回的引用。
  • 内容替换:replace_content,支持 mode="literal" 与 mode="regex"(正则模式下 DOTALL 与 MULTILINE 启用,可用通配符避免转录大段内容)。
  • 诊断:get_diagnostics_for_file,可设置 min_severity=2。
  • 记忆管理:list_memories、read_memory、write_memory、edit_memory,以及 memory_staleness_verification 用于校验记忆新鲜度。

使用方式

会话开始时:先调用 initial_instructions,再 activate_project 激活项目,然后 check_onboarding_performed 检查 onboarding,如未完成则执行 onboarding,最后用 list_memories 查看可用记忆。

典型流程示例:

  • 探索类成员:get_symbols_overview relative_path="src/main.ts" depth=1,再用 find_symbol name_path_pattern="MyClass/myMethod" include_body=true 获取具体实现。
  • 查找调用方:find_referencing_symbols name_path="processData" relative_path="src/processor.ts",并对每个调用方重复步骤以构建完整依赖树。
  • 修改方法:先用 find_referencing_symbols 识别所有使用处,再用 replace_symbol_body 执行修改;若接口签名变化,需更新步骤中识别出的所有调用点。
  • 正则替换:构造能唯一定位目标行的正则,执行 replace_content relative_path="src/main.ts" needle="oldPattern.*?boundary" repl="newContent" mode="regex",最后用 get_diagnostics_for_file 验证。
  • 字面量替换:replace_content relative_path="config.nix" needle="oldValue = true" repl="oldValue = false" mode="literal"。

技能内置多个决策树,用于选择代码操作类型、工具选择、首次工具选择以及语言特定符号操作。工具选择层级为:Serena 负责代码智能,标准工具负责文件系统导航。文件发现用 Glob,内容搜索用 Grep,定位后再用 Serena 的 find_symbol 或 find_referencing_symbols 导航。

适用场景

适用于需要符号级代码理解与重构的任务,例如查找引用、追踪依赖、重命名符号、替换方法体、按正则批量替换代码、检查诊断信息,以及在实现前后读写项目记忆。也适用于多语言仓库中的符号操作,但需注意语言检测限制。

限制

  • Serena 项目未激活时不可用,需先调用 initial_instructions 与 activate_project。
  • 文件类型不被 LSP 支持时不可用,应改用 Grep 或 Read。
  • 目标文件语言不在项目激活语言中时不可用;多语言检测以主导语言为准,此时应回退到 Grep 加文本编辑,而不是重试符号工具。
  • 工具显式报错时不可用。
  • 反模式:在只需要特定符号时读取整个文件;应改用 get_symbols_overview 与 find_symbol include_body。
  • 错误升级场景包括:精确匹配找不到符号、记忆文件不存在、记忆信息冲突、记忆损坏或状态无效。

最佳实践

会话开始始终激活项目并检查 onboarding;实现新功能前先 list_memories 与 read_memory;优先使用符号操作而非读取整个文件;已知范围时用 relative_path 限制搜索;符号名不确定时用 substring_matching;发现重要模式后用 write_memory 记录;用 edit_memory 更新已有记忆而非删除重建;重构前用 find_referencing_symbols 验证符号变更;按任务类型优先读取相关记忆。