大型 Monorepo 项目中使用 CodeBuddy 时，最令开发者头疼的问题之一便是语义索引——构建缓慢、卡顿甚至直接失败，跨包补全失效、类型推导不准、跳转失灵，开发体验直线下降。这通常并非模型能力不足，而是索引范围与上下文加载策略未能适配仓库规模所致。
针对这一问题，有一套经过验证的四步修复方案。踩过坑之后就会发现，每个步骤都有其存在的道理。
启用 Workspace-wide 上下文感知模式
CodeBuddy 默认以单文件为单位解析语义，这在小型项目中尚可应对。但面对一个包含数十个子包、数万文件的 Monorepo，这一默认配置就显得力不从心了——必须强制扩展它的理解边界。
第一步虽然基础但容易被忽略：确认项目根目录存在有效的 workspace 配置文件。pnpm-workspace.yaml、lerna.json 或 nx.json，三者至少得有一个。如果缺失，后续所有上下文配置都将被忽略。
第二步，打开 VS Code 或 JetBrains IDE 的 CodeBuddy 设置面板，将“Context Awareness Level”选项从默认的“File-scoped”切换为“Workspace-wide”。此操作会触发全量符号扫描的启动信号，但不会立即执行——需要第三步配合。
第三步：重启 IDE。然后留意右下角状态栏，当出现“Monorepo context loaded (X packages)”的提示时才算成功（X 代表实际识别出的子包数量）。如果长时间无响应或显示 0，说明 workspace 配置未被正确识别，需要返回第一步检查。
手动注册关键包导出路径
自动解析有时会失灵，尤其是当子包采用非标准导出方式，或者 index.ts 未统一进行 re‑export 时。这种情况下，索引会遗漏核心类型定义，补全质量断崖式下降。
解决途径有两个。方法一：在项目根目录下新建 .codebuddy/exports.json，明确写出需要显式暴露的包及其导出路径。格式如下：
{
"@myorg/ui": ["src/components/index.ts", "src/hooks/index.ts"],
"@myorg/utils": ["src/index.ts"]
}
注意路径必须是相对根目录的绝对路径，且指向真实存在的 TS 文件。如果路径写错，CodeBuddy 不会报错，但该包将完全不参与索引——这一点较为隐蔽，值得留意。
方法二更直接：保存文件后，在终端执行 codebuddy reload-exports 命令。该操作无需重启 IDE，但只对已经加载的缓存生效。若之前尚未完成首次索引，则需先触发一次完整构建。
配置 TypeScript 项目引用
TypeScript 原生提供了 project references 机制，CodeBuddy 可以借助这一机制复用 tsc 的增量构建图，避免重复解析依赖类型。如此一来，首次索引时间能大幅缩短，跨包精度也会提升。
操作分四步：
① 为每个子包的 tsconfig.json 添加 "composite": true 字段，确保其可被引用。
② 在根目录 tsconfig.json 的 "references" 数组中，逐条写入各子包的 tsconfig 路径。例如：
{"path": "./packages/ui/tsconfig.json"},
{"path": "./packages/utils/tsconfig.json"}
③ 运行 tsc --build 命令完成首次全量编译。这一步不可跳过，否则 CodeBuddy 无法加载项目引用图。
④ 编译成功后，CodeBuddy 会在后台自动识别并加载该图。后续索引将直接复用 tsc 生成的 .d.ts 和 .tsbuildinfo 文件，效率提升明显。
禁用 Isolation Mode 并重建索引
Isolation Mode 默认处于开启状态。其设计思路是将每个子包当作独立沙箱运行，安全性虽然提升，但同时也彻底切断了包间的语义关联。在 Monorepo 中，这实际上是一种反模式。
解决方法很简单：打开 CodeBuddy 设置面板，关闭“Isolation Mode”开关。随后执行 codebuddy rebuild-index --force 命令，强制清除旧缓存，基于当前 workspace 配置重建全局索引。
等到终端输出“Index rebuilt for N packages, total files: M”的信息后，跨包跳转与补全功能基本就能恢复连贯性了。
