read_many_files - 批量读取文件

概述

read_many_files 工具用于批量读取多个文件的内容。它可以通过路径或 glob 模式指定文件，主要用于文本文件，但也可以处理图片（如 .png、.jpg）和 PDF 文件（如果在 paths 参数中明确指定）。

工具名称

• 内部名称: read_many_files
• 显示名称: ReadManyFiles
• 图标: 文件堆栈 (FileStack)

参数

必需参数

参数名	类型	说明
paths	string[]	相对于目标目录的 glob 模式或路径数组。例如：['src/**/*.ts']、['README.md', 'docs/']。至少需要一个路径。

可选参数

参数名	类型	默认值	说明
exclude	string[]	[]	要排除的文件/目录的 glob 模式。如果 useDefaultExcludes 为 true，则会添加到默认排除项中。例如：["**/*.log", "temp/"]
include	string[]	[]	要包含的额外 glob 模式。这些会与 paths 合并。例如：["*.test.ts"] 用于添加测试文件
recursive	boolean	true	是否递归搜索（主要由 glob 模式中的 ** 控制）
useDefaultExcludes	boolean	true	是否应用默认排除模式列表（如 node_modules、.git、二进制文件）
per_file_max_lines	number	200	每个文本文件最多读取的行数
per_file_max_chars	number	20000	每个文本文件最多读取的字符数
max_total_files	number	20	最多读取的文件数量
max_total_chars	number	200000	所有文件的最大总字符数
prefer_full_read	boolean	false	设置为 true 可禁用单文件截断保护。总限制（max_total_files、max_total_chars）仍然有效
file_filtering_options	object	-	文件过滤选项
file_filtering_options.respect_git_ignore	boolean	true	是否遵守 .gitignore 规则（仅在 git 仓库中可用）
file_filtering_options.respect_sii_ignore	boolean	true	是否遵守 .siiignore 规则

功能说明

1. 批量读取：

   • 一次读取多个文件
   • 支持 glob 模式匹配
   • 自动合并文件内容

2. 文件类型支持：

   • 主要用于文本文件
   • 可处理明确指定的图片文件（PNG、JPG 等）
   • 可处理明确指定的 PDF 文件

3. 内容格式化：

   • 使用 --- {filePath} --- 分隔符
   • 默认 UTF-8 编码
   • 清晰的文件边界标记

4. 智能过滤：

   • 遵守 .gitignore 规则
   • 遵守 .siiignore 规则
   • 默认排除常见大型目录
   • 自动跳过二进制文件（除非明确请求）

5. 安全限制：

   • 文件数量限制
   • 单文件大小限制
   • 总字符数限制
   • 防止读取过大内容

使用场景

此工具适用于以下场景：

• 了解代码库的概览或部分内容（如 src 目录中的所有 TypeScript 文件）
• 查找特定功能的实现位置
• 审查文档文件（如 docs 目录中的所有 Markdown 文件）
• 从多个配置文件收集上下文
• 用户要求"读取 X 目录中的所有文件"或"显示所有 Y 文件的内容"

使用示例

读取所有 TypeScript 文件

{
  "paths": ["src/**/*.ts"]
}

读取特定文件和目录

{
  "paths": ["README.md", "package.json", "src/"]
}

读取并排除某些文件

{
  "paths": ["src/**/*.js"],
  "exclude": ["**/*.test.js", "**/*.spec.js"]
}

读取测试文件

{
  "paths": ["src/**/*.ts"],
  "include": ["**/*.test.ts", "**/*.spec.ts"]
}

完整读取小文件

{
  "paths": ["config/**/*.json"],
  "prefer_full_read": true,
  "max_total_files": 50
}

不使用默认排除

{
  "paths": ["node_modules/my-package/**/*.js"],
  "useDefaultExcludes": false,
  "file_filtering_options": {
    "respect_git_ignore": false
  }
}

返回结果

工具返回一个包含以下字段的对象：

• llmContent: 合并后的文件内容字符串
• returnDisplay: 用户友好的显示信息
• summary: 操作摘要（包含读取的文件数量等）

内容格式

--- /path/to/file1.ts ---
[file1 content]

--- /path/to/file2.ts ---
[file2 content]

...

错误处理

可能的错误情况：

1. 路径错误：

   • paths 参数为空
   • glob 模式无效
   • 路径不在允许的目录范围内

2. 文件访问错误：

   • 没有读取权限
   • 文件被忽略规则排除

3. 限制错误：

   • 超过文件数量限制
   • 超过总字符数限制
   • 单个文件过大

最佳实践

1. 使用具体的 glob 模式：

   • ✅ src/**/*.ts - 明确的文件类型
   • ❌ **/* - 过于宽泛

2. 合理设置限制：

   • 根据需要调整 max_total_files
   • 对于大型项目，使用更具体的路径

3. 利用排除功能：

   • 排除测试文件：exclude: ["**/*.test.ts"]
   • 排除构建产物：exclude: ["dist/", "build/"]

4. 分批处理：

   • 对于大型代码库，分多次读取
   • 先读取核心文件，再读取其他文件

5. 检查返回的摘要：

   • 确认读取了预期数量的文件
   • 检查是否有文件被截断

性能考虑

1. 文件数量：

   • 默认最多 20 个文件
   • 可根据需要调整

2. 文件大小：

   • 单文件默认最多 200 行或 20000 字符
   • 总计默认最多 200000 字符

3. 读取速度：

   • 文本文件读取快速
   • 图片和 PDF 处理较慢

4. 内存使用：

   • 所有内容加载到内存
   • 注意总字符数限制

与其他工具的对比

工具	用途	适用场景
read_file	读取单个文件	需要完整读取特定文件
read_many_files	批量读取文件	需要了解多个文件的内容
glob	查找文件路径	只需要文件列表，不需要内容
search_file_content	搜索文件内容	查找包含特定模式的文件

注意事项

1. 路径相对性：路径相对于工具的目标目录
2. 二进制文件：默认跳过，除非明确指定
3. 大文件处理：会自动截断，使用 prefer_full_read 需谨慎
4. 编码问题：默认 UTF-8，其他编码可能显示异常

相关工具

• read_file: 读取单个文件
• glob: 查找匹配的文件路径
• search_file_content: 在文件内容中搜索
• list_directory: 列出目录内容