# 工具系統參考 (/zh-Hant/docs/verdent-for-vscode/advanced-features/tool-reference)

> 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 [#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 [#file_edit]

    **功能：**

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

    **使用情境：**

    * 更新函式實作
    * 修改設定值
    * 跨檔案重構變數名稱

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

    ***

    ### file\_write [#file_write]

    **功能：**

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

    **使用情境：**

    * 產生新元件或模組
    * 建立設定檔
    * 撰寫測試檔案

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

  <Tab title="搜尋與導覽">
    ### glob [#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 [#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_file]

    **功能：**

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

    **使用情境：**

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

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

    ***

    ### list\_dir [#list_dir]

    **功能：**

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

    **使用情境：**

    * 理解專案結構
    * 驗證目錄組織
    * 找出特定子目錄
  </Tab>

  <Tab title="執行與整合">
    ### bash [#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 [#spawn_subagent]

    **功能：**

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

    **使用情境：**

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

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

    ***

    ### todo\_update [#todo_update]

    **功能：**

    * 建立並管理任務清單
    * 更新任務狀態（pending、in\_progress、completed）
    * 在複雜實作過程中追蹤進度

    **使用情境：**

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

  <Tab title="網路存取">
    ### web\_search [#web_search]

    **功能：**

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

    **使用情境：**

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

    ***

    ### web\_fetch [#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 效率 [#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 精準度 [#file_edit-精準度]

    **最佳做法：**

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

    ***

    ### file\_write 安全性 [#file_write-安全性]

    **最佳做法：**

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

  <Tab title="搜尋與導覽">
    ### glob 模式具體性 [#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 策略 [#grep-策略]

    **建議的工作流程：**

    1. 使用 `grep_file` 識別相關檔案
    2. 以 `file_read` 讀取特定檔案
    3. 當你需要周圍上下文時，使用 `grep_content`

    **效能提示：**

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

  <Tab title="命令執行">
    ### bash 最佳做法 [#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>