许多开发者在实际使用CodeBuddy时可能会注意到一个现象：有时它能精准把握项目的整体架构，实现跨文件函数修改、接口自动同步，甚至能依据代码历史调整命名规范；而有时它的回答似乎仅局限于当前打开的文件。这其中的核心差异，关键在于是否成功激活了“仓库级上下文理解”功能。
简而言之，这项能力使CodeBuddy从一个高效的代码补全工具，升级为真正理解项目架构的智能开发伙伴。它不再局限于分析单个文件，而是能够俯瞰整个代码库的关联脉络。接下来，我们将系统梳理如何确认并启用这项核心能力。
一、确认项目上下文加载状态
首先需要明确，CodeBuddy的仓库理解功能并非自动启用，需要开发者主动为其提供完整的项目结构信息。如果仅加载了当前文件，其分析视野自然会受到限制。
如何确认当前状态？可通过以下步骤：
1. 在VS Code中，请确保打开的是项目根目录（即包含package.json、pyproject.toml等标志性配置文件的文件夹）。
2. 点击左侧活动栏的CodeBuddy图标，查看右下角状态栏提示。若显示“✅ 已加载 [项目名称] 上下文”，则表示成功加载；若显示“⚠️ 仅当前文件”，则说明尚未获取完整项目视图。
3. 遇到后一种情况时，可手动触发全量索引：在项目根目录右键，选择“CodeBuddy: Load Project Context”。等待片刻，让工具完成项目结构的全面解析。
二、启用MCP协议增强上下文感知
加载项目文件仅是基础步骤。要让CodeBuddy深度理解文件间的依赖关系、构建配置等复杂关联，需要借助MCP（模型上下文协议）。该协议相当于为CodeBuddy构建了结构化的项目知识图谱。
具体配置路径如下：
1. 进入CodeBuddy高级设置：点击插件界面右上角的齿轮图标，选择“Advanced Settings”。
2. 找到并启用“Enable MCP Context Injection”选项。
3. 在终端执行命令：codebuddy mcp init --auto-discover。此命令将自动识别项目中的各类配置文件（如tsconfig.json、webpack.config.js等），并将相关路径信息注入上下文，显著提升模型理解的准确性。
三、通过Craft模式验证跨文件推理能力
Craft模式是检验仓库级理解是否生效的关键场景。该模式专为处理涉及多文件的复杂开发任务而设计。
可通过以下方式测试：
1. 在Craft模式输入框中，提交需要跨文件协作的需求。例如：“为用户管理模块增加手机号验证功能，需同步更新后端API接口定义、数据库迁移脚本以及前端表单验证逻辑。”
2. 提交后观察生成结果。若CodeBuddy一次性提供src/api/user.ts、migrations/202405_add_phone_to_users.py、src/components/UserForm.vue等多文件修改方案，则证明其已准确理解模块关联。
3. 若仅生成单个文件代码，可追加指令引导：“请先分析现有用户模块涉及的所有相关文件。”这将强制触发其对项目依赖关系的全面扫描。
四、检查模型选型对上下文窗口的支持
仓库级理解功能需要模型具备足够的“记忆容量”（即上下文窗口）来容纳项目摘要信息。不同模型在此方面的能力差异显著。
1. 最直接的方式是在Chat模式中询问：“当前使用的模型是什么？上下文长度限制是多少？”
2. 查看回复信息中的“context_window_size”字段数值。若大于等于10万tokens，通常可满足中等规模项目的需求；若远低于此数值，可能无法容纳完整项目摘要。
3. 若发现容量不足，建议在设置中切换模型。选择如“混元Pro-128K”或“DeepSeek-V2-Rag”等明确支持超大上下文的版本，可获得更佳体验。
五、验证Git历史集成能力
真正理解代码仓库的智能助手，不仅需要掌握代码现状，还应了解其演进历史。CodeBuddy通过读取Git历史记录，能够帮助开发者理解代码变更逻辑，例如“此函数为何被标记为废弃？”或“上次修改这行配置的原因是什么？”
验证方法如下：
1. 确保项目已初始化Git仓库，并存在有效的提交记录。
2. 在Chat模式中，尝试提出关于历史修改的问题。例如：“分析src/utils/date.js文件最近三次修改的原因及其影响范围。”
3. 若回答中包含具体的提交哈希值、作者信息、提交消息关键词，甚至能引用diff片段，则表明Git历史集成功能已正常启用。这意味着CodeBuddy不仅能编写新代码，还能协助梳理代码演进脉络。
完成以上五个步骤的验证与配置后，即可确保CodeBuddy处于功能完整状态。此时再处理代码重构、跨模块开发等复杂任务时，其表现将更加连贯智能，真正成为理解项目上下文的开发协作伙伴。