企业官网建设流程全解析

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

【免费下载链接】zedCode at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.项目地址: https://gitcode.com/GitHub_Trending/ze/zed

本文以 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

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

1. 工具权限（Tool Permissions）：决定某次工具调用是自动批准、自动拒绝，还是逐次要求你确认。权限门控的工具及其匹配输入见 Tool Permissions 文档。
2. Agent Profile：决定哪些工具"可见"。参考文档的正式版本明确指出，具体工具列表可能因 Agent Profile、所选模型提供方和 Zed 版本而变化，Profile 控制工具的可用性，而权限控制 allow/deny/confirm 行为（见 Agent Profiles）。
3. 项目信任与沙箱：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）可以确认其输入参数与默认行为：

结果每页 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。

源码中有两点值得注意：

1. 普通版与沙箱版并存：TerminalTool与SandboxedTerminalTool在add_default_tools中同时注册，enabled_tools按当前沙箱状态向模型暴露其中匹配的一个，统一以terminal名称呈现（crates/agent/src/thread.rs）。
2. 受限工作区禁用：受限模式下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）可以看到其输入结构与使用约束：

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

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

内置工具一览与延伸阅读

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

延伸阅读（对应参考文档的 See Also 部分）：

• Agent Panel —— 与 AI Agent 交互的入口界面；
• Tool Permissions —— 配置哪些工具需要审批；
• MCP Servers —— 通过 Model Context Protocol 添加自定义工具；
• Agent Profiles —— 控制线程中可用的内置与 MCP 工具集合；
• Zed Agent Sandboxing —— 为terminal工具附加 OS 级限制；
• docs/src/ai/tools.md —— 参考文档的正式版本，包含各工具的使用示例与随版本更新的工具清单。

【免费下载链接】zedCode at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.项目地址: https://gitcode.com/GitHub_Trending/ze/zed