在大型单体仓库中，代码检索慢不一定是模型或机器性能不足，更常见的原因是索引范围过大、切分方式不合理，或者索引更新不及时。OpenCode 接入代码库索引后，真正需要平衡的是两个指标：检索延迟决定开发者多久能看到结果，文件召回率则决定相关代码是否会被遗漏。
索引策略为何会成为性能瓶颈
大型单体仓库通常包含业务源码、公共组件、测试、文档、构建产物、依赖缓存和历史生成文件。若对所有目录进行无差别索引，文件扫描、语法解析、文本切分、向量生成以及索引写入都会产生额外开销。索引规模扩张后，候选结果也会增加，检索阶段需要执行更多匹配和排序，延迟自然上升。
以可供 OpenCode 使用的 open-codebase-index 为例，其检索机制组合了嵌入向量、BM25 关键词索引、符号查询和调用图，并支持文件监听、内容哈希复用及增量索引。多路检索有助于覆盖自然语言问题、精确标识符和依赖关系，但不同索引通道也意味着更多存储与维护成本，具体能力可参考项目说明。
索引范围直接影响延迟与召回
全仓索引通常具有较高的理论召回上限，因为冷门模块、脚本和跨项目公共代码也能进入候选集。不过，它会把大量低价值内容一并纳入，例如压缩文件、锁文件、覆盖率报告和编译输出。这些内容不但增加初次构建时间，还可能在检索时挤占候选位置。
白名单索引只处理指定源码目录和文件类型，索引更小，查询一般更容易保持稳定，但配置过窄会漏掉配置文件、接口定义、数据库迁移和内部文档。对大型单体仓库而言，更实用的做法通常是“源码默认纳入，噪声明确排除”，而不是只列出少数核心目录。
排除规则应重点覆盖依赖目录、构建产物、缓存、日志、大型压缩文件以及可自动生成的代码。同时要注意，Git 的忽略规则存在来源和优先级差异，而且已被 Git 跟踪的文件不会仅因加入忽略规则就自动消失，相关语义可查看 Git 官方文档。索引器是否完全沿用这些规则，则应以实际配置和版本说明为准。
切分粒度决定“找得准不准”
索引器通常不会把整个文件作为单个检索单元，而是切分为函数、类、语法节点或固定行数片段。切分过大时，一个向量会混合多种语义，查询虽然可能命中文件，却难以定位真正相关的实现，同时返回内容也会占用更多上下文。切分过小时，函数签名、注释与实现可能被拆散，导致语义不完整。
大型单体仓库更适合优先采用语法感知切分，在解析失败或不支持的文件类型上再使用按行切分。对于配置文件、文档和生成代码，可以采用不同的块大小。切分策略不必全仓统一，按语言和目录分层配置，往往比不断增大检索候选数量更有效。
增量索引决定结果是否新鲜
全量重建虽然简单，但在大型仓库中容易形成较长的不可用窗口。基于文件监听、修改时间或内容哈希的增量策略，只处理新增、修改和删除的文件，可显著减少重复计算。内容哈希还能避免文件时间变化但内容未变时重复生成索引。
增量机制的风险是状态漂移。例如切换分支后旧文件未清理、重命名被识别为新增但原记录仍保留，或者监听器遗漏批量变更，都可能产生过期结果。因此，应在日常使用增量更新的同时，为分支切换、索引版本升级和配置规则变更设置强制校验或定期重建机制。
混合检索比单一路径更稳健
精确搜索函数名、错误码和配置键时，关键词或符号索引通常更直接；查询“重试逻辑在哪里处理”这类意图时，语义检索更有优势；分析调用关系时，则需要符号和图结构提供补充。混合检索可以提高召回率，但应控制每一路返回的候选数，再进行去重、路径加权和统一排序，避免延迟随候选集合无限增长。
排序阶段还可加入仓库结构信息，例如提高当前工作目录、同一工作区和直接依赖模块的权重，但不应彻底屏蔽远端目录。较稳妥的方法是保留少量全仓候选作为兜底，从而兼顾局部响应速度与跨模块召回。
如何用可重复测试调整策略
- 准备多类真实查询，包括精确符号、自然语言描述、配置定位、调用关系和跨项目公共组件。
- 分别记录首次查询与缓存命中后的延迟，并观察中位数和高分位，而非只看单次最快结果。
- 使用已知相关文件集合计算召回情况，重点检查前若干条结果是否包含目标文件。
- 每次只修改一个变量，例如排除规则、切分大小或候选数量，避免无法判断优化来源。
- 把误命中的目录加入噪声清单，把经常遗漏的文件类型加入召回清单，持续修订索引配置。
总结
OpenCode 在大型单体仓库中的检索表现，本质上取决于索引覆盖、切分粒度、更新机制和排序策略的共同作用。范围过宽会增加延迟和噪声，范围过窄又会损害文件召回率。更可靠的实践是按目录与语言分层索引，明确排除低价值内容，采用语法感知切分和增量更新，再通过混合检索保留全仓兜底。最终配置不应依据主观感觉决定，而应使用真实查询集持续测量，让检索速度与召回质量保持可验证的平衡。
