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

# AgentFSFilesystem

透過 [AgentFS](https://github.com/nichochar/agentfs) SDK 將檔案儲存在 Turso/SQLite 資料庫中。檔案會跨工作階段持久保存於本機 SQLite 資料庫，讓 Agent 無需外部雲端服務亦可擁有持久儲存空間。如需介面詳情，請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-HK/reference/workspace/filesystem)。

## 安裝

**npm**:

```bash
npm install @mastra/agentfs
```

**pnpm**:

```bash
pnpm add @mastra/agentfs
```

**Yarn**:

```bash
yarn add @mastra/agentfs
```

**Bun**:

```bash
bun add @mastra/agentfs
```

## 使用方式

將 `AgentFSFilesystem` 加入 Workspace，並將其指派給 Agent。建立 `AgentFSFilesystem` 類別實例時，必須至少提供 `agentId`、`path` 或 `agent` 其中一項。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AgentFSFilesystem } from '@mastra/agentfs'

const workspace = new Workspace({
  filesystem: new AgentFSFilesystem({
    agentId: 'my-agent',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})
```

### 使用明確指定的資料庫路徑

根據預設設定，資料庫會儲存在 `.agentfs` 目錄內，並以 `agentId` 作為檔案名稱。你可以指定自訂資料庫路徑：

```typescript
import { AgentFSFilesystem } from '@mastra/agentfs'

const filesystem = new AgentFSFilesystem({
  path: '/data/my-agent.db',
})
```

### 使用預先開啟的 AgentFS 實例

如果你需要自行管理 AgentFS 生命週期：

```typescript
import { AgentFS } from 'agentfs-sdk'
import { AgentFSFilesystem } from '@mastra/agentfs'

const agent = await AgentFS.open({ id: 'my-agent' })

const filesystem = new AgentFSFilesystem({
  agent, // caller manages open/close
})
```

## 建構函數參數

你必須至少提供 `agentId`、`path` 或 `agent` 其中一項。

**agentId** (`string`): Agent ID — 在 .agentfs/\<agentId>.db 建立資料庫

**path** (`string`): 明確指定的資料庫檔案路徑（可取代 agentId）

**agent** (`AgentFS`): 預先開啟的 AgentFS 實例。提供此項時，呼叫者負責管理生命週期（開啟／關閉）。

**id** (`string`): 此檔案系統實例的唯一識別碼 (Default: `自動產生`)

**displayName** (`string`): 供使用者介面顯示、方便閱讀的名稱 (Default: `'AgentFS'`)

**icon** (`FilesystemIcon`): 使用者介面的圖示識別碼 (Default: `'database'`)

**description** (`string`): 在使用者介面中顯示的檔案系統簡短說明

**readOnly** (`boolean`): 設為 true 時，所有寫入操作都會被封鎖 (Default: `false`)

## 屬性

**id** (`string`): 檔案系統實例識別碼

**name** (`string`): Provider 名稱（'AgentFSFilesystem'）

**provider** (`string`): Provider 識別碼（'agentfs'）

**readOnly** (`boolean | undefined`): 檔案系統是否處於唯讀模式