接口interface io.agentscope.harness.agent.filesystem 2.x

AbstractFilesystem

public interface AbstractFilesystem

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:44–189

定义抽象文件系统契约的接口。位于 io.agentscope.harness.agent.filesystem 包。核心成员包括 ls、read、write、edit、grep、glob。

Abstract filesystem API for agents: list, read, write, edit, grep, glob, upload, download.

Implementations may target the local disk, a sandbox, a key-value store, or other storage. Host-rooted types LocalFilesystem and LocalFilesystemWithShell also expose constructors that take the workspace root as a String path (same semantics as java.nio.file.Path).

Every operation accepts a RuntimeContext so stores can scope work to the current session, user, or sandbox. Callers that are not inside a tool/agent call with a merged context should pass RuntimeContext#empty().

方法摘要Method Summary

方法Method	说明Description
`public` `LsResult ls(RuntimeContext runtimeContext, String path)`	执行 `ls` 方法。 List all files in a directory with metadata.
`public` `ReadResult read(RuntimeContext runtimeContext, String filePath, int offset, int limit)`	执行读取相关操作。 Read file content with optional line-based pagination.
`public` `WriteResult write(RuntimeContext runtimeContext, String filePath, String content)`	执行写入相关操作。 Write content to a new file, error if file already exists.
`public` `EditResult edit(RuntimeContext runtimeContext, String filePath, String oldString, String newString, boolean replaceAll)`	执行 `edit` 方法。 Perform exact string replacements in an existing file.
`public` `GrepResult grep(RuntimeContext runtimeContext, String pattern, String path, String glob)`	执行 `grep` 方法。 Search for a literal text pattern in files.
`public` `GlobResult glob(RuntimeContext runtimeContext, String pattern, String path)`	执行 `glob` 方法。 Find files matching a glob pattern.
`public List<FileUploadResponse> uploadFiles(RuntimeContext runtimeContext, List<Map.Entry<String, byte[]>> files)`	执行上传文件相关操作。 Upload multiple files.
`public List<FileDownloadResponse> downloadFiles(RuntimeContext runtimeContext, List<String> paths)`	执行下载文件相关操作。 Download multiple files.
`public` `WriteResult delete(RuntimeContext runtimeContext, String path)`	删除数据。 Delete a file or directory (recursive for directories).
`public` `WriteResult move(RuntimeContext runtimeContext, String fromPath, String toPath)`	执行 `move` 方法。 Move (rename) a file or directory from `fromPath` to `toPath`.
`public boolean exists(RuntimeContext runtimeContext, String path)`	判断数据是否存在。 Check whether a file or directory exists.
`static public void validatePath(String path)` static	校验路径。 Validates that `path` is safe (non-null, non-blank, no `..` traversal).

方法详情Method Detail

ls

public LsResult ls(RuntimeContext runtimeContext, String path)

执行 ls 方法。

List all files in a directory with metadata.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`path`	String	路径（类型 `String`）。absolute path to the directory to list (must start with '/')

返回Returns LsResult

返回LsResult。LsResult with directory entries or error

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:53

read

public ReadResult read(RuntimeContext runtimeContext, String filePath, int offset, int limit)

执行读取相关操作。

Read file content with optional line-based pagination.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`filePath`	String	文件路径（类型 `String`）。absolute path to the file to read (must start with '/')
`offset`	int	偏移量（类型 `int`）。line number to start reading from (0-indexed). Default: 0
`limit`	int	数量上限（类型 `int`）。maximum number of lines to read. Default: 2000

返回Returns ReadResult

返回ReadResult。ReadResult with file data on success or error on failure

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:64

write

public WriteResult write(RuntimeContext runtimeContext, String filePath, String content)

执行写入相关操作。

Write content to a new file, error if file already exists.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`filePath`	String	文件路径（类型 `String`）。absolute path where the file should be created
`content`	String	内容（类型 `String`）。string content to write to the file

返回Returns WriteResult

返回WriteResult。WriteResult with path on success, or error if the file already exists or write fails

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:74

edit

public EditResult edit(RuntimeContext runtimeContext, String filePath, String oldString, String newString, boolean replaceAll)

执行 edit 方法。

Perform exact string replacements in an existing file.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`filePath`	String	文件路径（类型 `String`）。absolute path to the file to edit
`oldString`	String	旧的 String（类型 `String`）。exact string to search for and replace
`newString`	String	新建 String（类型 `String`）。string to replace oldString with (must be different from oldString)
`replaceAll`	boolean	replace 所有（类型 `boolean`）。if true, replace all occurrences; if false, oldString must be unique

返回Returns EditResult

返回EditResult。EditResult with path and occurrence count on success, or error on failure

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:86–91

grep

public GrepResult grep(RuntimeContext runtimeContext, String pattern, String path, String glob)

执行 grep 方法。

Search for a literal text pattern in files.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`pattern`	String	pattern（类型 `String`）。literal string to search for (not regex)
`path`	String	路径（类型 `String`）。optional directory path to search in (null searches current working directory)
`glob`	String	glob（类型 `String`）。optional glob pattern to filter which files to search (e.g., "*.java")

返回Returns GrepResult

返回GrepResult。GrepResult with matches or error

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:102

glob

public GlobResult glob(RuntimeContext runtimeContext, String pattern, String path)

执行 glob 方法。

Find files matching a glob pattern.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`pattern`	String	pattern（类型 `String`）。glob pattern with wildcards to match file paths
`path`	String	路径（类型 `String`）。base directory to search from (default: "/")

返回Returns GlobResult

返回GlobResult。GlobResult with matching files or error

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:112

uploadFiles

public List<FileUploadResponse> uploadFiles(RuntimeContext runtimeContext, List<Map.Entry<String, byte[]>> files)

执行上传文件相关操作。

Upload multiple files.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`files`	List<Map.Entry<String, byte[]>>	文件（类型 `List >`）。list of path-to-content mappings to upload

返回Returns List<FileUploadResponse>

返回列出。list of FileUploadResponse objects, one per input file (order matches input order)

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:121–122

downloadFiles

public List<FileDownloadResponse> downloadFiles(RuntimeContext runtimeContext, List<String> paths)

执行下载文件相关操作。

Download multiple files.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`paths`	List<String>	paths（类型 `List`）。list of file paths to download

返回Returns List<FileDownloadResponse>

返回列出。list of FileDownloadResponse objects, one per input path (order matches input order)

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:131

delete

public WriteResult delete(RuntimeContext runtimeContext, String path)

删除数据。

Delete a file or directory (recursive for directories).

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`path`	String	路径（类型 `String`）。absolute path to the file or directory to delete

返回Returns WriteResult

返回WriteResult。WriteResult success when deleted (or already absent), failure on I/O error

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:142

move

public WriteResult move(RuntimeContext runtimeContext, String fromPath, String toPath)

执行 move 方法。

Move (rename) a file or directory from fromPath to toPath.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`fromPath`	String	来自路径（类型 `String`）。absolute source path
`toPath`	String	到路径（类型 `String`）。absolute destination path

返回Returns WriteResult

返回WriteResult。WriteResult success on completion, failure on I/O error or missing source

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:156

exists

public boolean exists(RuntimeContext runtimeContext, String path)

判断数据是否存在。

Check whether a file or directory exists.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call agent runtime; `RuntimeContext#empty()` when none
`path`	String	路径（类型 `String`）。absolute path to check

返回Returns boolean

返回布尔值，表示判断结果。`true` if the path exists, `false` otherwise

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:168

validatePath

static public void validatePath(String path)

static

校验路径。

Validates that path is safe (non-null, non-blank, no .. traversal).

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径到校验。the path to validate

抛出Throws

IllegalArgumentException 当if 路径是无效时抛出 `IllegalArgumentException`。if the path is invalid

源码Source io/agentscope/harness/agent/filesystem/AbstractFilesystem.java:178–188