LocalFilesystem

将文件存储在本地文件系统的目录中。

🌐 Stores files in a directory on the local filesystem.

info

有关接口详情，请参见 WorkspaceFilesystem 接口。

🌐 For interface details, see WorkspaceFilesystem Interface.

用法

🌐 Usage

向工作区添加一个 LocalFilesystem 并将其分配给代理。然后，代理可以在其任务中读取、写入和管理文件：

🌐 Add a LocalFilesystem to a workspace and assign it to an agent. The agent can then read, write, and manage files as part of its tasks:

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-4o',
  workspace,
});

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

构造函数参数

🌐 Constructor parameters

basePath:

string

Base directory path on disk. All file paths are resolved relative to this directory.

id?:

string

= Auto-generated

Unique identifier for this filesystem instance

readOnly?:

boolean

= false

When true, all write operations are blocked. Read operations are still allowed.

属性

🌐 Properties

id:

string

Filesystem instance identifier

name:

string

Provider name ('LocalFilesystem')

provider:

string

Provider identifier ('local')

basePath:

string

The absolute base path on disk

readOnly:

boolean | undefined

Whether the filesystem is in read-only mode

方法

🌐 Methods

init()

初始化文件系统。如果基目录不存在，则创建它。

🌐 Initialize the filesystem. Creates the base directory if it doesn't exist.

await filesystem.init();

由 workspace.init() 调用。

🌐 Called by workspace.init().

destroy()

清理文件系统资源。

🌐 Clean up filesystem resources.

await filesystem.destroy();

由 workspace.destroy() 调用。

🌐 Called by workspace.destroy().

readFile(path, options?)

读取文件内容。

🌐 Read file contents.

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

参数:

path:

string

File path relative to basePath

options.encoding?:

'utf-8' | 'binary'

= 'utf-8'

Text or binary encoding

writeFile(path, content, options?)

将内容写入文件。

🌐 Write content to a file.

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

参数:

path:

string

File path relative to basePath

content:

string | Buffer

File content

options.recursive?:

boolean

= false

Create parent directories if they don't exist

options.overwrite?:

boolean

= true

Overwrite existing file

appendFile(path, content)

将内容追加到现有文件。

🌐 Append content to an existing file.

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

参数:

path:

string

File path relative to basePath

content:

string | Buffer

Content to append

deleteFile(path, options?)

删除文件。

🌐 Delete a file.

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

参数:

path:

string

File path

options.force?:

boolean

= false

Don't throw error if file doesn't exist

copyFile(src, dest, options?)

将文件复制到新位置。

🌐 Copy a file to a new location.

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

参数:

src:

string

Source file path

dest:

string

Destination file path

options.overwrite?:

boolean

= true

Overwrite destination if it exists

moveFile(src, dest, options?)

移动或重命名文件。

🌐 Move or rename a file.

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

参数:

src:

string

Source file path

dest:

string

Destination file path

options.overwrite?:

boolean

= true

Overwrite destination if it exists

mkdir(path, options?)

创建一个目录。

🌐 Create a directory.

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

参数:

path:

string

Directory path

options.recursive?:

boolean

= false

Create parent directories

rmdir(path, options?)

删除目录。

🌐 Remove a directory.

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

参数:

path:

string

Directory path

options.recursive?:

boolean

= false

Remove contents recursively

options.force?:

boolean

= false

Don't throw if directory doesn't exist

readdir(path, options?)

列出目录内容。

🌐 List directory contents.

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

exists(path)

检查路径是否存在。

🌐 Check if a path exists.

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

stat(path)

获取文件或目录的元数据。

🌐 Get file or directory metadata.

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

getInfo()

返回有关此文件系统实例的元数据。

🌐 Returns metadata about this filesystem instance.

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

getInstructions()

返回此文件系统中路径如何工作的描述。用于工具说明中。

🌐 Returns a description of how paths work in this filesystem. Used in tool descriptions.

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

路径解析

🌐 Path resolution

basePath 的工作原理

🌐 How basePath works

basePath 选项设置所有文件操作的根目录。传递给类似 readFile() 的方法的文件路径将相对于此基础目录进行解析：

🌐 The basePath option sets the root directory for all file operations. File paths passed to methods like readFile() are resolved relative to this base:

• 开头的斜杠会被去掉：/docs/guide.md → docs/guide.md
• 路径已被规范化并与 basePath 连接
• 结果：./workspace + docs/guide.md → ./workspace/docs/guide.md

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');

相对路径和执行上下文

🌐 Relative paths and execution context

当你为 basePath 使用相对路径时，它会从 process.cwd() 解析。在 Mastra 项目中，cwd 会根据你运行代码的方式而有所不同：

🌐 When you use a relative path for basePath, it resolves from process.cwd(). In Mastra projects, cwd varies depending on how you run your code:

上下文	工作目录	./workspace 解析为
mastra dev	./src/mastra/public/	./src/mastra/public/workspace
mastra start	./.mastra/output/	./.mastra/output/workspace
直接脚本	运行命令的位置	相对于该位置

当相同的相对路径解析到不同位置时，这可能会导致混淆。

🌐 This can cause confusion when the same relative path resolves to different locations.

建议：使用绝对路径

🌐 Recommended: Use absolute paths

为了在所有执行环境中保持路径一致，请使用包含绝对路径的环境变量：

🌐 For consistent paths across all execution contexts, use an environment variable with an absolute path:

import { LocalFilesystem } from '@mastra/core/workspace';

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

在你的环境中将 WORKSPACE_PATH 设置为像 /home/user/my-project/workspace 这样的绝对路径。这可以确保无论你如何运行代码，工作区路径都是一致的。

🌐 Set WORKSPACE_PATH in your environment to an absolute path like /home/user/my-project/workspace. This ensures the workspace path is consistent regardless of how you run your code.

相关

🌐 Related

• 工作区文件系统接口
• 工作区类
• 工作区概览