---
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 | 优秀 | 高级样式、变量、混入 |
  </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>