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

# ArchilFilesystem

將檔案儲存在 [Archil](https://docs.archil.com) 的彈性 Serverless 磁碟上。它結合 S3 相容物件 API 以快速讀寫、用於 POSIX shell 操作的 `exec()`，以及用於伺服器端平行搜尋的 `grep()`。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/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 端點（選用）

```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 控制平面 URL（用於測試或自行託管部署）。

**s3BaseUrl** (`string`): 自訂 S3 相容 API URL。若未提供，則使用 ARCHIL\_S3\_BASE\_URL 環境變數。

**id** (`string`): 此檔案系統執行個體的唯一識別碼。 (Default: `Auto-generated`)

**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/zh-TW/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/zh-TW/reference/workspace/filesystem)
- [S3Filesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem)
- [GCSFilesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem 參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/azure-blob-filesystem)
- [Archil 文件](https://docs.archil.com)