Monorepo项目代码补全策略：CodeBuddy多包工程实战指南
当你在monorepo项目中使用CodeBuddy时，如果遇到跨包代码补全失效、类型推导错误或依赖路径解析混乱，问题根源通常在于工具未能正确识别整个工作区，其分析范围仍被限制在单个包内。
要解决此问题，使AI助手能够透彻理解你的复杂项目结构，可以依次尝试以下解决方案。
一、启用多包上下文感知模式
CodeBuddy的默认行为是仅分析当前打开的文件，这在单一代码库中运行良好。但在monorepo架构下，各包之间存在紧密的依赖关系，若工具无法感知其他包，自然无法提供准确的智能提示。
首先，你需要确保项目根目录下存在工作区配置文件，例如 pnpm-workspace.yaml、lerna.json 或 nx.json。这是CodeBuddy识别monorepo结构的基础。
随后，进入CodeBuddy设置面板，找到 “Context Awareness Level” 选项。将其从默认设置调整为 “Workspace-wide”。此操作将扩展工具的扫描范围，使其覆盖工作区内的所有包。
修改设置后，重启你的集成开发环境。稍等片刻，若状态栏出现类似 “Monorepo context loaded (X packages)” 的提示，即表示多包上下文已成功加载。
二、手动注册包内导出声明
当子包的导出方式较为特殊时（例如未使用统一的 index.ts 文件，或目录结构非标准），自动解析可能失败。此时，你需要手动为CodeBuddy提供一份导出声明映射。
在项目根目录下创建 .codebuddy/exports.json 文件。该文件用于明确告知CodeBuddy每个包对外暴露功能的入口文件。
文件格式为JSON对象。键为包名称，值为一个数组，列出该包内所有公开API的入口文件路径。示例如下：
{"@myorg/ui": ["src/components/index.ts", "src/hooks/index.ts"], "@myorg/utils": ["src/index.ts"]}
保存文件后，在终端执行 codebuddy reload-exports 命令。这将强制CodeBuddy依据你提供的映射关系，重新加载所有包的导出信息。
三、配置 TypeScript 项目引用（Project References）
对于TypeScript项目，可以利用其原生的Project References机制来显著提升跨包类型推导的准确性。该机制专为管理多项目间的类型依赖而设计。
首先，确保monorepo中每个子包的 tsconfig.json 文件都包含 "composite": true 字段，这将其标记为可独立构建的复合项目。
接着，在根目录的 tsconfig.json 中，通过 "references" 数组列出所有子包配置文件的路径，从而构建出完整的项目依赖图。
同时，检查每个子包 package.json 中的 "types" 字段，确保其指向正确的类型声明文件（例如 "types": "./dist/index.d.ts"）。
最后，执行一次 tsc --build 命令。此操作不仅完成增量编译，还会触发CodeBuddy加载项目引用图，从而大幅优化跨包的类型提示与代码导航体验。
四、使用 Craft Mode 进行跨包代码生成
前述方法主要优化了智能补全与提示。对于需要跨包协同创建新功能的复杂场景，例如新增一个共享Hook并立即在另一个包的组件中消费，传统的上下文补全难以胜任。
此时，应启用CodeBuddy的 Craft Mode。该模式允许你通过自然语言指令，驱动跨多个包和文件的代码生成流程。
设想以下场景：在编辑器中输入指令：
/craft add useAuthState hook to @myorg/utils and consume it in @myorg/ui/LoginPage
确认后，CodeBuddy将执行以下操作：分析整个工作区的依赖关系，定位到 @myorg/utils 和 @myorg/ui 两个目标包；在工具包中生成 useAuthState.ts 实现文件并更新其导出文件 index.ts；同时在UI包的 LoginPage.tsx 中插入调用代码。
最关键的是，所有生成的代码在呈现前，都会经过 tsc --noEmit 的类型检查，确保其正确性，有效避免了基础错误。
五、禁用隔离沙箱以启用全局符号索引
在使用Nx等高级构建工具的项目中，为了确保构建的确定性与速度，默认会启用“隔离沙箱”环境，导致每个包的构建过程相互独立。
这会造成一个问题：CodeBuddy在运行时可能无法访问其他包的源代码树，因而无法建立完整的符号索引。
解决方案是进入IDE设置，找到CodeBuddy的 “Execution Environment” 相关选项，将 “Isolation Mode” 设置为 “Disabled”。
对于Nx工作区，通常还需要在终端执行清理与重建索引的组合命令：npx nx reset && codebuddy rebuild-index。
完成后，观察日志输出。若出现 “Global symbol index built: X symbols from Y packages” 信息，则表明全局符号索引已成功构建，跨包开发的流畅度将得到显著提升。
本质上，让AI编码助手在monorepo中高效工作的核心，是赋予其完整的“全局视野”。上述策略涵盖了从自动配置、手动映射、利用TypeScript工具链到启用高级代码生成模式的完整路径，可根据你的具体项目架构组合应用，以解决绝大多数跨包协作的难题。