描述
FileSystem类提供在AgentBay云环境会话中进行文件操作的方法，包括读取、写入、编辑、搜索文件以及目录操作。
方法 | 说明 | 环境 | ||||
ComputerUseLinux | ComputerUseWindows | BrowserUse | MobileUse | CodeSpace | ||
| 读取文件内容（支持偏移量和长度限制） 说明 仅支持UTF-8编码的文件。 | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 写入大文件（按块大小） | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 读取大文件（按块大小） | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 同时读取多个文件 | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 创建或写入文件（支持覆盖/追加模式） 说明 仅支持UTF-8编码的文件。 | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 基于行的文件编辑 | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 创建目录（支持嵌套创建） | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 列出目录内容 | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 递归搜索文件和目录 | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 移动或重命名文件/目录 | 支持 | 支持 | 支持 | 不支持 | 支持 |
| 获取文件/目录的详细元数据 | 支持 | 支持 | 支持 | 不支持 | 支持 |
方法
create_directory / createDirectory / CreateDirectory- 创建目录
Golang
func (fs *FileSystem) CreateDirectory(path string) (bool, error)参数：
path（string）：要创建的目录路径。
返回值：
bool：若目录创建成功，返回true。error：若目录创建失败，返回错误信息。
示例：
// 创建目录
success, err := session.FileSystem.CreateDirectory("/tmp/test")
if err != nil {
log.Printf("Error creating directory: %v", err)
} else {
fmt.Printf("Directory created: %t\n", success)
}Python
create_directory(path: str) -> BoolResult参数：
path (str)：要创建的目录路径。
返回：
BoolResult：包含操作成功状态、布尔数据（成功时为True）、请求ID和错误信息（如有）的结果对象。
返回类型已从布尔值更新为结构化的BoolResult对象，提供更详细的返回信息。
TypeScript
createDirectory(path: string): Promise<string>参数：
path（string）：要创建的目录路径。
返回值：
Promise<string>：若目录创建成功，返回响应文本内容。
异常：
APIError：若目录创建失败，抛出错误。
EditFile - 编辑文件
Golang
func (fs *FileSystem) EditFile(path string, edits []map[string]string, dryRun bool) (bool, error)参数：
path（string）：要编辑的文件路径。
edits（[]map[string]string）：包含
oldText和newText的编辑操作数组。dryRun（bool）：若为
true，预览更改而不实际应用。
返回值：
bool：若文件编辑成功，返回true。error：若文件编辑失败，返回错误信息。
示例：
// 编辑文件
edits := []map[string]string{
{"oldText": "Hello", "newText": "Hi"},
}
success, err := session.FileSystem.EditFile("/tmp/test/example.txt", edits, false)
if err != nil {
log.Printf("Error editing file: %v", err)
} else {
fmt.Printf("File edited successfully: %t\n", success)
}Python
edit_file(path: str, edits: List[Dict[str, str]], dry_run: bool = False) -> BoolResult参数：
path (str)：要编辑的文件路径。edits (List[Dict[str, str]])：编辑操作列表，每个操作包含oldText和newText。dry_run (bool, optional)：是否预览更改而不实际应用，默认为False。
返回：
BoolResult：包含操作成功状态、布尔数据（成功时为True）、请求 ID 和错误信息（如有）的结果对象。
TypeScript
editFile(
path: string,
edits: Array<{ oldText: string, newText: string }>,
dryRun?: boolean
): Promise<string>参数：
path（string）：要编辑的文件路径。
edits（Array<{ oldText: string, newText: string }>）：包含
oldText和newText的编辑操作数组。dryRun（boolean，可选）：若为
true，预览更改而不实际应用。默认为false。
返回值：
Promise<string>：若文件编辑成功，返回响应文本内容。
异常：
APIError：若文件编辑失败，抛出错误。
GetFileInfo - 获取文件信息
Golang
func (fs *FileSystem) GetFileInfo(path string) (string, error)参数：
path（string）：要查询的文件或目录路径。
返回值：
string：文件或目录的文本信息（如大小、权限等）。error：若获取信息失败，返回错误信息。
示例：
// 获取文件信息
fileInfo, err := session.FileSystem.GetFileInfo("/tmp/test/example.txt")
if err != nil {
log.Printf("Error getting file info: %v", err)
} else {
fmt.Printf("File info: %s\n", fileInfo)
}Python
get_file_info(path: str) -> OperationResult参数：
path (str)：要查询的文件或目录路径。
返回：
OperationResult：包含文件信息（如大小、修改时间等）、成功状态、请求ID和错误信息（如有）的结果对象。
TypeScript
getFileInfo(path: string): Promise<string>参数：
path（string）：要查询的文件或目录路径。
返回值：
Promise<string>：返回文件或目录的文本信息（如大小、权限等）。
异常：
APIError：若获取信息失败，抛出错误。
ListDirectory - 列出目录
Golang
func (fs *FileSystem) ListDirectory(path string) (*DirectoryListResult, error)参数：
path（string）：要列出的目录路径。
返回值：
*DirectoryListResult：包含目录条目和请求ID的结果对象。error：若列出目录失败，返回错误信息。
DirectoryListResult 结构体：
type DirectoryListResult struct {
RequestID string // 调试用的唯一请求标识符
Entries []*DirectoryEntry // 目录条目数组
}
type DirectoryEntry struct {
Name string // 文件或目录名称
IsDirectory bool // 是否为目录
}示例：
// 列出目录
listResult, err := session.FileSystem.ListDirectory("/tmp/test")
if err != nil {
log.Printf("Error listing directory: %v", err)
} else {
for _, entry := range listResult.Entries {
entryType := "目录"
if !entry.IsDirectory {
entryType = "文件"
}
fmt.Printf("%s: %s\n", entryType, entry.Name)
}
}Python
list_directory(path: str) -> OperationResult参数：
path (str)：要列出的目录路径。
返回：
OperationResult：包含目录条目列表（如文件名、子目录名）、成功状态、请求ID和错误信息（如有）的结果对象。
TypeScript
listDirectory(path: string): Promise<any>参数：
path（string）：要列出的目录路径。
返回值：
Promise<any>：若解析成功，返回目录条目数组；否则返回原始文本内容。
异常：
APIError：若列出目录失败，抛出错误。
MoveFile - 移动文件
Golang
func (fs *FileSystem) MoveFile(source, destination string) (*FileDirectoryResult, error)参数：
source（string）：源文件或目录路径。
destination（string）：目标文件或目录路径。
返回值：
*FileDirectoryResult：包含操作状态和请求ID的结果对象。error：若移动文件失败，返回错误信息。
FileDirectoryResult 结构体：
type FileDirectoryResult struct {
RequestID string // 调试用的唯一请求标识符
Success bool // 操作是否成功
}Python
move_file(source: str, destination: str) -> BoolResult参数：
source (str)：源文件或目录路径。destination (str)：目标文件或目录路径。
返回：
BoolResult：包含操作成功状态、布尔数据（成功时为True）、请求ID和错误信息（如有）的结果对象。
TypeScript
moveFile(source: string, destination: string): Promise<string>参数：
source（string）：源文件或目录路径。
destination（string）：目标文件或目录路径。
返回值：
Promise<string>：若文件移动成功，返回响应文本内容。
异常：
APIError：若移动文件失败，抛出错误。
ReadFile - 读取文件
Golang
func (fs *FileSystem) ReadFile(path string, optionalParams ...int) (*FileReadResult, error)参数：
path（string）：要读取的文件路径。
optionalParams（int, 可选）：偏移量和长度的可选参数。
返回值：
*FileReadResult：包含文件内容和请求ID的结果对象。error: 若读取文件失败，返回错误信息。
FileReadResult 结构体：
type FileReadResult struct {
RequestID string // 调试用的唯一请求标识符
Content string // 文件内容
}示例：
// 读取文件
readResult, err := session.FileSystem.ReadFile("/etc/hosts")
if err != nil {
log.Printf("Error reading file: %v", err)
} else {
fmt.Printf("File content: %s\n", readResult.Content)
}Python
read_file(path: str, offset: int = 0, length: int = 0) -> OperationResult参数：
path (str)：要读取的文件路径。offset (int, optional)：从该字节偏移量开始读取，默认为0。length (int, optional)：要读取的字节数。若为0，则读取至文件末尾，默认为0。
返回：
OperationResult：包含文件内容（字符串）、成功状态、请求ID和错误信息（如有）的结果对象。
TypeScript
readFile(path: string, offset?: number, length?: number): Promise<string>参数：
path（string）：要读取的文件路径。
offset（number, 可选）：从该字节偏移量开始读取。默认为
0。length（number, 可选）：要读取的字节数。若为
0，则读取到文件末尾。默认为0。
返回值：
Promise<string>：返回文件内容。
异常：
APIError：若读取文件失败，抛出错误。
ReadMultipleFiles - 读取多个文件
Golang
func (fs *FileSystem) ReadMultipleFiles(paths []string) (string, error)参数：
paths（[]string）：要读取的文件路径数组。
返回值：
string：文件路径到内容的映射文本。error：若读取文件失败，返回错误信息。
Python
read_multiple_files(paths: List[str]) -> OperationResult参数：
paths (List[str])：要读取的文件路径列表。
返回：
OperationResult：包含文件路径到文件内容的映射字典、成功状态、请求ID和错误信息（如有）的结果对象。
TypeScript
readMultipleFiles(paths: string[]): Promise<string>参数：
paths（string[]）：要读取的文件路径数组。
返回值：
Promise<string>：返回文件路径到内容的映射文本。
异常：
APIError：若读取文件失败，抛出错误。
SearchFiles - 搜索文件
Golang
func (fs *FileSystem) SearchFiles(path, pattern string, excludePatterns []string) (*SearchFilesResult, error)参数：
path（string）：要搜索的起始目录路径。
pattern（string）：匹配模式。
excludePatterns（[]string）排除模式数组。
返回值：
*SearchFilesResult：包含搜索结果和请求ID的结果对象。error：若搜索失败，返回错误信息。
SearchFilesResult 结构体：
type SearchFilesResult struct {
RequestID string // 调试用的唯一请求标识符
Results []string // 搜索结果数组
}Python
search_files(path: str, pattern: str, exclude_patterns: Optional[List[str]] = None) -> OperationResult参数：
path (str)：开始搜索的目录路径。pattern (str)：要匹配的模式（如通配符）。exclude_patterns (List[str], optional)：要排除的模式列表，默认为None。
返回：
OperationResult：包含搜索结果（匹配的文件路径列表）、成功状态、请求ID和错误信息（如有）的结果对象。
TypeScript
searchFiles(
path: string,
pattern: string,
excludePatterns?: string[]
): Promise<any[]>参数：
path（string）：要搜索的起始目录路径。
pattern（string）：匹配模式。
excludePatterns（string[], 可选）：排除模式数组。默认为空数组。
返回值：
Promise<any[]>：返回搜索结果数组。
异常：
APIError：若搜索失败，抛出错误。
WriteFile - 写入文件
Golang
func (fs *FileSystem) WriteFile(path, content string, mode string) (*FileWriteResult, error)参数：
path（string）：要写入的文件路径。
content（string）：要写入的内容。
mode（string）：模式（
"overwrite"（默认）、"append"或"create_new"）。
返回值：
*FileWriteResult：包含操作状态和请求ID的结果对象。error：若写入文件失败，返回错误信息。
FileWriteResult 结构体：
type FileWriteResult struct {
RequestID string // 调试用的唯一请求标识符
Success bool // 文件是否写入成功
}示例：
// 写入文件
writeResult, err := session.FileSystem.WriteFile("/tmp/test/example.txt", "Hello, world!", "overwrite")
if err != nil {
log.Printf("Error writing file: %v", err)
} else {
fmt.Printf("File written successfully: %t\n", writeResult.Success)
}Python
write_file(path: str, content: str, mode: str = "overwrite") -> bool参数：
path (str)：要写入的文件路径。content (str)：要写入的内容。mode (str, optional)：写入模式，"overwrite"（默认）或"append"。
返回：
bool：文件是否写入成功。
异常：
FileError：若写入文件失败则抛出异常。
TypeScript
writeFile(path: string, content: string, mode?: string): Promise<string>参数：
path（string）：要写入的文件路径。
content（string）：要写入的内容。
mode（string，可选）：模式（
"overwrite"（默认）、"append"或"create_new"）。
返回值：
Promise<string>：若文件写入成功，返回响应文本内容。
异常：
APIError：若写入文件失败，抛出错误。
ReadLargeFile - 读取大文件
Golang
func (fs *FileSystem) ReadLargeFile(path string, chunkSize int) (string, error)参数：
path（string）：要读取的文件路径。
chunkSize（int）：每个数据块的字节大小。
返回值：
string：完整文件内容。error：若读取文件失败，返回错误信息。
Python
read_large_file_in_chunks(path: str, chunk_size: int) -> Generator[OperationResult, None, None]参数：
path (str)：要读取的大文件路径。chunk_size (int)：每次读取的块大小（字节数）。
返回：
Generator[OperationResult, None, None]：生成器，每次迭代返回包含文件块内容的结果对象。
作用：
通过分块处理解决底层 API 的文件大小限制问题。
TypeScript
readLargeFile(path: string, chunkSize?: number): Promise<string>参数：
path（string）：要读取的文件路径。
chunkSize（number，可选）：每个数据块的字节大小。默认为
60KB。
返回值：
Promise<string>：返回完整的文件内容。
异常：
APIError：若读取文件失败，抛出错误。
WriteLargeFile - 写入大文件
Golang
func (fs *FileSystem) WriteLargeFile(path, content string, chunkSize int) (bool, error)参数：
path（string）：要写入的文件路径。
content（string）：要写入的内容。
chunkSize（int）每个数据块的字节大小。
返回值：
bool：若文件写入成功，返回true。error：若写入文件失败，返回错误信息。
基础文件操作示例：
package main
import (
"fmt"
"log"
)
func main() {
// 创建会话
agentBay := agentbay.NewAgentBay("your-api-key")
sessionResult, err := agentBay.Create(nil)
if err != nil {
log.Fatal(err)
}
session := sessionResult.Session
// 读取文件
readResult, err := session.FileSystem.ReadFile("/etc/hosts")
if err != nil {
log.Printf("Error reading file: %v", err)
} else {
fmt.Printf("File content: %s\n", readResult.Content)
}
// 创建目录
success, err := session.FileSystem.CreateDirectory("/tmp/test")
if err != nil {
log.Printf("Error creating directory: %v", err)
} else {
fmt.Printf("Directory created: %t\n", success)
}
// 写入文件
writeResult, err := session.FileSystem.WriteFile("/tmp/test/example.txt", "Hello, world!", "overwrite")
if err != nil {
log.Printf("Error writing file: %v", err)
} else {
fmt.Printf("File written successfully: %t\n", writeResult.Success)
}
// 编辑文件
edits := []map[string]string{
{"oldText": "Hello", "newText": "Hi"},
}
success, err = session.FileSystem.EditFile("/tmp/test/example.txt", edits, false)
if err != nil {
log.Printf("Error editing file: %v", err)
} else {
fmt.Printf("File edited successfully: %t\n", success)
}
// 获取文件信息
fileInfo, err := session.FileSystem.GetFileInfo("/tmp/test/example.txt")
if err != nil {
log.Printf("Error getting file info: %v", err)
} else {
fmt.Printf("File info: %s\n", fileInfo)
}
// 列出目录
listResult, err := session.FileSystem.ListDirectory("/tmp/test")
if err != nil {
log.Printf("Error listing directory: %v", err)
} else {
for _, entry := range listResult.Entries {
entryType := "目录"
if !entry.IsDirectory {
entryType = "文件"
}
fmt.Printf("%s: %s\n", entryType, entry.Name)
}
}
}TypeScript
writeLargeFile(path: string, content: string, chunkSize?: number): Promise<boolean>参数：
path（string）：要写入的文件路径。
content（string）：要写入的内容。
chunkSize（number，可选）：每个数据块的字节大小。默认为
60KB。
返回值：
Promise<boolean>：若文件写入成功，返回true。
异常：
APIError：若写入文件失败，抛出错误。