CodeBuddy需显式触发仓库结构索引、指定根目录与配置、启用Git元数据感知、注入自定义结构描述文件及强制刷新缓存，才能准确理解全仓库项目结构。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用CodeBuddy时发现其对项目逻辑的理解不够准确或上下文感知薄弱，可能是因为它尚未完整加载和解析整个Git仓库的目录结构与依赖关系。以下是让CodeBuddy准确理解全仓库项目结构的关键操作路径：
一、显式触发仓库结构索引
CodeBuddy默认不会自动扫描整个Git仓库，需主动调用结构识别指令，使其构建项目拓扑图并建立文件间语义关联。该过程将生成内部AST映射与模块依赖图，支撑后续跨文件推理。
1、在CodeBuddy对话框中输入指令：/analyze-project-structure
2、等待系统返回“Project graph built successfully”提示，表示已完成结构建模
3、随后可使用/show-dependency-map查看可视化依赖关系（以文本树状图形式输出）
二、手动指定根目录与配置文件
当项目存在多级子模块或非标准目录布局时，CodeBuddy可能因无法识别主入口而误判结构层级。通过显式声明项目锚点，可强制其以指定路径为根进行递归分析。
1、执行命令：/set-root-dir ./（若当前已在仓库根目录）
2、补充关键配置识别：/load-config-file pyproject.toml 或 /load-config-file package.json
3、确认响应中包含“Config loaded, structure inference updated”字样
三、启用Git元数据感知模式
CodeBuddy可通过读取.git目录下的HEAD、refs、objects等元数据，还原分支历史、提交粒度变更及文件重命名轨迹，从而增强对重构后结构的理解能力。此模式对识别迁移中的模块拆分或API演进尤为关键。
1、运行指令：/enable-git-metadata-mode
2、CodeBuddy将自动读取.git/config与.git/logs/HEAD，构建时间线索引
3、后续提问如“这个service层类在v2.3版本中是否被移入core模块？”即可获得基于Git历史的精准回答
四、注入自定义结构描述文件
对于高度定制化或未遵循通用规范的项目（如含私有DSL、混合语言子系统），可提供machine-readable结构说明，引导CodeBuddy跳过启发式推断，直接加载预定义架构视图。
1、在仓库根目录创建codebuddy-structure.yaml文件，内容包含modules、entrypoints、excluded_paths等字段
2、执行：/import-structure-spec codebuddy-structure.yaml
3、验证加载结果：/list-known-modules 应返回yaml中定义的全部模块名称
五、强制刷新上下文缓存
当项目结构发生重大变更（如重命名src为app、新增monorepo workspace）后，CodeBuddy可能仍沿用旧缓存导致理解偏差。此时需清除结构缓存并重建上下文快照。
1、发送指令：/clear-structure-cache
2、立即执行：/reindex-all-files --depth=4（--depth参数控制递归扫描深度）
3、检查日志末尾是否出现“Context snapshot updated with N files”（N为实际扫描文件数）
