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

# AgentFSFilesystem

透過 [AgentFS](https://github.com/nichochar/agentfs) SDK 將檔案儲存在 Turso/SQLite 資料庫中。檔案會跨工作階段持久保存於本機 SQLite 資料庫，讓 Agent 無須外部雲端服務也能使用持久儲存空間。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/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`): 在 UI 中顯示的易讀名稱 (Default: `'AgentFS'`)

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

**description** (`string`): 在 UI 中顯示的檔案系統簡短說明

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

## 屬性

**id** (`string`): 檔案系統執行個體識別碼

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

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

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