内容
<div align="center">
[](https://github.com/infino-ai/code-context/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@infino-ai/code-context)
[](LICENSE)
[](https://nodejs.org/)
[](https://deepwiki.com/infino-ai/code-context)
</div>
**代码上下文** 是您编码代理下的检索层：整个代码仓库的本地索引（关键词、语义、混合和 SQL），通过 MCP 服务器和 CLI 访问，索引存储在代码仓库内的普通文件中。您的代理无需逐一读取文件即可回答有关代码库的问题。
经验法则：问题涉及的代码仓库范围越大，节省的越多，因为答案来自排名索引而非逐一拉取源代码。
**最多可减少 22 倍 token**。一个查询，“按语言分解此代码仓库”，使用代码上下文约为 6K token，而读取文件约为 140K token。测试框架在代码仓库中，因此您可以对自己的代码库进行复现。
**立即试用（早期预览）**：在 [lantern.infino.ai](https://lantern.infino.ai) 上询问任何公共 GitHub 代码仓库的问题，这是一个运行在代码上下文上的演示代理。
- 🔎 **按单词或含义查找代码**。一次排名通过融合精确关键词匹配与语义相似性，每个命中都带有代码和 `path:line` 引用。
- 📊 **询问 grep 无法回答的问题**。搜索作为 SQL 表函数，因此“哪些文件包含最多的关于 X 的代码”是一个查询：按相关性排名，按 `GROUP BY` 统计。
- ⚡ **秒级搜索，永久新鲜**。关键词索引在嵌入模型甚至完成下载之前提交，矢量在后台回填，编辑增量同步：只有更改的文件重新分块和重新嵌入。
- 🔒 **没有任何信息离开您的机器**。无需帐户，无需 API 密钥，无需数据库服务器，无需遥测。嵌入是一个小型本地模型，仅需下载一次；之后所有操作都可在离线状态下进行。
基于 [infino](https://github.com/infino-ai/infino)，一个快速的检索引擎，运行 SQL、全文本搜索和矢量搜索，基于您数据的单一副本。文本和数字数据存储为符合规范的 Parquet，同一个引擎处理日志、文档和代理内存。
<sub>Claude Code 通过代码上下文回答代码仓库的问题：索引它，然后询问，它会自主搜索和 SQL。</sub>
## 快速开始
通过一条命令将其添加到 Claude Code，无需安装任何内容：
```
claude mcp add code-context -- npx -y @infino-ai/code-context mcp
```
然后要求代理“索引此代码库”：`reindex` 工具在聊天中引导未索引的代码仓库，搜索功能在索引运行时生效。
持续集成在 Linux x64（glibc）和 macOS arm64 上测试；linux-arm64、musl 和 Windows-via-WSL 预计通过引擎的预构建绑定工作，但未覆盖持续集成。
## 评估
真实代理运行在代码库-Q&A 套件上：相同的模型（claude-opus-4-8），相同的回合预算，相同的提示，基线使用股票文件工具（Glob/Grep/Read/LS）。其最明显的优势是整个代码仓库的相关性聚合，这是文件工具无法表达的：**最多可减少 22 倍 token**（该“按语言分解”查询约为 6K，而 ~140K），以及整体聚合查询的 6.5 倍。在整个套件中：**55% 减少 token 和 71% 减少工具调用**，在盲双 pairwise 评委无法区分的答案质量下（8 vs 12 of 20，在噪声范围内）。
| 指标 | 股票文件工具 | 使用代码上下文 | 改进 |
| --- | --- | --- | --- |
| 每问题 token | 63.2k | 28.3k | **-55%** |
| 每问题工具调用 | 7.5 | 2.2 | **-71%** |
| 每问题成本 | $0.174 | $0.102 | **-41%** |
| 聚合查询（token） | 51.1k | 7.9k | **-85%** |
| 理解查询（token） | 81.3k | 59.0k | **-28%** |
完整的方法论和每问题表格在 [docs/benchmark.md](docs/benchmark.md) 中，测试框架在 [`bench/`](bench/) 中，您可以在自己的代码仓库中运行相同的测试。
## 您获得的内容
一个索引和一个刻意为代理设计的简洁工具表面：
| 工具 | 功能 | 代理使用场景 |
| --- | --- | --- |
| `search` | 一次排名通过融合精确关键词匹配（BM25）和语义相似性。命中携带块内容，因此答案直接来自结果。 | 了解子系统或按含义跨文件查找代码；精确标识符和释义在同一调用中。（对于已知符号，普通的 grep 就足够了。） |
| `sql` | 索引上的只读 SQL，包括搜索函数作为表值关系和 `regexp_like` 进行正则表达式匹配。 | 整个代码仓库的计数、排名和聚合，单次查询。 |
| `reindex` | 增量同步（服务器还会在后台自动同步）。 | 进行重大编辑后。 |
三个工具是一种刻意的设计：一种查找方式，一种计数方式，一种保持新鲜的方式。每个额外的近似检索工具都会使代理的工具选择恶化，而混合搜索的关键词部分已经将精确标识符项排名靠前，因此单独的词汇工具没有工作。
### SQL 操作
搜索作为表格与聚合组合。按相关性排名，按 SQL 统计，一次引擎通过：
```sql
SELECT path, SUM(end_line - start_line + 1) AS lines, COUNT(*) AS chunks
FROM bm25_search('chunks', 'content', 'vector index quantization', 300)
GROUP BY path ORDER BY lines DESC LIMIT 15
```
`hybrid_search(...)` 和 `vector_search(...)` 工作方式相同。CLI 和 MCP 服务器在服务器端嵌入 `{{name}}` 占位符，因此代理永远不会处理原始向量。
### 分阶段就绪
`cx index` 首先提交关键词（BM25）索引。在一个包含约 3,000 个块的代码仓库中，这需要不到一秒钟，因此在嵌入模型甚至存在于机器上之前，搜索功能就已生效。矢量在后台使用本地模型回填（下载一次，无需密钥；约两分钟适用于相同的代码仓库），混合和语义排名在矢量就位后自动解锁。如果矢量阶段失败，关键词搜索保持活动，索引会诚实地说明。
默认模型优化每分钟的质量。参见 [docs/embedder-eval.md](docs/embedder-eval.md) 了解其选择方式。
### 您的索引只是文件
所有内容都存放在代码仓库根目录的 `.infino/` 中（将其添加到您的 `.gitignore` 中）：您可以复制的普通文件，在 CI 中缓存，或存储在对象存储中。它是一个实时索引，引擎直接查询，而不是您需要导出和传递的快照。
## 代理设置
代码上下文是一个基于 stdio 的 MCP 服务器，因此任何 MCP 客户端都可以使用。注册一次，工具（`search`、`sql`、`reindex`）对代理可用。
<details>
<summary><strong>Claude Code</strong></summary>
```bash
claude mcp add code-context -- npx -y @infino-ai/code-context mcp
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
将以下内容添加到 `.cursor/mcp.json`：
```json
{ "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@infino-ai/code-context", "mcp"] } } }
```
</details>
<details>
<summary><strong>Codex CLI</strong></summary>
在 `~/.codex/config.toml` 中（注意键名为 `mcp_servers`）：
```toml
[mcp_servers.code-context]
command = "npx"
args = ["-y", "@infino-ai/code-context", "mcp"]
```
</details>
<details>
<summary><strong>Gemini CLI</strong></summary>
在 `~/.gemini/settings.json` 中：
```json
{ "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@infino-ai/code-context", "mcp"] } } }
```
</details>
<details>
<summary><strong>Windsurf、Cline 和其他 MCP 客户端</strong></summary>
标准 stdio MCP 配置：
```json
{ "mcpServers": { "code-context": { "command": "npx", "args": ["-y", "@infino-ai/code-context", "mcp"] } } }
```
当客户端的工作目录不是代码仓库时，通过 `env: { "CX_ROOT": "/path/to/repo" }` 显式指向代码仓库。
</details>
工具：`search`、`sql`、`reindex`（增量同步：未更改的代码仓库是快速的无操作，服务器还会在后台自动同步，因此结果跟踪您的编辑，无需任何请求）。
## 配置
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `CX_INDEX_DIR` | `<repo>/.infino` | 索引存储位置 |
| `CX_MAX_FILES` / `CX_MAX_FILE_BYTES` | 20000 / 1MB | 索引上限 |
| `CX_ROOT` | 当前目录 | MCP 服务器/CLI 的代码仓库根目录（当不在代码仓库中运行时） |
| `CX_AUTO_SYNC` | 开启 | `0` 禁用 MCP 服务器的后台过时同步 |
| `CX_SYNC_INTERVAL_SECS` | 30 | 自动同步去抖动之间的间隔 |
| `CX_NO_EMBED` | 关闭 | MCP 服务器的仅关键词模式（跳过矢量阶段） |
## CLI
同一个索引也可以从终端访问，用于脚本、CI 或自行检查结果。全局安装二进制文件，然后在代码仓库中运行任何命令：
```
npm install -g @infino-ai/code-context
```
```
cx index [path] 同步索引（增量；--full 重建，--watch 监听编辑）
cx search <query> 精确词条 + 含义，一次排名通过 (-k 命中)
cx sql <statement> 只读 SQL；--embed q="text" 填充 {{q}}
cx status 索引内容、更新程度、矢量准备情况
cx mcp 通过 stdio 提供 MCP 工具
```
## 它是什么，它不是什么
代码上下文的定位是排名 **内容** 检索和内容相关性聚合：按单词或含义查找代码，按主题对整个文件进行排名，始终带有 `path:line` 引用。它刻意 **不** 做结构化代码智能（调用图跟踪、死代码检测、类型解析）。这些工具是互补的：MCP 服务器堆栈，因此可以运行两者。
## 架构
- **分块：** tree-sitter（WASM，无需本地编译）按定义边界切割，适用于 TypeScript/JS、Python、Rust、Go、Java、C/C++、Ruby、C#、PHP；Markdown 按标题分割；其他情况则回落到固定窗口。每个块携带 `path、start_line、end_line、lang、content`。
- **索引：** `.infino/` 中的 [infino](https://github.com/infino-ai/infino) 表：BM25（全文搜索）和 IVF 矢量索引，基于数据的单一副本，通过 Node 绑定进行查询。无需服务器。
- **嵌入：** 始终本地。小型模型（通过 [measured eval](docs/embedder-eval.md) 选择）下载一次；无需密钥，无需每查询网络，代码从不离开机器。查询使用与索引构建相同的模型嵌入，模型不匹配是一个明确的错误，而不是静默错误结果。
- **新鲜度：** 设计为增量。每个文件状态映射（大小/mtime 预过滤，然后内容哈希）意味着同步仅重新分块和重新嵌入更改的文件：在一个包含约 3,000 个块的代码仓库中，不变的树检查时间为 ~20ms，一个文件编辑同步时间为 ~0.7s，矢量保持最新（更大代码仓库的基准 [benchmark](docs/benchmark.md)）。MCP 服务器在查询到达时在后台自动同步（从不阻塞查询），`cx index` 默认增量（`--full` 重建），`cx index --watch` 在文件事件上同步。
## 了解更多
- [编码代理的代码搜索](docs/concepts/code-search-for-coding-agents.md) - 爬取与检索模型以及索引何时节省 token。
- [FAQ](docs/faq.md) - 它是什么，何时使用，本地保证，新鲜度。
- [权衡](docs/tradeoffs.md) - 诚实的限制。
- [基准](docs/benchmark.md) - 测量结果，附有测试框架以在您自己的代码仓库中重现。
## 许可证
Apache-2.0
