以下问题发生在安装与登录均正常的情况下，按具体功能模块分类排查。
5.2.1 行内补全不触发或延迟明显
- 现象：停止输入后无灰色虚影提示，或需等待数秒才出现建议。
- 排查与解决：
- 确认未开启"手动触发"模式。进入 设置 > 编辑器基础偏好设置，检查补全触发方式是否为"自动"。
- 观察当前文件类型。纯文本、日志文件或某些冷门配置文件可能不在默认支持范围内，尝试在
.js、.py、.java等主流代码文件中测试。 - 若文件体积过大（超过数千行），模型定位上下文耗时增加，属于正常现象。尝试在函数内部而非文件顶部触发。
- 网络延迟高时，建议切换到"极速模型"作为行内补全专用模型，或检查本地代理是否分流了 API 请求。
5.2.2 侧边栏对话无响应或报错
- 现象：发送消息后持续转圈，或返回"请求失败""服务繁忙"等提示。
- 排查与解决：
- 先测试最简单的输入（如"你好"）。若简单输入能回复，说明服务正常，是上一轮超长上下文导致超时。点击对话顶部的 清空上下文 或 开启新会话 后再试。
- 若所有消息均无响应，进入 设置 > 模型设置，临时切换至另一个可用模型（如从深度模型切到均衡模型），确认是否为当前模型节点异常。
- 检查账号是否掉线。侧边栏头像处若显示"未登录"或"授权过期"，退出后重新登录。
- 企业内网用户需确认防火墙未拦截对话接口域名，可联系 IT 放行或切换至外部网络测试。
5.2.3 上下文引用（@文件/目录）失效
- 现象：使用
@文件名或@目录名后，AI 仍表示"未看到相关代码"或引用内容明显不完整。 - 排查与解决：
- 确认文件已保存且位于当前打开的工作区/项目内。若文件处于未保存的临时标签页，引用可能失效。
- 检查
@后的名称是否准确。建议输入@后等待下拉列表弹出，直接选择目标文件，避免手输路径错误。 - 单文件体积过大（如超过数百 KB 的日志或生成的 JSON）可能触发长度截断。此时先精简文件内容，或将关键代码片段复制到对话中直接粘贴。
- 若
@目录后 AI 对项目结构描述错误，可能是本地索引未更新。完全关闭客户端或重启 VS Code 后重新加载窗口。
5.2.4 代码生成/重构结果质量差
- 现象：生成的代码包含明显语法错误、使用了不存在的 API，或重构后逻辑被破坏。
- 排查与解决：
- 检查当前选用的模型。复杂逻辑生成或跨文件重构时，若使用"极速模型"，容易出现细节遗漏。切换至"均衡模型"或"深度模型"后重试。
- 补充更精确的上下文。在请求前用注释或自然语言说明目标语言的版本、使用的框架版本，以及特殊约束（如"不要引入新依赖""兼容 Java 8"）。
- 对于重构任务，建议先让 AI 输出"修改方案"供你确认，再执行实际代码替换，避免直接采纳全量重构结果。
- 若结果始终偏离预期，使用
Ctrl + Z撤销，并在下一轮对话中明确指出上一次的具体错误（如"上次的代码没有处理空指针"），利用多轮对话修正。
5.2.5 项目级功能卡顿或超时
- 现象：点击"项目结构梳理""全库排查"后长时间无结果，或提示"处理超时"。
- 排查与解决：
- 项目根目录若包含大量非代码文件（如
node_modules、build、dist、日志文件、视频资源），会严重拖慢索引速度。在设置中配置 排除目录 或.cbignore文件（如有），将这些目录加入忽略列表。 - 首次加载大型项目时，建立索引需要一定时间，建议等待 1–3 分钟。后续再次操作会明显加快。
- 跨文件批量修改建议分批进行，先选中相关目录而非整个项目根目录，减少单次处理的文件数量。
- 若频繁超时，可尝试将任务拆分为"先列出需要修改的文件列表"，再针对具体文件逐个处理。
5.2.6 VS Code 插件版特定异常
- 现象：侧边栏空白、快捷键失效、生成的代码无法插入到编辑器。
- 排查与解决：
- 面板空白：在 VS Code 中按
Ctrl+Shift+P/Cmd+Shift+P，执行 "Developer: Reload Window" 重载窗口。若仍空白，检查是否与其他 AI 编程插件冲突，尝试暂时禁用其他同类插件。 - 快捷键失效：进入 VS Code 的键盘快捷键设置，搜索"CodeBuddy"，查看是否被其他扩展占用，或重新绑定常用快捷键。
- 无法插入代码：确认当前编辑器处于可编辑状态（非只读模式、非差异对比视图）。在差异对比视图中，部分一键替换功能会被禁用，需手动复制代码粘贴。
- 插件升级后异常：在扩展面板卸载 CodeBuddy 插件，完全关闭 VS Code 后重新安装，可清除本地缓存状态。