list_directory - 列出目录

概述

list_directory 工具用于列出指定目录路径中的文件和子目录名称。可以选择性地忽略匹配提供的 glob 模式的条目。

工具名称

• 内部名称: list_directory
• 显示名称: ReadFolder
• 图标: 文件夹 (Folder)

参数

必需参数

参数名	类型	说明
path	string	要列出的目录的绝对路径（必须是绝对路径，不能是相对路径）。

可选参数

参数名	类型	说明
ignore	string[]	要忽略的 glob 模式列表。
file_filtering_options	object	文件过滤选项。
file_filtering_options.respect_git_ignore	boolean	是否遵守 .gitignore 模式。仅在 git 仓库中可用。默认为 true。
file_filtering_options.respect_sii_ignore	boolean	是否遵守 .siiignore 模式。默认为 true。

功能说明

1. 目录列表：

   • 列出直接子文件和子目录
   • 不递归列出子目录内容
   • 返回文件名、路径、类型、大小和修改时间

2. 过滤功能：

   • 支持 glob 模式忽略特定文件
   • 遵守 .gitignore 规则（可选）
   • 遵守 .siiignore 规则（可选）

3. 安全限制：

   • 路径必须是绝对路径
   • 路径必须在项目根目录内

4. 返回信息：

   • 文件/目录名称
   • 完整路径
   • 是否为目录
   • 文件大小（字节）
   • 最后修改时间

使用示例

基本用法

{
  "path": "/home/user/project/src"
}

忽略特定模式

{
  "path": "/home/user/project",
  "ignore": ["*.log", "*.tmp", "node_modules"]
}

自定义过滤选项

{
  "path": "/home/user/project",
  "file_filtering_options": {
    "respect_git_ignore": false,
    "respect_sii_ignore": true
  }
}

列出根目录

{
  "path": "/home/user/project"
}

返回结果

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

• llmContent: 目录内容的详细列表
• returnDisplay: 用户友好的显示信息
• summary: 操作摘要（例如："Listed 15 items in directory"）

返回的文件条目格式

每个文件/目录条目包含：

{
  name: string;          // 文件或目录名称
  path: string;          // 绝对路径
  isDirectory: boolean;  // 是否为目录
  size: number;          // 文件大小（字节），目录为 0
  modifiedTime: Date;    // 最后修改时间
}

错误处理

可能的错误情况：

1. 路径错误：

   • 路径不是绝对路径
   • 路径不在项目根目录内
   • 路径不存在

2. 访问错误：

   • 没有读取权限
   • 路径是文件而不是目录

3. 参数错误：

   • 缺少必需参数
   • 参数类型不正确

Glob 模式说明

支持的 glob 模式：

• *: 匹配任意字符（不包括 /）
• **: 匹配任意字符（包括 /）
• ?: 匹配单个字符
• [abc]: 匹配括号中的任意字符
• {a,b}: 匹配大括号中的任意模式

示例：

• *.js: 匹配所有 JavaScript 文件
• test/**: 匹配 test 目录下的所有内容
• *.{js,ts}: 匹配所有 JavaScript 和 TypeScript 文件

注意事项

1. 非递归：此工具只列出直接子项，不递归列出子目录内容
2. 性能：对于包含大量文件的目录，可能需要一些时间
3. 权限：确保有足够的权限读取目录
4. 符号链接：符号链接会被识别但不会被跟随

相关工具

• glob: 使用 glob 模式查找文件
• read_file: 读取文件内容
• search_file_content: 搜索文件内容
• read_many_files: 批量读取多个文件