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

# LocalFilesystem

**新增於：** `@mastra/core@1.1.0`

將檔案儲存在本機檔案系統的目錄中。介面詳情請參閱 [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)。

## 使用方式

將 `LocalFilesystem` 加入 Workspace，並指派給 Agent。Agent 接著就能在執行任務時讀取、寫入及管理檔案：

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
})

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

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')
```

## 建構函式參數

**basePath** (`string`): 磁碟上的基底目錄路徑。所有檔案路徑都會相對於此目錄解析。

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

**contained** (`boolean`): 設為 true 時，所有檔案操作都會限制在 basePath 內，以防止路徑周遊攻擊和 symlink 逸出。請參閱範圍限制。 (Default: `true`)

**allowedPaths** (`string[]`): Agent 可在 basePath 以外存取的其他目錄。 (Default: `[]`)

**instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): 自訂指示，用於覆寫 getInstructions() 傳回的預設指示。傳入字串可完全取代預設指示；傳入函式則可存取目前的 requestContext 並擴充指示，以便針對每個要求自訂。

**readOnly** (`boolean`): 設為 true 時，會封鎖所有寫入操作，但仍允許讀取操作。 (Default: `false`)

## 屬性

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

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

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

**basePath** (`string`): 磁碟上的絕對基底路徑

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

**allowedPaths** (`readonly string[]`): 目前已解析的允許路徑集合。啟用範圍限制時，這些路徑可位於 basePath 之外。

## 方法

### `init()`

初始化檔案系統。如果基底目錄不存在，則建立該目錄。

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

由 `workspace.init()` 呼叫。

### 延遲初始化

如果尚未初始化，LocalFilesystem 會在第一次操作時進行初始化，並自動建立基底目錄。你可以選擇明確呼叫 `init()`；若要在第一次操作前預先建立目錄，這麼做會很有用。

### `destroy()`

清除檔案系統資源。

```typescript
await filesystem.destroy()
```

由 `workspace.destroy()` 呼叫。

### `setAllowedPaths(pathsOrUpdater)`

在執行階段更新允許的路徑。可接受新的路徑陣列（取代目前陣列），或接受更新程式回呼函式；該函式會收到目前路徑並傳回新的集合。

```typescript
// Set directly
filesystem.setAllowedPaths(['/home/user/.config'])

// Update with callback
filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

// Clear all allowed paths
filesystem.setAllowedPaths([])
```

**參數：**

**pathsOrUpdater** (`string[] | ((current: readonly string[]) => string[])`): 新的允許路徑陣列，或接收目前路徑的更新程式函式

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

讀取檔案內容。

```typescript
const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
```

**參數：**

**path** (`string`): 相對於 basePath 的檔案路徑。

**options** (`Options`): 設定選項。

**options.encoding** (`'utf-8' | 'binary'`): 文字或二進位編碼

### `writeFile(path, content, options?)`

將內容寫入檔案。

```typescript
await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
```

**參數：**

**path** (`string`): 相對於 basePath 的檔案路徑。

**content** (`string | Buffer`): 檔案內容

**options** (`Options`): 設定選項。

**options.recursive** (`boolean`): 若上層目錄不存在則建立

**options.overwrite** (`boolean`): 覆寫現有檔案

**options.expectedMtime** (`Date`): 提供此值時，如果檔案目前的修改時間不相符，寫入會因 StaleFileError 而失敗。可用於樂觀並行控制，以偵測讀取與寫入之間的外部修改。

### `appendFile(path, content)`

將內容附加至現有檔案。

```typescript
await filesystem.appendFile('/logs/app.log', 'New log entry\n')
```

**參數：**

**path** (`string`): 相對於 basePath 的檔案路徑。

**content** (`string | Buffer`): 要附加的內容

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

刪除檔案。

```typescript
await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
```

**參數：**

**path** (`string`): 檔案路徑

**options** (`Options`): 設定選項。

**options.force** (`boolean`): 檔案不存在時不擲回錯誤

### `copyFile(src, dest, options?)`

將檔案複製到新位置。

```typescript
await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
await filesystem.copyFile('/src/config.json', '/backup/config.json', { overwrite: false })
```

**參數：**

**src** (`string`): 來源檔案路徑

**dest** (`string`): 目的檔案路徑

**options** (`Options`): 設定選項。

**options.overwrite** (`boolean`): 若目的地已存在則覆寫

### `moveFile(src, dest, options?)`

移動檔案或重新命名。

```typescript
await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
await filesystem.moveFile('/temp/upload.txt', '/files/document.txt')
```

**參數：**

**src** (`string`): 來源檔案路徑

**dest** (`string`): 目的檔案路徑

**options** (`Options`): 設定選項。

**options.overwrite** (`boolean`): 若目的地已存在則覆寫

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

建立目錄。

```typescript
await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })
```

**參數：**

**path** (`string`): 目錄路徑

**options** (`Options`): 設定選項。

**options.recursive** (`boolean`): 建立上層目錄

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

移除目錄。

```typescript
await filesystem.rmdir('/docs/old')
await filesystem.rmdir('/docs/nested', { recursive: true })
```

**參數：**

**path** (`string`): 目錄路徑

**options** (`Options`): 設定選項。

**options.recursive** (`boolean`): 以遞迴方式移除內容

**options.force** (`boolean`): 目錄不存在時不擲回錯誤

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

列出目錄內容。

```typescript
const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
```

### `exists(path)`

檢查路徑是否存在。

```typescript
const exists = await filesystem.exists('/docs/guide.md')
```

### `stat(path)`

取得檔案或目錄的中繼資料。

```typescript
const stat = await filesystem.stat('/docs/guide.md')
// { type: 'file', size: 1234, modifiedAt: Date, createdAt: Date, path: '/docs/guide.md' }
```

### `getInfo()`

傳回此檔案系統執行個體的中繼資料。

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'LocalFilesystem', provider: 'local', basePath: '/workspace', readOnly: false }
```

### `getInstructions(opts?)`

傳回此檔案系統中路徑運作方式的說明。指派給 Agent 時，此說明會注入 Agent 的系統訊息。

```typescript
const instructions = filesystem.getInstructions()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
```

當建構函式的 `instructions` 選項是函式時，傳入 `requestContext` 即可針對每個要求自訂：

```typescript
const instructions = filesystem.getInstructions({ requestContext })
```

**參數：**

**opts.requestContext** (`RequestContext`): 如果建構函式中提供了 instructions 函式，便會轉傳給該函式。

**傳回值：** `string`

若要覆寫預設輸出，請將 `instructions` 選項傳入建構函式。請參閱[建構函式參數](#constructor-parameters)。

## 路徑解析

### `basePath` 的運作方式

`basePath` 選項會設定所有檔案操作的根目錄。傳給 `readFile()` 等方法的檔案路徑會相對於此基底解析：

- 移除開頭斜線：`/docs/guide.md` → `docs/guide.md`
- 正規化路徑並與 basePath 結合
- 結果：`./workspace` + `docs/guide.md` → `./workspace/docs/guide.md`

```typescript
const filesystem = new LocalFilesystem({
  basePath: './workspace',
})

// These all resolve to ./workspace/docs/guide.md
await filesystem.readFile('/docs/guide.md')
await filesystem.readFile('docs/guide.md')
```

### 相對路徑與執行環境

當 `basePath` 使用相對路徑時，會從 `process.cwd()` 開始解析。在 Mastra 專案中，cwd 會依程式碼的執行方式而變更：

| 環境             | 工作目錄                   | `./workspace` 解析為               |
| -------------- | ---------------------- | ------------------------------- |
| `mastra dev`   | `./src/mastra/public/` | `./src/mastra/public/workspace` |
| `mastra start` | `./.mastra/output/`    | `./.mastra/output/workspace`    |
| 直接執行指令碼        | 執行指令的所在位置              | 相對於該位置                          |

當同一個相對路徑解析到不同位置時，可能會造成混淆。

### 建議：使用絕對路徑

若要讓所有執行環境都使用一致的路徑，請使用包含絕對路徑的環境變數：

```typescript
import { LocalFilesystem } from '@mastra/core/workspace'

const filesystem = new LocalFilesystem({
  basePath: process.env.WORKSPACE_PATH!,
})
```

在環境中將 `WORKSPACE_PATH` 設為絕對路徑，例如 `/home/user/my-project/workspace`。如此一來，無論如何執行程式碼，Workspace 路徑都能保持一致。

## 相關內容

- [WorkspaceFilesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)
- [Workspace 類別](https://mastra.zisheng.pro/zh-TW/reference/workspace/workspace-class)
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)