要让codebuddy准确识别src、api、store、tests等目录关系，必须触发全量项目结构索引：先执行/analyze-project-structure直至提示“project graph built successfully”，再用/show-dependency-map查看依赖树；若失败需检查根目录并加载pyproject.toml或package.json；多模块项目需/set-root-dir或/load-config-file；重构项目应启用/enable-git-metadata-mode；自定义结构须导入codebuddy-structure.yaml并验证/list-known-modules。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你想让CodeBuddy准确识别项目里src、api、store、tests这些目录之间的关系，而不是只盯着当前打开的单个文件猜逻辑——这需要它真正“看见”整个Git仓库的骨架，而非靠片段推测。
触发全量项目结构索引
CodeBuddy默认不自动扫描整个仓库，必须手动唤醒它的结构建模能力。否则它只会基于当前文件做局部推理，跨文件修改时极易漏掉依赖项。
在CodeBuddy对话框中输入：/analyze-project-structure
等待界面返回“Project graph built successfully”提示。这一步不可跳过，没有该提示说明AST映射和模块依赖图尚未生成，后续所有跨文件操作都缺乏底层支撑。
完成后，执行/show-dependency-map可查看文本树状图形式的依赖关系。若输出为空或仅显示当前文件，则说明索引失败，需检查是否在正确根目录下操作。
强制指定项目锚点与配置文件
当项目含多级子模块、monorepo结构或自定义构建路径时，CodeBuddy容易误判主入口位置，导致结构层级错乱。此时需人工钉住分析起点。
方法一：设置根目录
执行命令：/set-root-dir ./（确保你当前已在Git仓库根目录）
方法二：加载关键配置文件
补全指令：/load-config-file pyproject.toml 或 /load-config-file package.json
这两类文件是CodeBuddy识别技术栈和模块边界的锚点，缺一不可。比如没加载package.json，它可能把TypeScript类型定义当成普通JS文件处理。
确认响应中出现“Config loaded, structure inference updated”字样，才代表配置已生效并触发二次结构推断。
启用Git元数据感知模式
重构过的项目常有文件移动、重命名或分支合并痕迹，仅靠当前快照无法还原真实演化路径。Git历史是理解“为什么这个service被拆进core包”的唯一依据。
第一步：运行指令
/enable-git-metadata-mode
第二步：CodeBuddy将自动读取.git/config与.git/logs/HEAD，构建时间线索引。此过程无需人工干预，但要求.git目录完整且未被清理。
第三步：验证效果
提问：“user.service.ts在v2.1分支中是否曾位于legacy模块？”若能精准定位到commit哈希与路径变更记录，说明Git元数据模式已激活。
注入自定义结构描述文件
对于使用私有DSL、混合语言子系统或非标准目录约定的项目，CodeBuddy的启发式推断会失效。这时必须用机器可读的yaml文件接管结构定义权。
① 在仓库根目录创建codebuddy-structure.yaml文件，内容必须包含modules、entrypoints、excluded_paths等字段；
② 执行：/import-structure-spec codebuddy-structure.yaml；
③ 验证：/list-known-modules应逐行返回yaml中定义的全部模块名称。
注意：该yaml文件一旦导入，CodeBuddy将完全忽略自动推断结果，所有上下文加载均以其中声明为准。若字段缺失或格式错误，导入会静默失败，不会报错提示。
