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

ProjectAwareOverlay

public class ProjectAwareOverlay extends OverlayFilesystem implements AbstractSandboxFilesystem

源码Source io/agentscope/harness/agent/filesystem/ProjectAwareOverlay.java:54–327

Project Aware Overlay，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.filesystem 包，继承自 OverlayFilesystem，实现 AbstractSandboxFilesystem。核心成员包括 id、execute、write、edit、delete、uploadFiles。

Overlay variant that routes writes to the project directory for non-workspace paths, while keeping workspace metadata (memory, sessions, skills, etc.) in the upper (workspace) layer.

Produced exclusively by io.agentscope.harness.agent.filesystem.spec.LocalFilesystemSpec when projectWritable(true) is set. Other filesystem specs (RemoteFilesystemSpec, SandboxFilesystemSpec) are not affected.

Every routed path is first normalized to its agent-visible relative form: a workspace-rooted absolute path (e.g. <workspace>/src/Foo.java) has the workspace root and, when namespace scoping is configured, the caller's namespace prefix stripped, so the absolute and the relative spelling of the same path behave identically in every operation. Absolute paths outside the workspace root pass through unchanged and are never classified as workspace metadata.

Read operations retain standard overlay semantics: check upper (workspace) first, fall back to lower (project). Shell execute() delegates to the upper layer as before.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `ProjectAwareOverlay(AbstractSandboxFilesystem upper, AbstractFilesystem lower, LocalFilesystem projectFs, Path workspaceRoot, NamespaceFactory namespaceFactory)`	初始化 `ProjectAwareOverlay` 实例。 Creates a new instance.
`public` `ProjectAwareOverlay(AbstractSandboxFilesystem upper, AbstractFilesystem lower, LocalFilesystem projectFs, Path workspaceRoot)` deprecated	初始化 `ProjectAwareOverlay` 实例。 Namespace-unaware variant: workspace-rooted absolute paths keep their namespace segment and may misroute under namespace scoping.

方法摘要Method Summary

方法Method	说明Description
`public String id()`	返回标识。 Returns the id.
`public` `ExecuteResponse execute(RuntimeContext runtimeContext, String command, Integer timeoutSeconds)`	执行执行相关操作。 Performs the execute 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` `WriteResult delete(RuntimeContext runtimeContext, String path)`	删除数据。 Performs the delete operation.
`public List<FileUploadResponse> uploadFiles(RuntimeContext runtimeContext, List<Map.Entry<String, byte[]>> files)`	执行上传文件相关操作。 Performs the upload files operation.
`public` `ReadResult read(RuntimeContext runtimeContext, String filePath, int offset, int limit)`	执行读取相关操作。 Performs the read operation.
`public boolean exists(RuntimeContext runtimeContext, String path)`	判断数据是否存在。 Performs the exists operation.
`public List<FileDownloadResponse> downloadFiles(RuntimeContext runtimeContext, List<String> paths)`	执行下载文件相关操作。 Performs the download files operation.
`public` `LsResult ls(RuntimeContext runtimeContext, String path)`	执行 `ls` 方法。 Performs the ls 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` `WriteResult move(RuntimeContext runtimeContext, String fromPath, String toPath)`	执行 `move` 方法。 Performs the move operation.

构造器详情Constructor Detail

ProjectAwareOverlay

public ProjectAwareOverlay(AbstractSandboxFilesystem upper, AbstractFilesystem lower, LocalFilesystem projectFs, Path workspaceRoot, NamespaceFactory namespaceFactory)

初始化 ProjectAwareOverlay 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`upper`	AbstractSandboxFilesystem	upper（类型 `AbstractSandboxFilesystem`）。shell-capable workspace filesystem (read-write, workspace root)
`lower`	AbstractFilesystem	lower（类型 `AbstractFilesystem`）。read-only project filesystem (overlay fallback)
`projectFs`	LocalFilesystem	project Fs（类型 `LocalFilesystem`）。writable project filesystem for non-workspace writes
`workspaceRoot`	Path	工作区根（类型 `Path`）。absolute path of the workspace, used to classify absolute paths
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。namespace factory scoping the workspace and project filesystems; used to strip the caller's namespace prefix from workspace-rooted absolute paths; `null` when no namespace scoping is configured

源码Source io/agentscope/harness/agent/filesystem/ProjectAwareOverlay.java:86–97

ProjectAwareOverlay

public ProjectAwareOverlay(AbstractSandboxFilesystem upper, AbstractFilesystem lower, LocalFilesystem projectFs, Path workspaceRoot)

deprecated

初始化 ProjectAwareOverlay 实例。

Namespace-unaware variant: workspace-rooted absolute paths keep their namespace segment and may misroute under namespace scoping.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `#ProjectAwareOverlay(AbstractSandboxFilesystem, AbstractFilesystem, LocalFilesystem, Path, NamespaceFactory)` so workspace-rooted absolute paths resolve identically to their relative spelling under namespace scoping

参数Parameters

名称Name	类型Type	说明Description
`upper`	AbstractSandboxFilesystem	upper（类型 `AbstractSandboxFilesystem`）。shell-capable workspace filesystem (read-write, workspace root)
`lower`	AbstractFilesystem	lower（类型 `AbstractFilesystem`）。read-only project filesystem (overlay fallback)
`projectFs`	LocalFilesystem	project Fs（类型 `LocalFilesystem`）。writable project filesystem for non-workspace writes
`workspaceRoot`	Path	工作区根（类型 `Path`）。absolute path of the workspace, used to classify absolute paths

源码Source io/agentscope/harness/agent/filesystem/ProjectAwareOverlay.java:111–118

方法详情Method Detail

id

public String id()

返回标识。

Returns the id.

返回Returns String

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

源码Source io/agentscope/harness/agent/filesystem/ProjectAwareOverlay.java:120–123

execute

public ExecuteResponse execute(RuntimeContext runtimeContext, String command, Integer timeoutSeconds)

执行执行相关操作。

Performs the execute operation.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`command`	String	命令（类型 `String`）。The command.
`timeoutSeconds`	Integer	超时秒（类型 `Integer`）。The timeout seconds.

返回Returns ExecuteResponse

返回ExecuteResponse。Returns execute response.

源码Source io/agentscope/harness/agent/filesystem/ProjectAwareOverlay.java:125–129

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/ProjectAwareOverlay.java:133–140

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/ProjectAwareOverlay.java:142–158

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/ProjectAwareOverlay.java:160–170

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/ProjectAwareOverlay.java:172–195

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/ProjectAwareOverlay.java:199–203

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/ProjectAwareOverlay.java:205–208

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/ProjectAwareOverlay.java:210–216

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/ProjectAwareOverlay.java:218–221

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/ProjectAwareOverlay.java:223–228

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/ProjectAwareOverlay.java:230–233

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/ProjectAwareOverlay.java:235–241

继承成员Inherited Members

继承自Methods inherited from OverlayFilesystem

upper, lower, of, getUpper, getLower

继承自Methods inherited from AbstractFilesystem

validatePath