# 疑難排解 (/zh-Hant/docs/verdent-for-vscode/help-support/common-issues)

> 常見問題、診斷與解決方案



### 你將學到什麼 [#你將學到什麼]

Verdent for VS Code 的常見疑難排解程序、診斷步驟與已知問題的因應方式。

<Info>
  針對使用者回報最多的問題，我們正從支援資料中整理詳細的疑難排解方法。本頁提供一般性的診斷程序。若遇到此處未涵蓋的特定問題，請聯絡 [support@verdent.ai](mailto:support@verdent.ai)。
</Info>

***

## 快速診斷 [#快速診斷]

<Tabs>
  <Tab title="服務錯誤（最常見）">
    ### 「Service is experiencing high traffic. Please try again later!」 [#service-is-experiencing-high-traffic-please-try-again-later]

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

    **發生時機：**

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

    **復原步驟（依順序）：**

    <Steps>
      <Step title="回滾訊息" stepNumber="1">
        如果錯誤持續發生，請回滾最近一則訊息：

        * 點擊聊天介面中的回滾／復原按鈕
        * 稍候片刻後重新送出你的請求
      </Step>

      <Step title="開始新工作階段" stepNumber="2">
        如果錯誤仍持續，請開啟全新的工作階段：

        * 點擊頂部列的「+」（新工作階段）按鈕
        * 這會清除上下文與工具核准
        * 在乾淨的工作階段中重新送出你的請求
      </Step>

      <Step title="等待後重試" stepNumber="3">
        等待 30 至 60 秒後再次嘗試你的請求。大多數服務問題會很快解除。
      </Step>
    </Steps>

    <Warning>
      若問題在多個工作階段中持續超過 5 至 10 分鐘，請查看 [Verdent 狀態頁面](https://verdent.ai/status) 或聯絡 [support@verdent.ai](mailto:support@verdent.ai)。
    </Warning>
  </Tab>

  <Tab title="安裝與設定">
    ### 安裝與設定問題 [#安裝與設定問題]

    **系統需求：**

    * **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」）

    **乾淨重新安裝程序：**

    <Steps>
      <Step title="解除安裝 Verdent">
        View → Extensions → Verdent → Uninstall
      </Step>

      <Step title="重新啟動 VS Code">
        完全關閉並重新開啟 VS Code
      </Step>

      <Step title="重新安裝 Verdent">
        View → Extensions → 搜尋「Verdent」→ Install
      </Step>
    </Steps>

    **檢查記錄檔：**

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

    <Info>
      大多數安裝問題只要重新載入 VS Code 或乾淨重新安裝即可解決。如果問題持續，請檢查記錄檔，並在聯絡支援時附上記錄檔詳細資訊。
    </Info>
  </Tab>

  <Tab title="驗證與帳號">
    ### 無法登入 Verdent for VS Code [#無法登入-verdent-for-vs-code]

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

    **解決方法：**

    <Steps>
      <Step title="開啟 VS Code 設定">
        按下 `Cmd+,`（macOS）或 `Ctrl+,`（Windows/Linux）
      </Step>

      <Step title="搜尋 Proxy 設定">
        在設定搜尋列中搜尋「useProxy」或「verdent.enableProxy」
      </Step>

      <Step title="切換 Proxy 狀態">
        切換 proxy 設定的開／關（與目前狀態相反）
      </Step>

      <Step title="重試登入">
        再次嘗試登入 Verdent
      </Step>
    </Steps>

    <Info>
      如果你在企業防火牆後方，可能需要啟用 proxy 設定。如果你使用家用網路，請嘗試停用它。
    </Info>

    ***

    ### 未收到免費試用點數 [#未收到免費試用點數]

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

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

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

    ***

    ### 註冊失敗 [#註冊失敗]

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

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

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

    ***

    ### 缺少模型（Claude、GPT、Gemini） [#缺少模型claudegptgemini]

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

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

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

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

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

    <Note>
      地區限制是由 AI 模型供應商（Anthropic、OpenAI、Google）設定，而非由 Verdent 設定。Verdent 無法覆寫這些限制。
    </Note>
  </Tab>

  <Tab title="效能">
    ### 效能問題 [#效能問題]

    **症狀：**

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

    **常見原因與修正：**

    | 問題      | 原因             | 解決方法                                                       |
    | ------- | -------------- | ---------------------------------------------------------- |
    | 回應緩慢    | 正在讀取大型檔案       | 使用行範圍：`file_read("file.js", start_line=100, max_lines=50)` |
    | 上下文已滿   | 對話歷史過長         | 委派給子代理或開始新的對話                                              |
    | 工具逾時    | 長時間執行的 bash 指令 | 設定明確的逾時時間，或拆解成較小的指令                                        |
    | 記憶體用量過高 | 平行操作過多         | 限制同時執行的工具數量                                                |

    <Tip>
      將探索性任務委派給 @Explorer 子代理，以保留主要上下文。
    </Tip>
  </Tab>

  <Tab title="圖片錯誤">
    ### 圖片相關錯誤訊息 [#圖片相關錯誤訊息]

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

    | 錯誤訊息                           | 原因                         | 解決方法                      |
    | ------------------------------ | -------------------------- | ------------------------- |
    | **Unsupported Image Type**     | 僅支援 JPEG、PNG、GIF 或 WebP 圖片 | 回滾並將圖片類型改為支援的格式           |
    | **Image Dimensions Too Large** | 圖片寬度或高度不得超過 8000 像素        | 回滾並將圖片尺寸調整為 8000×8000 或更小 |
    | **Input Too Long**             | 輸入超過模型允許的最大長度              | 簡化你的輸入或縮小圖片大小             |
    | **File Too Large**             | 圖片大小不得超過 5 MB              | 回滾並傳送壓縮後的圖片（最大 5 MB）      |
    | **Unreadable Image**           | 無法處理該圖片，檔案可能已損毀或為不支援的格式    | 回滾並以有效的檔案取代該圖片            |
  </Tab>
</Tabs>

***

## 工具特定問題 [#工具特定問題]

<Tabs>
  <Tab title="file_edit 失敗">
    ### file\_edit 失敗 [#file_edit-失敗]

    **錯誤：** 「Failed to find exact match」

    **原因：**

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

    **解決方法：**

    ```bash
    # 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)
    ```

    <Warning>
      在編輯前務必立即讀取檔案，以確保你掌握的是目前的狀態。
    </Warning>
  </Tab>

  <Tab title="bash 失敗">
    ### bash 指令失敗 [#bash-指令失敗]

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

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

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

    ```bash
    # 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`
    * 檢查檔案／目錄權限
  </Tab>

  <Tab title="搜尋問題">
    ### 搜尋未傳回任何結果 [#搜尋未傳回任何結果]

    **問題：** grep\_file 或 glob 找不到預期的檔案

    **檢查模式語法：**

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

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

    **檢查排除項目：**

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

    **大小寫敏感性：**

    ```bash
    # Use case-insensitive search if needed
    grep_content("pattern", case_insensitive=true)
    ```
  </Tab>
</Tabs>

***

## 子代理與設定問題 [#子代理與設定問題]

<Tabs>
  <Tab title="子代理未被叫用">
    ### 子代理未被叫用 [#子代理未被叫用]

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

    **檢查清單：**

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

    **手動測試：**

    ```
    @subagent-name perform task
    ```

    <Tip>
      在排查自動叫用問題之前，先使用明確的 @ 提及來確認子代理是否正常運作。
    </Tip>
  </Tab>

  <Tab title="內建子代理">
    ### 內建子代理行為 [#內建子代理行為]

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

    **常見原因：**

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

    **解決方法：**

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

  <Tab title="AGENTS.md 規則">
    ### AGENTS.md 未套用 [#agentsmd-未套用]

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

    **診斷：**

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

    **優先順序檢查：**

    ```markdown
    # 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)
    ```
  </Tab>

  <Tab title="MCP 連線">
    ### MCP 連線失敗 [#mcp-連線失敗]

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

    **診斷步驟：**

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

    **常見修正：**

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

***

## 已知問題與因應方式 [#已知問題與因應方式]

<Tabs>
  <Tab title="二進位檔案">
    ### 二進位檔案限制 [#二進位檔案限制]

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

    **因應方式：**

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

    <Info>
      修改二進位檔案需要透過 bash 指令叫用外部工具。
    </Info>
  </Tab>

  <Tab title="大型檔案">
    ### 大型檔案處理 [#大型檔案處理]

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

    **因應方式：**

    ```bash
    # 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")
    ```

    <Tip>
      先使用 grep\_content 搜尋以定位相關的行號，再僅讀取那些特定的範圍。
    </Tip>
  </Tab>

  <Tab title="平台差異">
    ### 跨平台指令差異 [#跨平台指令差異]

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

    **因應方式：**

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

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

    **最佳實務：** 使用 npm 指令稿以達成跨平台相容性。
  </Tab>
</Tabs>

***

## 取得更多協助 [#取得更多協助]

### 支援管道 [#支援管道]

**針對此處未涵蓋的特定問題：**

* **電子郵件：** [support@verdent.ai](mailto:support@verdent.ai)
* **Discord：** [加入 Verdent 社群](https://discord.com/invite/NGjXEZcbJq) 以取得即時支援
* **GitHub Issues：** 回報錯誤或提出功能需求

**回報問題時，請附上：**

1. Verdent 版本（來自 Extensions 面板）
2. VS Code 版本
3. 作業系統
4. 錯誤訊息（確切的文字）
5. 重現步驟
6. 預期行為與實際行為

***

### 診斷資訊蒐集 [#診斷資訊蒐集]

**協助支援團隊進行診斷：**

```bash
# VS Code version
bash("code --version")

# System info
bash("uname -a")  # Unix
bash("systeminfo")  # Windows

# Verdent logs location
# Check VS Code Output panel → Verdent
```

***

## 另請參閱 [#另請參閱]

<CardGroup cols="2">
  <Card title="常見問題" icon="circle-question" href="/docs/verdent-for-vscode/help-support/faqs">
    常見問題解答
  </Card>

  <Card title="限制" icon="triangle-exclamation" href="/docs/verdent-for-vscode/help-support/limitations">
    已知限制與約束
  </Card>
</CardGroup>