URL: /guide/built-in-tools

---
title: 内置工具
description: Zapmyco 在 `zapmyco run` 模式下提供的 AI Agent 内置工具参考
---

Zapmyco 的内置工具系统为 AI Agent 提供了与本地环境和用户交互的能力。大多数工具在 `zapmyco run <content>` 一次性执行模式下可用，而交互式工具（如 `ask_user`、`task_*`）在交互模式（`zapmyco` 无参数）下也可用。

## 工具速查

| 工具名称 | 功能 | 能力 |
|----------|------|------|
| [web_fetch](/built-in/web_fetch) | 获取网页内容 | 将指定 URL 的网页转换为 Markdown，供 AI 分析 |
| [web_search](/built-in/web_search) | 搜索网络 | 搜索实时信息（新闻、文档、趋势等） |
| [shell_exec](/built-in/shell_exec) | 执行命令 | 在本地系统执行 shell 命令并返回输出 |
| [file_read](/built-in/file_read) | 读取文件内容 | 按行号范围读取本地文件内容，支持分段查看 |
| [file_search](/built-in/file_search) | 搜索文件内容 | 在本地文件系统中搜索文件内容，支持正则表达式 |
| [file_find](/built-in/file_find) | 查找文件 | 按 glob 通配符模式（如 `**/*.rs`）在本地文件系统中查找文件 |
| [file_edit](/built-in/file_edit) | 编辑文件内容 | 五种模式：line_range（推荐）、append、insert_after、批量编辑、旧模式 |
| [file_write](/built-in/file_write) | 写入文件 | 创建新文件或完整覆盖已有文件，含预读检查和二进制检测 |
| [ask_user](/built-in/ask_user) | 询问用户 | 向用户提出选项问题并获取回答，支持单选/多选和自定义输入 |
| [task_create](/built-in/task_create) | 创建任务 | 创建新任务以跟踪复杂多步骤工作进度 |
| [task_get](/built-in/task_get) | 查看任务 | 按 ID 获取单个任务的详情和状态 |
| [task_list](/built-in/task_list) | 列出任务 | 列出当前所有任务及其状态概览 |
| [task_update](/built-in/task_update) | 更新任务 | 更新任务的状态、字段和依赖关系 |
| [subagent](/built-in/subagent) | 子代理管理 | 创建独立子进程并发执行任务，支持 spawn/poll/list/kill |
| [skill](/built-in/skill) | Skill 管理 | 管理 Skill 工作流模板，支持 list/load 两种操作 |

## 按类别浏览

### 网络工具

| 工具 | 说明 | 文档 |
|------|------|:----:|
| `web_fetch` | 获取指定 URL 的网页内容 | [查看详情](/built-in/web_fetch) |
| `web_search` | 搜索网络获取实时信息 | [查看详情](/built-in/web_search) |

AI Agent 会自动组合两者：先用 `web_search` 找到相关页面，再用 `web_fetch` 获取具体内容。

### 命令执行

| 工具 | 说明 | 文档 |
|------|------|:----:|
| `shell_exec` | 在本地系统执行 shell 命令 | [查看详情](/built-in/shell_exec) |

执行命令前会弹出确认提示，需用户授权。

### 文件操作

| 工具 | 说明 | 文档 |
|------|------|:----:|
| `file_read` | 读取文件内容，支持行号范围分段查看 | [查看详情](/built-in/file_read) |
| `file_search` | 使用正则表达式搜索文件内容 | [查看详情](/built-in/file_search) |
| `file_find` | 按 glob 模式按名称查找文件 | [查看详情](/built-in/file_find) |
| `file_edit` | 对已有文件进行精确、安全的内容修改 | [查看详情](/built-in/file_edit) |
| `file_write` | 创建新文件或完整覆盖已有文件 | [查看详情](/built-in/file_write) |

文件操作工具之间可以组合使用：先用 `file_find` 定位文件，用 `file_search` 搜索内容，用 `file_read` 查看上下文，再用 `file_edit` 或 `file_write` 进行修改。

### 交互工具

| 工具 | 说明 | 文档 |
|------|------|:----:|
| `ask_user` | 向用户提出选项问题并获取回答 | [查看详情](/built-in/ask_user) |

### 任务管理

| 工具 | 说明 | 文档 |
|------|------|:----:|
| `task_create` | 创建新任务以跟踪工作进度 | [查看详情](/built-in/task_create) |
| `task_get` | 按 ID 获取任务详情和状态 | [查看详情](/built-in/task_get) |
| `task_list` | 列出所有任务及其当前状态 | [查看详情](/built-in/task_list) |
| `task_update` | 更新任务状态、字段或依赖关系 | [查看详情](/built-in/task_update) |

AI Agent 会自动组合任务工具完成复杂工作流：先拆解为子任务、跟踪进度、按需查看详情、更新状态。

### 子代理管理

| 工具 | 说明 | 文档 |
|------|------|:----:|
| `subagent` | 创建独立子进程并发执行子任务，支持 spawn/poll/list/kill 四种操作 | [查看详情](/built-in/subagent) |
| `skill` | 管理 Skill 工作流模板，支持 list/load 两种操作 | [查看详情](/built-in/skill) |

子代理通过 `--subagent` 标记禁止递归派生，子进程不注册 SubAgent 工具。输出自动折叠（>2KB 摘要化，>1MB 截断）。

---

## 未来扩展

`ToolHandler` 枚举通过 `#[non_exhaustive]` 标记，预留了扩展能力，未来版本将持续新增工具数量。

| 版本 | 新增工具 | 说明 |
|------|----------|------|
| v0.29+ | `web_fetch`, `web_search`, `shell_exec` | 初始工具：网络获取、网络搜索、命令执行 |
| v0.31+ | `file_read`, `file_search`, `file_find` | 文件操作：读取、内容搜索、文件查找 |
| v0.32+ | `file_edit`, `file_write`, `ask_user` | 文件编辑、文件写入、用户询问 |
| v0.33+ | `task_create`, `task_get`, `task_list`, `task_update` | 任务管理系统 |
| v0.34+ | `file_edit` 重构 | 新增 line_range、append、insert_after、批量编辑模式，内容验证算法 |
| v0.37+ | `subagent` | 子代理管理：创建独立子进程并发执行任务，支持 spawn/poll/list/kill |
| v0.38+ | `skill` | Skill 系统：预定义工作流模板管理，支持 list/load 两种操作；新增 `--skill` CLI 参数；三层 SKILL.md 发现机制；allowed-tools 白名单过滤 |

---

## 最佳实践

- **组合使用**：AI Agent 可自动组合多个工具，例如"搜索 Rust 最新版本 → 访问发布页面 → 总结变更内容"
- **`description` 参数**：在 prompt 中说明为什么需要执行某个命令，有助于 AI Agent 生成更有意义的描述，方便你判断是否授权
- **安全审慎**：只授权你确认过且安全的命令，对于删除、修改系统配置等危险操作应当慎重
- **大型页面限制**：`web_fetch` 对大文档页面输出上限为 100K 字符，AI 可能只能看到截断后的内容，复杂任务可考虑分步骤执行

---

## 相关文档

- [命令参考](/commands/run) — `run` 命令详细用法
- [AI 代理功能](/guide/ai-agent) — AI Agent 工作模式
- [file_edit 设计文档](/guide/file-edit) — 深入理解文件编辑工具的设计原理和安全模型