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

# ArchilFilesystem

[Archil](https://docs.archil.com) の伸縮可能なサーバーレスディスクにファイルを保存します。高速な読み書きに対応する S3 互換オブジェクト API、POSIX シェル操作用の `exec()`、サーバー側並列検索用の `grep()` を組み合わせています。インターフェースの詳細は、[WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/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
```

## 使用方法

Workspace に `ArchilFilesystem` を追加して 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`): この Filesystem インスタンスの一意な識別子。 (Default: `Auto-generated`)

**displayName** (`string`): UI に表示するわかりやすい名前。

**icon** (`FilesystemIcon`): UI に表示するアイコンの識別子。

**description** (`string`): UI に表示する Filesystem の短い説明。

**readOnly** (`boolean`): true の場合、すべての書き込み操作を禁止します。 (Default: `false`)

## プロパティ

**id** (`string`): Filesystem インスタンスの識別子。

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

**provider** (`string`): Provider 識別子（'archil'）。

**diskId** (`string | undefined`): Archil ディスク ID（初期化後に使用可能）。

**readOnly** (`boolean | undefined`): Filesystem が読み取り専用モードかどうか。

## メソッド

ArchilFilesystem は [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を実装し、標準の 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()`

Filesystem を初期化します。既存のディスクに接続するか、新しいディスクを作成します。

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

### `getInfo()`

この Filesystem インスタンスのメタデータを返します。

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

### Archil 固有のメソッド

#### `exec(command)`

ディスク上でシェルコマンドを実行し、終了コード、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/ja/reference/workspace/filesystem)
- [S3Filesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem)
- [GCSFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/gcs-filesystem)
- [AzureBlobFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/azure-blob-filesystem)
- [Archil ドキュメント](https://docs.archil.com)