Zed AI Agent 内置工具全景解析：从 read_file 到 terminal 的实现机制与权限控制

Zed 的内置 Agent 通过一组内置工具完成代码的读取、检索、编辑与验证，这些工具在 Agent Panel 中与 AI 模型的对话过程中被自动调用。本文基于 Zed 官方文档 AI Agent Tools 与 crates/agent 的源码实现，逐一讲解每类工具的用途、典型用法与边界限制，并深入剖析工具如何被注册、如何受 Agent Profile 与权限系统双重门控，帮助你在日常开发中充分利用、精确管控 Agent 的每个动作。

内置工具总览

Zed 内置 Agent 可访问的工具分为四大类：读取与搜索（diagnostics、fetch、find_path、grep、list_directory、read_file）、Web（search_web）、编辑（copy_path、create_directory、delete_path、edit_file、move_path、write_file、terminal）、其他（skill、spawn_agent）。这些工具在 Agent Panel 中参与对话，帮助 Agent 读取、搜索和编辑你的代码库。

需要注意的前提是：确切可用工具列表会因 Agent Profile、所选模型提供方和 Zed 版本不同而变化。从源码看，这一描述在 tools.rs 中有明确的实现支撑：

• 全部内置工具通过 tools! 宏集中登记，宏会生成编译期常量 ALL_TOOL_NAMES，并在编译期通过 const 检查阻止重名工具；
• built_in_tools() 将每个工具转换为 LanguageModelRequestTool（名称、描述、JSON Schema、是否支持输入流式解析），这是模型侧实际“看见”的工具清单；
• tool_feature_flag_enabled() 是功能开关门控的唯一事实来源：rename_symbol 受 RenameToolFeatureFlag 控制，find_references、get_code_actions、apply_code_action、go_to_definition 受 LspToolFeatureFlag 控制，create_thread 与 list_agents_and_models 受 CreateThreadToolFeatureFlag 控制，未列出的工具则默认始终可用。

此外，tools.rs 的源码注释明确指出，仅把工具加入宏列表还不够，模型能否真正收到某个工具还要通过三道关卡：

1. Agent Profile 白名单：assets/settings/default.json 中 write 和 ask 两个内置 Profile 各自带有显式 tools 允许列表，Thread::enabled_tools 会过滤掉其中未开启的工具；
2. 权限 UI 注册：调用 decide_permission_from_settings 的工具必须出现在权限设置页的 TOOLS 列表中（或在 EXCLUDED_TOOLS 中豁免）；
3. 功能开关：被 feature flag 门控的工具在开关未激活时会被静默丢弃，Profile 配置 UI 使用同一道门控，避免展示模型实际拿不到的工具。

读取与搜索工具

diagnostics

获取指定文件或整个项目的错误与警告，适合在编辑后判断是否还需进一步修改。提供路径时，返回该文件的全部诊断信息；不提供路径时，返回项目内所有文件错误/警告数量的汇总。

典型用法：编辑 src/parser.rs 后立即对该路径调用 diagnostics 检查类型错误；大规模重构涉及多个文件时，不带路径调用以获取全项目错误计数，再决定下一步修什么。对应实现位于 diagnostics_tool.rs。

fetch

抓取 URL 并以 Markdown 形式返回内容，适合把在线文档作为上下文喂给 Agent。

典型用法：在写集成代码前抓取某个库的 changelog 页面，确认近期版本是否引入了破坏性 API 变更。

边界限制：fetch 受工具权限、Agent Profile 和项目信任状态管理；它不运行在终端 OS 沙箱内，因此终端沙箱的网络放行项（如 allow_hosts、allow_all_hosts）对它无效。源码中这一策略有对应保障：tool_allowed_in_restricted_mode 对 fetch 与 terminal 明确返回 false，测试 fetch_and_terminal_are_forbidden_in_restricted_mode（见 tools.rs）验证了受限工作区下这两个工具会被禁用。对应实现位于 fetch_tool.rs。

find_path

按 glob 模式（如 *_test.js）快速匹配文件，按字母序返回匹配的文件路径。实现位于 find_path_tool.rs。

grep

在项目中用正则表达式搜索文件内容，是“知道符号名但不知道确切文件”时的首选。

典型用法：重命名函数前，搜索 parse_config\( —— 正则匹配函数名后紧跟左括号，过滤掉恰好包含该字符串的注释或变量名，从而精确定位所有调用点。实现位于 grep_tool.rs。

list_directory

列出给定路径下的文件和目录，提供文件系统结构概览。实现位于 list_directory_tool.rs。

read_file

读取项目中指定文件的内容，是 Agent 理解文件现状的入口工具；编辑工具的描述明确要求“先 read_file 再编辑”。实现位于 read_file_tool.rs。

Web 工具

search_web

搜索网页信息，返回带摘要片段与链接的相关页面结果，适合获取实时信息。

典型用法：查询某个依赖库已知 bug 是否已在最近版本修复；本地文档过时时，查找第三方库当前的 API 签名。

注意：内置 search_web 仅对使用 Zed 提供方的 Zed Pro 订阅用户可用。免费方案或使用其他提供方的用户，可通过接入提供 Web 搜索能力的 MCP server 获得等效功能。实现位于 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

以“替换指定文本”的方式编辑文件，是局部修改的核心工具。

典型用法：更新函数签名时，Agent 定位需替换的确切行并给出新版本，周围代码保持不变；大规模重命名时先配合 grep 找出所有出现位置，再逐一编辑。

从源码看，edit_file_tool.rs 中的输入结构给出了更丰富的实操细节：

• path 必须是项目根目录前缀开头的完整路径（多根项目中必须能唯一解析，否则调用失败），唯一例外是全局技能目录 ~/.agents/skills 及其子路径；
• edits 是顺序应用的编辑操作列表，每个操作在文件中查找 old_text 并替换为 new_text；
• 输入经 deserialize_maybe_stringified 反序列化：部分模型会把嵌套参数以 JSON 字符串形式给出，该辅助函数（见 tools.rs）会先按结构化值解析、失败后再尝试把字符串当 JSON 解析，从而容忍这一模型行为差异。

move_path

移动或重命名项目内的文件或目录；仅文件名不同时即为重命名操作。实现位于 move_path_tool.rs。

write_file

创建新文件，或用全新内容整体覆盖已有文件——与 edit_file 的局部替换形成互补。实现位于 write_file_tool.rs。

terminal

执行 shell 命令并返回合并输出，每次调用创建新的 shell 进程。

典型用法：编辑 Rust 文件后运行 cargo test --package my_crate 2>&1 | tail -30 确认改动不破坏现有测试；任务收尾前运行 git diff --stat 回顾哪些文件被修改过。实现位于 terminal_tool.rs。

当启用 Zed Agent 沙箱 时，terminal 还可以运行在额外的 OS 级限制之下（见 sandboxing.rs），对命令的网络与文件系统访问施加约束。

其他工具

skill

加载可用 Skill 中的指令，让 Agent 遵循项目级或工作流级的本地规范；技能也可由你直接用 slash 命令调用。

典型用法：仓库里有一个“撰写 release notes”的技能时，Agent 先加载它再起草，从而遵循本地格式约定。实现位于 skill_tool.rs。

spawn_agent

派生拥有独立上下文窗口的子 Agent 执行委派任务，适合并行调查、自包含任务或只关心结果的调研场景。每个子 Agent 与父 Agent 拥有相同的工具集合。

典型用法：重构认证模块时，派生一个子 Agent 调查会话 token 在代码库其他位置的校验方式；父 Agent 继续手头工作，待子 Agent 完成后再审阅其结论——两个上下文窗口各自聚焦单一任务。实现位于 spawn_agent_tool.rs。

工具可用性：Agent Profile 的白名单机制

除了功能开关，Profile 是工具可用性的第一道闸门。default.json 内置了两个 Profile：

• write（默认）：几乎所有内置工具均为 true，包括 copy_path、create_directory、delete_path、edit_file、write_file、terminal、search_web 等，ask_user 默认关闭；
• ask：只读取向，仅保留 create_thread、diagnostics、fetch、list_directory、find_path 等查询类工具，不含任何文件编辑与终端工具。

Profile 控制的是“工具能不能进对话”；而工具进对话后“自动放行、自动拒绝还是逐次确认”则由权限系统负责。二者分工明确，详见 Tool Permissions 与 Agent Profiles。

工具权限：允许、拒绝与逐次确认

default.json 中的 tool_permissions 配置展示了权限规则的结构：

"tool_permissions": {
  // "allow" - 自动批准，不提示
  // "deny"  - 自动拒绝
  // "confirm" - 总是提示（默认）
  "default": "confirm",
  "tools": {
    // "terminal": {
    //   "default": "confirm",
    //   "always_confirm": [
    //     { "pattern": "git\\s+(reset|clean)\\s+--hard" },
    //     { "pattern": "git\\s+push\\s+(-f|--force)" }
    //   ]
    // },
    // "edit_file": {
    //   "default": "confirm",
    //   "always_deny": [
    //     { "pattern": "\\.env($|\\.)" },
    //     { "pattern": "secrets?/" },
    //     { "pattern": "\\.pem$" },
    //     { "pattern": "\\.key$" }
    //   ]
    // }
  }
}

规则要点：

• default 是没有任何工具级规则命中时的全局兜底策略，默认值为 confirm；
• 每个工具可有自己的 default 及正则规则，正则对工具输入文本（命令、路径、URL 等）做匹配；对 copy_path 和 move_path，源路径与目标路径各自独立匹配；
• 工具级 default 同样作用于 MCP 工具，即自定义工具也能纳入同一套权限体系。

从源码结构看，权限判定集中在 tool_permissions.rs，工具执行前的授权路径（如 EditFileTool 的 authorize 方法，见 edit_file_tool.rs）会把待执行动作交给权限系统裁决，再决定是否弹出确认。

定制与扩展：MCP、Skills 与 Profile 的组合

三类机制组合起来构成完整管控面：

• 加工具：内置工具之外的自定义工具通过 MCP servers 接入；
• 控可用性：用 Agent Profiles 决定哪些内置工具与 MCP 工具出现在某个 Agent 线程中；
• 控行为：用 Tool Permissions 控制允许、拒绝、逐次确认三种行为，且权限系统仅在 Zed 本就会放行该动作时才介入。

此外，Agent 的行为规范还可以在 Skills 与 Instructions 层面注入，使内置工具在遵循团队规范的前提下执行。

小结

Zed 的 Agent 工具体系可以概括为：tools! 宏集中登记 24 个内置工具并生成模型侧可见的 JSON Schema；Agent Profile 白名单与 feature flag 决定工具能否进入对话；tool_permissions 正则规则决定每次调用的放行策略；OS 沙箱进一步约束 terminal 的副作用。掌握这一“注册—准入—授权—沙箱”的链路后，你可以放心让 Agent 跑测试、改代码，同时把高风险动作（如 git push --force、.env 修改）精准圈在确认或拒绝范围内。如需查看各工具的完整实现与测试（含编辑会话的流式解析 edit_session 与工具评测 test_tools.rs），可直接在 crates/agent/src/tools 下按文件名检索。