多文件读取工具 (`read_many_files`)

本文档描述 Gemini CLI 中的 read_many_files 工具。

描述

使用 read_many_files 可以读取由路径或 glob 模式指定的多个文件内容。该工具的行为取决于提供的文件类型：

read_many_files 可用于执行诸如获取代码库概览、查找特定功能的实现位置、查看文档或从多个配置文件中收集上下文等任务。

read_many_files 接受以下参数：

paths (list[string], 必需)：相对于工具目标目录的 glob 模式或路径数组（例如 ["src/**/*.ts"]，["README.md", "docs/", "assets/logo.png"]）
exclude (list[string], 可选)：要排除的文件/目录的 glob 模式（例如 ["**/*.log", "temp/"]）。如果 useDefaultExcludes 为 true，这些会被添加到默认排除项中
include (list[string], 可选)：额外的 glob 包含模式。这些会与 paths 合并（例如 ["*.test.ts"] 用于特别添加测试文件如果它们被广泛排除，或 ["images/*.jpg"] 用于包含特定图片类型）
recursive (boolean, 可选)：是否递归搜索。这主要由 glob 模式中的 ** 控制。默认为 true
useDefaultExcludes (boolean, 可选)：是否应用默认排除模式列表（例如 node_modules、.git、非图片/pdf 的二进制文件）。默认为 true
respect_git_ignore (boolean, 可选)：查找文件时是否遵循 .gitignore 模式。默认为 true

read_many_files 会搜索符合指定 paths 和 include 模式的文件，同时遵循 exclude 模式和默认排除规则（如果启用）。

对于文本文件：读取每个匹配文件的内容（尝试跳过未被显式请求为图像/PDF的二进制文件），并使用分隔符 --- {filePath} --- 将所有文件内容连接成单个字符串。默认使用 UTF-8 编码。
对于图像和PDF文件：如果通过文件名或扩展名显式请求（例如 paths: ["logo.png"] 或 include: ["*.pdf"]），工具会读取文件并将其内容作为 base64 编码字符串返回。
工具会尝试通过检查文件初始内容中的空字节来检测并跳过其他二进制文件（不符合常见图像/PDF类型或未被显式请求的文件）。

用法：

read_many_files(paths=["您的文件或路径"], include=["要包含的额外文件"], exclude=["要排除的文件"], recursive=False, useDefaultExcludes=false, respect_git_ignore=true)

读取 src 目录下所有 TypeScript 文件：

read_many_files(paths=["src/**/*.ts"])

读取主 README 文件、docs 目录下所有 Markdown 文件以及特定 logo 图片，并排除特定文件：

read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"])

读取所有 JavaScript 文件，但显式包含测试文件和 images 文件夹下所有 JPEG：

read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False)

二进制文件处理：
图片/PDF文件： 工具可以读取常见图片类型（PNG、JPEG等）和PDF文件，并以base64编码形式返回数据。这些文件_必须_通过paths或include模式显式指定（例如指定确切文件名如image.png或使用通配符模式如*.jpeg）。
其他二进制文件： 工具会通过检查文件初始内容中的空字节来尝试检测并跳过其他类型的二进制文件。这些文件会被排除在输出结果之外。
性能注意事项： 读取大量文件或单个超大文件可能会消耗较多系统资源。
路径指定： 确保路径和glob模式相对于工具的目标目录正确指定。对于图片/PDF文件，确保模式足够具体以包含它们。
默认排除项： 注意默认排除模式（如node_modules、.git），如需覆盖请使用useDefaultExcludes=False，但请谨慎操作。