跳到主要内容

ArchilFilesystem

将文件存储在 Archil 弹性 serverless 磁盘上。它结合了用于快速读写的 S3 兼容对象 API、用于执行 POSIX shell 操作的 exec()，以及用于并行服务端搜索的 grep()。有关接口详情，请参阅 WorkspaceFilesystem 接口。

安装
安装的直接链接

npm install @mastra/archil

用法
用法的直接链接

将 ArchilFilesystem 添加到 Workspace，并将其分配给 Agent：

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ArchilFilesystem } from '@mastra/archil'

const workspace = new Workspace({
  filesystem: new ArchilFilesystem({
    diskId: 'dsk-0123456789abcdef',
    apiKey: process.env.ARCHIL_API_KEY,
    region: 'aws-us-east-1',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

初始化时创建新磁盘
初始化时创建新磁盘的直接链接

如果没有现成的磁盘，请提供 createDiskOptions 以自动创建：

import { ArchilFilesystem } from '@mastra/archil'

const filesystem = new ArchilFilesystem({
  apiKey: process.env.ARCHIL_API_KEY,
  region: 'aws-us-east-1',
  createDiskOptions: {
    name: 'my-agent-workspace',
  },
})

await filesystem.init()
// filesystem.diskId now contains the newly created disk ID

环境变量回退值
环境变量回退值的直接链接

省略 apiKey 和 region 时，该 Provider 会从环境变量中读取：

  • ARCHIL_API_KEY - API 密钥
  • ARCHIL_REGION - 区域（例如 aws-us-east-1）
  • ARCHIL_S3_BASE_URL - 自定义 S3 endpoint（可选）
import { ArchilFilesystem } from '@mastra/archil'

// Uses ARCHIL_API_KEY and ARCHIL_REGION from environment
const filesystem = new ArchilFilesystem({
  diskId: 'dsk-0123456789abcdef',
})

构造函数参数
构造函数参数的直接链接

diskId?:

string
现有 Archil 磁盘 ID（例如 "dsk-0123456789abcdef"）。不能与 createDiskOptions 同时使用。

createDiskOptions?:

CreateDiskRequest
初始化时创建新磁盘的选项。不能与 diskId 同时使用。

apiKey?:

string
Archil API 密钥。未提供时回退到 ARCHIL_API_KEY 环境变量。

region?:

string
Archil 区域（例如 "aws-us-east-1"）。未提供时回退到 ARCHIL_REGION 环境变量。

baseUrl?:

string
自定义 Archil control plane URL（用于测试或自托管部署）。

s3BaseUrl?:

string
自定义 S3 兼容 API URL。未提供时回退到 ARCHIL_S3_BASE_URL 环境变量。

id?:

string
= 自动生成
此文件系统实例的唯一标识符。

displayName?:

string
在 UI 中显示的易读名称。

icon?:

FilesystemIcon
UI 中使用的图标标识符。

description?:

string
在 UI 中显示的此文件系统的简短说明。

readOnly?:

boolean
= false
设为 true 时，所有写入操作都会被阻止。

属性
属性的直接链接

id:

string
文件系统实例标识符。

name:

string
Provider 名称（'ArchilFilesystem'）。

provider:

string
Provider 标识符（'archil'）。

diskId:

string | undefined
Archil 磁盘 ID（初始化后可用）。

readOnly:

boolean | undefined
文件系统是否处于只读模式。

方法
方法的直接链接

ArchilFilesystem 实现了 WorkspaceFilesystem 接口，提供所有标准文件系统方法：

  • readFile(path, options?) - 读取文件内容
  • writeFile(path, content, options?) - 将内容写入文件
  • appendFile(path, content) - 将内容追加到文件
  • deleteFile(path, options?) - 删除文件
  • copyFile(src, dest, options?) - 复制文件
  • moveFile(src, dest, options?) - 移动文件或重命名
  • mkdir(path, options?) - 创建目录
  • rmdir(path, options?) - 删除目录
  • readdir(path, options?) - 列出目录内容
  • exists(path) - 检查路径是否存在
  • stat(path) - 获取文件或目录元数据

init()
init的直接链接

初始化文件系统。连接现有磁盘或创建新磁盘。

await filesystem.init()

getInfo()
getinfo的直接链接

返回此文件系统实例的元数据。

const info = filesystem.getInfo()
// { id: '...', name: 'ArchilFilesystem', provider: 'archil', status: 'ready' }

Archil 特有方法
Archil 特有方法的直接链接

exec(command)
execcommand的直接链接

在磁盘上运行 shell 命令。返回退出码、stdout 和 stderr。

const result = await filesystem.exec('ls -la /data')
// { exitCode: 0, stdout: '...', stderr: '' }

grep(options)
grepoptions的直接链接

在磁盘上的文件中运行并行服务端搜索。

const results = await filesystem.grep({
  directory: '/logs',
  pattern: 'ERROR',
  recursive: true,
  glob: '*.log',
})
// { matches: [...], stoppedReason: null }

share(path, options?)
sharepath-options的直接链接

生成用于共享文件的签名 URL。

const { url } = await filesystem.share('/reports/output.pdf', {
  expiresIn: 3600,
})
On this page