错误处理与恢复

了解如何解读、响应和报告错误，有助于你在使用 Verdent for VS Code 时保持高效的开发会话。

你将学到

常见错误类型及其成因
如何有效解读错误信息
系统化的排查步骤
何时该等待、何时该采取行动
如何向 Verdent 团队报告问题

常见错误类型

完整的错误文档正在编写中。以下内容涵盖了最常遇到的错误类别。如遇特定错误场景，请联系 support@verdent.ai 或访问 Discord 社区。

服务器过载错误

在高流量时段发生
临时性容量限制
应对：等待 5-10 分钟后重试

内部服务器错误

后端处理问题
临时性服务中断
应对：等待后重试，通常会自动恢复

503 服务不可用

没有可用的健康上游服务器
临时性基础设施问题
应对：等待服务恢复

速率限制错误

超出请求配额
API 限流保护
应对：等待速率限制重置，降低请求频率

凭证无效或已过期
会话超时问题
应对：通过 User Center 重新认证，确认套餐处于有效状态

网络连接问题
防火墙或 VPN 阻断连接
企业网络限制
应对：检查网络连接，尝试切换网络

设置或偏好无效
配置文件损坏
应对：检查近期的设置变更，验证配置

文件系统权限不足
工作区访问受限
应对：检查文件/文件夹权限，验证工作区访问权限

解读错误信息

详细的错误信息解读指南正在开发中。如遇到特定错误信息，请使用反馈按钮或 Discord 社区寻求帮助。

服务器端错误是临时性的，通常等待即可解决。除了几分钟后重试外，无需其他操作。

留意这些关键词：

"Overloaded" 或 "at capacity"（过载或容量已满）
"Internal server error" 或 "backend processing"（内部服务器错误或后端处理）
"503 Service Unavailable" 或 "no healthy upstream"（503 服务不可用或无健康上游）
"Rate limit" 或 "quota"（速率限制或配额）

应对方法：

等待 5-10 分钟后再重试
继续本地开发工作
检查目前已做的代码改动
将当前工作提交到 Git

通用规则： 如果错误信息提到服务器状态、容量或速率限制，则属于临时性问题。这些是会自动解决的基础设施问题。

临时性服务器错误（502、503、504）通常会在几分钟内解决。请等待 2-3 分钟后再重试。

何时升级处理：

错误持续超过 15 分钟
在 Discord 上查看是否有故障报告
留意状态页的更新

客户端错误需要你采取行动，等待无法解决这类问题。

留意这些迹象：

与身份认证或凭证相关的信息
配置或设置错误
文件权限错误
网络连接失败

应对方法：

身份认证错误：通过 User Center 重新认证，确认套餐处于有效状态
配置错误：检查近期的设置变更，验证配置文件
权限错误：检查文件/文件夹权限，验证工作区访问权限
网络错误：测试网络连接，尝试切换网络，检查 VPN/防火墙

通用规则： 如果错误提到身份认证、配置、权限或本地设置，你需要采取纠正措施。

排查步骤：

阅读完整的错误信息以获取具体指引
确定是哪个组件报告了错误（认证、配置、权限、网络）
根据错误类型采取针对性行动
重试原始操作以验证修复效果

阅读错误上下文

当错误发生时：

阅读完整的错误信息 —— 不要跳过细节
记下错误代码 —— 特定代码有助于诊断问题
识别相关组件 —— 是哪个系统报告了错误（服务器、API、本地）
检查发生时机 —— 是立即发生，还是延迟后发生？

系统化排查

当 Verdent 出现异常行为时，请按以下渐进式步骤操作，从干扰最小的行动开始。

初步响应

等待并观察

检查该行为是持续性的还是间歇性的。记下是哪个操作触发了异常行为。不要立即认定出了故障——许多问题都是临时性的。

基础重启

重启 Verdent for VS Code（关闭并重新打开 VS Code）。通常能解决卡顿状态或性能问题。这是最简单的首选排查步骤。

渐进式排查

如果基础重启无法解决问题：

请按顺序执行系统化排查步骤，跳过步骤往往意味着错过根本原因。

检查网络连接

用其他网站测试网络连接。尝试切换到不同网络（手机热点），以排除防火墙/VPN 问题。检查企业网络是否阻断了连接。

验证配置

确认你仍处于已认证状态。在 User Center 中验证套餐是否有效。检查可能影响行为的近期设置变更。

寻求帮助

在 Discord 社区中查看是否有类似报告：https://discord.com/invite/NGjXEZcbJq。使用反馈按钮报告问题。请附上对异常行为的描述以及复现步骤。

不应做的事

对于临时性问题，请避免以下操作：

不要立即重装 Verdent
不要清除 VS Code 缓存或应用数据
不要为临时性问题修改系统设置
除非其他应用也受影响，否则不要重启电脑

在手动接受模式下，切勿在未仔细审查确切命令的情况下批准破坏性操作（rm、DROP、DELETE）。

为什么？ 这些操作耗时且很少能解决问题。大多数问题只需简单重启，或等待临时性服务器问题自行恢复即可解决。

何时等待 vs 何时行动

理解该等待还是该采取行动，可以避免浪费排查精力。

这些错误会自动解决——除了等待和重试外无需任何操作。

服务器过载或容量错误：

"Overloaded" 或 "at capacity"（过载或容量已满）信息
高流量时段
临时性服务中断

速率限制：

"Rate limit" 或 "quota exceeded"（速率限制或配额超出）信息
短时间内请求过多
API 限流保护

间歇性连接问题：

偶发的请求失败，重试后成功
网络抖动
短暂的连接中断

等待期间可以做什么：

继续本地开发工作
检查目前已做的代码改动
规划后续步骤或待办事项
将当前工作提交到 Git

应等待多久：

标准等待：5-10 分钟
如果 10 分钟后仍然失败，转入排查流程
在 Discord 上查看是否有大范围问题的报告

这些错误无法通过等待解决——你必须采取纠正措施。

身份认证失败：

会话过期 → 通过 User Center 重新认证
凭证无效 → 确认套餐处于有效状态
需要重新认证 → 检查 User Center

持续性错误（10 分钟以上）：

多次重试后仍反复出现同一错误 → 开始排查
一致的失败模式 → 检查配置
重启后错误依然存在 → 验证环境

配置问题：

近期更改过设置 → 检查并还原改动
全新安装或配置 → 验证配置文件
网络环境已改变 → 测试连通性

权限错误：

文件系统访问被拒 → 检查文件/文件夹权限
工作区受限 → 验证工作区访问权限
文件夹权限 → 授予必要权限

网络问题：

完全无法连接 → 测试网络连接
VPN 或防火墙阻断 → 尝试切换网络
企业网络限制 → 联系 IT 支持

决策规则：

服务器/速率错误 → 等待
认证/配置/权限/网络 → 立即行动
不确定？→ 先等待 5-10 分钟，若持续再行动

提供错误上下文

在寻求帮助或报告问题时，请提供全面的上下文，以便更快诊断。

必要信息

错误详情：

完整的错误信息文本（复制粘贴，不要转述）
错误代码（如有）
错误发生的时间戳
频率（一次性、间歇性、持续性）

环境：

Verdent for VS Code 版本
VS Code 版本
操作系统及版本
网络环境（家庭、企业、VPN）

复现步骤：

你当时想做什么
使用的确切提示词或命令
涉及的文件或上下文
错误发生前采取的操作

上下文：

你当时使用的执行模式
工作区的规模与复杂度
近期的配置变更
之前成功的同类操作

错误报告示例

良好的错误报告格式：

Issue: Getting "Internal server error" when requesting code analysis

Error Message (exact):
"Error: Internal server error occurred during processing. Please try again later."

Environment:
- Verdent for VS Code v1.2.3
- VS Code 1.85.0
- macOS 14.2
- Home network (no VPN)

Steps to Reproduce:
1. Opened large TypeScript project (500+ files)
2. Used Auto-Run Mode
3. Requested: "Analyze authentication flow in auth.ts and suggest improvements"
4. Error occurred immediately after request

Additional Context:
- First time working with this project
- Same request worked fine yesterday in different project
- Other requests (small file edits) work normally

为什么这样做有效

完整的错误信息文本
完整的环境详情
清晰的复现步骤
与正常场景的对比
关于规律的额外上下文

报告问题

位置： Verdent 面板顶部栏

作用：

打开弹出层用于提交问题和建议
直达 Verdent 团队的渠道
最适合用于错误报告和功能请求

何时使用：

有清晰复现步骤的确认错误
有具体使用场景的功能请求
需要与团队直接沟通
需要调查的非紧急问题

应包含内容：

清晰的问题描述
错误信息（确切文本）
复现步骤
预期行为 vs 实际行为
Verdent 版本和平台
问题开始出现的时间

链接： https://discord.com/invite/NGjXEZcbJq

提供内容：

活跃的 Verdent 用户与团队成员社区
实时排查协助
可附带截图分享问题
从经验丰富的用户处获得帮助
社区讨论与变通方案

何时使用：

需要立即讨论的紧急问题
需要来回沟通的复杂排查
关于最佳实践的社区意见
在提交正式报告前的快速提问
与社区分享变通方案

问题类型	使用反馈按钮	使用 Discord
有复现步骤的确认错误	✓
功能请求	✓
需要紧急排查		✓
需要讨论的复杂问题		✓
快速提问		✓
想征求社区意见		✓
正式错误报告	✓
一般帮助		✓