跳转到内容
Flue

输入关键词开始搜索文档。

Modal

最后更新 查看 Markdown 源文件

Modal 适配器将已初始化的 Modal Sandbox（来自 modal JavaScript SDK）适配为 Flue 的沙箱接口。当你的应用配置 Modal 沙箱资源时，可使用它进行提供商支持的命令执行和文件操作。

快速开始

使用 Modal 蓝图为现有 Flue 项目添加提供商支持的计算沙箱能力。在终端或你选择的编码智能体中运行以下命令：

flue add sandbox modal

概述

Modal 蓝图会在需要时安装 modal JavaScript SDK，并在你的源码根目录下创建 sandboxes/modal.ts。生成的适配器接受应用创建的 Modal Sandbox；资源分配、镜像选择、凭据和关闭操作在适配器之外完成。

<source-root>/sandboxes/modal.ts (abridged)
// flue-blueprint: sandbox/modal@1
import { sandboxFromDriver } from '@flue/runtime';
import type { SandboxDriver, SandboxFactory, Sandbox, FileStat } from '@flue/runtime';
import type { Sandbox as ModalSandbox } from 'modal';

export interface ModalAdapterOptions {
  cwd?: string;
}

function shellQuote(value: string): string {
  return `'${value.replace(/'/g, `'\\''`)}'`;
}

class ModalSandboxDriver implements SandboxDriver {
  constructor(private sandbox: ModalSandbox) {}

  /* 适配 Modal 的 open/read/write 句柄，并关闭每个打开的文件。 */

  /* 使用带引号的 shell 工具实现 stat、readdir、exists、mkdir 和 rm。 */

  /* 通过 bash -lc 运行命令，转发 timeoutMs，并排空两个输出流。 */
}

export function modal(sandbox: ModalSandbox, options?: ModalAdapterOptions): SandboxFactory {
  return {
    async createSandbox(): Promise<Sandbox> {
      const sandboxCwd = options?.cwd ?? '/';
      const driver = new ModalSandboxDriver(sandbox);
      return sandboxFromDriver(driver, sandboxCwd);
    },
  };
}

将 modal(sandbox) 作为智能体的 sandbox 传入，通过 Flue 暴露创建的 Modal Sandbox 的文件和命令执行，相对路径默认以 / 为根目录，除非你设置了 cwd。所选镜像必须提供 bash 和兼容的文件系统工具，用于 Modal SDK 未直接暴露的操作；生成的 stat 解析器支持 GNU 和 BusyBox stat 的输出，rm 会接收请求的递归和强制标志。

配置

变量用途
MODAL_TOKEN_ID无 ~/.modal.toml 时必需 — 当基于文件的凭据不可用时，标识 Modal 令牌。
MODAL_TOKEN_SECRET无 ~/.modal.toml 时必需 — 当基于文件的凭据不可用时，认证 Modal 令牌。
覀求用途
modal 包必需 — 提供 Modal JavaScript SDK。
Node.js 22 或更高版本必需 — 运行生成的适配器使用的 SDK。
合适的 Modal 镜像必需 — 提供智能体工作所需的 shell 和系统工具。

适用场景

当你的应用已经管理 Modal 应用、镜像或沙箱生命周期，需要将该计算边界暴露给 Flue 操作时，使用 Modal。适配器适配已创建的沙箱；创建、关闭、密钥处理、网络和镜像内容仍由你负责。

参见沙箱和沙箱适配器 API。