文件搜索、读取与编辑

文件工具在当前工作区与允许访问范围内运行。先查文件位置，再查文本和读取相关部分，最后进行精确修改。以下字段按官方总表及核实日官方仓库源码整理；已安装版本的 /tools desc 是本机实际能力入口。

工具与字段

工具	主要参数与行为
list_directory	dir_path，可选 ignore 和 file_filtering_options
glob	pattern、可选 dir_path；返回绝对路径并按修改时间排序
grep_search	pattern、可选 dir_path 和 include_pattern，结果带文件与行号
read_file	file_path、可选 start_line 和 end_line，行号从 1 开始，结束行包含在内
write_file	file_path、content，创建或覆盖整个文件
replace	file_path、instruction、old_string、new_string，可选 allow_multiple

文件专页仍写 read_file 的零基 offset/limit、glob/grep_search 的 path 和 include，与总表及当前源码不一致。不要把两套参数混合；对特定已发布版本先核对实际 schema。

查找与读取

glob 的 case_sensitive 默认 false，respect_git_ignore 与 respect_gemini_ignore 默认 true，但配置可影响最终过滤行为。常见噪声目录默认被过滤，搜索结果缺失时检查忽略设置，而非直接扩大所有文件范围。

grep_search 查文件内容，不是文件名；它在合适的 Git 仓库用 git grep，不可用时回退。当前核实的基本参数还包括 exclude_pattern、names_only、max_matches_per_file、total_max_matches；实现可能随搜索后端不同，不承诺总表列出的每个可选项都适合旧版本。

read_file 支持文字、图片、音频和 PDF。大文本分段读取，保留前后语义，避免把截断输出当作完整文件。

修改

replace 默认 allow_multiple: false，要求旧文本恰好匹配一次；希望同一文字全部替换才使用 true。应提供足够上下文，避免把重复片段误改到另一位置。

write_file 会覆盖已有内容，适合完整生成而非小改动。审批时检查实际 diff；工具页将修改列为需确认，自动批准模式或策略另有控制，不能据工具名推断始终会弹窗。

从定位到验证的工作流

不知道路径时，先让 Agent 定位组件或函数；已有路径时，可以在一条提示中组合多个 @ 引用，提供实现与类型定义。创建不存在的新文件时直接说明目标路径，避免把失败的 @ 读取当成已提供内容。

提出具体修改要求后检查实际 diff，再读取结果或运行相关测试。教程中的逐次 y/n 确认是其演示流程，实际批准由当前模式与策略决定。目录读取还受忽略规则影响，不能据目录引用推断所有内容都已加载。