5.3 KiB
5.3 KiB
name, description
| name | description |
|---|---|
| 文件系统查询专家 | 查询文件系统中的文件和目录信息，支持基本的路径解析和权限检查。 |
Skill: 文件系统查询专家
1. 适用范围
当用户提出以下诉求时触发本技能：
- 查询某个目录中有什么文件/子目录
- 查找特定名称或后缀的文件（如
.md、.log） - 检查文件或目录是否存在
- 读取指定文件内容并给出摘要
- 比较两个路径下的文件差异（仅基础层面）
不适用场景：
- 需要修改系统配置、安装软件、执行高风险命令
- 需要递归扫描超大目录并输出完整明细（应先收敛范围）
2. 可用工具与约束
优先工具：
shell：用于目录枚举、检索、路径探测file：用于读取文件内容（必要时）
必须遵守：
- 仅在
ALLOWED_DIRS白名单路径范围内操作 - 仅使用
ALLOWED_COMMANDS中允许的命令 - 先做最小探测，再逐步扩大范围，避免一次性重命令
- 结果必须基于工具真实输出，禁止臆测
3. 执行策略（ReAct 指南）
- 明确用户目标：目录列表 / 文件查找 / 内容读取 / 存在性检查。
- 抽取目标路径：若用户未给路径，默认从
WORK_DIR开始，并向用户说明。 - 先进行低成本探测：
- 目录查询可先列顶层
- 文件查询可先限定后缀与最大层级
- 若输出过长：
- 先返回摘要（数量、关键文件、下一步建议）
- 再询问是否继续细化
- 若命令失败：
- 返回错误原因（路径不存在、权限不足、命令受限等）
- 提供最短修复建议（改路径、缩范围、提供更具体条件）
4. 推荐动作模板
4.1 列出目录内容
- 目标：查看目录下文件与子目录
- 行为：先顶层，再按需递归
4.2 检索特定文件
- 目标：查找匹配名称/后缀的文件
- 行为：限制目录范围与深度，优先返回命中摘要
4.3 读取文件内容
- 目标：读取并总结关键信息
- 行为：先确认文件存在，再使用
file工具读取
4.4 路径存在性检查
- 目标：确认路径是否存在、类型是文件还是目录
- 行为：给出明确判断与后续可执行动作
5. 输出规范
回复格式建议：
- 结论：一句话说明查到了什么。
- 依据：列出关键路径/文件名/数量。
- 风险与限制：说明白名单、权限、输出截断等限制。
- 下一步：给用户 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 下推荐执行优先级
- 路径确认优先：先确认用户给的是相对路径还是绝对路径。
- 目录探测优先：先做小范围探测，避免全盘递归。
- 读取优先
file工具：当目标是读取具体文件内容时，优先使用file read <path>。 - 命令失败即回退：若
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/...）。