类class io.agentscope.harness.agent.filesystem.local 2.x

LocalFilesystem

public class LocalFilesystem implements AbstractFilesystem

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:76–925

本地文件系统，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.filesystem.local 包，实现 AbstractFilesystem。核心成员包括 getCwd、getMode、getPathPolicy、ls、read、write。

AbstractFilesystem implementation that reads and writes files on the local disk.

Path-resolution behaviour is controlled by the LocalFsMode passed at construction:

LocalFsMode#SANDBOXED — paths anchored to rootDir, .. and outside-root absolute paths blocked. Equivalent to legacy virtualMode=true.
LocalFsMode#ROOTED — absolute paths accepted only when they fall under one of the configured PathPolicy roots; relative paths anchor to rootDir.
LocalFsMode#UNRESTRICTED — absolute paths pass through; relative paths anchor to rootDir. Equivalent to legacy virtualMode=false.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `LocalFilesystem(String rootDir)`	初始化 `LocalFilesystem` 实例。 Same as `#LocalFilesystem(Path)` with Path.of(path) (`Path#of(String, String...)`) after `String#strip()`.
`public` `LocalFilesystem(Path rootDir)`	初始化 `LocalFilesystem` 实例。 Creates a abstract filesystem rooted at the given directory.
`public` `LocalFilesystem(Path rootDir, boolean virtualMode, int maxFileSizeMb)`	初始化 `LocalFilesystem` 实例。 Creates a abstract filesystem with explicit configuration.
`public` `LocalFilesystem(String rootDir, boolean virtualMode, int maxFileSizeMb)`	初始化 `LocalFilesystem` 实例。 Same as `#LocalFilesystem(Path, boolean, int)` with a path string; see `#LocalFilesystem(String)` for `null` / blank rules.
`public` `LocalFilesystem(Path rootDir, boolean virtualMode, int maxFileSizeMb, NamespaceFactory namespaceFactory)`	初始化 `LocalFilesystem` 实例。 Legacy constructor: maps `virtualMode` to `LocalFsMode#SANDBOXED` or `LocalFsMode#UNRESTRICTED` and uses an empty `PathPolicy`.
`public` `LocalFilesystem(String rootDir, boolean virtualMode, int maxFileSizeMb, NamespaceFactory namespaceFactory)`	初始化 `LocalFilesystem` 实例。 Same as `#LocalFilesystem(Path, boolean, int, NamespaceFactory)` with a path string; see `#LocalFilesystem(String)` for `null` / blank rules.
`public` `LocalFilesystem(Path rootDir, LocalFsMode mode, PathPolicy pathPolicy, int maxFileSizeMb, NamespaceFactory namespaceFactory)`	初始化 `LocalFilesystem` 实例。 Creates a filesystem with explicit mode and path policy.

方法摘要Method Summary

方法Method	说明Description
`public Path getCwd()`	返回根目录用于此文件系统。 Returns the root directory for this filesystem.
`public` `LocalFsMode getMode()`	获取模式。 Returns the active path-resolution mode.
`public` `PathPolicy getPathPolicy()`	获取路径策略。 Returns the configured path policy.
`public` `LsResult ls(RuntimeContext runtimeContext, String path)`	执行 `ls` 方法。 Performs the ls operation.
`public` `ReadResult read(RuntimeContext runtimeContext, String filePath, int offset, int limit)`	执行读取相关操作。 Performs the read operation.
`public` `WriteResult write(RuntimeContext runtimeContext, String filePath, String content)`	执行写入相关操作。 Performs the write operation.
`public` `EditResult edit(RuntimeContext runtimeContext, String filePath, String oldString, String newString, boolean replaceAll)`	执行 `edit` 方法。 Performs the edit operation.
`public` `GrepResult grep(RuntimeContext runtimeContext, String pattern, String path, String glob)`	执行 `grep` 方法。 Performs the grep operation.
`public` `GlobResult glob(RuntimeContext runtimeContext, String pattern, String path)`	执行 `glob` 方法。 Performs the glob operation.
`public List<FileUploadResponse> uploadFiles(RuntimeContext runtimeContext, List<Map.Entry<String, byte[]>> files)`	执行上传文件相关操作。 Performs the upload files operation.
`public List<FileDownloadResponse> downloadFiles(RuntimeContext runtimeContext, List<String> paths)`	执行下载文件相关操作。 Performs the download files operation.
`public` `WriteResult delete(RuntimeContext runtimeContext, String path)`	删除数据。 Performs the delete operation.
`public` `WriteResult move(RuntimeContext runtimeContext, String fromPath, String toPath)`	执行 `move` 方法。 Performs the move operation.
`public boolean exists(RuntimeContext runtimeContext, String path)`	判断数据是否存在。 Performs the exists operation.
`protected` `NamespaceFactory getNamespaceFactory()`	获取命名空间工厂。 Returns the namespace factory.
`protected Path resolvePath(RuntimeContext rc, String key)`	解析路径。 Performs the resolve path operation.
`protected String toVirtualPath(Path path)`	设置该参数。 Performs the to virtual path operation.

构造器详情Constructor Detail

LocalFilesystem

public LocalFilesystem(String rootDir)

初始化 LocalFilesystem 实例。

Same as #LocalFilesystem(Path) with Path.of(path) (Path#of(String, String...)) after String#strip().

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	String	根目录（类型 `String`）。filesystem root as a path string, or `null` for process working directory

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:102–104

LocalFilesystem

public LocalFilesystem(Path rootDir)

初始化 LocalFilesystem 实例。

Creates a abstract filesystem rooted at the given directory.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。root directory for all operations (`null` means CWD)

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:111–113

LocalFilesystem

public LocalFilesystem(Path rootDir, boolean virtualMode, int maxFileSizeMb)

初始化 LocalFilesystem 实例。

Creates a abstract filesystem with explicit configuration.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。root directory for all operations (`null` means CWD)
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。when true, all paths are anchored to rootDir and traversal is blocked
`maxFileSizeMb`	int	最大文件大小 Mb（类型 `int`）。maximum file size in megabytes for search operations

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:122–124

LocalFilesystem

public LocalFilesystem(String rootDir, boolean virtualMode, int maxFileSizeMb)

初始化 LocalFilesystem 实例。

Same as #LocalFilesystem(Path, boolean, int) with a path string; see #LocalFilesystem(String) for null / blank rules.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	String	根目录（类型 `String`）。The root dir.
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。The virtual mode.
`maxFileSizeMb`	int	最大文件大小 Mb（类型 `int`）。The max file size mb.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:130–132

LocalFilesystem

public LocalFilesystem(Path rootDir, boolean virtualMode, int maxFileSizeMb, NamespaceFactory namespaceFactory)

初始化 LocalFilesystem 实例。

Legacy constructor: maps virtualMode to LocalFsMode#SANDBOXED or LocalFsMode#UNRESTRICTED and uses an empty PathPolicy.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。root directory for all operations (`null` means CWD)
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。when true, all paths are anchored to rootDir and traversal is blocked
`maxFileSizeMb`	int	最大文件大小 Mb（类型 `int`）。maximum file size in megabytes for search operations
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。optional namespace factory for path scoping (`null` for none)

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:144–155

LocalFilesystem

public LocalFilesystem(String rootDir, boolean virtualMode, int maxFileSizeMb, NamespaceFactory namespaceFactory)

初始化 LocalFilesystem 实例。

Same as #LocalFilesystem(Path, boolean, int, NamespaceFactory) with a path string; see #LocalFilesystem(String) for null / blank rules.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	String	根目录（类型 `String`）。The root dir.
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。The virtual mode.
`maxFileSizeMb`	int	最大文件大小 Mb（类型 `int`）。The max file size mb.
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。The namespace factory.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:161–167

LocalFilesystem

public LocalFilesystem(Path rootDir, LocalFsMode mode, PathPolicy pathPolicy, int maxFileSizeMb, NamespaceFactory namespaceFactory)

初始化 LocalFilesystem 实例。

Creates a filesystem with explicit mode and path policy.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。root directory for relative paths (`null` means CWD)
`mode`	LocalFsMode	模式（类型 `LocalFsMode`）。path-resolution policy (`null` defaults to `LocalFsMode#UNRESTRICTED`)
`pathPolicy`	PathPolicy	路径策略（类型 `PathPolicy`）。allow-list for `LocalFsMode#ROOTED`; ignored otherwise (`null` treated as empty)
`maxFileSizeMb`	int	最大文件大小 Mb（类型 `int`）。maximum file size in megabytes for search operations
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。optional namespace factory for path scoping (`null` for none)

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:185–199

方法详情Method Detail

getCwd

public Path getCwd()

返回根目录用于此文件系统。

Returns the root directory for this filesystem.

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:219–221

getMode

public LocalFsMode getMode()

获取模式。

Returns the active path-resolution mode.

返回Returns LocalFsMode

返回LocalFsMode。Returns local fs mode.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:224–226

getPathPolicy

public PathPolicy getPathPolicy()

获取路径策略。

Returns the configured path policy.

返回Returns PathPolicy

返回PathPolicy。Returns path policy.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:233–235

ls

public LsResult ls(RuntimeContext runtimeContext, String path)

执行 ls 方法。

Performs the ls operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`path`	String	路径（类型 `String`）。The path.

返回Returns LsResult

返回LsResult。Returns ls result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:237–272

read

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

执行读取相关操作。

Performs the read operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`filePath`	String	文件路径（类型 `String`）。The file path.
`offset`	int	偏移量（类型 `int`）。The offset.
`limit`	int	数量上限（类型 `int`）。The limit.

返回Returns ReadResult

返回ReadResult。Returns read result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:274–322

write

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

执行写入相关操作。

Performs the write operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`filePath`	String	文件路径（类型 `String`）。The file path.
`content`	String	内容（类型 `String`）。The content.

返回Returns WriteResult

返回WriteResult。Returns write result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:324–345

edit

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

执行 edit 方法。

Performs the edit operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`filePath`	String	文件路径（类型 `String`）。The file path.
`oldString`	String	旧的 String（类型 `String`）。The old string.
`newString`	String	新建 String（类型 `String`）。The new string.
`replaceAll`	boolean	replace 所有（类型 `boolean`）。The replace all.

返回Returns EditResult

返回EditResult。Returns edit result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:347–390

grep

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

执行 grep 方法。

Performs the grep operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`pattern`	String	pattern（类型 `String`）。The pattern.
`path`	String	路径（类型 `String`）。The path.
`glob`	String	glob（类型 `String`）。The glob.

返回Returns GrepResult

返回GrepResult。Returns grep result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:392–411

glob

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

执行 glob 方法。

Performs the glob operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`pattern`	String	pattern（类型 `String`）。The pattern.
`path`	String	路径（类型 `String`）。The path.

返回Returns GlobResult

返回GlobResult。Returns glob result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:413–477

uploadFiles

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

执行上传文件相关操作。

Performs the upload files operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`files`	List<Map.Entry<String, byte[]>>	文件（类型 `List >`）。The files.

返回Returns List<FileUploadResponse>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:479–500

downloadFiles

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

执行下载文件相关操作。

Performs the download files operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`paths`	List<String>	paths（类型 `List`）。The paths.

返回Returns List<FileDownloadResponse>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:502–526

delete

public WriteResult delete(RuntimeContext runtimeContext, String path)

删除数据。

Performs the delete operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`path`	String	路径（类型 `String`）。The path.

返回Returns WriteResult

返回WriteResult。Returns write result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:528–555

move

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

执行 move 方法。

Performs the move operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`fromPath`	String	来自路径（类型 `String`）。The from path.
`toPath`	String	到路径（类型 `String`）。The to path.

返回Returns WriteResult

返回WriteResult。Returns write result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:557–576

exists

public boolean exists(RuntimeContext runtimeContext, String path)

判断数据是否存在。

Performs the exists operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`path`	String	路径（类型 `String`）。The path.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:578–588

getNamespaceFactory

protected NamespaceFactory getNamespaceFactory()

获取命名空间工厂。

Returns the namespace factory.

返回Returns NamespaceFactory

返回NamespaceFactory。Returns namespace factory.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:592–594

resolvePath

protected Path resolvePath(RuntimeContext rc, String key)

解析路径。

Performs the resolve path operation.

参数Parameters

名称Name	类型Type	说明Description
`rc`	RuntimeContext	rc（类型 `RuntimeContext`）。The rc.
`key`	String	键（类型 `String`）。The key.

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:596–607

toVirtualPath

protected String toVirtualPath(Path path)

设置该参数。

Performs the to virtual path operation.

参数Parameters

名称Name	类型Type	说明Description
`path`	Path	路径（类型 `Path`）。The path.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystem.java:729–737

继承成员Inherited Members

继承自Methods inherited from AbstractFilesystem

validatePath