mcpField
C
code-semantic-search

code-semantic-search

github.com/oimiragieo开发4477 次安装17 周前更新
代码仓库

关于 code-semantic-search

code-semantic-search 是面向开发者的代码搜索技能，可按代码行为查找实现与模式，并结合语义和结构搜索，也支持单独搜索概念或精确模式。

主要功能

  1. 01语义与结构混合搜索
  2. 02仅语义概念搜索
  3. 03仅结构模式搜索
  4. 04搜索结果排序

适用场景

  1. 01按行为定位身份验证逻辑
  2. 02查找错误处理模式
  3. 03发现相似实现

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oimiragieo/agent-studio --skill code-semantic-search

安装后在 Claude Code 中输入/code-semantic-search确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

commands/
code-semantic-search.md
hooks/
post-execute.cjs
pre-execute.cjs
references/
research-requirements.md
rules/
code-semantic-search.md
schemas/
input.schema.json
output.schema.json
scripts/
main.cjs
templates/
implementation-template.md

详细介绍

代码语义搜索

概览

使用 Phase 1 向量嵌入和 Phase 2 混合搜索（语义 + 结构）进行代码语义搜索。根据含义查找代码，而不只是匹配关键词。

核心原则： 根据代码的功能搜索，而不是根据它的名称搜索。

Phase 2：混合搜索

此技能现已支持三种搜索模式：

  1. 混合搜索（默认）：

    • 结合语义搜索 + 结构搜索
    • 准确率最高（95%+）
    • 速度稍慢，但仍低于 150ms
    • 推荐用于所有搜索

  2. 仅语义搜索：

    • 仅使用 Phase 1 语义向量
    • 速度最快（<50ms）
    • 适用于概念搜索
    • 结构不重要时使用

  3. 仅结构搜索：

    • 仅使用 ast-grep 模式
    • 精确匹配时非常精准
    • 最适合查找函数/类定义
    • 需要精确结构模式时使用
性能对比
模式速度准确率最适用于
混合搜索<150ms95%通用搜索
仅语义搜索<50ms85%概念搜索
仅结构搜索<50ms100%精确模式
仅 Phase 1<50ms80%旧版（回退）

适用场景

始终使用：

  • 不知道函数名称时查找身份验证逻辑
  • 搜索错误处理模式
  • 定位数据库查询
  • 查找与某个概念相似的代码
  • 发现实现模式

不要使用：

  • 精确文本匹配（改用 Grep）
  • 文件名搜索（改用 Glob）
  • 简单关键词搜索（改用 ripgrep）

使用示例

混合搜索（推荐）
// Basic hybrid search
Skill({ skill: 'code-semantic-search', args: 'find authentication logic' });

// With options
Skill({
  skill: 'code-semantic-search',
  args: 'database queries',
  options: {
    mode: 'hybrid',
    language: 'javascript',
    limit: 10,
  },
});
仅语义搜索
// Fast conceptual search
Skill({
  skill: 'code-semantic-search',
  args: 'find authentication',
  options: { mode: 'semantic-only' },
});
仅结构搜索
// Exact pattern matching
Skill({
  skill: 'code-semantic-search',
  args: 'find function authenticate',
  options: { mode: 'structural-only' },
});

实现参考

混合搜索： .claude/lib/code-indexing/hybrid-search.cjs

查询分析： .claude/lib/code-indexing/query-analyzer.cjs

结果排序： .claude/lib/code-indexing/result-ranker.cjs

集成点

  • developer：代码探索、实现发现
  • architect：系统理解、模式分析
  • code-reviewer：查找相似模式、一致性检查
  • reverse-engineer：理解陌生代码库
  • researcher：研究现有实现

铁律

  1. 通用搜索始终使用混合模式（语义 + 结构）——仅语义搜索会漏掉精确匹配；仅结构搜索会漏掉概念变体；混合搜索的准确率为 95%，单一模式则为 85%。
  2. 快速发现关键词时始终先使用 ripgrep/关键词搜索——语义搜索适用于基于含义的查询；使用 ripgrep 查找精确字符串、函数名称和文件名更快。
  3. 没有有意义的自然语言查询时，绝不使用语义搜索——单个词或代码语法查询会产生较差的语义搜索结果；应描述代码的功能，而不是名称。
  4. 始终结合 code-structural-search 进行精准优化——先通过语义搜索广泛发现，再使用 ast-grep 模式从语义搜索结果中查找精确的结构匹配。
  5. 绝不未经检查就忽略相似度低的结果——相似度分数只是近似值；对于不常见的模式，0.7 分的结果可能比 0.9 分的结果更相关。

反模式

反模式失败原因正确做法
使用语义搜索进行精确字符串匹配比文本搜索更慢，准确性也更低使用 ripgrep/Grep 进行精确关键词匹配
使用单词查询（“auth”）对语义匹配而言过于宽泛；会返回无关结果使用自然语言描述（“authentication token validation logic”）
对常规搜索使用纯语义模式会漏掉结构变体；准确率为 85%，而非 95%对常规查询使用混合模式（默认）
忽略不符合预期的搜索结果语义搜索会找到出乎意料但相关的代码阅读所有结果；意外的匹配往往最有价值
不结合结构搜索能找到概念，却找不到精确模式使用语义搜索进行发现 → 使用结构搜索提高精度

记忆协议（强制）

开始之前： 阅读 .claude/context/memory/learnings.md

完成之后：

  • 新模式 -> .claude/context/memory/learnings.md
  • 发现问题 -> .claude/context/memory/issues.md
  • 做出决策 -> .claude/context/memory/decisions.md

假设任务可能会被中断：如果没有记录在记忆中，就等于没发生。

评论

支持 Markdown