# 工具系统参考 (/zh-CN/docs/verdent-for-vscode/advanced-features/tool-reference)
> Verdent 工具系统完整参考
### 你将学到什么 [#你将学到什么]
Verdent 内置工具系统的全面参考，涵盖文件操作、搜索能力、命令执行和集成工具。
***
## 可用工具概览 [#可用工具概览]
Verdent for VS Code 提供了一套全面的工具集，用于代码操作、导航和外部交互。
| 工具 | 用途 | 核心能力 |
| ------------ | ------- | --------------------- |
| `file_read` | 读取文件内容 | 支持大文件的行范围读取，适用于所有文本格式 |
| `file_edit` | 定向修改 | 替换精确匹配的文本，支持多处替换，保留格式 |
| `file_write` | 创建或覆盖文件 | 完整创建/替换文件，处理文本内容 |
| 工具 | 用途 | 核心能力 |
| -------------- | --------- | ------------------------------ |
| `glob` | 基于模式的文件搜索 | Glob 模式（`**/*.ts`）、排除模式、结果数量限制 |
| `grep_content` | 带上下文的内容搜索 | 支持正则、上下文行、忽略大小写选项 |
| `grep_file` | 列出含匹配项的文件 | 在读取内容前快速识别文件 |
| `list_dir` | 目录结构 | 显示层级、排除模式、深度控制 |
| 工具 | 用途 | 核心能力 |
| ---------------- | ---------- | ------------------------------------------------- |
| `bash` | Shell 命令执行 | 超时配置、摘要描述、命令链式调用 |
| `spawn_subagent` | 委派给专家 | 启动 general、explorer、verifier 或 code-reviewer 子智能体 |
| `todo_update` | 追踪任务进度 | 管理任务列表、更新状态、进度追踪 |
| 工具 | 用途 | 核心能力 |
| ------------ | ------- | ----------------- |
| `web_search` | 互联网搜索 | 查询执行、结果数量控制、时效性过滤 |
| `web_fetch` | 抓取并分析页面 | 获取内容，通过查询提取信息 |
***
## 工具能力与使用场景 [#工具能力与使用场景]
### 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`。
### 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` 参数控制深度
* 通过排除模式过滤输出
**使用场景：**
* 理解项目结构
* 验证目录组织
* 查找特定子目录
### 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）
* 在复杂实现中追踪进度
**使用场景：**
* 拆解多步骤功能
* 追踪重构进度
* 管理迁移任务
### web\_search [#web_search]
**能力：**
* 查询互联网搜索引擎
* 控制结果数量
* 按时效性过滤（最近天数）
**使用场景：**
* 查找陌生 API 的文档
* 研究错误信息
* 查看当前最佳实践
***
### web\_fetch [#web_fetch]
**能力：**
* 获取网页内容
* 用特定查询分析内容
* 提取结构化信息
**使用场景：**
* 阅读文档页面
* 分析 API 文档
* 从教程中提取示例
***
## 文件格式支持 [#文件格式支持]
Verdent 通过其文件操作工具支持所有基于文本的文件格式。
| 类别 | 语言/扩展名 |
| ------- | ------------------------------------------ |
| **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 |
| 格式 | 常见示例 |
| -------- | ----------------------------------------------- |
| **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 配置 |
| 格式 | 使用场景 |
| -------------------- | -------------- |
| **Markdown** | README.md、文档文件 |
| **HTML** | 模板、网页 |
| **LaTeX** | 科学文档、学术论文 |
| **reStructuredText** | Python 文档 |
| **AsciiDoc** | 技术文档 |
### 数据格式 [#数据格式]
| 格式 | 描述 |
| ------------- | --------- |
| **CSV/TSV** | 表格数据文件 |
| **基于文本的数据** | 日志文件、数据转储 |
| **JSON/YAML** | 结构化数据交换 |
### 构建与包文件 [#构建与包文件]
| 文件 | 用途 |
| -------------------- | ---------- |
| **Makefile** | 构建自动化 |
| **package.json** | Node.js 依赖 |
| **requirements.txt** | Python 包 |
| **Gemfile** | Ruby gems |
| **Cargo.toml** | Rust 包 |
| **build.gradle** | Gradle 构建 |
| 格式类型 | 示例 | 可编辑性 |
| ------------- | -------------------- | ------ |
| **图片** | PNG、JPG、GIF、SVG（二进制） | 不可直接编辑 |
| **视频** | MP4、AVI、MOV | 不可直接编辑 |
| **已编译二进制文件** | EXE、DLL、SO | 不可直接编辑 |
| **压缩包** | ZIP、TAR、GZ | 不可直接编辑 |
| **Office 文档** | DOCX、XLSX、PPTX | 不可直接编辑 |
| **PDF** | PDF 文件 | 不可直接编辑 |
二进制文件可以在代码中被引用，但无法通过文件工具修改。
***
## 编程语言支持 [#编程语言支持]
Verdent 为所有基于文本的编程语言和框架提供全面支持。
| 语言/框架 | 支持级别 | 常见使用场景 |
| ---------- | ---- | ------------------- |
| JavaScript | 优秀 | 前端逻辑、Node.js 后端、工具链 |
| TypeScript | 优秀 | 类型安全的 Web 应用、大型项目 |
| React | 优秀 | 基于组件的 UI、hooks、状态管理 |
| Vue | 优秀 | 渐进式 Web 应用、单文件组件 |
| Angular | 优秀 | 企业级应用、TypeScript 集成 |
| Svelte | 很好 | 编译型组件、响应式编程 |
| HTML/CSS | 优秀 | 标记、样式、响应式设计 |
| SCSS/LESS | 优秀 | 高级样式、变量、混入 |
| 语言/框架 | 支持级别 | 常见使用场景 |
| -------------------- | ---- | ----------------------- |
| 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、遗留应用 |
| 语言/框架 | 支持级别 | 常见使用场景 |
| ------------ | ---- | ------------------- |
| Swift | 优秀 | iOS/macOS 原生应用 |
| Kotlin | 优秀 | Android 原生应用 |
| Dart/Flutter | 优秀 | 跨平台移动应用 |
| React Native | 优秀 | 基于 JavaScript 的移动应用 |
| Objective-C | 良好 | 遗留 iOS/macOS 应用 |
| 语言 | 支持级别 | 常见使用场景 |
| ------ | ---- | ------------------------------------ |
| Python | 优秀 | NumPy、Pandas、scikit-learn、TensorFlow |
| R | 很好 | 统计分析、数据可视化 |
| SQL | 优秀 | 数据库查询、模式设计 |
| Julia | 良好 | 科学计算、数值分析 |
| 语言 | 支持级别 | 常见使用场景 |
| -------- | ---- | --------- |
| C | 很好 | 系统编程、嵌入式 |
| C++ | 很好 | 性能关键应用 |
| Rust | 很好 | 内存安全的系统编程 |
| Go | 优秀 | 并发系统、云服务 |
| Assembly | 良好 | 底层优化、调试 |
**支持质量：** 常见语言（JavaScript、Python、TypeScript）由于训练数据丰富，支持更强。较冷门或领域专用的语言支持质量可能较低，但仍可正常使用。
***
## 使用限制与最佳实践 [#使用限制与最佳实践]
### 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` 以确保安全
### 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`）限制在必要范围内
### 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)
```
***
### 安全注意事项 [#安全注意事项]
**关键安全规则：**
* 命令以用户权限执行
* 切勿运行不可信的命令
* 在共享代码库中使用手动接受模式进行审查
* 避免暴露凭据或敏感数据的命令
在共享代码库或生产环境中工作时，请始终在手动接受模式下审查 bash 命令。
### 子智能体委派效率 [#子智能体委派效率]
**何时使用子智能体：**
* **Explorer：** 代码库搜索、架构问题（节省主上下文）
* **Verifier：** 快速验证检查（隔离验证）
* **Code-reviewer：** 安全与质量审查（详细分析）
* **General：** 复杂的多步骤任务（并行执行）
**最佳实践：**
将探索性和研究性任务委派给子智能体，以便为活跃的开发工作保留主对话上下文。
***
### 上下文管理 [#上下文管理]
**策略性工具使用：**
* 有策略地读取文件——只读所需内容
* 使用子智能体进行后台研究
* 在长会话中监控上下文消耗
* 用 todo\_update 将复杂操作拆分为步骤
**高效工作流：**
1. **规划：** 用 glob/grep 确定范围
2. **读取：** 仅读取相关文件/部分
3. **执行：** 在合适时委派给子智能体
4. **验证：** 用 Verifier 子智能体进行快速检查
### 文件大小限制 [#文件大小限制]
**大文件处理：**
超大文件（>10,000 行）应分段读取，以避免：
* 上下文窗口耗尽
* 响应时间变慢
* 内存问题
对于超过 500 行的文件，请始终使用 `file_read` 配合行范围，以保持最佳性能。
***
### 工具超时默认值 [#工具超时默认值]
**工具限制：**
* **Bash 超时：** 最大 120 秒（2 分钟）
* **文件操作：** 无大小限制（大文件自动分批读取）
* **大文件处理：** 大于 256KB 的文件仅返回前 256KB 内容
* **搜索结果：** `glob` 或 `grep_content` 结果无限制
* **并发子智能体：** 并行执行无限制
**超时配置：**
* 为长时间运行的操作设置明确的超时
* 监控挂起的进程
* 超过 2 分钟超时的命令将被终止
***
### 并发操作 [#并发操作]
**并行执行：**
多个子智能体可并行运行，以更快完成复杂操作。主智能体会自动处理协调。
**性能优势：**
* 减少多步骤任务的总执行时间
* 高效利用资源
* 自动任务编排
* 并发子智能体数量无限制
***
## 另请参阅 [#另请参阅]
了解专门的智能体
通过模式控制工具执行