FileSystem SDK檔案與目錄操作開發參考-無影 Agent 開發套件 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` - 寫入大檔案