Zed AI Agent 内置工具完全参考：读取搜索、文件编辑与子代理工具的文档与源码解析

2026-09-06 13:25:03作者：虞亚竹Luna

本文以 Zed 官方的 Agent 工具参考文档（docs/.doc-examples/reference.md，其正式版本维护在 docs/src/ai/tools.md）为核心，逐一讲解 Zed 内置 AI Agent 的 16 类内置工具：它们各自的用途、输入行为与权限边界，并结合 crates/agent/src/tools.rs、crates/agent/src/thread.rs 及各工具实现源码，说明这些工具是如何被注册、过滤并暴露给模型的。读完后，你将能够准确描述每个工具的能力边界，并知道如何用 Agent Profile 与 Tool Permissions 控制工具的可用性与审批行为。

Agent 工具是什么，在哪里被使用

Zed 内置 Agent 在 Agent Panel 中与模型对话时，可以通过一组内置工具读取、搜索和编辑当前项目的代码库。官方文档将其按职责划分为三类：

Read & Search Tools（读取与搜索工具）：diagnostics、fetch、find_path、grep、list_directory、read_file、search_web
Edit Tools（编辑工具）：copy_path、create_directory、delete_path、edit_file、move_path、write_file、terminal
Other Tools（其他工具）：spawn_agent

工具行为受三层机制共同约束，理解这三层是正确使用它们的前提：

工具权限（Tool Permissions）：决定某次工具调用是自动批准、自动拒绝，还是逐次要求你确认。权限门控的工具及其匹配输入见 Tool Permissions 文档。
Agent Profile：决定哪些工具"可见"。参考文档的正式版本明确指出，具体工具列表可能因 Agent Profile、所选模型提供方和 Zed 版本而变化，Profile 控制工具的可用性，而权限控制 allow/deny/confirm 行为（见 Agent Profiles）。
项目信任与沙箱：terminal 工具在开启 Zed Agent 沙箱时还可附加操作系统级限制；而 fetch 不在终端 OS 沙箱内运行，终端沙箱的网络授权（如 allow_hosts）对它不生效。

想要在此基础之上扩展自定义工具，可以接入 MCP servers（Model Context Protocol）。

源码视角：工具是如何注册的

从源码结构看，所有内置工具在 crates/agent/src/tools.rs 中通过 tools! 宏集中声明。该宏在编译期生成 ALL_TOOL_NAMES 常量列表（并校验工具名唯一性），同时提供两个关键查询函数：

tool_supports_provider：判断某工具是否支持特定模型提供方；
tool_allowed_in_restricted_mode：判断工具能否在受限工作区使用——源码测试确认 fetch 与 terminal 在受限模式下被禁止，其余内置工具与未知（如 MCP）工具放行（crates/agent/src/tools.rs）。

工具实例化发生在 Thread::add_default_tools（crates/agent/src/thread.rs）：每个会话线程构造时会依次 add_tool 注册文件操作、搜索、诊断、终端、网络等全部工具。其中有两个值得注意的细节：

terminal 与 SandboxedTerminalTool 会同时注册，模型实际看到的 terminal 由当前沙箱状态决定暴露哪一个；
SpawnAgentTool 仅在 self.depth() < MAX_SUBAGENT_DEPTH 时注册，即子代理嵌套超过深度上限后不能再派生新的子代理。

另外，crates/agent/src/tools.rs 中的 tool_feature_flag_enabled 是功能开关的唯一事实来源：部分工具（如 LSP 相关工具、rename 等）受 feature flag 门控，flag 未开启时会被静默丢弃；Agent Profile 配置 UI 使用同一道门控，保证界面上不会列出 Agent 实际无法使用的工具。源码注释也明确指出，把工具加进宏列表并不等于模型能收到它——Agent Profile 的 tools 白名单（见 assets/settings/default.json）会进一步过滤。

参数反序列化还有一个工程细节：deserialize_maybe_stringified（crates/agent/src/tools.rs）允许工具入参以 JSON 字符串的形式给出并自动二次解析，因为部分模型偶尔会把嵌套参数 stringify。

读取与搜索工具（Read & Search Tools）

`diagnostics`：编辑后检查编译/类型错误

获取单个文件或整个项目的错误与警告，适合在编辑之后判断是否还需要进一步修改：

提供 path 时，返回该文件的全部诊断信息；
不提供 path 时，返回整个项目的错误/警告数量汇总。

典型用法：编辑某个源文件后，用该文件路径调用 diagnostics 立刻确认是否引入类型错误；跨多文件的大规模重构后，不带路径调用以获得全项目错误计数，再决定下一步修什么。实现位于 crates/agent/src/tools/diagnostics_tool.rs。

`fetch`：抓取 URL 并转为 Markdown

抓取指定 URL 的内容并以 Markdown 形式返回，常用于把在线文档作为上下文提供给模型。注意其权限语义：fetch 受工具权限、Agent Profile 和项目信任共同约束，且不运行在终端 OS 沙箱内，因此终端沙箱的网络授权（allow_hosts、allow_all_hosts）对它无效。实现位于 crates/agent/src/tools/fetch_tool.rs。

`find_path`：按 glob 模式快速定位文件

用 glob 模式（如 **/*.js、src/**/*.ts）匹配项目内文件路径，按字母序返回匹配结果。源码层面（crates/agent/src/tools/find_path_tool.rs）可以看到它的完整输入与行为约定：

输入字段：glob（必填，对项目中每个路径做匹配）、offset（可选，0 基分页起点）；
结果分页，每页 50 条（RESULTS_PER_PAGE = 50），超出一页时输出中会提示"提供 offset 参数获取后续结果"；
工具描述中明确建议：搜索代码符号时优先用 grep 而不是猜路径，find_path 只用于按文件名模式查找。

`grep`：跨项目正则搜索文件内容

用正则表达式搜索整个项目的文件内容，是"不知道符号在哪个文件里"时的首选。从源码（crates/agent/src/tools/grep_tool.rs）可以确认其输入参数与默认行为：

参数	说明
`regex`	必填，正则表达式，由 Rust `regex` crate 解析；只匹配内容，不要在此指定路径
`include_pattern`	可选 glob，限定参与搜索的文件（如 `backend/*/.rs`），匹配的是包含项目根的完整路径
`offset`	可选，0 基分页起点
`case_sensitive`	可选，是否区分大小写，默认 `false`（不区分）

结果每页 20 条（RESULTS_PER_PAGE = 20）。实用技巧：重命名函数前，用 parse_config\( 这类"函数名+左括号"的正则匹配全部调用点，可以过滤掉恰好包含该字符串的注释或变量名。

`list_directory`：列出目录内容

列出指定路径下的文件和目录，提供文件系统概览。实现位于 crates/agent/src/tools/list_directory_tool.rs。

`read_file`：读取文件内容

读取项目内指定文件的内容。实现位于 crates/agent/src/tools/read_file_tool.rs；从注册代码可以看到，ReadFileTool 还会承担更新 Agent 位置信息（仅根线程）的副作用（crates/agent/src/thread.rs）。

`search_web`：联网搜索

搜索网络信息，返回带有摘要和链接的结果，用于获取实时信息（例如确认某个依赖的已知 bug 是否已在新版本修复，或查询本地文档过期后的第三方库 API 签名）。实现位于 crates/agent/src/tools/web_search_tool.rs。其权限匹配输入是搜索查询词本身（见下文权限表）。

编辑工具（Edit Tools）

`copy_path`：递归复制文件或目录

在项目内递归复制文件或目录。相比"读取内容再写入新文件"，直接复制在复制场景下更高效。实现位于 crates/agent/src/tools/copy_path_tool.rs。

`create_directory`：创建目录（等价 `mkdir -p`）

在项目内指定路径创建新目录，自动创建所有缺失的父目录，行为类似 mkdir -p。实现位于 crates/agent/src/tools/create_directory_tool.rs。

`delete_path`：删除文件/目录并确认

删除指定路径的文件或目录（目录递归删除内容），并确认删除结果。实现位于 crates/agent/src/tools/delete_path_tool.rs。从注册代码看，DeletePathTool 构造时持有 action_log，删除操作会被记入动作日志，便于用户在 Agent 会话中回溯。

`edit_file`：按文本替换编辑文件

以"定位旧文本 → 替换为新文本"的方式编辑文件，只改动指定片段，保留周围代码不变。典型场景是更新函数签名：Agent 先定位要替换的确切行，再提供更新后的版本；大范围重命名时它会先用 grep 找出所有出现位置。实现位于 crates/agent/src/tools/edit_file_tool.rs，其构造依赖 language_registry，编辑时会结合语言信息处理缩进等细节。

`move_path`：移动或重命名文件/目录

移动或重命名项目内的文件/目录；若源与目标仅文件名不同，则执行重命名。实现位于 crates/agent/src/tools/move_path_tool.rs。

`write_file`：新建或整体覆盖文件

创建新文件，或用全新内容整体覆盖已有文件。适合生成全新文件；局部修改应使用 edit_file。实现位于 crates/agent/src/tools/write_file_tool.rs。

`terminal`：执行 shell 命令

执行 shell 命令并返回合并后的输出，每次调用创建一个新的 shell 进程。典型用法：编辑 Rust 文件后运行 cargo test --package my_crate 2>&1 | tail -30 确认测试未破坏；收工前运行 git diff --stat 审查改动范围。实现位于 crates/agent/src/tools/terminal_tool.rs。

源码中有两点值得注意：

普通版与沙箱版并存：TerminalTool 与 SandboxedTerminalTool 在 add_default_tools 中同时注册，enabled_tools 按当前沙箱状态向模型暴露其中匹配的一个，统一以 terminal 名称呈现（crates/agent/src/thread.rs）。
受限工作区禁用：受限模式下 terminal 被 tool_allowed_in_restricted_mode 直接拒绝（crates/agent/src/tools.rs）。

其他工具（Other Tools）

`spawn_agent`：派生子代理并行工作

spawn_agent 会派生一个拥有独立上下文窗口的子代理来执行被委派的子任务，适用于并行调查、自包含任务或"只关心最终结论"的研究型工作。每个子代理拥有与父代理相同的工具集。

从源码（crates/agent/src/tools/spawn_agent_tool.rs）可以看到其输入结构与使用约束：

参数	说明
`label`	必填，子代理运行期间显示在 UI 上的短标签
`message`	必填，发给子代理的提示词；新会话必须包含完整上下文（文件路径、需求、约束），因为子代理看不到你的对话历史
`session_id`	可选；提供已存在的会话 ID 时延续该会话追问，此时只发简短直接的后续消息，不要重复原始任务

工具描述中还给出了一组委派设计准则：子任务必须具体、自包含、能实质推进主任务；不要用子代理做"一两次工具调用就能完成"的小事（比如读一个文件）；代码编辑类子任务应拆成互不重叠的写入范围以便并行；同一子问题不要重复委派，应复用返回的 session_id 追问。返回值只包含子代理的最终消息和 session_id。

注册条件（crates/agent/src/thread.rs）决定了它能嵌套的最大深度：只有当前线程深度小于 MAX_SUBAGENT_DEPTH 时才会注册 SpawnAgentTool。

用 Tool Permissions 控制这些工具的审批行为

参考文档强调：可以为工具动作配置权限，包括自动批准、自动拒绝、或逐次确认（confirm）。完整说明见 Tool Permissions 文档。权限规则通过 agent.tool_permissions 设置项配置，核心结构为：

{
  "agent": {
    "tool_permissions": {
      "default": "confirm",
      "tools": {
        "<tool_name>": {
          "default": "confirm",
          "always_allow": [{ "pattern": "...", "case_sensitive": false }],
          "always_deny": [{ "pattern": "...", "case_sensitive": false }],
          "always_confirm": [{ "pattern": "...", "case_sensitive": false }]
        }
      }
    }
  }
}

三类正则规则的行为：自动批准你信任的操作；自动拒绝危险操作（即使全局默认是 allow 也会被拦截）；始终确认敏感操作。一个实用示例——自动批准 cargo 构建/测试命令、始终要求确认 sudo 命令：

{
  "agent": {
    "tool_permissions": {
      "default": "allow",
      "tools": {
        "terminal": {
          "default": "confirm",
          "always_allow": [
            { "pattern": "^cargo\\s+(build|test|check)" },
            { "pattern": "^npm\\s+(install|test|run)" }
          ],
          "always_confirm": [{ "pattern": "sudo\\s+/" }]
        }
      }
    }
  }
}

权限规则匹配时针对的工具输入字段（摘自 Tool Permissions 文档的 Supported Tools 表）：

工具	用于匹配的模式输入
`terminal`	shell 命令字符串
`edit_file` / `write_file`	文件路径
`delete_path`	被删除的路径
`move_path` / `copy_path`	源路径与目标路径
`create_directory`	目录路径
`fetch`	URL
`search_web`	搜索查询词

对于 MCP 工具，权限名采用 mcp:<server>:<tool_name> 的格式（例如 mcp:github:create_issue）。

内置工具一览与延伸阅读

汇总本文覆盖的全部内置工具，便于快速查阅：

分类	工具	一句话职责	实现文件
读取搜索	`diagnostics`	查看单文件或全项目的错误/警告	diagnostics_tool.rs
读取搜索	`fetch`	抓取 URL 转 Markdown（不受终端沙箱约束）	fetch_tool.rs
读取搜索	`find_path`	glob 匹配文件路径（每页 50 条）	find_path_tool.rs
读取搜索	`grep`	正则搜索文件内容（每页 20 条）	grep_tool.rs
读取搜索	`list_directory`	列出目录内容	list_directory_tool.rs
读取搜索	`read_file`	读取文件内容	read_file_tool.rs
读取搜索	`search_web`	联网搜索	web_search_tool.rs
编辑	`copy_path`	递归复制文件/目录	copy_path_tool.rs
编辑	`create_directory`	创建目录（等价 `mkdir -p`）	create_directory_tool.rs
编辑	`delete_path`	递归删除并确认	delete_path_tool.rs
编辑	`edit_file`	文本替换式编辑	edit_file_tool.rs
编辑	`move_path`	移动/重命名	move_path_tool.rs
编辑	`write_file`	新建或整体覆盖文件	write_file_tool.rs
编辑	`terminal`	执行 shell 命令（每次新进程，可沙箱化）	terminal_tool.rs
其他	`spawn_agent`	派生独立上下文的子代理	spawn_agent_tool.rs