LaodingBot/skills/filesystem_query/skill.md

name, description

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/...）。