在进行接口调试时，如果项目经历重构、迁移或框架升级等重大变更，目录结构、入口文件和依赖关系都会发生实质性变化。此时，CodeBuddy 原有的项目理解会完全失效。如果你继续执行 /init 或输入自然语言指令，AI 很可能会生成错误的路径、调用已不存在的模块，或者遗漏新接入的中间件。简单来说，只有重新初始化，才能让 AI 准确识别当前项目的真实结构与状态。

确认是否真的需要重新初始化

首先执行 /status 命令，查看当前项目的解析状态。如果输出中 【Project Root】 的路径与终端当前工作目录不一致，或者 【Detected Framework】 显示为 "Unknown" 或明显过时（例如仍然显示 Express 3.x，而实际已迁移到 FastAPI），则说明上下文已经失效，必须重置项目解析。

这一步不要嫌麻烦直接跳过——一旦误判，后续所有操作都将建立在错误的结构基础上，改动越多错误越深，最终白费力气。

彻底清除旧上下文缓存

CodeBuddy 的项目理解缓存存储在本地，仅靠重启 IDE 或切换目录无法清除。需要手动执行以下操作：

在项目根目录下运行命令：rm -rf .codebuddy/.cache

这一步不能省略。缓存残留会导致 /init 命令抓取到旧索引，无法扫描当前文件。例如，你新添加了 src/ 目录，但旧缓存仍然指向 legacy/，那么 AI 会完全忽略新结构，该识别的接口一个都识别不出来。

执行全新项目初始化

首先将终端当前工作目录切换到真正需要调试的项目根目录——即包含 package.json、pyproject.toml 或 server.js 的那一层。

然后在 CodeBuddy 交互界面中输入：/init

系统将自动扫描全部文件，识别语言、框架、API 路由定义文件（例如 routes/、controllers/）、配置入口（如 config/index.ts）、测试目录（test/ 或 __tests__/）。扫描完成后会生成一份结构摘要，大致内容如："检测到 3 个 RESTful 路由文件，2 个 Swagger 定义，1 个统一错误处理器"。

完成这一步后，你再输入接口调试指令——例如"调用 /v2/users/list 接口并验证返回字段"——AI 才能准确定位到 handler 文件、构造正确的 mock 请求体、注入所需的环境变量。否则，所有指令都等于瞎指挥。