list_files

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工具时，它遵循以下流程：

参数验证：验证必需的path参数和可选的recursive参数
路径解析：将相对路径解析为绝对路径
安全检查：防止列出敏感位置如根目录或主目录中的文件
目录/文件扫描：
- 使用ripgrep工具高效列出文件，应用10秒超时
- 使用Node.js fs模块列出目录
- 对递归和非递归模式应用不同的过滤逻辑
结果过滤：
- 在递归模式下跳过常见大型目录如node_modules、.git等
- 在递归模式下遵循.gitignore规则
- 处理.rooignore模式，要么隐藏文件，要么用锁符号标记它们
格式化：
- 用斜杠(/)标记目录
- 排序结果以在内容前显示目录，保持逻辑层次结构
- 当启用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
...
文件列表截断(显示543个文件中的200个)。在特定子目录上使用list_files获取更多细节。

当使用.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可能列出项目文件以在深入特定代码前理解其结构
当被要求查找特定类型文件(如所有JavaScript文件)时，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>

参数​

功能​

使用场景​

主要特性​

限制​

工作原理​

文件列表格式​

使用示例​

用法示例​

参数

功能