read_file

read_file 工具用于检查项目中的文件内容。它允许 Roo 理解代码、配置文件、文档，甚至图像，从而提供更好的帮助。

read_file 工具用于检查项目中的文件内容。它允许 Roo 理解代码、配置文件、文档，甚至图像，从而提供更好的帮助。

多文件支持
当 maxConcurrentFileReads 设置大于 1 时，read_file 工具可以同时读取多个文件。这对于需要分析多个相关文件的任务来说，能显著提高效率。
注意：在读取文件时（即使是单个文件），LLM 将会看到一条消息，鼓励进行多文件读取：“同时读取多个文件对 LLM 来说效率更高。如果其他文件与您当前的任务相关，请同时读取它们。”

参数

该工具接受两种格式的参数，具体取决于您的配置：

标准格式（单个文件）

path（必需）：要读取的文件的路径，相对于当前工作目录。
start_line（可选）：要开始读取的行号（基于 1 的索引）。
end_line（可选）：要结束读取的行号（基于 1，包含）。

传统格式
虽然单文件参数（path、start_line、end_line）为了向后兼容性仍然受到支持，但我们建议使用更新的 args 格式，以保持一致性和未来的兼容性。

增强格式（多文件）

当 maxConcurrentFileReads 设置为大于 1 的值时，该工具接受一个包含多个文件条目的 args 参数：

args（必需）：包含多个文件规格的容器。
- file（必需）：单个文件规格。
  - path（必需）：要读取的文件的路径。
  - line_range（可选）：行范围规格（例如，“1-50”或“100-150”）。每个文件可以指定多个 line_range 元素。

功能与使用时机

该工具读取指定文件的内容并返回带有行号的内容以方便参考。它可以读取整个文件或特定部分，从 PDF 和 Word 文档中提取文本，并以各种格式显示图像。

它在以下情况中使用：

当 Roo 需要理解现有代码结构时。
当 Roo 需要分析配置文件时。
当 Roo 需要从文本文件中提取信息时。
当 Roo 在建议更改之前需要查看代码时。
在讨论中需要引用特定行号时。

主要功能

显示带有行号的文件内容，便于参考。
可通过指定行范围读取文件的特定部分。
从 PDF 和 DOCX 文件中提取可读文本。
支持多种格式的图像：显示 PNG、JPG、JPEG、GIF、WebP、SVG、BMP、ICO、TIFF 等格式的图像。
自动截断大型文本文件：当未指定行范围时，仅显示文件开头部分。
为被截断的大型代码文件提供带行范围的方法摘要。
高效地仅流式传输请求的行范围，以获得更好的性能。
通过行号使讨论特定代码部分变得容易。
多文件支持：当 maxConcurrentFileReads > 1 时，可同时读取多个文件并进行批量批准。

多文件处理能力

当 maxConcurrentFileReads 设置大于 1 时，read_file 工具将获得增强功能：

配置

位置：设置 > 上下文 > “并发文件读取限制”
描述：“read_file 工具可以同时处理的最大文件数量。值越高，读取多个小文件的速度可能越快，但会增加内存使用。”
范围：1-100（滑块控制）
默认值：5

批量处理

单次请求可读取多达 100 个文件（可配置，默认 5 个）。
并行处理可提高性能。
提供批量批准界面以征得用户同意。

增强的用户体验

单个批准对话框用于多个文件。
独立的文件覆盖选项。
清晰可见将要访问哪些文件。
优雅处理混合成功/失败场景。

提高效率

减少因多个批准对话框造成的干扰。
通过并行文件读取加快处理速度。
智能批量处理相关文件。
可配置的并发限制以匹配系统能力。

局限性

大型文件：在不使用行范围参数的情况下，可能无法高效处理特大型文件。
二进制文件：对于二进制文件（除了 PDF、DOCX 和支持的图像格式），可能会返回不可读的内容。
图像文件：返回 base64 编码的数据 URL，对于高分辨率图像来说可能很大。
- 默认最大单个图像大小：20MB
- 默认最大总图像大小：20MB

工作原理

当调用 read_file 工具时，它会遵循以下流程：

参数验证：验证所需的 path 参数和可选参数
路径解析：将相对路径解析为绝对路径
读取策略选择：
- 该工具使用严格的优先级层次结构（下面有详细说明）
- 它会在范围读取、自动截断或完整文件读取之间进行选择
内容处理：
- 为内容添加行号（例如："1 | const x = 13"，其中 1 | 是行号）
- 对于被截断的文件，添加截断提示和方法定义
- 对于特殊格式（PDF、DOCX），提取可读文本
- 对于图像格式，返回带有 MIME 类型的 base64 编码数据 URL

读取策略优先级

该工具使用清晰的决策层次来确定如何读取文件：

第一优先级：显式行范围
- 如果提供了 start_line 或 end_line，工具始终执行范围读取
- 实现会高效地仅流式处理请求的行，非常适合处理大型文件
- 这优先于所有其他选项
第二优先级：大型文本文件的自动截断

仅在满足以下所有条件时适用：
- 未指定 start_line 或 end_line。
- 文件被识别为基于文本的文件（不是 PDF/DOCX 这类二进制文件）。
- 文件的总行数超过 maxReadFileLine 设置（默认：500 行）。
当自动截断发生时：
- 工具只读取前 maxReadFileLine 行。
- 它会附加一个指示截断的提示（例如，[仅显示 500 行，共 1200 行…]）。
- 对于代码文件，它还可能附加在被截断部分中找到的源代码定义摘要。
特殊情况 - 仅定义模式：当 maxReadFileLine 设置为 0 时，工具仅返回源代码定义而不包含任何文件内容。

默认行为：读取整个文件
- 如果既没有显式范围，也不满足自动截断条件（例如文件在行数限制内，或是受支持的二进制类型），工具会读取整个内容。
- 对于 PDF 和 DOCX 等受支持的格式，它会尝试提取完整的文本内容。
- 对于图像格式，它会返回 base64 编码的数据 URL，可以在聊天界面中显示。

使用示例

当被要求解释或改进代码时，Roo 首先读取相关文件以理解当前实现。
当排查配置问题时，Roo 会读取配置文件以识别潜在问题。
在处理文档时，Roo 会读取现有文档以理解当前内容，然后再提出改进建议。

示例

以下是几个场景，展示了如何使用 read_file 工具以及你可能收到的典型输出。

读取整个文件

要读取文件的完整内容：

输入:

<read_file>
  <path>src/app.js</path>
</read_file>

模拟输出（对于像 example_small.txt 这样的小文件）：

1 | This is the first line.
2 | This is the second line.
3 | This is the third line.

（输出会根据实际文件内容而有所不同）

读取特定行

为了只读取特定范围的行（例如，第 46-68 行）：

输入：

<read_file>
  <path>src/app.js</path>
  <start_line>46</start_line>
  <end_line>68</end_line>
</read_file>

模拟输出（对于 example_five_lines.txt 文件的第 2-3 行）：

2 | Content of line two.
3 | Content of line three.

（输出仅显示请求的行及其原始行号）

读取大型文本文件（自动截断）

当读取大型文本文件而未指定行范围时，如果内容超过内部行限制（例如 500 行），工具会自动截断内容。

输入：

<read_file>
  <path>logs/large_app.log</path>
</read_file>

模拟输出（对于一个 1500 行的日志文件，限制为 500 行）：

1 | Log entry 1...
2 | Log entry 2...
...
500 | Log entry 500...

[总共 1500 行，仅显示其中 500 行。使用 start_line 和 end_line 来读取特定范围。]
// 可选：对于代码文件，这里可能会出现源代码定义摘要

（输出显示了直到 maxReadFileLine 限制的开头行，以及一个截断通知。使用行范围可以完全访问。）

仅读取定义

当用户设置中将 maxReadFileLine 设置为 0 时，工具仅返回源代码定义而不包含文件内容：

输入：

<!-- Assuming maxReadFileLine is set to 0 in user settings -->
<read_file>
  <path>src/services/auth.service.ts</path>
</read_file>

模拟输出：

<file>
  <path>src/services/auth.service.ts</path>
  <list_code_definition_names>
    class AuthService
    method validateUser
    method generateToken
  </list_code_definition_names>
  <notice>Showing only 0 of 150 total lines. Use line_range if you need to read more lines</notice>
</file>

（此模式在不读取内容的情况下，提供文件结构的快速概览。）

尝试读取不存在的文件

如果指定的文件不存在：

输入：

<read_file>
  <path>non_existent_file.txt</path>
</read_file>

模拟输出（错误）：

Error: File not found at path 'non_existent_file.txt'.

尝试读取被阻止的文件

如果文件因 .rooignore 文件中的规则而被排除：

输入：

<read_file>
  <path>.env</path>
</read_file>

模拟输出（错误）：

<file>
  <path>.env</path>
  <error>Access denied by .rooignore rules</error>
</file>

图像读取示例

read_file 工具现在支持在聊天界面中直接读取和显示图像，从而实现强大的视觉分析工作流。

读取单张图像

输入:

<read_file>
  <path>assets/logo.png</path>
</read_file>

输出:

<image_content>
  <path>assets/logo.png</path>
  <mime_type>image/png</mime_type>
  <dimensions>width: 512, height: 512</dimensions>
  <data_url>data:image/png;base64,iVBORw0KGgoAAAANS...</data_url>
</image_content>

图像将直接显示在聊天界面中，Roo 可以对其进行视觉内容分析。

光学字符识别 (OCR) 工作流示例

从文件夹中读取多张图像以进行文本提取：

输入:

<read_file>
  <args>
    <file>
      <path>screenshots/page1.png</path>
    </file>
    <file>
      <path>screenshots/page2.png</path>
    </file>
    <file>
      <path>screenshots/page3.png</path>
    </file>
  </args>
</read_file>

用法:

Please extract all text from these screenshot images and compile them into a single markdown document.

设计评审工作流

分析多个设计模型图：

输入:

<read_file>
  <args>
    <file>
      <path>designs/homepage-v1.jpg</path>
    </file>
    <file>
      <path>designs/homepage-v2.jpg</path>
    </file>
    <file>
      <path>designs/mobile-view.png</path>
    </file>
  </args>
</read_file>

用法:

Compare these design mockups and provide feedback on:
1. Visual consistency
2. Mobile responsiveness
3. Accessibility concerns
4. UI/UX improvements

支持的图像格式

该工具支持以下图像格式：

PNG - 支持尺寸提取
JPG/JPEG - 标准和渐进式
GIF - 静态和动态
WebP - 现代网络格式
SVG - 可缩放矢量图形
BMP - 位图图像
ICO - 图标文件
TIFF - 标记图像文件格式

图像分析用例

文档截图：从 UI 屏幕截图中提取文本并创建文档。
错误调试：分析错误截图以了解问题。
设计评审：比较模型图并提供视觉反馈。
图表分析：理解架构图和流程图。
代码截图：在文本不可用时从图像中提取代码。
UI 测试：验证视觉元素和布局。

多文件示例

当 maxConcurrentFileReads 设置为大于 1 的值时，read_file 工具支持使用增强的 XML 格式同时读取多个文件，从而极大地提高了效率。

读取多个完整文件

要一次性读取多个完整文件，您可以在 <read_file> 标签内的 <args> 容器中列出每个文件，并使用 <file> 标签指定其路径。

输入格式示例：

<read_file>
  <args>
    <file>
      <path>src/app.ts</path>
    </file>
    <file>
      <path>src/utils.ts</path>
    </file>
    <file>
      <path>src/config.json</path>
    </file>
  </args>
</read_file>

模拟输出示例：

<files>
  <file>
    <path>src/app.ts</path>
    <content>
      1 | import React from 'react'
      2 | import { Utils } from './utils'
      3 | // ... rest of file content
    </content>
  </file>
  <file>
    <path>src/utils.ts</path>
    <content>
      1 | export class Utils {
      2 |   static formatDate(date: Date): string {
      3 |     // ... utility functions
    </content>
  </file>
  <file>
    <path>src/config.json</path>
    <content>
      1 | {
      2 |   "apiUrl": "https://api.example.com",
      3 |   "timeout": 5000
      4 | }
    </content>
  </file>
</files>

读取多个文件的特定行范围

您还可以为每个文件指定一个或多个 <line_range> 标签，以只读取文件的特定部分。这对于大型文件特别有用。

输入格式示例：

<read_file>
  <args>
    <file>
      <path>src/app.ts</path>
      <line_range>1-20</line_range>
      <line_range>45-60</line_range>
    </file>
    <file>
      <path>src/utils.ts</path>
      <line_range>10-25</line_range>
    </file>
  </args>
</read_file>

模拟输出示例：

<files>
  <file>
    <path>src/app.ts</path>
    <content>
      1 | import React from 'react'
      2 | import { Utils } from './utils'
      ...
      20 | const App = () => {

      45 |   const handleSubmit = () => {
      46 |     // Handle form submission
      ...
      60 |   }
    </content>
  </file>
  <file>
    <path>src/utils.ts</path>
    <content>
      10 |   static formatDate(date: Date): string {
      11 |     return date.toISOString().split('T')[0]
      ...
      25 |   }
    </content>
  </file>
</files>

处理混合结果

当您请求多个文件时，部分文件可能因 .rooignore 规则而被拒绝访问，或因用户拒绝而无法读取。在这种情况下，输出会清晰地显示每个文件的状态，成功读取的文件会返回其内容，而失败的文件则会返回错误信息。

输入格式示例：

<read_file>
  <args>
    <file>
      <path>src/app.ts</path>
    </file>
    <file>
      <path>.env</path>
    </file>
    <file>
      <path>src/secret-config.ts</path>
    </file>
  </args>
</read_file>

模拟输出示例：

<files>
  <file>
    <path>src/app.ts</path>
    <content>
      1 | import React from 'react'
      2 | // ... file content successfully read
    </content>
  </file>
  <file>
    <path>.env</path>
    <error>Access denied by .rooignore rules</error>
  </file>
  <file>
    <path>src/secret-config.ts</path>
    <error>User denied access to file</error>
  </file>
</files>

批量批准界面

在请求多个文件时，你会看到一个批量批准界面，允许你：

批准全部：授予对所有请求文件的访问权限
拒绝全部：拒绝对所有请求文件的访问权限
单独控制：对特定文件覆盖决策
文件预览：点击文件标题在编辑器中打开它们

界面清晰显示每个文件路径，使你在授予权限前容易理解 Roo 想要访问的内容。

混合内容类型

你可以在一次请求中读取不同类型的文件：

输入：

<read_file>
<args>
  <file>
    <path>README.md</path>
  </file>
  <file>
    <path>architecture-diagram.png</path>
  </file>
  <file>
    <path>config.json</path>
  </file>
  <file>
    <path>requirements.pdf</path>
  </file>
</args>
</read_file>

这允许 Roo 在同一个上下文中分析文档、可视化图表、配置和规范。

new_task

new_task 工具通过创建具有不同模式的子任务，同时保持父子关系，从而实现复杂的工作流管理。它将复杂的项目分解为可管理的、每个都以最适合特定工作的模式运行的独立部分。

search_files

search_files 工具用于在项目工作区内的多个文件中执行正则表达式搜索。出于安全考虑，它无法搜索当前工作区目录之外的区域。它通过提供上下文结果，帮助 Roo 在您的代码库中定位特定的代码模式、文本或其他内容。