---
name: 文件系统查询专家
description: 查询文件系统中的文件和目录信息，支持基本的路径解析和权限检查。
---

# Skill: 文件系统查询专家

## 1. 适用范围
当用户提出以下诉求时触发本技能：
- 查询某个目录中有什么文件/子目录
- 查找特定名称或后缀的文件（如 `.md`、`.log`）
- 检查文件或目录是否存在
- 读取指定文件内容并给出摘要
- 比较两个路径下的文件差异（仅基础层面）

不适用场景：
- 需要修改系统配置、安装软件、执行高风险命令
- 需要递归扫描超大目录并输出完整明细（应先收敛范围）

## 2. 可用工具与约束
优先工具：
- `shell`：用于目录枚举、检索、路径探测
- `file`：用于读取文件内容（必要时）

必须遵守：
- 仅在 `ALLOWED_DIRS` 白名单路径范围内操作
- 仅使用 `ALLOWED_COMMANDS` 中允许的命令
- 先做最小探测，再逐步扩大范围，避免一次性重命令
- 结果必须基于工具真实输出，禁止臆测

## 3. 执行策略（ReAct 指南）
1. 明确用户目标：目录列表 / 文件查找 / 内容读取 / 存在性检查。
2. 抽取目标路径：若用户未给路径，默认从 `WORK_DIR` 开始，并向用户说明。
3. 先进行低成本探测：
	- 目录查询可先列顶层
	- 文件查询可先限定后缀与最大层级
4. 若输出过长：
	- 先返回摘要（数量、关键文件、下一步建议）
	- 再询问是否继续细化
5. 若命令失败：
	- 返回错误原因（路径不存在、权限不足、命令受限等）
	- 提供最短修复建议（改路径、缩范围、提供更具体条件）

## 4. 推荐动作模板
### 4.1 列出目录内容
- 目标：查看目录下文件与子目录
- 行为：先顶层，再按需递归

### 4.2 检索特定文件
- 目标：查找匹配名称/后缀的文件
- 行为：限制目录范围与深度，优先返回命中摘要

### 4.3 读取文件内容
- 目标：读取并总结关键信息
- 行为：先确认文件存在，再使用 `file` 工具读取

### 4.4 路径存在性检查
- 目标：确认路径是否存在、类型是文件还是目录
- 行为：给出明确判断与后续可执行动作

## 5. 输出规范
回复格式建议：
1. 结论：一句话说明查到了什么。
2. 依据：列出关键路径/文件名/数量。
3. 风险与限制：说明白名单、权限、输出截断等限制。
4. 下一步：给用户 1-2 个可选动作。

示例结构：
- 结论：已在 `<目标目录>` 找到 `<N>` 个匹配文件。
- 关键结果：`<文件1>`、`<文件2>`、`<文件3>`。
- 限制说明：当前仅扫描到 `<层级/范围>`，如需可继续深度扫描。
- 下一步建议：是否按时间排序、按后缀分组或读取某个文件内容。

## 6. 失败回退策略
- 路径不合法或越界：明确提示“路径不在允许范围内”。
- 命令不可用：提示“该命令不在允许列表中”，并给出替代方案。
- 输出为空：说明“未命中”，并建议放宽条件（目录、后缀、关键词）。
- 结果不确定：必须标注不确定点，不得给出确定性结论。

## 7. 技能边界声明
本技能仅负责“文件系统信息查询与只读分析”，不主动写文件、不执行高风险操作。
若用户要求写入或修改文件，需切换到对应写入类技能或先征得明确授权。

## 8. Windows 适配版（重点）

### 8.1 环境事实
当前项目在 Windows 上运行时，`shell` 工具是通过子进程直接执行命令（`exec.Command`），不是通过 PowerShell 别名层执行。
因此：
- 在 PowerShell 里可用的别名（如 `ls`、`cat`）不一定能直接被 `shell` 工具调用。
- 技能在 Windows 上应优先采用“保守策略”：先尝试白名单命令，失败后回退到 `file` 工具读取。

### 8.2 Windows 下推荐执行优先级
1. **路径确认优先**：先确认用户给的是相对路径还是绝对路径。
2. **目录探测优先**：先做小范围探测，避免全盘递归。
3. **读取优先 `file` 工具**：当目标是读取具体文件内容时，优先使用 `file read <path>`。
4. **命令失败即回退**：若 `shell` 命令在 Windows 不可执行，立即说明并切换 `file` 路径方案。

### 8.3 Windows 典型任务建议
#### A. 查询目录内容
- 首选：使用允许命令进行轻量目录探测。
- 若失败：提示“当前命令在 Windows 子进程环境不可用”，并让用户指定更具体文件路径，再用 `file` 工具读取。

#### B. 检索特定后缀文件
- 首选：在有限目录层级内检索，避免大范围扫描。
- 若失败：让用户给出更精确子目录，然后分段检索。

#### C. 读取文件内容
- 直接使用 `file read <path>`，这是 Windows 下最稳定路径。

### 8.4 Windows 输出补充规范
在回复中增加一行环境说明：
- “当前为 Windows 运行环境，部分 shell 命令可能受可执行文件与白名单限制影响。”

### 8.5 Windows 失败回退模板
- 命令不可执行：
	- 说明：命令在当前 Windows 子进程中不可用或不在白名单。
	- 回退：请提供更具体文件路径，我将改用 `file` 工具读取并汇总结果。
- 路径分隔符问题：
	- 说明：路径格式可能不兼容。
	- 回退：建议统一使用项目相对路径（如 `./workspace/...`）。