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

# WorkspaceFilesystem

**添加于：** `@mastra/core@1.1.0`

`WorkspaceFilesystem` 接口定义 Workspace 如何与文件存储交互。

## 方法

### `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`): readFile 选项。

**options.encoding** (`'utf-8' | 'binary'`): 文本或二进制编码

**返回值：** `Promise<string | Buffer>`

### `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。可将其用于乐观并发控制，以检测读取和写入之间发生的外部修改。

### `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`): 如果文件不存在，不抛出错误

### `appendFile(path, content)`

将内容追加到文件；如果文件尚不存在，则创建该文件。父目录会自动创建。

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

**参数：**

**path** (`string`): 文件路径

**content** (`string | Buffer`): 要追加的内容

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

将文件复制到新位置。

```typescript
await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
```

**参数：**

**src** (`string`): 源文件路径

**dest** (`string`): 目标文件路径

**options** (`Options`): 配置选项。

**options.overwrite** (`boolean`): 如果目标已存在，则将其覆盖

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

移动文件或重命名。

```typescript
await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
```

**参数：**

**src** (`string`): 源文件路径

**dest** (`string`): 目标文件路径

**options** (`Options`): 配置选项。

**options.overwrite** (`boolean`): 如果目标已存在，则将其覆盖

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

列出目录内容。

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

**返回值：** `Promise<FileEntry[]>`

```typescript
interface FileEntry {
  name: string
  type: 'file' | 'directory'
  size?: number
  isSymlink?: boolean
  symlinkTarget?: string
}
```

### `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`): 如果目录不存在，不抛出错误

### `exists(path)`

检查路径是否存在。

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

**返回值：** `Promise<boolean>`

### `stat(path)`

获取文件或目录元数据。

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

**返回值：** `Promise<FileStat>`

```typescript
interface FileStat {
  name: string // File or directory name (basename only)
  path: string // Path relative to the filesystem basePath
  type: 'file' | 'directory'
  size: number
  createdAt: Date
  modifiedAt: Date
  mimeType?: string
}
```

## 可选方法

### `init()`

初始化文件系统。由 `workspace.init()` 调用。

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

### `destroy()`

清理资源。由 `workspace.destroy()` 调用。

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

### `getInfo()`

获取文件系统元数据。

```typescript
const info = await filesystem.getInfo?.()
// { id, name, provider, basePath, readOnly, status, storage? }
```

**返回值：** `Promise<FilesystemInfo>`

```typescript
interface FilesystemInfo {
  id: string
  name: string
  provider: string
  basePath?: string
  readOnly?: boolean
  status?: string
  storage?: {
    totalBytes?: number
    usedBytes?: number
    availableBytes?: number
  }
}
```

### `getInstructions(opts?)`

返回此文件系统工作方式的说明。将 Workspace 分配给 Agent 时，该说明会注入 Agent 的系统消息中。

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

**参数：**

**opts.requestContext** (`RequestContext`): 如果构造函数中提供了 instructions 函数，则转发给该函数。

**返回值：** `string`

## 相关内容

- [Workspace 类](https://mastra.zisheng.pro/reference/workspace/workspace-class)
- [Sandbox 接口](https://mastra.zisheng.pro/reference/workspace/sandbox)