简体中文

English
日本語

简体中文

English
日本語

read_file ​

read_file 工具用于检查项目中的文件内容。它允许 VJSP 理解代码、配置文件和文档，以提供更好的协助。

参数 ​

该工具接受以下参数:

  • path (必需): 要读取的文件路径，相对于当前工作目录
  • start_line (可选): 开始读取的行号(从1开始索引)
  • end_line (可选): 结束读取的行号(从1开始，包含)
  • auto_truncate (可选): 当未指定行范围时是否自动截断大文件(true/false)

它的作用 ​

该工具读取指定文件的内容，并返回带行号的内容以便于引用。它可以读取整个文件或特定部分，甚至可以从 PDF 和 Word 文档中提取文本。

何时使用? ​

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

主要功能 ​

  • 显示带行号的文件内容以便于引用
  • 可以通过指定行范围来读取文件的特定部分
  • 从 PDF 和 DOCX 文件中提取可读文本
  • 智能截断大文件以专注于最相关的部分
  • 为大型代码文件提供带有行范围的方法摘要
  • 高效地仅流式传输请求的行范围以获得更好的性能
  • 通过行编号轻松讨论代码的特定部分

限制 ​

  • 如果不使用行范围参数，可能无法高效处理非常大的文件
  • 对于二进制文件(PDF 和 DOCX 除外)，可能返回不可读的内容

工作原理 ​

当调用 read_file 工具时，它遵循以下过程:

  1. 参数验证: 验证必需的 path 参数和可选参数
  2. 路径解析: 将相对路径解析为绝对路径
  3. 读取策略选择:
    • 该工具使用严格的优先级层次结构(下面详细说明)
    • 它在范围读取、自动截断或完整文件读取之间进行选择
  4. 内容处理:
    • 向内容添加行号(例如，"1 | const x = 13")，其中 1 | 是行号
    • 对于截断的文件，添加截断通知和方法定义
    • 对于特殊格式(PDF、DOCX、IPYNB)，提取可读文本

读取策略优先级 ​

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

1. 第一优先级: 显式行范围 ​

  • 如果提供了 start_line 或 end_line 中的任何一个，工具始终执行范围读取
  • 该实现高效地仅流式传输请求的行，使其适合处理大文件
  • 这优先于所有其他选项

2. 第二优先级: 大文件的自动截断 ​

这仅在满足以下所有条件时适用:

  • 既未指定 start_line 也未指定 end_line
  • auto_truncate 参数设置为 true
  • 该文件不是二进制文件
  • 该文件超过配置的行阈值(通常为 500-1000 行)

当启用自动截断时，工具将:

  • 仅读取文件的第一部分(由 maxReadFileLine 设置决定)
  • 添加截断通知，显示显示的行数与总行数
  • 提供带有行范围的方法定义摘要

3. 默认行为: 读取整个文件 ​

  • 如果不满足上述任何一个条件，它将读取整个文件内容
  • 对于 PDF、DOCX 和 IPYNB 等特殊格式，它使用专门的提取器

使用示例 ​

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

读取整个文件 ​

要读取文件的完整内容:

输入:

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

模拟输出(对于像 example_small.txt 这样的小文件):

1 | 这是第一行。
2 | 这是第二行。
3 | 这是第三行。

(输出将根据实际文件内容而异)

读取特定行 ​

要仅读取特定的行范围(例如 46-68):

输入:

xml
<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 | 第二行的内容。
3 | 第三行的内容。

(输出仅显示请求的行及其原始行号)

读取大文件(自动截断) ​

当读取大文件时未指定行且启用了 auto_truncate(或根据设置默认为 true):

输入:

xml
<read_file>
<path>src/large-module.js</path>
<auto_truncate>true</auto_truncate> <!-- 如果默认为 true 则可选 -->
</read_file>

模拟输出(对于具有 1500 行的 large_file.log，限制为 1000 行):

1 | 日志条目 1...
2 | 日志条目 2...
...
1000 | 日志条目 1000...
[... 截断 500 行 ...]

(输出限制为配置的最大行数，并带有截断通知)

尝试读取不存在的文件 ​

如果指定的文件不存在:

输入:

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

模拟输出(错误):

错误: 在路径 'non_existent_file.txt' 处未找到文件。

尝试读取被阻止的文件 ​

如果文件被 .vjspignore 文件中的规则排除:

输入:

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

模拟输出(错误):

错误: 由于 .vjspignore 规则，对文件 '.env' 的访问被拒绝。