list_files

list_files 工具用于展示指定路径下的文件与目录，助力 VJSP 理解项目结构，实现对代码库的高效导航。

参数说明

该工具支持以下参数配置：

path（必选）：待列出内容的目录路径，为相对当前工作目录的路径
recursive（可选）：是否递归列出文件。设为true时开启递归列出，设为false或省略时仅列出顶层内容

功能介绍

本工具可列出指定路径下的所有文件和目录，清晰呈现项目结构。支持两种展示模式：仅展示顶层目录内容，或递归遍历所有子目录并展示内容。

适用场景

VJSP 需要理解项目整体结构时
VJSP 读取特定文件前，需排查可用文件清单时
VJSP 需映射代码库，进一步理解其组织架构时
使用read_file、search_files等精准工具前的前置操作
VJSP 需要在项目中检索特定类型文件（如配置文件）时

核心特性

同时列出文件和目录，且目录会做明确标识
支持递归/非递归两种文件列出模式
递归模式下，智能忽略node_modules、.git等常见大型目录
递归模式下，遵循.gitignore配置规则
开启showVJSPIgnoredFiles时，被.vjspignore忽略的文件会标注锁形符号（🔒）
采用逐层目录遍历方式，优化工具运行性能
对结果进行排序，目录优先于其内部内容展示，保持逻辑层级关系
以简洁、规整的格式呈现列出结果
自动为项目结构建立逻辑映射

限制说明

为避免性能问题，文件列出结果默认限制约200个文件
目录遍历设置10秒超时机制，防止在复杂目录结构下出现进程挂起
达到文件数量限制时，会给出提示，建议对指定子目录单独执行list_files
不适用作验证刚创建文件是否存在的校验工具
在超大型目录结构中运行时，性能可能有所下降
出于安全考虑，无法列出根目录或用户主目录下的文件

工作流程

调用list_files工具后，将按以下流程执行：

参数校验：校验必选参数path和可选参数recursive的有效性
路径解析：将相对路径解析为绝对路径
安全校验：禁止列出根目录、用户主目录等敏感路径下的文件
目录扫描：
- 非递归模式：仅列出目录顶层内容
- 递归模式：逐层遍历目录结构，且设置10秒超时
- 若触发超时，返回截至超时前收集到的部分结果
结果过滤：
- 递归模式下，跳过node_modules、.git等常见大型目录
- 递归模式下，遵循.gitignore配置规则
- 解析.vjspignore的过滤规则，对匹配文件执行隐藏或锁形标注操作
结果格式化：
- 为目录添加尾斜杠（/）标识
- 对结果排序，目录优先于其内部内容展示，保证逻辑层级
- 开启showVJSPIgnored时，为被忽略文件标注锁形符号（🔒）
- 默认将结果限制为200个文件，同时给出子目录单独查询的提示
- 对结果进行规整排版，提升可读性

结果展示格式

文件列出结果包含以下规范：

每个文件路径单独占一行展示
目录以尾斜杠（/）标识
开启showVJSPIgnored时，被.vjspignore忽略的文件标注锁形符号（🔒）
结果按逻辑排序，目录优先于其内部内容展示
达到文件数量限制时，将弹出提示，建议对指定子目录执行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以查看完整内容。

启用.vjspignore且开启showVJSPIgnored时的展示示例：

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

实际应用场景

启动新任务时，VJSP 会先列出项目文件，理解整体结构后，再深入处理具体代码
接收到检索特定类型文件（如所有JavaScript文件）的指令时，VJSP 会先列出目录，确定检索范围
提供代码组织优化建议前，VJSP 会先分析当前项目的结构布局
搭建新功能模块时，VJSP 会列出相关目录，适配项目的开发规范

使用示例

列出当前目录下的顶层文件：

<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>

list_files ​

参数说明 ​

功能介绍 ​

适用场景 ​

核心特性 ​

限制说明 ​

工作流程 ​

结果展示格式 ​

实际应用场景 ​

使用示例 ​