⚡

语义代码猎手Skill semantic-code-hunter

语义代码猎手是一个基于Serena MCP的智能代码搜索工具，专为开发人员设计，通过概念语义而非简单文本匹配来查找和理解代码。该工具能高效定位认证流程、验证逻辑、组件依赖关系，支持多文件重构和架构分析。核心功能包括符号查找、引用追踪、文件结构概览等，相比传统搜索方法可节省70%以上的token消耗。适用于中大型项目的代码维护、重构和架构理解。 关键词：语义代码搜索，Serena MCP，代码重构，认证流程查找，组件依赖分析，多文件搜索，代码架构理解，开发效率工具，智能代码分析，令牌优化搜索

架构设计 2 次安装 14 次浏览 更新于 3/2/2026

名称: 语义代码猎手 描述: 当你需要通过概念（不仅仅是文本）查找代码时使用。利用Serena MCP在整个代码库中进行语义代码搜索，同时最小化token使用量。适用于理解架构、查找认证流程或多文件重构。

语义代码猎手（由Serena MCP驱动）

何时使用

  • “我们在哪里处理X？”这类问题
  • 查找认证流程
  • 定位验证逻辑
  • 多文件重构
  • 理解组件关系
  • 查找符号的所有用法
  • 追踪依赖关系

何时不使用

  • 小型项目（<10个文件）- 使用Grep代替
  • 简单文本搜索 - 使用Grep代替
  • 单文件编辑 - 使用Read代替
  • 你已经知道确切文件

工作原理

利用Serena MCP工具进行语义理解：

  • find_symbol - 通过概念查找符号，而不仅仅是名称
  • find_referencing_symbols - 追踪代码关系
  • find_referencing_code_snippets - 查找代码使用位置
  • get_symbols_overview - 首先理解文件结构
  • 令牌高效（相比传统搜索节省70%消耗）

可用的Serena工具

find_symbol

全局或本地查找具有/包含给定名称/子字符串的符号。

示例：find_symbol("authenticate")
查找：authenticateUser, isAuthenticated, AuthenticationService

find_referencing_symbols

查找引用另一个符号的符号。

示例：find_referencing_symbols("User", type="function")
查找：所有使用User模型的函数

get_symbols_overview

获取文件中符号的高级概览。

示例：get_symbols_overview("src/services/auth.ts")
返回：文件中的类、函数、导出列表

search_for_pattern

跨项目进行模式搜索（当语义搜索不足时）。

使用模式

步骤1：从概览开始

如果你知道文件：
1. get_symbols_overview("path/to/file.ts")
2. 识别相关符号
3. 使用find_symbol获取详细信息

步骤2：语义搜索

如果你不知道文件：
1. find_symbol("concept")
2. 查看结果
3. 使用find_referencing_symbols追踪使用情况

步骤3：定向检索

一旦你知道需要什么：
1. 使用find_symbol获取特定代码
2. 仅加载相关部分（而非整个文件）
3. 最小化令牌消耗

示例

示例1：查找认证流程

任务：“我们在哪里处理用户认证？”

流程：
1. find_symbol("auth") - 查找与认证相关的符号
2. 识别：authenticateUser, validateToken等
3. find_referencing_symbols("authenticateUser") - 它在哪里被调用？
4. 追踪流程：登录路由 → 认证服务 → JWT生成

结果：无需阅读完整文件即可映射完整的认证流程

示例2：多文件重构

任务：“将User模型重命名为Account”

流程：
1. find_symbol("User") - 查找User模型
2. find_referencing_symbols("User") - 查找所有使用情况
3. 列出所有需要更新的文件
4. 使用rename_symbol（Serena工具）进行安全重构

结果：找到所有引用并一致地重命名

示例3：理解组件关系

任务：“ProjectCard组件如何获取数据？”

流程：
1. find_symbol("ProjectCard")
2. find_referencing_symbols("ProjectCard") - 它在哪里被使用？
3. 向后追踪到数据源
4. 理解数据流

结果：从API → 页面 → 组件的完整数据流

最佳实践

  1. 从广泛开始，逐步缩小范围

    • 首先使用通用术语进行find_symbol
    • 按类型（函数、类、接口）过滤结果
    • 然后获取特定符号详细信息

  2. 使用类型过滤器

    • type=“function” - 仅函数
    • type=“class” - 仅类
    • type=“interface” - 仅接口

  3. 利用符号关系

    • find_referencing_symbols显示依赖关系
    • 帮助理解变更影响
    • 揭示架构模式

  4. 与传统工具结合使用

    • Serena用于语义理解
    • Grep用于简单文本匹配
    • Read用于配置文件、文档

令牌效率

传统方法（无Serena）：

  1. 读取整个文件 → 10,000+令牌
  2. 多次grep迭代 → 5,000+令牌
  3. 手动分析 → 高认知负荷

Serena方法：

  1. find_symbol → 200令牌
  2. 定向检索 → 500令牌
  3. 总计：~700令牌（节省93%）

故障排除

如果Serena返回过多结果：

  • 添加类型过滤器：type=“function”
  • 使用更具体的搜索词
  • 首先使用get_symbols_overview检查特定文件

如果Serena无结果：

  • 检查拼写（区分大小写）
  • 尝试更广泛的搜索词
  • 回退到Grep进行文本搜索
  • 确保Serena已索引（运行：serena project index）

如果符号缺失：

  • 重新索引项目：serena project index
  • 检查文件是否在.gitignore中
  • 验证语言服务器是否支持文件类型