疑難排解

「Service is experiencing high traffic. Please try again later!」

這是使用者最常遇到的第一名錯誤，代表 Verdent 服務暫時負載過高。

發生時機：

• 在使用尖峰時段
• 後端服務承受大量負載時
• 暫時性的服務降級

復原步驟（依順序）：

安裝與設定問題

系統需求：

• VS Code 版本： 1.90.0 或更新版本（必要）
• 網際網路連線： 需要有效連線
• 訂閱： 有效的 Verdent 訂閱

基本診斷檢查清單：

1. 確認 VS Code 版本： Help → About（必須為 1.90.0 以上）
2. 檢查網際網路連線： Verdent 需要有效的連線
3. 確認訂閱： 確保 Verdent 訂閱處於有效狀態
4. 重新啟動 VS Code： 在安裝或變更設定後
5. 檢查擴充功能狀態： View → Extensions → Verdent（應顯示為「Enabled」）

乾淨重新安裝程序：

檢查記錄檔：

• 開啟輸出面板：View → Output
• 從下拉選單中選擇「Verdent」
• 尋找錯誤訊息或堆疊追蹤

無法登入 Verdent for VS Code

最常見的原因： Proxy 設定問題

解決方法：

未收到免費試用點數

錯誤： 未收到免費試用點數，或免費試用存取遭拒

原因： 註冊期間偵測到違反服務條款

解決方法： 聯絡 support@verdent.ai 以協助處理你的免費試用存取。支援團隊會審查你的帳號並協助解決問題。

註冊失敗

錯誤： 帳號註冊遭拒或受到限制

原因： 該註冊違反了 Verdent 的服務條款，導致存取受限

解決方法： 聯絡 support@verdent.ai 以取得協助。支援團隊可審查你的註冊並提供解決問題的指引。

缺少模型（Claude、GPT、Gemini）

問題： 在模型選擇中找不到 Claude、GPT 或 Gemini 模型

原因： 模型供應商基於地區的限制

說明： 某些 AI 模型供應商有地區限制，使得特定模型無法在特定地理位置提供使用。發生這種情況時：

• 受限制的模型不會出現在你的模型選擇選單中
• 你仍可不受中斷地使用所有其他可用的模型
• 不會影響你的訂閱或點數

查看可用模型： 前往 https://www.verdent.ai/regions 查看你所在地區有哪些模型可用

效能問題

症狀：

• 回應速度緩慢
• 上下文視窗已滿的錯誤
• 工具執行逾時

常見原因與修正：

圖片相關錯誤訊息

常見圖片處理錯誤的快速參考：

file_edit 失敗

錯誤： 「Failed to find exact match」

原因：

• 文字在上次 file_read 之後已變更
• 空白字元差異（tab 與空格）
• 字串在檔案中並非唯一

解決方法：

# 1. Read file again to get current state
file_read("file.js")

# 2. Use larger context string for uniqueness
file_edit("file.js",
  old_string="function foo() {\n  return 42;\n}",
  new_string="...")

# 3. For multiple identical strings, use replace_all
file_edit("file.js", old_string="TODO", new_string="DONE", replace_all=true)

bash 指令失敗

錯誤： 指令逾時或執行失敗

最大逾時時間： 120 秒（2 分鐘，硬性上限）

解決方法： 將長指令拆解成較小的操作：

# Instead of one long command, break into steps
bash("step1")  # Completes in < 2min
bash("step2")  # Completes in < 2min

找不到指令：

• 檢查指令是否存在：bash("which command-name")
• 確保路徑正確，或先啟用環境
• 對執行檔使用完整路徑

權限錯誤：

• 指令會以使用者權限執行
• 僅在必要時且處於 Manual Accept Mode 下使用 sudo
• 檢查檔案／目錄權限

搜尋未傳回任何結果

問題： grep_file 或 glob 找不到預期的檔案

檢查模式語法：

# Wrong
grep_file("*.ts")  # Missing ** for recursive

# Correct
grep_file("**/*.ts")  # Recursive search

檢查排除項目：

# Ensure not accidentally excluding target files
glob("**/*.js", exclude=["**/dist/**", "**/node_modules/**"])

大小寫敏感性：

# Use case-insensitive search if needed
grep_content("pattern", case_insensitive=true)

子代理未被叫用

問題： 自訂子代理未自動啟用

檢查清單：

• 檔案位置：~/.verdent/subagents/[name].md
• 有效的 YAML frontmatter，包含 name 與 description
• 叫用政策符合使用情境（strict 需要 @ 提及）
• 「何時使用」指引符合請求模式
• markdown 檔案中沒有語法錯誤

手動測試：

@subagent-name perform task

內建子代理行為

問題： @Explorer、@Verifier 或 @Code-reviewer 的行為不如預期

常見原因：

• 請求與子代理的專長不符
• 子代理上下文已滿（罕見）
• 主要對話上下文影響路由

解決方法：

• 使用明確的 @ 提及來強制指定子代理
• 重新措辭請求，使其符合子代理的專長
• 若上下文有問題，開始新的對話

AGENTS.md 未套用

問題： 專案規則未影響 Verdent 行為

診斷：

1. 位置： 檔案必須位於專案根目錄
2. 語法： 有效的 Markdown（檢查語法錯誤）
3. 明確性： 規則必須是指令式的：「Always use X」而非「Try to use X」
4. 測試： 開始新對話以測試全新套用情況

優先順序檢查：

# In AGENTS.md (highest priority)
- Use 4-space indentation

# In VERDENT.md (lower priority)
- Use 2-space indentation

# Result: 4-space indentation (AGENTS.md wins)

MCP 連線失敗

錯誤： 無法連線至 MCP 伺服器

診斷步驟：

1. 檢查 mcp.json： ~/.verdent/mcp.json 中的 JSON 語法是否有效
2. 伺服器運行中： 確保 MCP 伺服器程序處於使用中狀態
3. 網路： 驗證與伺服器端點的連線
4. 驗證： 確認憑證正確
5. 記錄檔： 檢查 MCP 伺服器記錄檔中的錯誤詳細資訊

常見修正：

• 重新啟動 MCP 伺服器
• 確認連線字串格式
• 檢查防火牆規則是否允許 MCP 流量
• 驗證 API 金鑰或權杖

二進位檔案限制

問題： 無法編輯圖片、PDF、編譯後的二進位檔

因應方式：

# Use bash to call external tools
bash("convert input.png -resize 50% output.png")
bash("pdftotext document.pdf output.txt")

大型檔案處理

問題： 超過 10,000 行的檔案會造成上下文問題

因應方式：

# Always use line ranges for large files
file_read("large.log", start_line=1000, max_lines=100)

# Search first to find relevant sections
grep_content("ERROR", glob="large.log")

跨平台指令差異

問題： bash 指令在 Windows 與 Unix 之間有所不同

因應方式：

# Use cross-platform tools when possible
bash("npm run build")  # Works everywhere

# Or conditional execution
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")

最佳實務： 使用 npm 指令稿以達成跨平台相容性。