FileSystem_无影 Agent 开发套件 AgentBay(AgentBay)-阿里云帮助中心

描述

FileSystem类提供在AgentBay云环境会话中进行文件操作的方法，包括读取、写入、编辑、搜索文件以及目录操作。

方法	说明	环境
方法	说明	ComputerUseLinux	ComputerUseWindows	BrowserUse	MobileUse	CodeSpace
`read_file`	读取文件内容（支持偏移量和长度限制）说明仅支持UTF-8编码的文件。	支持	支持	支持	不支持	支持
`write_large_file`	写入大文件（按块大小）	支持	支持	支持	不支持	支持
`read_large_file`	读取大文件（按块大小）	支持	支持	支持	不支持	支持
`read_multiple_files`	同时读取多个文件	支持	支持	支持	不支持	支持
`write_file`	创建或写入文件（支持覆盖/追加模式）说明仅支持UTF-8编码的文件。	支持	支持	支持	不支持	支持
`edit_file`	基于行的文件编辑	支持	支持	支持	不支持	支持
`create_directory`	创建目录（支持嵌套创建）	支持	支持	支持	不支持	支持
`list_directory`	列出目录内容	支持	支持	支持	不支持	支持
`search_files`	递归搜索文件和目录	支持	支持	支持	不支持	支持
`move_file`	移动或重命名文件/目录	支持	支持	支持	不支持	支持
`get_file_info`	获取文件/目录的详细元数据	支持	支持	支持	不支持	支持

方法

`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：若写入文件失败，抛出错误。

描述

方法

create_directory / createDirectory / CreateDirectory- 创建目录

Golang

参数：

返回值：

示例：

Python

参数：

返回：

TypeScript

参数：

返回值：

异常：

EditFile - 编辑文件

Golang

参数：

返回值：

示例：

Python

参数：

返回：

TypeScript

参数：

返回值：

异常：

GetFileInfo - 获取文件信息

Golang

参数：

返回值：

示例：

Python

参数：

返回：

TypeScript

参数：

返回值：

异常：

ListDirectory - 列出目录

Golang

参数：

返回值：

DirectoryListResult 结构体：

示例：

Python

参数：

返回：

TypeScript

参数：

返回值：

异常：

MoveFile - 移动文件

Golang

参数：

返回值：

FileDirectoryResult 结构体：

Python

参数：

返回：

TypeScript

参数：

返回值：

异常：

ReadFile - 读取文件

Golang

参数：

返回值：

FileReadResult 结构体：

示例：

Python

参数：

返回：

TypeScript

参数：

返回值：

异常：

ReadMultipleFiles - 读取多个文件

Golang

参数：

返回值：

`create_directory` / `createDirectory` / `CreateDirectory`- 创建目录

`EditFile` - 编辑文件

`GetFileInfo` - 获取文件信息

`ListDirectory` - 列出目录

`ReadFile` - 读取文件

`SearchFiles` - 搜索文件

`WriteFile` - 写入文件

`ReadLargeFile` - 读取大文件

`WriteLargeFile` - 写入大文件