codebuddy在monorepo中索引失效需四步修复：①确认存在pnpm-workspace.yaml/lerna.json/nx.json之一；②将上下文感知设为workspace-wide并重启ide；③手动配置.exports.json或执行codebuddy reload-exports；④启用ts project references并禁用isolation mode后强制重建索引。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在大型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配置未被正确识别，请回查第一步。
手动注册关键包导出路径
当自动解析无法识别子包公共API入口时（例如子包使用非标准导出方式、或index.ts未统一re-export），索引会遗漏核心类型定义，补全质量断崖式下降。
方法一：创建.exports.json声明文件
在项目根目录下新建.codebuddy/exports.json，按JSON格式填写需显式暴露的包及其导出路径：
{"@myorg/ui": ["src/components/index.ts", "src/hooks/index.ts"], "@myorg/utils": ["src/index.ts"]}
注意：路径必须是相对根目录的绝对路径，且指向真实存在的TS文件；若路径错误，CodeBuddy不会报错但该包将完全不参与索引。
方法二：执行重载指令
保存文件后，在终端执行codebuddy reload-exports命令。此操作无需重启IDE，但仅对已加载的缓存生效；若此前未完成首次索引，需先触发一次完整构建。
配置TypeScript项目引用
利用TS原生的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”后，跨包跳转与补全即可恢复连贯性。
