CodeBuddy 的增量索引功能并非需要手动开启的开关，它默认在后台持续运行。然而，其实际效果很大程度上取决于项目的结构、使用的编程语言以及配置的完整性。真正需要您主动关注和调整的，是触发条件、索引覆盖范围以及语义理解的深度——尤其当您处理大型或结构复杂的工程时，对这几个方面的思考就显得至关重要。

接下来，我们先梳理几个关键要点，检查您的项目环境是否已为增量索引做好准备。

确认项目已支持增量索引

对于 C++、TypeScript、JavaScript（包括 monorepo 架构）以及 Python 等主流编程语言，CodeBuddy 默认启用了增量索引机制。但要使其真正生效，需要满足以下几个前提条件：

• 项目根目录下必须包含标准的构建或配置文件，例如 CMakeLists.txt、tsconfig.json 或 pyproject.toml。这些文件相当于索引的“导航地图”。
• IDE 必须能够正确识别当前的语言工程。例如，在 VS Code 的状态栏上，您应该能看到该项目被识别为 TypeScript 或 C++ 工程。
• 最关键的是，您没有在配置中主动禁用索引。请检查设置，如果存在 "indexing.enabled": false，则增量索引功能将无法生效。

以上几点是增量索引生效的基础，缺一不可。

调高索引精度与响应速度

如果您正在处理包含 500 个以上头文件的大型 C++ 项目，则可以考虑主动优化符号索引的行为，以获得更高的精度和响应速度：

• 在 IDE 的设置中，找到并启用 “工程理解智能体 Plus” 模块。该功能可能位于 Settings → Advanced → Engineering Agent 等路径下，不同版本名称可能略有不同，但其核心作用是增强对复杂结构的理解能力。
• 确保 PIMPL 惯用法、前向声明以及多层命名空间等常见 C++ 结构能够被正常识别。实际上，您无需过多担心，CodeBuddy 会自动扫描 class X; 和 namespace A::B 等语法，无需额外手动指令。
• 完成首次全量索引后，后续每次编辑的符号响应延迟将稳定保持在 180ms 以内。这一性能由系统自动维持，无需手动刷新或重启。

monorepo 场景下的跨包增量索引

当项目采用 pnpm、Nx 或 Lerna 等工具管理，并包含多个子包时，情况会相对复杂。要实现真正的跨包增量更新，您需要扩展 CodeBuddy 的上下文感知范围：

• 在 IDE 或编辑器设置中，将 Context Awareness Level 选项调整为 Workspace-wide，而非默认的 File 或 Package 级别。这是实现跨包协同的基础。
• 在项目根目录下手动创建并配置 .codebuddy/exports.json 文件。在该文件中，您需要显式声明每个子包的导出路径。这一步十分关键，可有效避免因 re-export 不规范而导致的索引断裂。
• 对于 TypeScript 项目，建议为每个子包的 tsconfig.json 启用 "composite": true，并在根目录的 tsconfig.json 中配置好 "references"。这样一来，CodeBuddy 可以复用 tsc 自身的增量构建图，显著提升索引效率。

CLI 环境下验证与调试索引状态

如果您更习惯使用命令行，CodeBuddy 的 CLI 工具同样提供了实时查看和调试索引状态的功能：

• 执行 codebuddy status --index 命令，可获取当前索引的全局状态，包括是否已加载、文件总数以及最后更新时间。
• 如需排查具体问题，可添加 --debug 参数启动，例如 codebuddy --debug。此时控制台会输出详细的符号解析日志，告知您哪些头文件或模块未被正确索引。
• 如果发现某类文件长期未被纳入索引（例如自动生成的 .gen.h 文件），您可以通过 --add-dir 参数手动追加扫描路径，例如：codebuddy --add-dir ./generated。