Haystack MirageShellTool 实战指南让 Agent 通过 bash 操作统一虚拟文件系统【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackMirageShellTool 是 Haystack 集成生态中一个特殊的 Agent 工具它把 S3、Google Drive、Postgres、本地磁盘等异构后端挂载成一棵统一的虚拟文件系统目录树并把这个文件系统的一次性execute接口封装成带command参数的、描述清晰的标准 HaystackTool。读完本文你将掌握MirageMount/MirageWorkspace/MirageShellTool三个核心类的作用与配置方法能够用几行代码让 Agent 通过ls、cat、grep等常规 bash 命令自行探查挂载的数据并回答复杂问题同时理解其“按挂载点只读 命令白名单 路径黑名单”的三层安全模型。本文主体基于 version-2.19 集成 API 参考并补充了现行 MirageShellTool 使用指南 与 Haystack 源码中的工具调度实现作为佐证。背景为什么需要“给 Agent 一个文件系统”常规 RAG 的做法是把文件内容预加载进 prompt这对数据量小、结构简单的场景可行。但当数据分散在对象存储、数据库、SaaS 应用和本地磁盘等多个系统且 Agent 需要按需检索、聚合、统计时预加载既不现实也不灵活。Mirage 的解决思路是把异构后端统一挂载为一个虚拟文件系统让 Agent 自己用 bash 命令去探索、过滤和汇总数据。MirageShellTool 正是 Haystack 接入这一能力的桥梁——它把 Mirage 的execute表面暴露给 Agent输出统一规范化为文本并在返回给模型前截断避免超长输出撑爆上下文。从源码看这类工具本质上是一个标准Tool数据类定义见 haystack/tools/tool.py由Agent在运行时调用其invoke。由于所有后端都以相同方式挂载同一个 Agent、同一套 bash 命令只需更换一个MirageMount就能切换到不同后端。三个核心类Mount、Workspace、ShellToolMirage 集成由两个可序列化的辅助类和一个工具类组成三者职责清晰类角色说明MirageMount单后端挂载描述声明挂在哪path、是哪个后端resource即 Mirage 注册名如s3、gdrive、如何配置config以及是否只读MirageWorkspace挂载树描述持有MirageMount列表与缓存配置懒加载构建真实的mirage.Workspace是工具背后的共享后端MirageShellToolAgent 工具把 workspace 包装成一个带command参数的Tool供Agent驱动其中MirageWorkspace也可以脱离 Agent 单独使用通过run()/run_async()直接执行命令——这对测试挂载树、构建非 Agent 型管道非常方便。安装与快速上手Agent 场景安装集成包pip install mirage-haystack以官方 API 参考中的最小示例为例version-2.19 参考文档from haystack.components.agents import Agent from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack_integrations.tools.mirage import MirageWorkspace, MirageMount, MirageShellTool workspace MirageWorkspace([ MirageMount(path/data, resourceram), MirageMount(path/s3, resources3, config{bucket: my-bucket}, read_onlyTrue), ]) tool MirageShellTool(workspace, allowed_commands[ls, cat, grep, head, wc, cp]) agent Agent(chat_generatorOpenAIChatGenerator(modelgpt-4o-mini), tools[tool]) result agent.run(messages[ChatMessage.from_user(How many lines in /s3/log.txt mention alert?)]) print(result[messages][-1].text)这段代码完成了四件事把内存ram与 S3 桶挂载进一个虚拟文件系统限制 Agent 只能使用 6 个命令把工具交给Agent最后 Agent 通过 bash 探查/s3/log.txt并回答统计问题。一个完整的“日志分诊”实战现行使用指南mirageshelltool.mdx给出了更完整的端到端示例在本地tempfile目录写入两份日志只读挂载到/logs用disk后端让示例完全自包含再配一个专门的角色提示词import os import tempfile from haystack.components.agents import Agent from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack_integrations.tools.mirage import ( MirageMount, MirageShellTool, MirageWorkspace, ) # 准备样例数据真实场景中这些文件已存在 data_dir tempfile.mkdtemp(prefixmirage-logs-) with open(os.path.join(data_dir, api.log), w) as fh: fh.write(INFO request /health 200\nERROR db connection timeout\nERROR db connection timeout\n) with open(os.path.join(data_dir, worker.log), w) as fh: fh.write(INFO job 41 done\nERROR job 42 failed: OutOfMemory\n) # 只读挂载是权威写入边界无论模型选择什么命令Mirage 都会拒绝向只读挂载写入 workspace MirageWorkspace( mounts[ MirageMount(path/logs, resourcedisk, config{root: data_dir}, read_onlyTrue), ], ) tool MirageShellTool(workspace, allowed_commands[ls, cat, grep, head, wc]) agent Agent( chat_generatorOpenAIChatGenerator(modelgpt-4o-mini), tools[tool], system_prompt( You are a log-triage assistant. A virtual filesystem is available through the mirage_shell tool. Use bash commands (ls, cat, grep, wc, ...) to inspect the mounted files under /logs before answering. Base your answer only on what the files actually show. ), ) response agent.run( messages[ ChatMessage.from_user( Across all files in /logs, what is the single most common ERROR message, and how many times does it occur?, ), ], ) print(response[last_message].text) tool.close()要点提示workspace是唯一必填参数其余参数都有默认值system_prompt中明确告诉模型可用mirage_shell工具并用 bash 探查/logs显著提升工具调用成功率用完调用tool.close()释放底层 workspace 资源。独立使用 MirageWorkspace不经过 AgentMirageWorkspace可单独运行命令适合测试挂载树或搭建非 Agent 管道。独立使用时建议先warm_up()或让首次run()懒构建结束前close()from haystack_integrations.tools.mirage import MirageMount, MirageWorkspace workspace MirageWorkspace( mounts[ MirageMount(path/data, resourceram), # 内存临时空间 MirageMount(path/s3, resources3, config{bucket: my-bucket}, read_onlyTrue), ], ) print(workspace.run(ls /s3)) print(workspace.run(grep -r alert /s3/logs | wc -l)) workspace.close()run()的签名见 API 参考为run(command: str, *, timeout: float 60.0, max_chars: int | None None) - strcommand一行 bash 命令例如grep -r alert /s3/logs | wc -ltimeout等待命令完成的最大秒数默认60.0max_chars若设置返回文本截断到该字符数返回值合并的 stdout 字符串命令非零退出时会附带尾部错误说明。run_async()是run()的异步对应版本签名一致适合AsyncPipeline等异步执行环境。挂载带凭据的后端需要凭据的后端通过config传入。凭据应使用 Haystack 的Secret对象包装这样只在构建真实 workspace 时才解析、序列化时绝不落明文from haystack.utils import Secret from haystack_integrations.tools.mirage import MirageMount MirageMount(path/data, resourceram) # 内存临时空间 MirageMount(path/local, resourcedisk, config{root: /srv/data}) # 本地磁盘 MirageMount(path/s3, resources3, config{bucket: my-bucket}, read_onlyTrue) MirageMount( path/drive, resourcegdrive, config{client_id: ..., refresh_token: Secret.from_env_var(GDRIVE_REFRESH_TOKEN)}, read_onlyTrue, )关于config值API 参考 明确说明它可以是三种形态普通值直接传给后端 Mirage config 的键值HaystackSecret用于凭据构建时解析OAuth token 源如OAuthRefreshTokenSource用于 config 接受 token-provider 可调用对象的后端如 Mirage OneDrive 的access_token构建时转为 token 提供函数。每个后端创建方式完全相同用MirageMount.available_resources()发现注册名如s3、gdrive、postgresconfig 键则来自该后端对应的 Mirage config 类参考mirage.resource.registry.REGISTRY。三层安全模型Mirage永远不会在宿主机上 shell out每条命令都运行在 Mirage 自己的虚拟文件系统解释器内因此 Agent 的爆炸半径被限制在你挂载的范围内。在此基础上还有三层控制1. 按挂载点只读——权威写入边界MirageMount(..., read_onlyTrue)是防止修改或删除数据的唯一权威手段。无论命令是什么Mirage 都会拒绝写入只读挂载——这与白名单无关因此“Agent 不应改动的一切”都应挂载为只读。2. 命令白名单——尽力而为的引导过滤器allowed_commands限制哪些命令可以运行。关键点在于白名单针对 Mirage 将执行的每一条命令强制生效包括嵌套在$(...)、反引号、(...)和子 shell 中的命令所以ls $(rm x)在未放行rm时会被拒绝。但必须清醒认识其定位官方文档明确强调它是引导 Agent 的尽力而为过滤器不是沙箱。任何本身能再执行其他命令的命令eval、bash、sh、source、xargs、timeout一旦放行就相当于放行一切——面向不可信/托管场景不要列入这些命令。3. 路径黑名单denied_paths拒绝任何在命令文本中引用了给定路径子串的命令可进一步约束 Agent 访问特定目录或文件。综合起来的安全姿势是数据只读挂载 白名单限定命令集 黑名单封禁敏感路径三者配合使用。生命周期与序列化 APIMirageShellTool__init__( workspace: MirageWorkspace, *, name: str mirage_shell, description: str | None None, invocation_timeout: float 60.0, max_output_chars: int 20000, allowed_commands: list[str] | None None, denied_paths: list[str] | None None ) - None参数默认值说明workspace必填描述挂载树的MirageWorkspacenamemirage_shell暴露给 LLM 的工具名descriptionNone自定义工具描述为None时根据挂载树自动生成invocation_timeout60.0等待命令完成的最大秒数max_output_chars20000返回给模型前输出截断的字符数allowed_commandsNone若设置仅允许这些命令名如[ls, cat, grep, head, wc]None表示允许任意命令不推荐用于不可信/托管场景denied_pathsNone若设置引用任一给定路径子串的命令被拒绝其余方法warm_up() - None急切构建底层真实 workspace由Agent.warm_up()/Pipeline.warm_up()调用to_dict() - dict[str, Any]序列化为{type: ..., data: ...}格式字典from_dict(data) - MirageShellTool从字典反序列化close() - None关闭底层 workspace。MirageWorkspace__init__(mounts: list[MirageMount], *, cache_limit: str | int 512MB) - Nonemounts要挂载的后端列表为空或挂载路径不唯一时抛出MirageConfigErrorcache_limitMirage 文件缓存大小上限如512MB或整数字节数默认512MB。方法包括warm_up()急切构建真实 workspace幂等、close()释放资源线程安全、run()/run_async()同步/异步执行命令、to_dict()/from_dict()Secret 安全的序列化/反序列化、describe()返回挂载树的人类/LLM 可读摘要用于工具描述。MirageMountMirageMount(path, resource, config, read_only)path虚拟文件系统中的挂载点如/s3resourceMirage 注册的后端名如ram、disk、s3、gdrive完整列表见mirage.resource.registry.REGISTRY或MirageMount.available_resources()config传给后端 Mirage config 的关键字参数值可以是Secret或 OAuth token 源read_only为True时以 READ 模式挂载写入由 Mirage 本身拒绝。源码级佐证Agent 如何驱动这类工具Haystack 的Agent在warm_up()阶段会统一初始化其全部工具。在 haystack/components/agents/agent.py 中可以看到def warm_up(self) - None: warm_up_tools(toolsself.tools) warm_up_hooks(self.hooks) if hasattr(self.chat_generator, warm_up): self.chat_generator.warm_up()而warm_up_tools实现在 haystack/tools/utils.py对传入的单个Tool/Toolset或混合列表逐项调用其warm_up()若存在。这正是MirageShellTool.warm_up()构建真实 workspace 的调用入口——也就是说只要 Agent 调用了warm_up()Mirage 挂载树就会在运行前建好。API 参考中的方法说明与此完全一致“Called byAgent.warm_up()/Pipeline.warm_up()”。MirageShellTool的基类是haystack.tools.tool.Toolhaystack/tools/tool.py该数据类承载name、description、parametersJSON Schema 形式的参数定义以及function/async_function。LLM 依据name与description决定如何调用工具因此官方建议为description保留自动生成的挂载树摘要或在需要时提供更精细的自定义描述。小结MirageShellTool 把“文件系统即数据接口”的理念带入了 Haystack Agent 生态用MirageMount声明挂载、用MirageWorkspace描述挂载树、用MirageShellTool暴露给 Agent三者皆可序列化、可独立测试。其安全模型按挂载只读 命令白名单 路径黑名单为生产环境提供了清晰的操作边界而warm_up()与Agent.warm_up()的衔接则保证了资源在运行前就绪。后续阅读可继续参考 Ready-Made Tools 总览 了解其它预置工具或在 Agent 使用指南 中深入 Agent 的工具调度机制。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考