Lzh on GitHub

list_files

list_files 工具用于显示指定位置的文件和目录。它帮助 Roo 理解您的项目结构并有效地浏览您的代码库。

list_files 工具用于显示指定位置的文件和目录。它帮助 Roo 理解您的项目结构并有效地浏览您的代码库。

参数

该工具接受以下参数：

  • path（必需）：要列出内容的目录路径，该路径相对于当前工作目录。
  • recursive（可选）：是否递归地列出文件。true 表示递归列出，false 或省略则只列出顶级内容。

功能与使用时机

该工具列出指定位置的所有文件和目录，提供项目结构的清晰概览。它可以只显示顶级内容，也可以递归地探索子目录。

它在以下情况中使用：

  • 当 Roo 需要理解您的项目结构时。
  • 当 Roo 在读取特定文件之前探索有哪些文件可用时。
  • 当 Roo 映射代码库以更好地理解其组织结构时。
  • 在使用更具针对性的工具（如 read_file 或 search_files）之前。
  • 当 Roo 需要在项目中检查特定文件类型（如配置文件）时。

主要功能与局限性

主要功能

  • 同时列出文件和目录，并明确标记目录。
  • 提供递归和非递归两种列表模式。
  • 在递归模式下智能忽略 node_modules 和 .git 等常见的大型目录。
  • 在递归模式下遵守 .gitignore 规则。
  • 当 showRooIgnoredFiles 启用时，用锁符号（🔒）标记被 .rooignore 忽略的文件。
  • 利用 ripgrep 工具优化文件列表性能。
  • 对结果进行排序，使目录在其内容之前显示，以保持逻辑层次结构。
  • 以整洁、有序的格式呈现结果。
  • 自动创建项目的思维导图。

局限性

  • 文件列表上限：默认情况下，文件列表上限约为 200 个，以防止性能问题。
  • 超时限制：底层的 ripgrep 文件列表过程有 10 秒的超时时间；如果超出，可能会返回部分结果。
  • 文件数量限制提示：当达到文件数量上限时，会添加一条提示，建议对特定的子目录使用 list_files。
  • 功能局限：该工具并非设计用于确认您刚刚创建的文件是否存在。
  • 性能影响：在非常大的目录结构中，性能可能会降低。
  • 安全限制：出于安全原因，无法列出根目录或主目录中的文件。

工作原理

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

  1. 参数验证：验证所需的 path 参数和可选的 recursive 参数
  2. 路径解析：将相对路径解析为绝对路径
  3. 安全检查：防止列出诸如根目录或主目录等敏感位置的文件
  4. 目录/文件扫描：
    • 使用 ripgrep 工具高效列出文件，设置 10 秒超时
    • 使用 Node.js fs 模块列出目录
    • 根据递归模式和非递归模式应用不同的过滤逻辑
  5. 结果过滤：
    • 在递归模式下，跳过常见的大型目录，如 node_modules、.git 等
    • 在递归模式下遵循 .gitignore 规则
    • 处理 .rooignore 模式，可以隐藏文件或用锁定符号标记
  6. 格式化：
    • 用斜杠（/）标记目录
    • 排序结果，将目录显示在其内容之前以保持逻辑层级
    • 在启用 showRooIgnoredFiles 时，用锁定符号（🔒）标记被忽略的文件
    • 默认将结果限制为 200 个文件，并提示可使用子目录
    • 组织结果以提高可读性

文件列表格式

文件列表结果包括：

  • 文件路径：每个文件路径都显示在单独的一行上。
  • 目录标记：目录末尾带有斜杠（/）。
  • 被忽略的文件：当 showRooIgnoredFiles 启用时，被 .rooignore 忽略的文件会用一个锁符号（🔒）进行标记。
  • 逻辑排序：结果经过逻辑排序，目录会出现在其内容之前。
  • 文件数量限制提示：当达到文件数量限制时，会出现一条消息，建议对特定的子目录使用 list_files。

示例输出格式：

src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
src/utils/
src/utils/helpers.ts
src/index.ts
...
File listing truncated (showing 200 of 543 files). Use list_files on specific subdirectories for more details.

当使用 .rooignore 文件且 showRooIgnoredFiles 启用时：

src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
🔒 src/secrets.json
src/utils/
src/utils/helpers.ts
src/index.ts

使用示例

  • 开始新任务时：Roo 可能会列出项目文件，以了解其结构，然后再深入研究特定的代码。
  • 查找特定类型的文件时：Roo 首先列出目录以知道去哪里查找。
  • 提供代码组织建议时：Roo 首先检查当前的项目结构。
  • 设置新功能时：Roo 列出相关目录以了解项目约定。

用法示例

在当前目录中列出顶级文件：

<list_files>
  <path>.</path>
</list_files>

递归列出源目录中的所有文件：

<list_files>
  <path>src</path>
  <recursive>true</recursive>
</list_files>

检查特定项目子目录：

<list_files>
  <path>src/components</path>
  <recursive>false</recursive>
</list_files>