codeseeker

CodeSeeker

为 AI 编码助手打造的四层混合搜索与知识图谱。
BM25 + 向量嵌入 + RAPTOR 目录摘要 + 图扩展，融合为一个 MCP 工具，让 Claude、Copilot 和 Cursor 真正理解你的代码库。

适用于 Claude Code、GitHub Copilot（VS Code 1.99+）、Cursor、Windsurf 和 Claude Desktop。
只需一条命令即可建立索引；之后由 Claude Code 插件让索引保持同步。

由 PragmaWorks 打造，属于 Generative Specification 的一部分——这是一门借助 AI 构建软件、避免偏离目标的学科。还有两个配套 MCP 服务可与它组合使用，分别解决同一问题的不同方面：

它们相互独立：可安装其中一个，也可全部安装。

何时不再需要它

CodeSeeker 解决的是检索问题，而这个问题正在逐渐缩小。

如果你采用规范驱动的循环，并配备真正的测试框架——规范足够精确，让无状态模型能据此推导结果；质量门禁则会针对运行中的系统验证结果——或者采用意图驱动的流程，那么助手拿到的结构就不必再自行寻找。使用哨兵工具路由操作，而不是铺开十几个端点，也能减少一部分搜索需求。具备更强导航能力和更大有效上下文的前沿模型，则会进一步减少需求。到了某个阶段，在自己的代码上进行语义搜索便不再是瓶颈；此时卸载这个服务，你甚至不会察觉。

这正是预期结果，而非缺陷：有效的方法应该让自身的脚手架变得不再必要。不过，大多数团队起步时还做不到这一点；在流程建立之前，CodeSeeker 是一种成本更低的替代方案——用一条命令代替一门学科。

如果你想要的是流程，而非替代方案，请从这份实地指南开始： Generative Specification — 实地指南（PDF）。

问题

AI 助手是强大的编辑器，但它们浏览代码的方式就像游客：

• Grep 查找的是文本——而非含义。"find authentication logic" 会返回每个包含“auth”一词的文件
• 文件读取彼此孤立——Claude 能看到一个文件，却看不到它的依赖项、调用方，也看不到团队确立的模式
• 不了解项目——每次会话都从头开始

CodeSeeker 解决了这个问题。它只需为代码库建立一次索引，就能为 AI 助手提供可查询的知识图谱，供它们在每轮对话中使用。

工作原理

每次查询都会运行一个 4 阶段流水线：

Query: "find JWT refresh token logic"
        │
        ▼  Stage 1 — Hybrid retrieval
   ┌─────────────────────────────────────────────────────┐
   │ BM25 (exact symbols, camelCase tokenized)           │
   │   +                                                 │
   │ Vector search (384-dim Xenova embeddings)           │
   │   ↓                                                 │
   │ Reciprocal Rank Fusion: score = Σ 1/(60 + rank_i)  │
   │ Top-30 results, including RAPTOR directory nodes    │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 2 — RAPTOR cascade (conditional)
   ┌─────────────────────────────────────────────────────┐
   │ IF best directory-summary score ≥ 0.5:              │
   │   → narrow results to that directory automatically  │
   │ ELSE: all 30 results pass through unchanged         │
   │ Effect: "what does auth/ do?" scopes to auth/       │
   │         "jwt.ts decode function" bypasses this      │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 3 — Scoring and deduplication
   ┌─────────────────────────────────────────────────────┐
   │ Dedup: keep highest-score chunk per file            │
   │ Source files:  +0.10  (definition sites matter)     │
   │ Test files:    −0.15  (prevent test dominance)      │
   │ Symbol boost:  +0.20  (query token in filename)     │
   │ Multi-chunk:   up to +0.30  (file has many hits)    │
   └─────────────────────────────────────────────────────┘
        │
        ▼  Stage 4 — Graph expansion
   ┌─────────────────────────────────────────────────────┐
   │ Top-10 results → follow IMPORTS/CALLS/EXTENDS edges │
   │ Structural neighbors scored at source × 0.7        │
   │ Avg graph connectivity: 20.8 edges/node             │
   └─────────────────────────────────────────────────────┘
        │
        ▼
   auth/jwt.ts (0.94), auth/refresh.ts (0.89), ...

知识图谱在建立索引时根据 AST 解析的导入构建。它为 graph 操作、死代码检测以及每次搜索中的图扩展提供支持。

与众不同之处

LSP 工具无法做到的事：

• “查找处理此类错误的代码” → 语义模式搜索
• “此项目采用什么验证方式？” → 自动检测编码规范
• “显示所有与身份验证相关的内容” → 遍历图谱，查询间接依赖

仅向量搜索会遗漏的内容：

• 直接的导入 / 导出链
• 类继承层级
• 哪些文件实际依赖哪些文件

安装

推荐：安装一次，配置一次

npm install -g codeseeker
claude mcp add codeseeker --scope user -e CODESEEKER_STORAGE_MODE=embedded -- codeseeker serve --mcp

--scope user 会让它在你打开的每个项目中都可用，而不仅限于当前项目。

为什么选择全局安装，而不是 npx -y： 在从未安装过此软件包的机器上，npx 会先下载软件包并构建原生依赖，然后服务才能响应。实测完成 MCP 握手需要 13.7 秒。提前退出的客户端会将其报告为连接失败。全局安装的响应时间为 759 毫秒——下载只需进行一次，而且你可以选择在预期会发生下载时进行。

npx（无需安装）

便于移植，软件包已缓存时也完全够用。首次启动可能较慢。

{
  "mcpServers": {
    "codeseeker": {
      "command": "npx",
      "args": ["-y", "codeseeker", "serve", "--mcp"],
      "env": { "CODESEEKER_STORAGE_MODE": "embedded" }
    }
  }
}

将此内容添加到 MCP 配置文件（按客户端查看各自的位置，请参阅下文），然后重启编辑器。

其他编辑器

npm install -g codeseeker
codeseeker install --vscode      # or --cursor, --windsurf, --vs

🔌 Claude Code 插件

适用于 Claude Code CLI 用户——添加自动同步钩子和斜杠命令：

/plugin install codeseeker@github:jghiringhelli/codeseeker#plugin

斜杠命令：/codeseeker:init、/codeseeker:reindex

☁️ Devcontainers / GitHub Codespaces

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
  "postCreateCommand": "npm install -g codeseeker && codeseeker install --vscode"
}

✅ 验证

向 AI 助手询问：“你有哪些 CodeSeeker 工具？”

你应该会看到一个名为 codeseeker 的工具。这是有意为之：使用带有 action 路由键的单一工具，可以降低每个请求的 token 开销（ADR-002）。可用操作包括 search、sym、graph、analyze 和 index。

高级安装选项

{
  "mcpServers": {
    "codeseeker": {
      "command": "npx",
      "args": ["-y", "codeseeker", "serve", "--mcp"]
    }
  }
}

npm install -g codeseeker
cd your-project
codeseeker init
codeseeker -c "how does authentication work in this project?"

CodeSeeker 提供 一个 MCP 工具：codeseeker。通过 action 选择行为，并且 只填写对应的嵌套参数组：

codeseeker({ action, project, search?|sym?|graph?|analyze?|index? })

始终传入 project（项目根目录的绝对路径）——MCP 服务无法检测你的 工作目录。

你不需要手动调用这些工具——Claude 会在搜索代码或分析关系时自动使用它们。

索引的工作方式

你无需预先建立任何索引。 搜索 CodeSeeker 从未处理过的项目时，会自动开始建立索引 并告知你。索引在后台运行，因此调用会立即返回，而不会阻塞你的助手：

User: "Find the authentication logic"
        │
        ▼
┌────────────────────────────────────────────────────────┐
│ Claude calls codeseeker({action:"search"})             │
│         │                                              │
│         ▼                                              │
│ Project indexed? ──No──► starts indexing, returns      │
│         │                {status:"indexing_started"}   │
│        Yes                                             │
│         ▼                                              │
│ Return ranked results + confidence                     │
└────────────────────────────────────────────────────────┘

因此，你对新项目提出的第一个问题会得到“索引已开始，请稍后重试”， 而不是搜索结果。小型项目只需几秒即可就绪；大型项目则需要几分钟。 请使用 index({op:"status"}) 检查，而不要猜测。

你仍然可以主动建立索引；对于大型代码库，这样做很值得，因为你可以自行安排等待时间：

codeseeker({ action: "index", index: { op: "init", path: "/abs/path", name: "my-project" } })

codeseeker init          # or, from the CLI

显式 init 相比自动 init 唯一能提供的是 name——否则项目会以其目录名注册。

保持索引最新

索引是一个快照。没有任何机制会监视文件系统，因此文件发生更改后，有三种方式可以让索引重新同步：

如果不使用插件，即使索引逐渐过时，搜索仍会继续返回结果；只是这些结果 反映的是代码过去的状态。stale_index 信号会提示你这一点。

搜索质量研究

npm run build
node scripts/real-bench.js

自动检测的编码规范

CodeSeeker 会分析你的代码库并提取模式：

{
  "validation": {
    "email": {
      "preferred": "z.string().email()",
      "usage_count": 12,
      "files": ["src/auth.ts", "src/user.ts"]
    }
  },
  "react-patterns": {
    "state": {
      "preferred": "useState<T>()",
      "usage_count": 45
    }
  }
}

检测到的模式类别：

• 验证：Zod、Yup、Joi、validator.js、自定义正则表达式
• 错误处理：API 错误响应、try-catch 模式、自定义 Error 类
• 日志记录：Console、Winston、Bunyan、结构化日志记录
• 测试：Jest/Vitest 设置、断言模式
• React 模式：Hooks（useState、useEffect、useMemo、useCallback、useRef）
• 状态管理：Redux Toolkit、Zustand、React Context、TanStack Query
• API 模式：Fetch、Axios、Express 路由、Next.js API 路由

Claude 编写新代码时，会遵循你现有的规范，而不是另行发明新规范。

管理索引排除项

如果 Claude 发现不应编入索引的文件（例如 Unity 的 Library 文件夹、构建输出或生成的文件），它可以动态排除这些文件：

// Exclude Unity Library folder and generated files
codeseeker({
  action: "index",
  project: "/abs/path/to/my-unity-game",
  index: {
    op: "exclude",
    exclude_op: "exclude",
    paths: ["Library/**", "Temp/**", "*.generated.cs"],
    reason: "Unity build artifacts"
  }
})

排除项会保存在 .codeseeker/exclusions.json 中，并在重新索引时自动生效。

代码清理工具

CodeSeeker 通过查找重复代码和检测死代码，帮助你保持代码库整洁。

查找重复代码

让 Claude 查找可合并的相似代码块：

"Find duplicate code in my project"
"Are there any similar functions that could be merged?"
"Show me copy-pasted code that should be refactored"

CodeSeeker 使用向量相似度查找语义相似的代码，而不只是完全匹配的代码。它能检测：

• 只有细微差异的复制粘贴函数
• 跨文件的相似验证逻辑
• 可提取到工具函数中的重复模式

查找死代码

让 Claude 找出可安全删除的未使用代码：

"Find dead code in this project"
"What functions are never called?"
"Show me unused exports"

CodeSeeker 会分析知识图谱，查找：

• 从未被导入的导出函数/类
• 没有调用方的内部函数
• 没有传入依赖关系的孤立文件

示例工作流：

User: "Use CodeSeeker to clean up this project"

Claude: I'll analyze your codebase for cleanup opportunities.

Found 3 duplicate code blocks:
- validateEmail() in auth.ts and user.ts (92% similar)
- formatDate() appears in 4 files with minor variations
- Error handling pattern repeated in api/*.ts

Found 2 dead code files:
- src/utils/legacy-helper.ts (0 imports)
- src/services/unused-service.ts (exported but never imported)

Would you like me to:
1. Consolidate the duplicate validators into a shared utility?
2. Remove the dead code files?

语言支持

所有语言都已建立索引且可搜索——分块和嵌入不依赖解析器。解析器改变的是知识图谱：CodeSeeker 判断某个符号是否为声明，以及各项之间的依赖关系，准确度有多高。

**Regex 提取确实存在局限，并非只是同一种能力的弱化版本。**它根据代码形态查找声明，因此会遗漏不常见的写法，也无法区分声明和调用。TypeScript 和 JavaScript 的导入边仍然可靠，因为 Babel 会解析它们；调用边在所有语言中都是启发式提取的。

以上评级均经过测量，并非主观判断。scripts/corpus-bench.js 会为七个真实项目建立索引，scripts/graph-quality.js 会报告生成的每个图中有多少内容可能是真实声明。Java 没有自己的评级，因为该语料库中没有 Java 项目；它与 Python 共用 Tree-sitter 代码路径，这就是我们所能说明的全部。

在四个 RealWorld Conduit 实现上进行测量——它们是同一个应用的四种实现，因此彼此间的差距反映的是语言处理能力，而非任务难度——在 30 个带标签的查询上，平均倒数排名分别为：TypeScript 83.3%、Python 81.5%、JavaScript 77.1%、C# 70.5%。

为你的语言添加解析器

如果你的项目主要使用 Go、Rust、C++ 或 Ruby，可以为其安装 Tree-sitter 语法：

npm install -g tree-sitter-go        # or tree-sitter-rust, tree-sitter-cpp, …

然后向你的助手提问，或运行：

codeseeker({ action: "index", project: "/abs/path", index: { op: "parsers", list_available: true } })

响应会为每个解析器标记 wired: true 或 wired: false。只有标记为 wired: true 的解析器才会被图构建器使用——安装标记为 false 的解析器目前不会带来任何变化；响应会明确说明这一点，而不是让你因为没注意到改进而自行发现。

目前已接入：TypeScript、JavaScript、Python、Java、C#。其他解析器均如实标记为 false。接入解析器只需进行一项小型、独立的改动——实现 ILanguageParser 的解析器，并在 extensionToParser 中注册（src/mcp/indexing-service.ts）——欢迎贡献。scripts/graph-quality.js 会衡量新解析器是否确实改善了图，因此改进是可验证的，而非假定的。

保持索引同步

使用 Claude Code 插件

插件会安装钩子，自动更新索引：

你无需进行任何操作——插件会自动处理同步。

仅使用 MCP 服务（Cursor、Claude Desktop）

• Claude 发起的更改：Claude 可以调用 codeseeker({action:"index", index:{op:"sync"}})
• 手动更改：不会自动检测——请定期让 Claude 重新建立索引

同步摘要

CodeSeeker 最能发挥作用的场景

适用场景：

• 规模庞大的代码库（10K+ 个文件），Claude 难以找到相关代码
• 已建立规范、希望 Claude 遵循这些规范的项目
• 跨多个文件的复杂依赖链
• 希望 AI 生成的代码保持一致的团队

不太适用：

• 几乎没有现有代码的全新项目
• 单文件脚本
• 正在积极调整架构的项目

架构

┌──────────────────────────────────────────────────────────┐
│                     Claude Code                          │
│                         │                                │
│                    MCP Protocol                          │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────┐    │
│  │              CodeSeeker MCP Server               │    │
│  │  ┌─────────────┬─────────────┬────────────────┐ │    │
│  │  │   Vector    │  Knowledge  │    Coding      │ │    │
│  │  │   Search    │    Graph    │   Standards    │ │    │
│  │  │  (SQLite)   │  (SQLite)   │   (JSON)       │ │    │
│  │  └─────────────┴─────────────┴────────────────┘ │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────┘

所有数据都存储在本地的 .codeseeker/ 中。无需外部服务。

对于大型团队（100K+ 个文件、共享索引），服务端模式支持 PostgreSQL + Neo4j。请参阅存储文档。

如需了解完整的技术内部原理——精确的评分公式、MCP 工具架构、图边类型、RAPTOR 阈值逻辑、流水线阶段、分析置信度层级——请参阅**技术架构手册**。

故障排除

MCP 服务无法连接

1. 验证 npm 和 npx 是否可用：npx -y codeseeker --version
2. 检查 MCP 配置文件语法（有效的 JSON，不含尾随逗号）
3. 完全重启编辑器/Claude 应用
4. 检查是否已安装 Node.js：node --version（需要 v18+）

索引速度似乎很慢

大型项目（50K+ 个文件）首次建立索引可能需要 5 分钟以上。后续使用会立即完成。

Claude 中未显示工具

1. 询问 Claude：“你有哪些 CodeSeeker 工具？”
2. 如果没有显示工具，请检查 MCP 配置文件是否存在且语法正确
3. 完全重启 IDE（而不只是重新加载窗口）
4. 检查 IDE 中 Claude/Copilot 的 MCP 连接状态

仍然无法解决？

提交问题：GitHub Issues

文档

• 集成指南 - 各组件如何连接
• 架构 - 技术深入解析
• CLI 命令 - 完整命令参考

支持的平台

Claude Code 和 GitHub Copilot 共用同一个 .vscode/mcp.json——配置一次，即可同时使用。

支持

如果 CodeSeeker 对你有帮助，可以考虑赞助该项目。

许可证

Apache License 2.0。 请参阅 LICENSE 和 NOTICE。

免费用于任何用途，包括商业用途——对公司规模或收入没有限制。与 MIT 相比，Apache-2.0 明确授予专利许可，因此这里选择了它。

在团队中运行 CodeSeeker

以上介绍的是本地单人开发者配置：索引存储在你电脑上的 .codeseeker/ 中，绝不会离开本机。

团队可以使用集中式部署——为组织的代码仓库建立一个共享索引（PostgreSQL + pgvector、Neo4j），这样工程师就不必各自为相同的代码重复建立索引，图谱也可以跨越服务边界，而不再局限于单个仓库。它还能揭示本地工具在结构上无法呈现的信息：代码理解实际上如何分布在整个代码库中，以及知识缺口所在的位置。

如果你的团队觉得这有帮助，请联系我们：https://pragmaworks.dev

CodeSeeker 为 Claude 提供了仅靠 grep 和嵌入无法实现的代码理解能力。

生成式规范的一部分

一款基于 Apache-2.0 许可的工具，践行生成式规范（GS）——这是一门借助 AI 构建软件、避免偏离预期的学科：你编写足够精确的规范，让无状态 AI 据此生成正确的代码，再由测试框架对照运行中的系统进行验证。

• 📄 白皮书（开放获取）：https://doi.org/10.5281/zenodo.21726017
• 📕 实战指南——简明实用的入门指南：https://github.com/jghiringhelli/generative-specification/blob/main/docs/white-paper/GenerativeSpecification_FieldGuide.pdf
• 🧭 从这里开始——方法、工具、用户评价：https://pragmaworks.dev
• 🔨 The Forge——面向你团队的 2 天 GS 实战工作坊：https://forgeworkshop.dev