錯誤處理與復原

了解如何解讀、回應與回報錯誤，有助於你在使用 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／防火牆

一般原則： 若錯誤提到驗證、設定、權限或本機設定，你就必須採取修正行動。

疑難排解步驟：

完整閱讀錯誤訊息以取得具體指引
辨識是哪個元件回報錯誤（驗證、設定、權限、網路）
依錯誤類型採取對應行動
重試原本的操作以驗證是否修復

閱讀錯誤上下文

當錯誤發生時：

完整閱讀錯誤訊息 — 不要略過細節
記下錯誤代碼 — 特定代碼有助於診斷問題
辨識元件 — 是哪個系統回報了錯誤（伺服器、API、本機）
檢查發生時機 — 是立即發生，還是延遲後才出現？

系統化疑難排解

當 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）

重現步驟：

你當時想做什麼
使用的確切提示詞或指令
涉及的檔案或上下文
錯誤發生前所採取的動作

上下文：

你當時使用的執行模式
工作區的規模與複雜度
最近的設定變更
先前成功的類似操作

錯誤回報範例

良好的錯誤回報格式：

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 文件