常見問題

最常見的原因： 代理設定問題

解決方法：

1. 開啟 VS Code 設定（macOS 上為 Cmd+,，Windows/Linux 上為 Ctrl+,）
2. 搜尋 "useProxy" 或 "verdent.enableProxy"
3. 切換代理設定的開/關（與目前狀態相反）
4. 再次嘗試登入

說明： 如果你位於企業防火牆後方，可能需要啟用代理設定。如果你使用的是家用網路，請嘗試停用它。

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

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

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

錯誤： 帳戶註冊被拒絕或受限

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

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

問題： 在模型選擇選單中找不到某些 AI 模型

原因： 來自模型供應商的地區限制

說明： 部分 AI 模型供應商（Anthropic、OpenAI、Google）設有地區限制，使得某些模型無法在特定地理位置使用。發生這種情況時：

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

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

注意： 地區限制是由 AI 模型供應商設定的，而非 Verdent。Verdent 無法覆寫這些限制。

Visual Studio Code 是由 Microsoft 開發的免費開源程式碼編輯器。它是一個輕量但功能強大的開發環境，支援多種程式語言，並提供除錯、語法高亮、智慧程式碼補全與整合版本控制等功能。Verdent 以擴充功能的形式直接整合進 Visual Studio Code，為你既有的工作流程加入 AI 驅動的程式設計能力。

Verdent 是一個用於 Visual Studio Code 的 AI 程式設計助理擴充功能，透過自然語言對話協助進行程式碼生成、重構、除錯與專案導覽。

主要能力：

• 透過檔案工具進行程式碼生成與修改
• 透過專門的子代理探索程式碼庫
• 透過 bash 整合執行指令
• 透過規則與 MCP 伺服器進行自訂擴充

最低需求：

• Visual Studio Code 1.90.0 或更高版本
• 有效的 Verdent 訂閱
• 網路連線

平台支援： macOS、Windows、Linux、WSL

1. 從 VS Code marketplace 安裝 Verdent 擴充功能
2. 在系統提示時使用你的 Verdent 帳戶登入
3. 開啟任何程式碼檔案或專案
4. 開啟 Chat View 並開始與 Verdent 對話

首個任務建議： 請 Verdent 解釋你的專案結構或審查某個特定檔案。

開啟 Visual Studio Code 並前往 Help → About（macOS 上為 Code → About Visual Studio Code）。版本號會顯示在對話框中。Verdent 需要 Visual Studio Code 1.90.0 或更高版本。

你也可以透過指令列查看：

code --version

請參閱點數與方案，了解 Verdent 各產品共通的點數定義、定價層級與使用基礎。

請參閱點數用完時會發生什麼，了解共通的帳戶政策與恢復選項。

透過剪貼簿貼上或以檔案路徑引用的圖片會在你的對話工作階段內處理。圖片不會被永久儲存，並會在你開始新對話時清除。檔案路徑引用會在本機讀取圖片而不會上傳。

Plan Mode 是一種唯讀的執行模式，Verdent 會分析程式碼、進行研究並建立詳細的實作計畫，而不會修改檔案或執行指令。產生計畫後，Verdent 會提供兩個選項：Edit（要求修改並改進計畫）或 Start Building（切換到 Agent Mode 並開始執行）。代理可以提出釐清問題，以在執行前消除不確定性。此模式非常適合複雜任務，讓你能在確定進行變更前先審查方法，確保你的預期與 Verdent 提出的解決方案一致。

不會。 Plan Mode 嚴格屬於唯讀模式：

• Verdent 可以讀取檔案、搜尋程式碼並分析你的程式碼庫
• Plan Mode 期間不會發生檔案寫入、編輯或刪除
• 計畫只會顯示在 Chat View 中
• 只有在你明確核准並切換到 Agent Mode 後，程式碼執行才會開始

安全保證： Plan Mode 不會意外修改你的程式碼。它專為安全探索與策略制定而設計。

透過 Input Box 即時切換：

進入 Plan Mode：

• 點擊 Input Box 中的 Switch Mode 按鈕
• 從下拉選單中選擇 Plan Mode
• 或說：「Switch to Plan Mode」

離開 Plan Mode：

• 點擊 Input Box 中的 Switch Mode 按鈕
• 從下拉選單中選擇 Agent Mode
• 或在審查計畫後選擇 Start Building

模式持續性：

• 模式選擇會在目前工作階段中保持
• 新工作階段以預設的 Agent Mode 開始
• 你可以隨時自由切換模式

典型工作流程： Plan Mode → 審查 → Agent Mode → 執行 → 回到 Plan Mode 進行下一個複雜功能。

點擊頂部列的「New Session」按鈕。這會清除目前的對話歷史，為你的下一個任務提供一個全新的 Verdent 上下文視窗。

可以，每個 VS Code 視窗都獨立運作。你可以在多個專案中開啟 Verdent，每個都維持各自獨立的對話上下文。

可以。Verdent 使用標準 Git 指令，因此無論託管平台為何，它都能與任何 Git 儲存庫搭配運作。在建立 pull request 時，Verdent 使用需要 GitHub 的 gh CLI，但所有其他 Git 操作都通用。

支援： 所有以文字為基礎的檔案格式，包括：

• 原始碼（JavaScript、Python、TypeScript、Java、Go 等）
• 設定檔（JSON、YAML、TOML、XML、ENV）
• 文件（Markdown、HTML、LaTeX）
• 建置檔案（package.json、Makefile、requirements.txt）

不支援： 二進位檔案（圖片、影片、PDF、編譯後的二進位檔、Office 文件）

替代方案： 在程式碼中引用二進位檔案，但修改需要外部工具。

極佳支援：

• JavaScript、TypeScript、Python、React、Vue、Angular
• Node.js、Go、Java/Spring、C#/.NET
• Swift、Kotlin、Flutter

非常好的支援： Rust、C/C++、Ruby、R

良好支援： PHP、Assembly、Julia

常見語言因有大量訓練資料而獲得更強的支援。

三種檔案操作工具：

• file_read： 讀取完整檔案或特定行範圍
• file_edit： 取代特定文字模式（精準修改）
• file_write： 建立新檔案或完整重寫檔案

最佳實務： 使用 file_edit 進行修改，file_write 僅用於新檔案。

透過 Verdent 執行終端機指令或 shell 指令碼，包括執行測試、安裝套件或執行建置指令等操作。在大多數權限模式下，指令執行需要核准，以防止意外的系統變更。

可以，使用 bash 工具。Verdent 可以執行終端機指令，具備：

• 最大逾時時間：120 秒（2 分鐘）
• 使用 && 串接指令
• 跨平台支援（Unix 上使用 bash，Windows 上使用 PowerShell）

安全性： 指令以你的使用者權限執行。使用 Manual Accept Mode 在執行前進行審查。

最大逾時時間： 120 秒（2 分鐘）

超過 2 分鐘的指令會被自動終止。對於較長的操作，可考慮：

替代方案：

• 拆分成較小的指令：bash("task1") && bash("task2")
• 拆分成較小的操作
• 在背景執行並分開檢查結果

這是一個迭代式驗證流程，程式碼會被生成、測試與修復，直到通過全面測試為止。Verdent 會自動執行測試、分析失敗、修正問題並重新測試，經過多次循環直到程式碼正確運作。這交付的是可上線的程式碼，而不僅僅是建議。每個結果都包含詳細摘要與程式碼 diff，確切顯示了哪些內容發生了變更。

子代理是具有隔離上下文視窗、用於特定任務的專門 AI 代理。

內建子代理：

• @Explorer： 程式碼庫搜尋、架構問題
• @Verifier： 快速驗證檢查
• @Code-reviewer： 安全性與品質審查

何時使用： 將研究、驗證或審查任務委派出去，以節省主對話的上下文。

如何建立自訂子代理：

在 ~/.verdent/subagents/ 中建立一個 markdown 檔案：

---
name: your-subagent
description: Purpose description
---
# System Prompt
[Behavior definition and expertise]

使用案例： 特定領域專業知識（金融、醫療）、團隊工作流程、技術專家。

當上下文中先前的操作與資訊產生了非預期的行為模式，進而影響未來的任務時。例如，如果你反覆更新程式碼然後部署它，代理可能會開始將所有程式碼更新與立即部署聯想在一起，即使你只是在做實驗。子代理透過以隔離的上下文視窗運作來防止上下文污染，讓每個專門任務都能以乾淨的上下文開始，避免不同類型工作之間的交叉污染。

查看 Verdent 面板底部的輸入框。「Switch Permission」按鈕會顯示你目前的模式（例如「Manual」、「Auto」、「Plan」）。你可以點擊它來切換模式。

Auto-Run Mode：

• 檔案操作會自動執行，無需核准
• 指令仍然需要授權
• 為受信任的程式碼庫提供更快的工作流程
• 最適合有版本控制的個人專案

Manual Accept Mode：

• 審查並核准每個受保護的操作
• 對於共享程式碼庫或正式環境更安全
• 在執行前確切看到將執行的內容

透過設定或命令選擇區切換模式。

只讀取資料而不做變更的操作：檔案讀取與網路搜尋。這些操作在 Auto-Run Mode 中會自動核准，而檔案編輯與指令執行為了安全仍需要核准。

不可以，權限模式是互斥的——你一次只能使用其中一種：

• Manual Accept - 預設，最大控制權
• Auto-Run - 為受信任的專案精簡流程
• Plan - 唯讀規劃模式
• Skip Permissions - 完全自主

你可以透過 Input Box 中的 Switch Permission 按鈕即時切換模式。大多數使用者會根據任務情境在各模式間切換（例如，複雜功能用 Plan Mode，快速修正用 Auto-Run）。

對於探索與搜尋任務使用 Explorer 代理，這樣不會消耗主上下文。只有在需要修改檔案時才用 @-mention 直接載入檔案。Explorer 非常適合「找出所有……的檔案」這類問題，而 @-mention 則用於「更新這個特定檔案」的任務。

可以！在 ~/.verdent/subagents/ 中建立自訂子代理：

---
name: your-subagent
description: Purpose description
---
# System Prompt
[Behavior definition and expertise]

使用案例： 特定領域專業知識（金融、醫療）、團隊工作流程、技術專家。

可以。你可以隨時中斷執行。Verdent 會完成它正在進行的當前步驟，然後停止。到該點為止的進度會被保留。你可以審查已完成的內容、進行調整，並選擇繼續或採取不同的方法。

觀察待辦清單。它會顯示即時狀態，任何時候都有一個項目標記為「進行中」。作用中的項目會確切顯示 Verdent 目前正在處理的內容。已完成的項目會標記為完成，而待處理的項目則顯示剩餘的工作。

不會。Verdent 只在你明確要求時才會建立 commit。你對於何時提交變更保有完全的控制權。準備好時只要說「Stage all changes and create a commit」即可。

不會。Verdent 只在你明確要求時才會推送到遠端儲存庫。所有 Git 操作（commit、push、merge、rebase）為了安全都需要你的明確指示。

三種自訂方法：

1. VERDENT.md： 個人全域偏好設定（~/.verdent/VERDENT.md）
2. AGENTS.md： 專案特定的團隊標準（專案根目錄，受版本控制）
3. plan_rules.md： Plan Mode 輸出格式（~/.verdent/plan_rules.md）

為了團隊一致性，AGENTS.md 會覆寫 VERDENT.md。

大多數 Verdent 設定會立即套用，無需重新啟動：

• 權限模式： 透過 Input Box 即時切換
• 模型預設： 套用於下一個請求
• 規則檔案： 套用於新對話（儲存時觸發重新載入）
• 子代理： 建立後立即可用
• 鍵盤快捷鍵： 在 VS Code 中儲存後套用

例外： VS Code 擴充功能設定（如 verdent.enableCheckpoints）會立即生效，但可能需要重新開啟檔案或工作階段才能完整套用。

Model Context Protocol（MCP）以外部工具與服務擴充 Verdent：

設定： ~/.verdent/mcp.json 透過 Settings → MCP Servers

功能：

• 資料庫連線（PostgreSQL、MySQL、MongoDB）
• 雲端服務（AWS、Azure、GCP）
• 專案管理工具（Jira、Linear）
• CI/CD 流程（Jenkins、GitHub Actions）

狀態： MCP 整合文件正在開發中。如需設定協助，請聯絡 support@verdent.ai。

這是上下文視窗的計量單位。Token 代表 AI 模型處理的文字片段（單字、單字的一部分或字元）。上下文限制是以 token 而非字元或單字來計量，典型的對話會消耗數千個 token。

你工作階段中的所有內容：對話中的所有訊息、載入上下文的檔案內容、工具輸出（grep/搜尋結果、檔案讀取）、系統提示與指令，以及 MCP 伺服器定義。這些都會從你的總上下文容量中消耗 token。

標準模型（Claude 4.5 Sonnet、Haiku、GPT-5、GPT-5-Codex、MiniMax-M2）擁有 200K token 的上下文視窗，足以應付大多數任務。Claude Sonnet 4.5 為具有 1000+ 檔案的大型程式碼庫、複雜的多檔案重構或長時間開發工作階段提供延伸的 1M token 上下文（大 5 倍）。1M 上下文會在輸入超過 200K token 時自動啟用，或可明確選擇。

沒有固定的檔案數量限制——這取決於檔案大小與總 token 數。對於 200K 上下文，請避免載入 20+ 個大型檔案（每個 >1000 行）。專注於與你當前任務直接相關的檔案。選擇性地使用 @-mentions，並利用 AGENTS.md 文件，而不是載入許多範例檔案。有了 1M 上下文，檔案選擇就變得不那麼關鍵了。

徵兆包括回應時間變慢、工作階段已執行數小時，或載入了許多大型檔案。監控你的工作階段長度與檔案數量。當你注意到效能下降時，完成你當前的任務、提交進度，並以乾淨的上下文開始新的工作階段。

策略：

1. 策略性檔案讀取： 對大型檔案使用行範圍
2. 委派給子代理： 用 Explorer/Verifier 進行背景研究
3. 讀取前先搜尋： 使用 grep_file 來識別相關檔案
4. 拆分操作： 使用 todo_update 來追蹤多步驟任務

經驗法則： 超過 500 行的檔案應使用行範圍。

你必須手動開始新的工作階段來重設上下文——Verdent 不會自動清除上下文。最佳實務：在完成一個原子性的工作單元、測試並提交到版本控制後重設。對於 1M token 上下文，重設的需求頻率會低很多。

不會——重設上下文只會從記憶體中清除對話歷史與已載入的檔案。你實際的程式碼變更、commit 與檔案修改都會被保留。為了安全，請在重設上下文前務必將你的工作提交到版本控制。重設 → 開始新工作階段 → 繼續處理下一個任務。

要具體到足以消除歧義，但不要過度說明顯而易見的細節。包含：確切的檔案路徑、實作方法、預期結果與限制。不好的範例：「Fix the code」——太模糊。好的範例：「Add input validation to the email field in ContactForm.js to reject invalid email formats」——範圍與目標清晰。有疑慮時，寧可偏向更具體。

Verdent 會自動載入提示詞中以名稱提及的檔案以及同目錄下的相關檔案。@-mentions（@filename.js）明確保證某個檔案位於上下文中，這在處理緊密耦合的檔案、引用某個檔案的模式以套用至另一個檔案，或在大型程式碼庫中自動偵測可能遺漏上下文時至關重要。當你要求 Verdent「follow the same pattern as...」時，務必使用 @-mentions 以確保精確的程式碼引用。

不需要——Verdent 會在工作階段內維持對話上下文，所以你不需要重複已討論過的架構細節或慣例。然而，對於關鍵限制或當工作階段變長時（100+ 則訊息），請重述重要的上下文。更好的做法：使用專案規則（AGENTS.md）來記錄持久的上下文，如技術堆疊、程式碼撰寫標準與模式——這樣你就永遠不需要重複它們。

使用迭代式改進：審查輸出、找出錯誤之處，然後在後續的提示詞中提供修正。範例：「The validation logic is good, but use Joi schema validation instead of manual checks. Match the validation pattern in ProductController.js.」你也可以要求解釋：「Why did you use Redux instead of Context API?」然後根據理解進行改進。不要重複相同的提示詞——根據失敗之處進行調整。

在以下情況使用 Plan Mode：大型重構或架構變更、你想在執行前審查範圍的多檔案修改、你對需求不確定的複雜任務，或當你想讓 Verdent 在實作前以釐清問題訪談你的時候。略過 Plan Mode 的情況：簡單、定義明確的任務、快速錯誤修正或例行操作。Plan Mode 會增加額外負擔，但能在複雜工作上預防代價高昂的錯誤。

根據任務複雜度與預算來搭配模型預設：

使用 Efficiency（比 Sonnet 高效 3.2 倍）：

• 快速錯誤修正與簡單程式碼生成
• 例行操作與高頻任務
• 當速度比深度更重要時

使用 Balance（1 倍基準）- 預設：

• 一般開發與日常程式設計
• 功能實作與程式碼審查
• 適用於大多數情境的平衡效能

使用 Performance（0.5 倍效率，2 倍成本）：

• 複雜的架構決策
• 需要大量上下文的大型程式碼庫（200k+ token）
• 精密的除錯與重構

專業提示： 大多數使用者保持 Balance 為預設，只在遇到上下文限制或需要深度推理時才切換到 Performance。

如果 Verdent 無法連線到 AI 服務，請檢查以下常見問題：

測試基本連線能力：

• 確認你有有效的網路存取
• 嘗試存取其他 HTTPS 服務以確認對外連線可運作

企業環境：

• 聯絡你的網路管理員將 Verdent 的 API 端點加入白名單
• 確保允許對外的 HTTPS 流量通過你的防火牆
• 檢查代理伺服器是否已正確設定以傳遞 API 請求
• SSL/TLS 檢查可能需要為 Verdent 端點設定例外

常見徵兆：

• 擴充功能似乎卡住或逾時
• 儘管憑證正確仍驗證失敗

如果在設定防火牆後問題仍然存在，請聯絡 Verdent 支援以取得需要加入白名單的特定端點詳情。

檢查：

• 位置： 檔案位於專案根目錄
• 語法： 有效的 Markdown
• 明確性： 規則為指令式（「Always use...」而非「Try to...」）
• 全新測試： 開始新對話以測試套用

優先順序： 對於專案特定行為，AGENTS.md 會覆寫 VERDENT.md。

原因：

• 文字自上次讀取後已變更
• 空白字元差異（空格 vs tab）
• 字串在檔案中並非唯一

解決方法：

• 再次讀取檔案以取得當前內容
• 提供較大的上下文字串以確保唯一性
• 對多個相同字串使用 replace_all=true
• 確認 file_path 正確

檢查：

• 位置： 檔案位於 ~/.verdent/subagents/[name].md
• 呼叫政策： 嚴格政策需要明確的 @-mention
• YAML frontmatter： 有效的語法
• 「When to use」指引： 與你的請求模式相符

測試： 使用明確的 @-mention 來驗證子代理是否運作：@your-subagent do task