feat: add workspace-isolated toolhost runtime and capability-gap skill loop

skills/filesystem_query/skill.md

@@ -1,19 +1,122 @@
-# Skill: Filesystem Query
+---
+name: 文件系统查询专家
+description: 查询文件系统中的文件和目录信息，支持基本的路径解析和权限检查。
+---
 
-用途：
-- 查询目录下文件
-- 检查路径是否存在
-- 快速列出文件树
+# Skill: 文件系统查询专家
 
-建议工具：
-- `shell`
+## 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/...`）。
 
-常见动作：
-- 查看目录内容：`ls -la <dir>`
-- 递归列出文件：`find <dir> -maxdepth 3 -type f`
-- 查询特定后缀：`find <dir> -name "*.md"`
 
-触发信号：
-- 用户提问“某目录有什么文件”
-- 用户提问“帮我查一下 data 目录内容”
-- 用户提问“列出/检索/查找 文件”