在 IDE 中集成 AI 代码补全插件后，最常见的故障不是模型本身不可用，而是插件调用模型接口后返回错误，开发者却拿不到足够信息判断问题出在哪一层。本文从工程排查角度，给出一套可复用的日志抓取与根因定位流程。

一、先开启插件调试日志

多数 AI 补全插件默认只输出 info 级别日志，错误堆栈和请求细节被过滤。排查第一步是把日志级别调到 debug 或 trace。

常见配置方式有三类：

  1. IDE 设置面板：在插件配置项中查找 Log Level、Debug、Verbose 等字段，改为 debug。
  2. 环境变量：部分插件读取 LOG_LEVEL=debug 或 AI_PLUGIN_DEBUG=1 之类的变量，重启 IDE 后生效。
  3. 配置文件：在插件目录下的 config.json / settings.json 中增加日志级别字段。

开启后需要确认日志输出位置。IDE 插件日志通常出现在：IDE 内置的 Output 面板、插件专属日志文件、系统临时目录下的插件日志目录。如果日志仍为空，先检查插件是否真正加载、IDE 版本是否满足插件最低要求。

二、抓取请求与响应体

仅有日志级别还不够，关键是拿到完整的 HTTP 请求和响应。需要关注四类字段：

  • 请求 URL 与 HTTP 方法：确认是否指向预期的模型服务端点，而不是被代理或配置覆盖后的地址。
  • 请求头：重点看 Authorization、Content-Type、User-Agent，以及自定义的租户或项目标识头。
  • 请求体：模型名称、prompt 长度、max_tokens、temperature 等参数是否合法。
  • 响应体：状态码、错误码、错误消息、request id。

如果插件不直接打印响应体，可以通过以下方式补充：

  • 在插件配置中开启“记录请求/响应”开关。
  • 使用系统级代理工具（如 mitmproxy、Charles）拦截 HTTPS 流量，但需处理证书信任问题。
  • 在本地起一个反向代理，把插件端点指向代理，由代理转发并落盘日志。

注意：请求体中可能包含代码片段，抓取和存储时要遵守团队的隐私与合规要求。

三、区分四类错误来源

拿到日志后，按错误特征归类，能大幅缩短定位时间。

1. 鉴权错误

典型表现：HTTP 401、403，错误消息含 invalid api key、unauthorized、token expired。

排查点：

  • API Key 是否过期、是否被撤销。
  • Key 是否被错误地加了空格或换行。
  • 请求头字段名是否正确，例如是 Authorization: Bearer xxx 还是自定义头。
  • 如果使用 OAuth 或临时凭证，检查刷新逻辑是否失败。

2. 网络与代理错误

典型表现：连接超时、DNS 解析失败、SSL 证书校验失败、ECONNREFUSED、ETIMEDOUT。

排查点：

  • 插件是否配置了代理，代理地址和端口是否可达。
  • 系统代理与插件代理是否冲突。
  • 企业网络是否拦截了模型服务域名。
  • 自签名证书场景下，插件是否支持关闭证书校验或导入 CA。

需要强调：关闭证书校验只应作为临时排查手段，不应作为长期方案。

3. 模型服务错误

典型表现：HTTP 400、422、429、500、503，错误消息含 model not found、rate limit、context length exceeded、invalid parameter。

排查点：

  • 模型名称是否拼写正确、是否在当前账号可用。
  • 请求参数是否超出范围，例如 max_tokens 过大、temperature 非法。
  • 是否触发速率限制或配额耗尽。
  • 上下文长度是否超过模型上限。

4. IDE 兼容性错误

典型表现：插件崩溃、补全不触发、日志中出现插件内部异常堆栈，但网络请求正常。

排查点：

  • IDE 版本是否在插件支持范围内。
  • 是否与其他插件冲突，尤其是其他 AI 补全或快捷键插件。
  • 插件依赖的运行时（Node、Python、JVM）版本是否匹配。
  • 工作区过大或文件类型不被支持时，补全可能被静默跳过。

四、推荐的排查顺序

按以下顺序推进，避免在错误层面反复试探：

  1. 确认插件已加载且日志级别为 debug。
  2. 复现一次报错，记录时间戳。
  3. 在日志中定位对应时间窗口的请求记录。
  4. 先看 HTTP 状态码，判断是鉴权、网络、模型服务还是插件内部错误。
  5. 若是鉴权问题，检查 Key 与请求头。
  6. 若是网络问题，检查代理、DNS、证书。
  7. 若是模型服务问题，检查模型名、参数、配额。
  8. 若以上均正常，转向 IDE 兼容性与插件冲突排查。

五、工程化建议

  • 在插件配置中固化日志级别开关，便于一键开启排查。
  • 对请求和响应做结构化日志，至少包含 request id、状态码、耗时、错误码。
  • 对敏感字段做脱敏，避免代码片段和 Key 泄露。
  • 在 CI 或本地开发环境提供代理配置模板，减少环境差异导致的误判。
  • 建立错误码对照表，把常见状态码映射到排查动作。

日志抓取的核心不是“看到报错”，而是拿到足够区分错误来源的证据。把日志级别、请求响应体、四类错误特征和排查顺序固定下来，AI 代码补全插件的集成问题就能从随机试错变成可重复的工程流程。