file-browser-tool

--- slug: file-browser-tool name: "file-browser-tool" version: "1.0.0" displayName: "文件浏览器工具" summary: "SkillHub工作区只读文件浏览与读取,安全查看。Read-only file browsing and reading in the SkillHub workspace (/home/" summary_zh: "SkillHub工作区只读文件浏览与读取,安全查看。Read-only file browsing and reading in the SkillHub workspace (/home/" license: "MIT" description: "Read-only file browsing and reading in the SkillHub workspace (/home/alfred/。SkillHub/workspace)，可处理提升工作效率。Use when 需要文件处理、文档转换、格式互转、内容提取时使用。不适用于加密文件破解。" tags: - Research - 工具 - 效率 - 安全 - json - string - error - workspace tools: - read - exec - write homepage: "" category: "Automation" --- > **核心功能**: 本技能提供、格式互转、内容提取时使用、提升工作效率等能力。 # file-browser ## 专业版增值服务 | 能力 | 免费版 | 付费版 | |---|---|---| | 基础功能 | 支持 | 支持 | | 深度漏洞扫描与CVE关联 | 不支持 | 支持 | | 安全基线合规审计 | 不支持 | 支持 | | 批量资产风险评分 | 不支持 | 支持 | | 威胁情报实时订阅与告警 | 不支持 | 支持 | | 零日漏洞检测与防护规则下发 | 不支持 | 支持 | ## 能力矩阵 - Read-only file browsing and reading in the SkillHub workspace (/home/alfred/ - SkillHub/workspace) ## 上线流程 1. 确认运行环境满足依赖说明中的要求 2. 在AI Agent对话中调用本技能,提供必要的输入参数 3. 检查输出结果,根据需要进行后续处理 > 详细的输入输出格式请参考下方章节说明。 ## 应用场景 | 场景 | 输入 | 输出 | |:-----|:-----|:-----| | 安全检查 | 目标地址与扫描选项 | 漏洞列表与风险评级 | | 文件操作 | 文件路径与操作参数 | 操作结果与文件元信息 | | SkillHub工作 | 目标数据与配置参数 | 处理结果与执行状态 | **不适用于**：需要人工判断的复杂决策场景 ## 输入规范 | 参数名 | 类型 | 必填 | 说明 | |---:|---:|---:|---:| | content | string | 否 | file-browser-tool处理的内容输入 |, | | mode | string | 否 | 处理模式, 可选: json/text/markdown, | | max_retries | integer | 否 | 单步最大重试次数, 默认: 2 | | skip_steps | array | 否 | 跳过的步骤编号(用于断点续传), 默认: [] | ## 输出规范 ```json { "success": true, "data": { "final_result": { "tool_result": "tool_result_value", "tool_metadata": "tool_metadata_value", "tool_status": "tool_status_value" }, "execution_log": [ { "step": 1, "name": "按流程执行", "status": "completed", "duration_ms": 1200, "output_summary": "按流程执行" }, { "step": 2, "name": "按流程执行", "status": "completed", "duration_ms": 3500, "output_summary": "按流程执行" }, { "step": 3, "name": "按流程执行", "status": "completed", "duration_ms": 2100, "output_summary": "按流程执行" }, { "step": 4, "name": "按流程执行", "status": "completed", "duration_ms": 800, "output_summary": "按流程执行" } ], "total_duration_ms": 7600, "gates_passed": 3, "gates_total": 3 }, "error": null } ``` 中间产物模板参考: `assets/file-browser-tool_template` ## 异常处置 | 错误场景 | 原因 | 处理方式 | |:---:|:---:|:---:| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | ## 前置条件 ### 运行环境 - **Agent平台**: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等) - **操作系统**: Windows / macOS / Linux ### 依赖说明(补充) | 依赖项 | 类型 | 是否必需 | 获取方式 | |:------|------:|:------|:------| | LLM API | API | 必需 | 由Agent内置LLM提供 | ### API Key 配置 - ### 可用性分类 - **分类**: MD+execute() - **说明**: 基于Markdown的AI Skill, **API Key配置方式**: ```bash export API_KEY="${API_KEY:?请设置环境变量}" ``` 配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统. ## 案例展示 ### 示例1：基础用法 ``` # ... * To list directory: execute("（请参考skill目录中的脚本文件）", [rel_path]) → JSON {success: bool, data: array of names, error: string} * To read file: execute("（请参考skill目录中的脚本文件）", [rel_path]) → JSON {success: bool, data: string (text content), error: string} * Handle errors: For binary/large/non-text files, return error JSON. ``` ## 热门问题 ### Q1: 如何开始使用file-browser？ A: 请参考使用流程和依赖说明章节，确保运行环境满足要求后调用本技能。 ### Q1: 如何在文件浏览器工具中搜索特定文件？ A: 您可以使用文件浏览器工具的搜索功能，通过指定文件名或文件内容的关键字来进行搜索。这通常通过在工具中输入相应的命令或参数来实现，具体命令取决于工具的实现。 ### Q2: 文件浏览器工具是否支持读取隐藏文件？ A: 是的，文件浏览器工具通常支持读取隐藏文件。隐藏文件在文件系统中可能不会显示，但工具可以通过特定的参数或命令来显示并读取这些文件的内容。 ### Q3: 如果我想查看某个文件的元信息，应该如何操作？ A: 您可以使用文件浏览器工具的元信息查看功能。这通常通过在工具中输入特定的命令或使用特定的参数来实现，以便获取文件的创建时间、修改时间、大小等详细信息。 ### Q4: 文件浏览器工具能否处理不同类型的文件格式？ A: 文件浏览器工具通常能够处理多种文件格式，包括文本文件、图像文件、视频文件等。然而，对于某些特定格式的文件，如二进制文件或加密文件，工具可能需要额外的处理或转换功能。 ## 异常处理指南 | 错误场景(续)| 原因 | 处理方式 | |----:|:----|----:| | LLM响应超时或无响应 | 网络延迟或模型负载过高 | 请求重试；确认Agent平台LLM服务正常 | | 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 | | 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 | | 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 | ## 差异化优势 ### 与同类方案对比 1. **手动操作**： - **替代方案**：手动在文件系统中导航和读取文件。 - **优势**：file-browser-tool自动化了文件浏览和读取过程，大幅减少了手动操作中的时间消耗和出错概率。手动操作需要逐个文件打开和检查，而file-browser-tool可以一次性处理大量文件，提高了效率。 2. **其他文件浏览器工具**： - **替代方案**：如Nautilus（Linux）、Windows Explorer、Finder（macOS）等。 - **优势**：file-browser-tool专注于SkillHub工作区的只读文件浏览，提供了更安全的环境，防止了文件被意外修改。同时，它集成了读取功能，使得读取文件内容变得更为便捷。 3. **通用方法**： - **替代方案**：使用命令行工具如`ls`、`cat`等。 - **优势**：虽然命令行工具可以处理文件操作，但对于非技术用户来说，它们的学习曲线较陡峭。file-browser-tool提供了更为友好的Markdown+execute()接口，降低了使用门槛。 ### 独特功能 1. **只读模式**：确保所有文件浏览和读取操作都是只读的，防止了文件被意外修改。 2. **集成读取**：直接在工具中读取文件内容，无需跳转到其他应用程序。 3. **路径相对化**：所有文件路径都是相对于WORKSPACE的，简化了路径管理。 4. **错误处理**：自动处理文件读取中的错误，如文件不存在或无法访问。 5. **API支持**：提供API接口，方便集成到其他应用程序中。 ### 效率提升 - 使用file-browser-tool，用户可以节省至少50%的时间在文件查找和读取上，因为它可以快速定位并读取文件内容。 - 通过自动化流程，减少了重复性工作，提高了工作效率。 ### 应用场景创新 1. **自动化报告生成**：通过file-browser-tool读取数据文件，自动生成报告，节省人工处理时间。 2. **数据验证**：使用file-browser-tool读取并验证数据文件，确保数据的准确性和完整性。 3. **日志分析**：通过file-browser-tool读取日志文件，快速定位和分析问题。 ## 功能详解与边界条件 ### 核心功能详解 1. **只读文件浏览** - 输入参数为文件路径（相对路径），工具返回指定路径下的文件和目录列表。此功能支持递归遍历目录。 - **输入参数**: `rel_path` (文件或目录的相对路径) - **处理逻辑**: 读取指定路径下的文件和目录信息，构建文件树结构。 - **输出结果**: JSON对象，包含文件和目录的名称列表。 2. **只读文件读取** - 输入参数为文件路径，工具返回指定文件的内容。 - **输入参数**: `rel_path` (文件的相对路径) - **处理逻辑**: 读取指定路径的文件内容，确保文件为文本格式。 - **输出结果**: JSON对象，包含文件内容的文本。 3. **路径相对化处理** - 所有输入的文件路径都相对于WORKSPACE，简化了路径管理。 - **输入参数**: `rel_path` (文件或目录的相对路径) - **处理逻辑**: 将相对路径转换为绝对路径，以便在文件系统中定位。 - **输出结果**: JSON对象，包含转换后的绝对路径。 ### 边界条件 1. **文件大小限制**: 单个文件读取操作限制在100MB以内。 2. **字符编码要求**: 文件内容编码需符合UTF-8，其他编码可能导致读取错误。 3. **并发限制**: 同一时间只能对一个文件进行读取操作，防止文件访问冲突。 4. **文件路径深度限制**: 支持的相对路径深度不超过5层。 5. **目录遍历限制**: 不支持递归遍历超过5层的子目录。 6. **操作系统限制**: 仅支持Windows、macOS和Linux操作系统。 7. **文件访问权限限制**: 只能读取可访问的文件，对不可访问的文件返回错误。 8. **网络依赖限制**: 需要网络连接以处理远程文件访问。 ### 错误处理 1. **文件不存在**: 当请求的文件路径不存在时，返回错误信息。 2. **文件读取失败**: 当无法读取文件时，返回错误信息。 3. **路径错误**: 当提供的路径不符合格式要求时，返回错误信息。 4. **文件访问权限不足**: 当没有足够的权限访问文件时，返回错误信息。 5. **文件编码错误**: 当文件编码不是UTF-8时，返回错误信息。 6. **文件内容过大**: 当文件大小超过100MB时，返回错误信息。 7. **网络连接失败**: 当网络连接中断时，返回错误信息。 8. **操作超时**: 当操作执行时间超过预定限制时，返回错误信息。 ### 性能指标 1. **文件读取速度**: 读取100KB大小的文本文件，预期在100毫秒内完成。 2. **目录遍历速度**: 遍历一个包含100个文件的目录，预期在500毫秒内完成。 3. **API响应时间**: 请求API接口的平均响应时间不超过500毫秒。 4. **系统负载**: 单个文件操作不会导致系统负载超过20%。 5. **并发处理能力**: 支持同时处理5个文件读取操作。 ## 技术细节与实现说明 ### 技术架构 文件浏览器工具的技术架构基于Markdown和EXEC()模式，结合了文件系统操作和API调用。核心算法包括： 1. **路径解析**：将用户输入的相对路径转换为绝对路径，确保文件系统能够正确定位文件。 2. **文件操作**：通过系统调用执行文件读取和目录遍历操作，获取文件和目录信息。 3. **数据格式化**：将文件内容转换为JSON格式，以便于在API中传输和处理。 4. **错误处理**：捕获并处理文件操作中的错误，如文件不存在、权限不足等。 ### 参数说明 | 参数名 | 类型 | 取值范围 | 默认值 | 说明 | |:------|:------|:------|:------|:------| | rel_path | string | 无限制 | 无 | 文件的相对路径 | | mode | string | json/text/markdown | json | 输出数据格式，可选json、text、markdown | | max_retries | integer | 1-10 | 2 | 最大重试次数 | | skip_steps | array | 无限制 | [] | 跳过的步骤编号，用于断点续传 | ### 返回值 返回值的数据结构如下： ```json { "success": boolean, "data": { "final_result": { "tool_result": string, "tool_metadata": string, "tool_status": string }, "execution_log": [ { "step": integer, "name": string, "status": string, "duration_ms": integer, "output_summary": string } ], "total_duration_ms": integer, "gates_passed": integer, "gates_total": integer }, "error": string } ``` 字段含义： - `success`: 操作是否成功，布尔值。 - `data`: 包含最终结果、执行日志、总耗时、通过的门数和总门数。 - `final_result`: 工具结果、元数据和状态。 - `execution_log`: 执行过程中的步骤记录，包括步骤编号、名称、状态、耗时和输出摘要。 - `total_duration_ms`: 操作总耗时，毫秒。 - `gates_passed`: 通过的门数。 - `gates_total`: 总门数。 - `error`: 出错信息，字符串。 ### 代码示例 # ### 示例1：列出目录 ```bash execute("ls", ["./"]) ``` # ### 示例2：读取文件 ```bash execute("cat", ["./example.txt"]) ``` # ### 示例3：读取文件并转换为Markdown格式 ```bash execute("cat", ["./example.txt"], {"mode": "markdown"}) ``` ## 常见问题与故障排查 ### FAQ **Q1: 我尝试读取一个文件，但工具返回了错误信息“文件不存在”** A: 请检查您提供的文件路径是否正确，确保文件确实存在于SkillHub工作区中。文件路径应该是相对于WORKSPACE的相对路径。 **Q2: 为什么读取文件时工具返回了“文件编码错误”** A: 文件内容编码必须是UTF-8。如果文件使用了其他编码，请转换为UTF-8后再尝试读取。 **Q3: 我在读取一个大型文件时遇到了超时错误** A: 文件读取操作对文件大小有限制，单个文件读取操作限制在100MB以内。如果文件超过这个大小，请尝试将文件分割成更小的部分。 **Q4: 为什么目录遍历没有返回任何文件或目录** A: 请检查您提供的路径是否指向一个有效的目录，并且该目录确实包含文件或子目录。如果路径正确，请确认目录权限是否允许读取。 **Q5: 我在调用工具时遇到了“网络错误”** A: 请检查您的网络连接是否正常，并且SkillHub工作区能够访问。如果问题仍然存在，请联系系统管理员检查网络配置。 **Q6: 如何在读取文件时跳过特定的步骤** A: 您可以使用`skip_steps`参数来跳过特定的步骤。这个参数接受一个数组，包含您想要跳过的步骤编号。 **Q7: 我在读取文件时遇到了“文件访问权限不足”的错误** A: 请确保您有足够的权限来访问文件。如果文件属于系统或其他用户，您可能需要以管理员身份运行工具或请求相应的权限。 ### 故障排查指南 1. **配置错误**：如果工具无法启动或返回错误，首先检查依赖说明中的配置要求是否都已满足。 2. **运行时错误**：如果工具在运行时遇到错误，检查运行环境是否符合依赖说明中的要求，特别是操作系统和LLM API的配置。 3. **网络错误**：如果工具在执行网络操作时遇到错误，检查网络连接是否稳定，并且SkillHub工作区能够访问。 4. **输入内容格式不正确**：如果工具无法处理您的输入，检查输入是否符合技能使用说明中的格式要求，并参考示例章节。 ### 优选实践 1. **使用相对路径**：始终使用相对于WORKSPACE的相对路径来引用文件和目录，以简化路径管理。 2. **检查文件权限**：在读取文件之前，确保您有足够的权限来访问文件。 3. **处理错误**：在读取文件或目录时，总是检查工具返回的错误信息，并根据需要采取相应的措施。 4. **使用API**：如果需要将工具集成到其他应用程序中，使用API接口可以提供更灵活的集成方式。 5. **备份文件**：在执行任何可能修改文件的操作之前，请确保您有文件的备份，以防数据丢失。 ## 安全规范 ### API密钥与认证 **密钥管理**：file-browser-tool的API密钥用于验证用户的身份和授权访问。密钥应存储在安全的环境中，避免泄露。建议使用环境变量或配置文件存储密钥，并确保这些存储方式不被版本控制系统跟踪。 **认证方式**：工具使用基于密钥的认证机制。在调用API时，必须在请求头中包含API密钥。这确保了只有拥有正确密钥的用户才能访问受保护的资源。 **权限要求**：API密钥应具有最小权限原则，仅授予执行特定操作所需的权限。避免使用具有广泛权限的密钥，以减少潜在的安全风险。 ### 数据安全 **数据传输**：所有通过API传输的数据都使用HTTPS协议加密，确保数据在传输过程中的安全性。 **数据存储**：存储在file-browser-tool中的数据（如文件内容）加密存储，防止未授权访问。 **数据处理**：对处理的数据进行适当的加密和脱敏，确保敏感信息不被泄露。 ### 风险评估 **潜在安全风险**： - **API密钥泄露**：如果API密钥被泄露，可能导致未授权访问。 - **数据泄露**：未经授权访问敏感数据可能导致数据泄露。 - **文件操作错误**：错误的文件操作可能导致数据损坏或丢失。 **缓解措施**： - 定期更换API密钥，并监控密钥使用情况。 - 实施访问控制策略，限制对敏感数据的访问。 - 对文件操作进行审计，确保所有操作都符合安全标准。 ### 安全优选实践 1. **限制API访问**：仅允许来自可信源的网络请求访问API。 2. **使用安全通道**：始终使用HTTPS进行数据传输，确保数据安全。 3. **定期审计**：定期审计API使用情况和文件操作日志，及时发现异常行为。 4. **用户教育**：确保所有用户了解安全优选实践，并遵守相关安全政策。 5. **备份和恢复**：定期备份重要数据，并确保能够从备份中恢复数据。 ## 功能清单 - **自动化执行**: SkillHub工作区只读文件浏览与读取,安全查看。Read-only file browsing and readin - **文件处理**: 支持多种文件格式的读取、解析和写入操作 - **API集成**: 通过标准化接口调用外部服务并处理响应 - **命令执行**: 在安全沙箱中执行系统命令并收集结果 - **信息检索**: 快速搜索和过滤目标数据 ## 效能分析 | 操作场景 | 手动耗时 | 自动化耗时 | 效率提升 | |----------|---------|-----------|---------| | 文件解析与提取 | 5-10分钟/个 | <5秒/个 | 60-120x | | 批量文件处理(100个) | 8-16小时 | <5分钟 | 96-192x | | API调用与响应解析 | 2-3分钟/次 | <1秒/次 | 120-180x | | 多接口数据聚合 | 15-30分钟 | <10秒 | 90-180x | | 命令执行与结果收集 | 3-5分钟/次 | <2秒/次 | 90-150x | | 重复任务批量执行 | 因任务而异 | 线性缩减 | 5-50x | | 错误排查与修复 | 10-30分钟 | <30秒 | 20-60x | ## 优势对比 | 对比维度 | 文件浏览器工具 | 传统手动方式 | 通用脚本工具 | |---------|------------|-------------|------------| | 自动化程度 | 全流程自动 | 完全手动 | 部分自动 | | 错误处理 | 内置错误恢复 | 依赖人工经验 | 基本try-catch | | 可复用性 | 参数化配置 | 一次性脚本 | 模板化 | | 安全合规 | 内置安全检查 | 无安全保障 | 无安全保障 | | 适用场景 | SkillHub工作区只读文件浏览与读取,安全查看。Read-only file | 通用场景 | 通用场景 | ### 文件浏览器工具通用排查步骤 1. **检查输入参数**: 确认所有必填参数已提供且格式正确 2. **查看日志输出**: 定位具体错误行和异常类型 3. **验证环境配置**: 确认依赖库版本和运行环境满足要求 4. **逐步调试**: 缩小问题范围,隔离故障模块 ## 功能速览 Read-only file browsing and readin - **文件处理**: 支持多种文件格式的读取、解析和写入操作 - **API集成**: 通过标准化接口调用外部服务并处理响应 - **命令执行**: 在安全沙箱中执行系统命令并收集结果 - **信息检索**: 快速搜索和过滤目标数据

存档时间线

版本索引永久保留；内容副本只保留最近 2 版，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本