限制與約束

不支援二進位檔案

Verdent 的檔案工具僅適用於文字格式。以下類型無法編輯：

替代方案： 二進位檔案可以在程式碼中被引用或進行概念上的討論，但修改需要外部工具。

file_read 行數限制

限制：

• 大型檔案（>10,000 行）應分段讀取
• 完整讀取大型檔案可能導致上下文耗盡

解決方案： 使用行範圍：file_read("file.js", start_line=100, max_lines=50)

bash 指令逾時

限制：

• 最大逾時時間：120 秒（2 分鐘）
• 長時間執行的操作會被自動終止

解決方案： 將操作拆分為可在 2 分鐘內完成的較小指令

搜尋效能

限制：

• 過於寬泛的 glob 模式（**/*）可能回傳數千筆結果
• 正規表示式搜尋比字面字串慢

解決方案： 使用特定模式並排除不必要的目錄

上下文耗盡

問題： 在長時間的工作階段或複雜操作期間，AI 的上下文視窗可能會被填滿，限制了引用較早對話內容的能力。

緩解策略：

• 使用子代理進行探索性研究（結果只會消耗主上下文）
• 使用行範圍策略性地讀取檔案
• 在讀取完整內容前先使用 grep_file
• 將背景任務委派給 Explorer 子代理

無法直接進行系統管理

無法：

• 以程式方式修改 VS Code 設定
• 自動安裝 VS Code 擴充功能
• 變更系統層級的設定
• 重新啟動 VS Code 或系統服務

範圍： Verdent 在 VS Code 工作區內運作，而非系統管理層級。

無法自主執行

手動接受模式控制：

• 使用者必須在手動接受模式中核准工具執行
• 未經核准不會有自動化的背景操作
• 無法在 VS Code 關閉時執行指令

目的： 確保安全性以及使用者對所有操作的掌控。

無法即時監控

無法：

• 持續監控執行中的程序
• 即時追蹤檔案系統變更
• 對系統事件發出警示
• 持續串流記錄檔

替代方案： 使用 MCP 整合來搭配外部監控工具。

沒有 MCP 時無法進行網路操作

內建限制：

• 無法發出任意 HTTP 請求（使用 web_fetch 處理特定頁面）
• 無法直接連接資料庫（需要 MCP）
• 無法直接存取雲端服務（需要 MCP）
• 沒有即時 API 整合（需要 MCP）

解決方案： 設定 MCP 伺服器以存取外部系統。

二進位檔案修改

限制： 無法編輯圖片、PDF 或編譯後的二進位檔

替代方案：

• 在 bash 指令中引用外部工具：bash("convert input.png -resize 50% output.png")
• 產生可供外部工具執行的指令碼
• 為二進位檔案操作記錄手動步驟

範例：

# Image conversion
bash("convert input.png -resize 50% output.png")

# PDF to text
bash("pdftotext document.pdf output.txt")

大型檔案處理

限制： 超過 10,000 行的檔案會對上下文視窗造成負擔

替代方案：

• 使用行範圍：file_read("large.log", start_line=1000, max_lines=100)
• 先搜尋：grep_content("ERROR", glob="large.log") 以找出相關段落
• 將檔案拆分為較小的模組以便管理

上下文視窗耗盡

限制： 長時間對話會填滿上下文視窗

替代方案：

• 委派給 Explorer 子代理進行程式碼庫研究
• 使用 Verifier 子代理進行隔離的驗證任務
• 為不同任務開啟新對話
• 使用 todo_update 跨工作階段追蹤進度

最佳實務： 將背景研究委派給子代理，以保留主上下文供進行中的開發使用。

平台指令差異

限制： bash 指令在 Windows 與 Unix 之間有所不同

替代方案：

• 使用跨平台工具：以 npm 指令碼取代原生 bash
• 條件式指令：bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
• 在專案專屬的 AGENTS.md 中加入平台備註

範例：

# Cross-platform
bash("npm run build")

# Platform-specific conditional
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then make; else nmake; fi")