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_webEdit Tools编辑工具copy_path、create_directory、delete_path、edit_file、move_path、write_file、terminalOther 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 serversModel 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_toolscrates/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_stringifiedcrates/agent/src/tools.rs允许工具入参以 JSON 字符串的形式给出并自动二次解析因为部分模型偶尔会把嵌套参数 stringify。读取与搜索工具Read Search Toolsdiagnostics编辑后检查编译/类型错误获取单个文件或整个项目的错误与警告适合在编辑之后判断是否还需要进一步修改提供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必填正则表达式由 Rustregexcrate 解析只匹配内容不要在此指定路径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 Toolscopy_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 21 | 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 Toolsspawn_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 表工具用于匹配的模式输入terminalshell 命令字符串edit_file/write_file文件路径delete_path被删除的路径move_path/copy_path源路径与目标路径create_directory目录路径fetchURLsearch_web搜索查询词对于 MCP 工具权限名采用mcp:server:tool_name的格式例如mcp:github:create_issue。内置工具一览与延伸阅读汇总本文覆盖的全部内置工具便于快速查阅分类工具一句话职责实现文件读取搜索diagnostics查看单文件或全项目的错误/警告diagnostics_tool.rs读取搜索fetch抓取 URL 转 Markdown不受终端沙箱约束fetch_tool.rs读取搜索find_pathglob 匹配文件路径每页 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 -pcreate_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延伸阅读对应参考文档的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考