--- title: 错误处理与恢复 description: 解读错误并从错误中恢复 --- --- 了解如何解读、响应和报告错误，有助于你在使用 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/防火墙 **通用规则：** 如果错误提到身份认证、配置、权限或本地设置，你需要采取纠正措施。 **排查步骤：** 1. 阅读完整的错误信息以获取具体指引 2. 确定是哪个组件报告了错误（认证、配置、权限、网络） 3. 根据错误类型采取针对性行动 4. 重试原始操作以验证修复效果 ### 阅读错误上下文 当错误发生时： 1. **阅读完整的错误信息** —— 不要跳过细节 2. **记下错误代码** —— 特定代码有助于诊断问题 3. **识别相关组件** —— 是哪个系统报告了错误（服务器、API、本地） 4. **检查发生时机** —— 是立即发生，还是延迟后发生？ --- ## 系统化排查 当 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） **复现步骤：** 1. 你当时想做什么 2. 使用的确切提示词或命令 3. 涉及的文件或上下文 4. 错误发生前采取的操作 **上下文：** - 你当时使用的执行模式 - 工作区的规模与复杂度 - 近期的配置变更 - 之前成功的同类操作 ### 错误报告示例 良好的错误报告格式： ``` 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 | |------------|:------------------:|:-----------:| | 有复现步骤的确认错误 | ✓ | | | 功能请求 | ✓ | | | 需要紧急排查 | | ✓ | | 需要讨论的复杂问题 | | ✓ | | 快速提问 | | ✓ | | 想征求社区意见 | | ✓ | | 正式错误报告 | ✓ | | | 一般帮助 | | ✓ | **不应报告的内容：** - 临时性服务器错误（小于 10 分钟） - 高流量时段 - 已有文档记录的问题 - 预期内的行为 **应这样做：** 临时性问题请耐心等待，在 Discord 上查看近期报告，查阅文档。 --- ## 预防最佳实践 主动的实践能降低错误频率，并在错误发生时改善恢复效果。 在提示词中使用具体的措辞，并包含相关的文件上下文，可以在许多常见错误发生前就将其预防。 ### 开始工作前 **1. 验证设置** - 在 User Center 中检查认证状态 - 确认套餐处于有效状态 - 确保网络连接稳定 - 检查近期的配置变更 **2. 初始化 Git** - 在使用宽松模式前务必先有版本控制 - 提交当前工作以获得干净的起点 - 在出现问题时提供回滚选项 **3. 检查积分余额** - 验证积分足以支撑计划中的工作 - 如有需要，在开始复杂任务前先充值 - 避免因积分耗尽导致任务中途中断 ### 开发过程中 **1. 使用合适的执行模式** - 对不熟悉的代码使用手动接受 - 对复杂改动使用 Plan Mode - 仅在有 Git 安全网时使用自动运行 - 让模式与风险等级相匹配 **2. 监控性能** - 留意响应质量的下降 - 注意响应时间变慢 - 当性能下降时开启新会话 - 手动跟踪上下文使用情况 **3. 清晰、具体的提示词** - 减少因误解请求而产生的错误 - 包含相关的上下文和约束 - 引用已有的模式 - 明确界定范围 ### 错误发生后 **1. 从规律中学习** - 记下是什么触发了错误 - 识别可复现的条件 - 调整工作流以避免触发因素 - 与社区分享发现 **2. 记录变通方案** - 记录有效的解决方案 - 与团队成员分享 - 为社区知识库做出贡献 - 向 Verdent 团队报告以便修复 **3. 更新配置** - 根据经验调整设置 - 针对你的工作流进行优化 - 配置规则以预防问题 - 维护 AGENTS.md 文档 --- ## 另请参阅 编写高效的提示词以减少错误 优化上下文以预防性能问题 选择合适的模式以将风险降至最低