# 在没有本地索引器的情况下，给 AI 智能体大型仓库的上下文

Canonical source: https://maguyva.ai/zh-hans/blog/large-repo-context-without-a-local-indexer

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-08-14 · Author: Maguyva Team

> 如何在不在笔记本电脑上运行本地索引器的情况下，从云端为编码智能体提供一张大型仓库的可查询地图。

一个大型仓库放不进上下文窗口，而如果你曾经把笔记本电脑上的索引器指向一个真正的 monorepo，你就知道它在那里也放不舒服——内存飙升，第一次索引要花一个小时，而你的智能体在下一个会话开始时，依然在猜哪些文件重要。

通常的答案是在编辑器旁边运行一个索引器，对于能舒服放进一台机器的仓库来说，这是个不错的答案。如果你的 monorepo 在 Cursor 中已经索引得很快，而那也是你唯一需要这张地图的地方，那么这篇文章没有什么可以补充的——跳过它就好。

这篇文章讲的是另一种情况——当一个智能体需要一张大型仓库的可查询地图，而你又不想为此运行本地索引器时。

## 什么时候本地索引器是错误的工具

本地索引假定代码存在于查询它的那台机器上，而在真正的 monorepo 规模下，即便在单个编辑器内部，这个假设也会变得吃紧。这个仓库单纯就是大到你不想一直在笔记本电脑上保持热索引：你在一个包里工作，而影响范围却在三个目录之外，一次针对两百万行代码树的冷启动首次索引，不是你想经历两次的事——无论是在你自己的机器上，还是在一个从未克隆过这棵代码树的 CI 运行器上。或者，某个同事应该能查询你在用的同一张地图，而不必等自己的机器吃力地跑完同一个索引。

这些都不是丢弃一个好的编辑器索引器的理由。这是一个理由，说明你还应该拥有一张任何智能体都能通过 MCP 查询的托管地图。

而规模问题比“文件太多没法粘贴”要深得多。在一棵大代码树上，有意思的问题几乎从来不是“给我看这个文件”——而是哪个文件、哪个符号、哪些调用方、哪些测试。一个从列出 `src/` 并读取前三个结果开始的智能体，会心安理得地漏掉 `apps/api` 里的处理函数和 `packages/sdk` 里生成的客户端。你需要的是从整棵代码树构建、然后排序、然后带引用的检索。

## “大型仓库的上下文”到底意味着什么

把文件一股脑塞进提示词不是上下文——那只是代码树更小、更差的一份拷贝。你的智能体真正需要的是提出问题，并得到带引用的答案：这个符号定义在哪里、谁在调用它，我即将修改的模块有什么依赖它，哪个测试文件覆盖了这个行为，以及代码树*现在*是什么样子，而不是上个季度的样子。

这些答案必须来自一个基于你的仓库构建的索引，而不是模型对别人仓库的记忆，而且这个索引必须存在于智能体上下文窗口之外的某个地方。对这个问题来说，它也应该存在于你笔记本电脑之外的某个地方。

还有一件事，指令文件替你做不到：`CLAUDE.md` 和 `AGENTS.md` 是放置约定和行为规范的正确地方，但它们不是一张两百万行代码树的、活的、经过排序的、可查询的地图。行为用规则，事实用仓库智能。

## 在云端构建地图，从任何客户端查询它

Maguyva 是一个远程 MCP 代码库上下文层。你连接 GitHub，选择你的仓库，然后就可以放手，让云端流水线解析代码树、构建符号和图边、维护一张排序后的地图——永远不需要本地索引器。

当你推送代码时，变更的文件会被增量解析，图和排序层会按计划重建：免费方案每天一次，付费方案每小时一次。每份快照都带有时间戳，让你的智能体能分辨自己读到的是哪个版本的代码树。这里诚实的限制是未同步的本地工作——只存在于你工作树中、从未推送过的编辑，还不在托管地图里。

然后，你把 API 密钥添加到你已经在用的客户端的 MCP 配置中，完成接入。这里有 24 个有文档记录的 MCP 客户端的设置指南，任何支持标准配置的其他 MCP 兼容客户端也都能连接。如果 Cursor 是你的主场，[Cursor 页面](/zh-hans/for-cursor) 会带你走完那条路；同一个服务器也服务于 Claude Code、VS Code、Windsurf、Codex CLI 等等。

你不需要更换编辑器。你给智能体的是一整套工具界面——11 个 MCP 工具，涵盖搜索、符号、依赖分析、文件检索和仓库上下文——覆盖 279 种以上的语言和基于文本的技术，这在一个早已不再是单一语言的 monorepo 上，比你想象的更重要。

答案带着依据返回，以带行号的文件路径形式呈现。语义、结构、图和文本检索被融合成排序结果，所以像“什么依赖 parseConfig”这样的问题，得到的既不是一堆 grep 转储，也不是单一的语义片段，而是真正重要的那一小撮位置。

## 一份具体的操作指南

不要一上来就索引整个公司。以下是行之有效的路径：

1. 选一个你已经很熟悉的仓库——一个你能手动评判的包，胜过你手头最大的代码树。
2. 免费开始：3 个仓库，5 万行索引额度，全部 11 个工具，没有月度查询配额。如果你的代表性仓库比这更大，[定价页面](/zh-hans/pricing) 按已索引规模——而不是按席位数——列出了工作区档位（$0、$19、$49、$149）。
3. 连接 GitHub，等待首次索引完成。你没有在本地编译任何东西。
4. 接入 MCP 客户端——几行配置。Maguyva 是一个远程 MCP 服务器，所以没有插件、没有扩展，也不需要采用第二个编辑器。
5. 问一个你能核实的问题。“什么依赖 parseConfig?”或者“登录会话过期在哪里处理？”然后打开被引用的 `file.ext:line` 结果，对照眼前的代码树核对。
6. 只有在引用经受住那次核对之后，才让智能体去编辑。

如果第一个仓库合适，而你的代码树很大，就按你的已索引行数和重建节奏提升工作区规模。人类和智能体共享同一个用户数——Maguyva 按工作区计费，而不是按席位——所以往这个循环里再加一个智能体不会多花你一分钱。

激活测试和[文档](/zh-hans/docs)为任何首次运行推荐的一样：索引一个你已经了解的仓库，问一个你能核实的问题。大型仓库不会改变这个测试，只会让第一个选错的文件代价更高。

## 接入之后要留意什么

留意三件事。新鲜度：付费方案每小时重建，免费方案每天重建，未推送的本地工作不会出现在地图里——这是你接受的权衡。范围：索引一组有代表性的仓库，而不是每一个被归档的分叉仓库；免费档位是刻意设计成这个规模，让你先弄清楚这些答案值不值得留下。以及验证：一张无法引用路径和行号的大型仓库地图，只是一台更慢的猜测机器，所以在智能体交付补丁之前，让它先展示位置。

然后运行你在小仓库上会运行的同一个测试。索引一个你已经了解的仓库。问一个你能核实的问题。如果这张地图是真实的，你的智能体就不会再从一棵冷代码树开始。

`// no laptop got hot building this map.`