--- title: 錯誤處理與復原 description: 解讀錯誤並從中復原 --- --- 了解如何解讀、回應與回報錯誤，有助於你在使用 Verdent for VS Code 時維持高效的開發流程。 ### 你將學到 - 常見的錯誤類型及其成因 - 如何有效解讀錯誤訊息 - 系統化的疑難排解步驟 - 何時該等待、何時該採取行動 - 如何向 Verdent 團隊回報問題 --- ## 常見錯誤類型 完整的錯誤文件目前仍在開發中。以下資訊涵蓋最常遇到的錯誤類別。如遇特定錯誤情境，請聯絡 support@verdent.ai 或造訪 Discord 社群。 **伺服器過載錯誤** - 發生於流量高峰期間 - 暫時性容量限制 - **處理方式**：等待 5-10 分鐘後重試 **內部伺服器錯誤** - 後端處理問題 - 暫時性服務中斷 - **處理方式**：稍候並重試，通常會自動恢復 **503 服務無法使用** - 沒有健康的上游伺服器 - 暫時性基礎設施問題 - **處理方式**：等待服務恢復 **速率限制錯誤** - 超出請求配額 - API 節流保護 - **處理方式**：等待速率限制重置，降低請求頻率 - 憑證無效或已過期 - 工作階段逾時問題 - **處理方式**：透過 User Center 重新驗證，確認方案處於有效狀態 - 網路連線問題 - 防火牆或 VPN 阻擋連線 - 企業網路限制 - **處理方式**：檢查網路連線，嘗試切換不同網路 - 設定或偏好無效 - 設定檔損毀 - **處理方式**：檢視最近的設定變更，確認設定正確 - 檔案系統權限不足 - 工作區存取限制 - **處理方式**：檢查檔案／資料夾權限，確認工作區存取權 --- ## 解讀錯誤訊息 詳細的錯誤訊息解讀指南仍在開發中。如遇特定錯誤訊息，請使用 Feedback 按鈕或 Discord 社群尋求協助。 伺服器端錯誤屬於暫時性，通常等待後即可恢復。除了幾分鐘後重試之外，無需採取其他行動。 **留意這些關鍵字：** - 「Overloaded」或「at capacity」 - 「Internal server error」或「backend processing」 - 「503 Service Unavailable」或「no healthy upstream」 - 「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。使用 Feedback 按鈕回報問題。請附上非預期行為的描述與重現步驟。 ### 不該做的事 對於暫時性問題，請避免下列動作： - 不要立即重新安裝 Verdent - 不要清除 VS Code 快取或應用程式資料 - 不要為了暫時性問題而修改系統設定 - 除非其他應用程式也受影響，否則不要重新啟動電腦 在 Manual Accept Mode 下，未仔細檢視確切指令前，切勿核可破壞性操作（rm、DROP、DELETE）。 **為什麼？** 這些動作耗時且很少能解決問題。多數問題只要簡單重新啟動，或等待暫時性伺服器問題排除即可解決。 --- ## 何時等待、何時行動 了解該等待還是採取行動，可避免浪費疑難排解的精力。 這些錯誤會自動恢復 — 除了等待並重試外無需採取任何行動。 **伺服器過載或容量錯誤：** - 「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 團隊的管道 - 最適合回報錯誤與功能請求 **何時使用：** - 已確認、具備清楚重現步驟的錯誤 - 具備明確使用情境的功能請求 - 需要直接與團隊溝通 - 需要調查的非緊急問題 **應包含內容：** - 清楚的問題描述 - 錯誤訊息（確切文字） - 重現步驟 - 預期行為與實際行為 - Verdent 版本與平台 - 問題開始的時間 **連結：** https://discord.com/invite/NGjXEZcbJq **提供的協助：** - 活躍的 Verdent 使用者與團隊成員社群 - 即時的疑難排解協助 - 可附截圖分享問題 - 從資深使用者取得協助 - 社群討論與替代方案 **何時使用：** - 需要即時討論的緊急問題 - 需要往返溝通的複雜疑難排解 - 需要社群對最佳做法的意見 - 正式回報前的快速提問 - 與社群分享替代方案 | 問題類型 | 使用 Feedback 按鈕 | 使用 Discord | |------------|:------------------:|:-----------:| | 已確認且具重現步驟的錯誤 | ✓ | | | 功能請求 | ✓ | | | 需要緊急疑難排解 | | ✓ | | 需要討論的複雜問題 | | ✓ | | 快速提問 | | ✓ | | 想取得社群意見 | | ✓ | | 正式錯誤回報 | ✓ | | | 一般協助 | | ✓ | **不需要回報的內容：** - 暫時性伺服器錯誤（小於 10 分鐘） - 流量高峰期間 - 已記錄的已知問題 - 預期內的行為 **改為：** 等待暫時性問題排除、至 Discord 查看近期回報、檢視文件。 --- ## 預防最佳實務 主動的做法可降低錯誤發生頻率，並在錯誤發生時改善復原效果。 在提示詞中使用具體的措辭並納入相關檔案上下文，可在許多常見錯誤發生前就加以預防。 ### 開始工作前 **1. 驗證設定** - 在 User Center 檢查驗證狀態 - 確認方案處於有效狀態 - 確保網路連線穩定 - 檢視最近的設定變更 **2. 初始化 Git** - 使用較寬鬆的模式前務必先建立版本控制 - 提交目前工作以取得乾淨的起點 - 在發生問題時提供回復選項 **3. 檢查點數餘額** - 確認有足夠的點數可完成計畫中的工作 - 如有需要，在開始複雜任務前先儲值 - 避免因點數耗盡而中途中斷 ### 開發期間 **1. 使用適當的執行模式** - 不熟悉的程式碼使用 Manual Accept - 複雜變更使用 Plan Mode - Auto-Run 僅在有 Git 安全網時使用 - 讓模式與風險程度相符 **2. 監控效能** - 留意回應品質下降 - 注意回應時間變慢 - 效能下滑時開啟全新工作階段 - 手動追蹤上下文使用量 **3. 清楚、具體的提示詞** - 減少因誤解請求而產生的錯誤 - 納入相關上下文與限制 - 參考既有的模式 - 明確指定範圍 ### 錯誤發生後 **1. 從模式中學習** - 記下觸發錯誤的原因 - 辨識可重現的條件 - 調整工作流程以避開觸發因素 - 與社群分享發現 **2. 記錄替代方案** - 為有效的解法保留筆記 - 與團隊成員分享 - 貢獻給社群知識庫 - 回報給 Verdent 團隊以修復 **3. 更新設定** - 依經驗調整設定 - 為你的工作流程進行最佳化 - 設定規則以預防問題 - 維護 AGENTS.md 文件 --- ## 延伸閱讀 撰寫有效的提示詞以減少錯誤 最佳化上下文以避免效能問題 選擇適當的模式以將風險降至最低