WorkspaceFilesystem

WorkspaceFilesystem 接口定义了工作区与文件存储的交互方式。

🌐 The WorkspaceFilesystem interface defines how workspaces interact with file storage.

方法

🌐 Methods

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

返回值: Promise<string | Buffer>

writeFile(path, content, options?)

写入文件内容。

🌐 Write file contents.

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

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

readdir(path, options?)

列出目录内容。

🌐 List directory contents.

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

返回值: Promise<FileEntry[]>

interface FileEntry {
  name: string;
  type: 'file' | 'directory';
  size?: number;
  modifiedAt?: Date;
}

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

exists(path)

检查路径是否存在。

🌐 Check if a path exists.

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

返回值: Promise<boolean>

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' }

返回值: Promise<FileStat>

interface FileStat {
  type: 'file' | 'directory';
  size: number;
  modifiedAt: Date;
  createdAt: Date;
  path: string;
}

可选方法

🌐 Optional Methods

init()

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

🌐 Initialize the filesystem. Called by workspace.init().

await filesystem.init?.();

destroy()

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

🌐 Clean up resources. Called by workspace.destroy().

await filesystem.destroy?.();

getInfo()

获取文件系统元数据。

🌐 Get filesystem metadata.

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

返回值: Promise<FilesystemInfo>

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

getInstructions()

获取该文件系统的工作原理描述。在工具说明中使用，以帮助代理理解路径语义。

🌐 Get a description of how this filesystem works. Used in tool descriptions to help agents understand path semantics.

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

返回值: string

相关

🌐 Related

• 工作区类
• 沙盒界面