---
title: 工具系統參考
description: Verdent 工具系統的完整參考
---



### 你將學到什麼

Verdent 內建工具系統的完整參考，涵蓋檔案操作、搜尋功能、命令執行以及整合工具。

---

## 可用工具總覽

Verdent for VS Code 提供完整的工具組，用於程式碼操作、導覽以及與外部互動。

<Tabs>
  <Tab title="檔案操作">
    | 工具 | 用途 | 主要功能 |
    |------|---------|------------------|
    | `file_read` | 讀取檔案內容 | 支援大型檔案的行範圍，適用於所有文字格式 |
    | `file_edit` | 針對性修改 | 替換完全相符的文字、多處替換、保留格式 |
    | `file_write` | 建立或覆寫檔案 | 完整建立／替換檔案，處理文字內容 |
  </Tab>

  <Tab title="搜尋與導覽">
    | 工具 | 用途 | 主要功能 |
    |------|---------|------------------|
    | `glob` | 以模式為基礎的檔案搜尋 | Glob 模式（`**/*.ts`）、排除模式、結果數量限制 |
    | `grep_content` | 帶上下文的內容搜尋 | 支援正規表達式、上下文行、不分大小寫選項 |
    | `grep_file` | 列出含相符項目的檔案 | 在讀取內容前快速找出檔案 |
    | `list_dir` | 目錄結構 | 顯示階層、排除模式、深度控制 |
  </Tab>

  <Tab title="執行與整合">
    | 工具 | 用途 | 主要功能 |
    |------|---------|------------------|
    | `bash` | Shell 命令執行 | 逾時設定、摘要說明、命令串接 |
    | `spawn_subagent` | 委派給專家 | 啟動 general、explorer、verifier 或 code-reviewer 子代理 |
    | `todo_update` | 追蹤任務進度 | 管理任務清單、更新狀態、進度追蹤 |
  </Tab>

  <Tab title="網路存取">
    | 工具 | 用途 | 主要功能 |
    |------|---------|------------------|
    | `web_search` | 網路搜尋 | 查詢執行、結果數量控制、新鮮度篩選 |
    | `web_fetch` | 擷取並分析網頁 | 取得內容、以查詢擷取資訊 |
  </Tab>
</Tabs>

---

## 工具功能與使用情境

<Tabs>
  <Tab title="檔案操作">
    ### file_read

    **功能：**
    - 讀取完整檔案內容或特定行範圍
    - 在修改前理解程式碼的必要工具
    - 透過範圍指定有效處理大型檔案

    **使用情境：**
    - 編輯前讀取設定檔
    - 理解既有的實作模式
    - 審查測試檔案以了解覆蓋率

    **範例：**
    ```bash
    # Read entire file
    file_read("src/components/Button.tsx")

    # Read specific range for large files
    file_read("package-lock.json", start_line=1, max_lines=50)
    ```

    ---

    ### file_edit

    **功能：**
    - 使用完全字串相符進行精準文字替換
    - 透過 `multiple` 旗標進行多處替換
    - 保留檔案結構與格式

    **使用情境：**
    - 更新函式實作
    - 修改設定值
    - 跨檔案重構變數名稱

    **最佳做法：** 用於針對性的變更。若要完整重寫，請改用 `file_write`。

    ---

    ### file_write

    **功能：**
    - 從零開始建立新檔案
    - 完全替換既有檔案內容
    - 處理任何以文字為基礎的格式

    **使用情境：**
    - 產生新元件或模組
    - 建立設定檔
    - 撰寫測試檔案

    **警告：** 會完全覆寫既有檔案。針對局部修改請使用 `file_edit`。
  </Tab>

  <Tab title="搜尋與導覽">
    ### glob

    **功能：**
    - 找出符合模式的檔案：`**/*.ts`、`src/**/*.js`
    - 依目錄路徑篩選
    - 以排除模式縮小結果
    - 控制結果數量

    **使用情境：**
    - 找出專案中的所有元件
    - 定位測試檔案
    - 跨目錄識別設定檔

    **範例模式：**
    ```bash
    **/*.tsx          # All TypeScript React files
    src/**/*.test.js  # All test files in src
    **/config.*       # All config files anywhere
    ```

    ---

    ### grep_content

    **功能：**
    - 使用正規表達式模式搜尋檔案內容
    - 顯示相符項目前後的上下文行（`-B`、`-A` 旗標）
    - 不分大小寫搜尋
    - 使用 glob 模式依檔案類型篩選

    **使用情境：**
    - 找出函式定義
    - 定位 API 端點實作
    - 搜尋特定錯誤訊息
    - 識別安全模式

    **範例：**
    ```bash
    # Find authentication-related code
    grep_content("auth.*login", glob="**/*.ts")

    # Search with context
    grep_content("TODO", glob="src/**", context_before=2, context_after=2)
    ```

    ---

    ### grep_file

    **功能：**
    - 列出含有相符模式的檔案
    - 當你只需檔案位置時，比 `grep_content` 更快
    - 支援正規表達式模式
    - 以 glob 篩選檔案類型

    **使用情境：**
    - 識別哪些檔案需要重構
    - 找出匯入特定模組的檔案
    - 定位含過時模式的檔案

    **最佳做法：** 先用 `grep_file` 識別相關檔案，再用 `file_read` 進行詳細檢視。

    ---

    ### list_dir

    **功能：**
    - 顯示目錄階層
    - 透過 `max_depth` 參數控制深度
    - 以排除模式篩選輸出

    **使用情境：**
    - 理解專案結構
    - 驗證目錄組織
    - 找出特定子目錄
  </Tab>

  <Tab title="執行與整合">
    ### bash

    **功能：**
    - 執行 shell 命令
    - 最大逾時：120 秒（2 分鐘，硬性限制）
    - 以 `&&` 串接有相依關係的命令
    - 提供說明性摘要以利清晰

    **使用情境：**
    - 執行測試
    - 建置專案
    - 安裝相依套件
    - Git 操作
    - 資料庫遷移

    **範例：**
    ```bash
    # Run tests
    bash("npm test", timeout=60000, summary="Run Jest test suite")

    # Chain dependent commands
    bash("npm install && npm run build", timeout=120000)
    ```

    **安全性：** 命令以使用者權限執行。請在手動接受模式下審查命令。

    ---

    ### spawn_subagent

    **功能：**
    - 啟動具有獨立上下文的專門子代理
    - 類型：`explorer`、`verifier`、`code-reviewer`
    - 委派複雜任務而不污染主要上下文
    - 平行執行子代理以提升效率

    **使用情境：**
    - **explorer：** 在大型程式碼庫中搜尋模式
    - **verifier：** 驗證實作邏輯
    - **code-reviewer：** 安全與品質評估

    **最佳做法：** 將探索性研究委派給 Explorer 子代理，以保留主要對話的上下文。

    ---

    ### todo_update

    **功能：**
    - 建立並管理任務清單
    - 更新任務狀態（pending、in_progress、completed）
    - 在複雜實作過程中追蹤進度

    **使用情境：**
    - 拆解多步驟功能
    - 追蹤重構進度
    - 管理遷移任務
  </Tab>

  <Tab title="網路存取">
    ### web_search

    **功能：**
    - 查詢網路搜尋引擎
    - 控制結果數量
    - 依新鮮度篩選（近期天數）

    **使用情境：**
    - 為不熟悉的 API 尋找文件
    - 研究錯誤訊息
    - 查看目前的最佳做法

    ---

    ### web_fetch

    **功能：**
    - 取得網頁內容
    - 以特定查詢分析內容
    - 擷取結構化資訊

    **使用情境：**
    - 閱讀文件頁面
    - 分析 API 文件
    - 從教學擷取範例
  </Tab>
</Tabs>

---

## 檔案格式支援

Verdent 透過其檔案操作工具，適用於所有以文字為基礎的檔案格式。

<Tabs>
  <Tab title="原始碼">
    | 類別 | 語言／副檔名 |
    |----------|---------------------|
    | **Web** | JavaScript、TypeScript、HTML、CSS、SCSS、LESS |
    | **後端** | Python、Java、Go、Rust、C、C++、C#、Ruby、PHP、Perl |
    | **行動裝置** | Swift、Kotlin、Dart（Flutter）、Objective-C |
    | **函數式** | Haskell、Scala、Elixir、Clojure、F# |
    | **指令稿** | Bash、PowerShell、Zsh、Fish |
    | **資料** | SQL、R、Julia、MATLAB |
  </Tab>

  <Tab title="設定">
    | 格式 | 常見範例 |
    |--------|----------------|
    | **JSON** | package.json、tsconfig.json、settings.json |
    | **YAML** | docker-compose.yml、GitHub Actions、Kubernetes 設定 |
    | **TOML** | Cargo.toml、pyproject.toml |
    | **XML** | pom.xml、web.xml、設定檔 |
    | **INI** | .gitconfig、.editorconfig |
    | **ENV** | .env 檔案、環境設定 |
    | **HCL** | Terraform 設定 |
  </Tab>

  <Tab title="文件">
    | 格式 | 使用情境 |
    |--------|-----------|
    | **Markdown** | README.md、文件檔案 |
    | **HTML** | 範本、網頁 |
    | **LaTeX** | 科學文件、學術論文 |
    | **reStructuredText** | Python 文件 |
    | **AsciiDoc** | 技術文件 |
  </Tab>

  <Tab title="資料與建置">
    ### 資料格式

    | 格式 | 說明 |
    |--------|-------------|
    | **CSV/TSV** | 表格資料檔案 |
    | **以文字為基礎的資料** | 記錄檔、資料傾印 |
    | **JSON/YAML** | 結構化資料交換 |

    ### 建置與套件檔案

    | 檔案 | 用途 |
    |------|---------|
    | **Makefile** | 建置自動化 |
    | **package.json** | Node.js 相依套件 |
    | **requirements.txt** | Python 套件 |
    | **Gemfile** | Ruby gems |
    | **Cargo.toml** | Rust 套件 |
    | **build.gradle** | Gradle 建置 |
  </Tab>

  <Tab title="二進位限制">
    | 格式類型 | 範例 | 可編輯性 |
    |-------------|----------|-------------|
    | **圖片** | PNG、JPG、GIF、SVG（二進位） | 無法直接編輯 |
    | **影片** | MP4、AVI、MOV | 無法直接編輯 |
    | **編譯後的二進位檔** | EXE、DLL、SO | 無法直接編輯 |
    | **壓縮檔** | ZIP、TAR、GZ | 無法直接編輯 |
    | **Office 文件** | DOCX、XLSX、PPTX | 無法直接編輯 |
    | **PDF** | PDF 檔案 | 無法直接編輯 |

    <Note>
    二進位檔案可在程式碼中被參照，但無法透過檔案工具修改。
    </Note>
  </Tab>
</Tabs>

---

## 程式語言支援

Verdent 為所有以文字為基礎的程式語言與框架提供完整支援。

<Tabs>
  <Tab title="Web 開發">
    | 語言／框架 | 支援程度 | 常見使用情境 |
    |-------------------|---------------|------------------|
    | JavaScript | 優異 | 前端邏輯、Node.js 後端、工具 |
    | TypeScript | 優異 | 型別安全的 Web 應用、大規模專案 |
    | React | 優異 | 元件化 UI、hooks、狀態管理 |
    | Vue | 優異 | 漸進式 Web 應用、單一檔案元件 |
    | Angular | 優異 | 企業級應用、TypeScript 整合 |
    | Svelte | 非常好 | 編譯型元件、響應式程式設計 |
    | HTML/CSS | 優異 | 標記、樣式、響應式設計 |
    | SCSS/LESS | 優異 | 進階樣式、變數、mixins |
  </Tab>

  <Tab title="後端">
    | 語言／框架 | 支援程度 | 常見使用情境 |
    |-------------------|---------------|------------------|
    | Python | 優異 | API、資料處理、自動化 |
    | Django/Flask/FastAPI | 優異 | Web 框架、REST API |
    | Node.js/Express | 優異 | JavaScript 後端、微服務 |
    | Java/Spring | 優異 | 企業級應用、Spring Boot |
    | Go | 優異 | 高效能服務、CLI |
    | Rust | 非常好 | 系統程式設計、效能關鍵程式碼 |
    | C/C++ | 非常好 | 系統、嵌入式、遊戲引擎 |
    | C# / .NET | 優異 | Windows 應用、Web 服務、Unity |
    | Ruby/Rails | 非常好 | Web 應用、快速開發 |
    | PHP | 良好 | WordPress、Laravel、舊版應用 |
  </Tab>

  <Tab title="行動裝置">
    | 語言／框架 | 支援程度 | 常見使用情境 |
    |-------------------|---------------|------------------|
    | Swift | 優異 | iOS/macOS 原生應用 |
    | Kotlin | 優異 | Android 原生應用 |
    | Dart/Flutter | 優異 | 跨平台行動應用 |
    | React Native | 優異 | 以 JavaScript 為基礎的行動應用 |
    | Objective-C | 良好 | 舊版 iOS/macOS 應用 |
  </Tab>

  <Tab title="資料與科學">
    | 語言 | 支援程度 | 常見使用情境 |
    |----------|---------------|------------------|
    | Python | 優異 | NumPy、Pandas、scikit-learn、TensorFlow |
    | R | 非常好 | 統計分析、資料視覺化 |
    | SQL | 優異 | 資料庫查詢、結構描述設計 |
    | Julia | 良好 | 科學計算、數值分析 |
  </Tab>

  <Tab title="系統與底層">
    | 語言 | 支援程度 | 常見使用情境 |
    |----------|---------------|------------------|
    | C | 非常好 | 系統程式設計、嵌入式 |
    | C++ | 非常好 | 效能關鍵應用 |
    | Rust | 非常好 | 記憶體安全的系統程式設計 |
    | Go | 優異 | 並行系統、雲端服務 |
    | Assembly | 良好 | 底層最佳化、除錯 |
  </Tab>
</Tabs>

**支援品質：** 常見語言（JavaScript、Python、TypeScript）因有大量訓練資料而支援較強。較不常見或特定領域的語言可能支援品質較低，但仍可運作。

---

## 使用限制與最佳做法

<Tabs>
  <Tab title="檔案操作">
    ### file_read 效率

    **最佳做法：**
    - 對超過 500 行的檔案使用行範圍，以避免上下文超載
    - 只讀取任務所需的相關區段
    - 對於大型檔案，先用 `grep_content` 識別相關的行號

    ```bash
    # Good: Read specific section
    file_read("large-config.json", start_line=100, max_lines=50)

    # Less efficient: Read entire large file
    file_read("large-config.json")  # May consume excessive context
    ```

    ---

    ### file_edit 精準度

    **最佳做法：**
    - 確保完全字串相符以避免失敗的編輯
    - 對多處類似變更，使用 `multiple=true` 旗標
    - 編輯前驗證檔案路徑

    ---

    ### file_write 安全性

    **最佳做法：**
    - 仔細檢查路徑以防止意外覆寫
    - 僅用於新檔案或完整重寫
    - 進行修改時，為求安全請優先使用 `file_edit`
  </Tab>

  <Tab title="搜尋與導覽">
    ### glob 模式具體性

    **最佳做法：**
    - 使用具體模式以縮小範圍：用 `src/**/*.ts` 而非 `**/*`
    - 以排除模式排除目錄：`!**/node_modules/**`
    - 限制結果以防止輸出過多

    ```bash
    # Good: Specific scope
    glob("src/components/**/*.tsx", max_results=50)

    # Less efficient: Too broad
    glob("**/*")  # Returns thousands of results
    ```

    ---

    ### grep 策略

    **建議的工作流程：**
    1. 使用 `grep_file` 識別相關檔案
    2. 以 `file_read` 讀取特定檔案
    3. 當你需要周圍上下文時，使用 `grep_content`

    **效能提示：**
    - 正規表達式模式可能比純字串花更久
    - 不分大小寫搜尋較慢
    - 將上下文行（`-A`、`-B`）限制在必要範圍內
  </Tab>

  <Tab title="命令執行">
    ### bash 最佳做法

    **安全的命令執行：**
    - 為命令說明提供清楚的摘要
    - 為長時間執行的操作設定適當的逾時
    - 以 `&&` 串接有相依關係的命令
    - 仔細審查破壞性命令（rm、drop、truncate）

    ```bash
    # Good: Clear summary, reasonable timeout
    bash("npm run build", timeout=120000, summary="Build production bundle")

    # Good: Chained dependencies
    bash("npm install && npm run test", timeout=180000)
    ```

    ---

    ### 安全性考量

    **關鍵安全規則：**
    - 命令以使用者權限執行
    - 切勿執行不受信任的命令
    - 在共用程式碼庫中使用手動接受模式進行審查
    - 避免會暴露憑證或敏感資料的命令

    <Warning>
    在共用程式碼庫或正式環境中工作時，務必在手動接受模式下審查 bash 命令。
    </Warning>
  </Tab>

  <Tab title="子代理與上下文">
    ### 子代理委派效率

    **何時使用子代理：**
    - **Explorer：** 程式碼庫搜尋、架構問題（節省主要上下文）
    - **Verifier：** 快速驗證檢查（獨立驗證）
    - **Code-reviewer：** 安全與品質審查（詳細分析）
    - **General：** 複雜的多步驟任務（平行執行）

    **最佳做法：**
    將探索與研究任務委派給子代理，以保留主要對話的上下文供進行中的開發工作使用。

    ---

    ### 上下文管理

    **策略性工具使用：**
    - 有策略地讀取檔案——只讀取所需內容
    - 使用子代理進行背景研究
    - 在長時間工作階段中監控上下文消耗
    - 以 todo_update 將複雜操作拆解為步驟

    **高效的工作流程：**
    1. **規劃：** 使用 glob/grep 識別範圍
    2. **讀取：** 只讀取相關的檔案／區段
    3. **執行：** 適當時委派給子代理
    4. **驗證：** 以 Verifier 子代理進行快速檢查
  </Tab>

  <Tab title="效能">
    ### 檔案大小限制

    **大型檔案處理：**
    非常大的檔案（>10,000 行）應分段讀取，以避免：
    - 上下文視窗耗盡
    - 回應緩慢
    - 記憶體問題

    <Tip>
    對於超過 500 行的檔案，務必使用 `file_read` 搭配行範圍，以維持最佳效能。
    </Tip>

    ---

    ### 工具逾時預設值

    **工具限制：**
    - **Bash 逾時：** 最大 120 秒（2 分鐘）
    - **檔案操作：** 無大小限制（大型檔案會自動分批讀取）
    - **大型檔案處理：** >256KB 的檔案僅回傳前 256KB 的內容
    - **搜尋結果：** `glob` 或 `grep_content` 的結果無限制
    - **並行子代理：** 平行執行無限制

    **逾時設定：**
    - 為長時間執行的操作設定明確的逾時
    - 監控是否有掛起的處理程序
    - 超過 2 分鐘逾時的命令將被終止

    ---

    ### 並行操作

    **平行執行：**
    多個子代理可平行執行，以加快複雜操作。主要代理會自動處理協調。

    **效能優勢：**
    - 減少多步驟任務的總執行時間
    - 高效的資源運用
    - 自動任務編排
    - 並行子代理數量無限制
  </Tab>
</Tabs>

---

## 另請參閱

<CardGroup cols={2}>
  <Card title="子代理管理" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    了解專門代理
  </Card>
  <Card title="執行模式" icon="sliders" href="/docs/verdent-for-vscode/execution-modes/overview">
    透過模式控制工具執行
  </Card>
</CardGroup>