> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# ArchilFilesystem

将文件存储在 [Archil](https://docs.archil.com) 弹性 serverless 磁盘上。它结合了用于快速读写的 S3 兼容对象 API、用于执行 POSIX shell 操作的 `exec()`，以及用于并行服务端搜索的 `grep()`。有关接口详情，请参阅 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)。

## 安装

**npm**:

```bash
npm install @mastra/archil
```

**pnpm**:

```bash
pnpm add @mastra/archil
```

**Yarn**:

```bash
yarn add @mastra/archil
```

**Bun**:

```bash
bun add @mastra/archil
```

## 用法

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

```typescript
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` 以自动创建：

```typescript
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（可选）

```typescript
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`): 此文件系统实例的唯一标识符。 (Default: `自动生成`)

**displayName** (`string`): 在 UI 中显示的易读名称。

**icon** (`FilesystemIcon`): UI 中使用的图标标识符。

**description** (`string`): 在 UI 中显示的此文件系统的简短说明。

**readOnly** (`boolean`): 设为 true 时，所有写入操作都会被阻止。 (Default: `false`)

## 属性

**id** (`string`): 文件系统实例标识符。

**name** (`string`): Provider 名称（'ArchilFilesystem'）。

**provider** (`string`): Provider 标识符（'archil'）。

**diskId** (`string | undefined`): Archil 磁盘 ID（初始化后可用）。

**readOnly** (`boolean | undefined`): 文件系统是否处于只读模式。

## 方法

ArchilFilesystem 实现了 [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)，提供所有标准文件系统方法：

- `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()`

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

```typescript
await filesystem.init()
```

### `getInfo()`

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

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

### Archil 特有方法

#### `exec(command)`

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

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

#### `grep(options)`

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

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

#### `share(path, options?)`

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

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

## 相关内容

- [WorkspaceFilesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)
- [S3Filesystem 参考](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)
- [GCSFilesystem 参考](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem 参考](https://mastra.zisheng.pro/reference/workspace/azure-blob-filesystem)
- [Archil 文档](https://docs.archil.com)