跳到主内容

mirage-dsh 使用指南

把 dsh 的 ctx.fs 和 ctx.shell 两个能力缝隙替换为 Mirage 工作区，让 DSH Agent 直接读写挂载进来的 S3、Slack、Redis 等数据源。

本文为派生内容（基于 wiki / faq / compatibility_json 自动组装），非 AI 即时创作。

本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

mirage

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add @struktoai/mirage-dsh

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

  • One interface instead of N SDKs and M MCPs. Every service speaks the same filesystem semantics, and pipelines compose across services as naturally as on a local disk.
  • Portable workspaces: clone, snapshot, and version a workspace; agent runs move between machines without restarting or reconfiguring the system.
  • Embeddable: the Python and TypeScript SDKs run in-process inside FastAPI, Express, browser apps, or any async runtime; no separate process required.
  • Agent integrations: OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, and OpenHands via the SDKs; coding agents through native adapters, installable plugins, MCP, or FUSE.
  • Python ≥ 3.11 for the mirage-ai package and the mirage CLI

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

装上之后 dsh 默认能看到什么内容？

自动挂载了一个 /tmp 路径，类型是 RAM 临时盘，权限是 exec（可执行）。除此之外没有别的真实数据源，所有读写都在这次会话的内存里。

怎么把 Slack、Redis、S3 等真实数据接进来？

在你 profile 自己的 cordis.patch.yml 里覆盖 mirage 那一行，用 mounts 块声明资源（resource 写注册名、mode 写 read/write/exec、config 写资源所需的字段），token 等秘密字段用 !!js process.env.X 解析。

启用之后 dsh 自带的 PowerShell 和 ripgrep 搜索工具怎么不见了？

这两个工具会跑宿主进程，而 mirage 工作区里没有它们的位置，所以安装包显式禁用了 dsh 的 pwsh-sandbox、tool-pwsh 和 tool-fs-search；用 bash 工具里的 grep 就能覆盖搜索。

怎么让 bash 工具在多次调用之间保持目录和变量？

给 shell 插件传 sessionId 字段，cd、export、函数定义就会跨调用保留；不传 sessionId 时每次调用都是独立子 shell，状态不持久。

大输出量的后台命令会怎样处理？

默认 stdout 缓冲 200KB、stderr 缓冲 64KB，超出会被截掉并标记 truncated；想拿完整输出就给 shell 的 spillDir 指向一个工作区目录（如 /tmp），溢出部分会落盘成文件，路径在 readOutput() 里返回。

它是 DSH 官方插件吗？

不是 DSH 仓库自带的；它通过 dsh 的 bundle 机制（cordis.patch.yml）把自己的三个 Cordis 插件插入到 dsh 体系里，从而接管 ctx.fs 和 ctx.shell 这两个能力缝隙。

— 源: plugin_wiki.faq_json

兼容性

  • DSH: 0.1.0-rc.6
  • Node: >=20.10.0

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则

mirage-dsh 使用指南