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

LocalFilesystemSpec

public class LocalFilesystemSpec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:49–355

本地文件系统规格，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.filesystem.spec 包。核心成员包括 executeTimeoutSeconds、maxOutputBytes、env、inheritEnv、virtualMode、mode。

Specification for the local filesystem mode (with shell execution).

This spec produces a LocalFilesystemWithShell whose root is the agent workspace and whose shell runs directly on the host as sh -c <command>. Long-term memory (MEMORY.md, memory/) and session logs live on the same local disk.

Suitable for single-process deployments (personal assistants, CLI tools, local dev loops) where distributed sharing is not required and the agent is trusted to run host shell commands.

For distributed deployments where long-term memory must be shared across replicas, prefer RemoteFilesystemSpec (no shell) or a sandbox filesystem spec (shell via sandbox).

方法摘要Method Summary

方法Method	说明Description
`public` `LocalFilesystemSpec executeTimeoutSeconds(int seconds)`	设置默认命令执行超时 in 秒。 Sets the default command execution timeout in seconds.
`public` `LocalFilesystemSpec maxOutputBytes(int bytes)`	设置最大输出字节。 Sets the maximum number of output bytes captured from any single shell command.
`public` `LocalFilesystemSpec env(String name, String value)`	执行 `env` 方法。 Adds an environment variable that will be set for every shell command.
`public` `LocalFilesystemSpec inheritEnv(boolean inherit)`	设置该参数。 Controls whether the parent process environment is inherited by shell commands.
`public` `LocalFilesystemSpec virtualMode(boolean virtual)` deprecated	设置该参数。 Legacy: `true` maps to `LocalFsMode#SANDBOXED`, `false` to `LocalFsMode#UNRESTRICTED`.
`public` `LocalFilesystemSpec mode(LocalFsMode mode)`	设置模式。 Sets the path-resolution policy for the upper `LocalFilesystemWithShell`.
`public` `LocalFilesystemSpec isolationScope(IsolationScope scope)`	执行隔离范围相关操作。 Sets the isolation scope controlling how file paths are namespaced per user, session, or agent.
`public` `IsolationScope getIsolationScope()`	获取隔离范围。 Returns the configured isolation scope, or `null` to use the default.
`public` `LocalFilesystemSpec addRoot(Path root)`	添加根。 Adds an extra host directory the agent is allowed to access by absolute path under `LocalFsMode#ROOTED`.
`public` `LocalFilesystemSpec projectWritable(boolean writable)`	设置该参数。 Enables or disables project-writable mode.
`public boolean isProjectWritable()`	判断是否 `isProjectWritable`。 Returns whether project-writable mode is enabled.
`public` `LocalFilesystemSpec additionalRoots(Collection<Path> roots)`	设置该参数。 Replaces the list of extra host directories.
`public` `LocalFilesystemSpec project(Path project)`	设置该参数。 Sets the user project root used as the lower layer of the resulting `OverlayFilesystem`.
`public Path getProject()`	获取 `getProject`。 Project root explicitly configured, or `null` to fall back to `${user.dir}`.
`public` `LocalFsMode getMode()`	获取模式。 Currently configured path-resolution policy mode.
`public` `LocalFilesystemSpec sharedLocalWorkspace(boolean shared)`	设置共享本地工作区。 Enables or disables the shared workspace root for non-routed paths; see the field javadoc.
`public List<Path> getAdditionalRoots()`	获取 `getAdditionalRoots`。 Snapshot of configured extra roots.
`public` `AbstractFilesystem toFilesystem(Path workspace, NamespaceFactory localNamespaceFactory)`	执行到文件系统相关操作。 Performs the to filesystem operation.

方法详情Method Detail

executeTimeoutSeconds

public LocalFilesystemSpec executeTimeoutSeconds(int seconds)

设置默认命令执行超时 in 秒。

Sets the default command execution timeout in seconds.

参数Parameters

名称Name	类型Type	说明Description
`seconds`	int	秒（类型 `int`）。timeout (must be positive)

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:118–124

maxOutputBytes

public LocalFilesystemSpec maxOutputBytes(int bytes)

设置最大输出字节。

Sets the maximum number of output bytes captured from any single shell command.

参数Parameters

名称Name	类型Type	说明Description
`bytes`	int	字节（类型 `int`）。byte cap (must be positive)

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:132–138

env

public LocalFilesystemSpec env(String name, String value)

执行 env 方法。

Adds an environment variable that will be set for every shell command.

参数Parameters

名称Name	类型Type	说明Description
`name`	String	名称（类型 `String`）。variable name
`value`	String	值（类型 `String`）。variable value

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:147–153

inheritEnv

public LocalFilesystemSpec inheritEnv(boolean inherit)

设置该参数。

Controls whether the parent process environment is inherited by shell commands.

参数Parameters

名称Name	类型Type	说明Description
`inherit`	boolean	inherit（类型 `boolean`）。whether to inherit parent env

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:162–165

virtualMode

public LocalFilesystemSpec virtualMode(boolean virtual)

deprecated

设置该参数。

Legacy: true maps to LocalFsMode#SANDBOXED, false to LocalFsMode#UNRESTRICTED.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。use `#mode(LocalFsMode)` for the full three-way selection

参数Parameters

名称Name	类型Type	说明Description
`virtual`	boolean	virtual（类型 `boolean`）。whether to enable virtual mode

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:176–179

mode

public LocalFilesystemSpec mode(LocalFsMode mode)

设置模式。

Sets the path-resolution policy for the upper LocalFilesystemWithShell.

参数Parameters

名称Name	类型Type	说明Description
`mode`	LocalFsMode	模式（类型 `LocalFsMode`）。policy mode

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:188–194

isolationScope

public LocalFilesystemSpec isolationScope(IsolationScope scope)

执行隔离范围相关操作。

Sets the isolation scope controlling how file paths are namespaced per user, session, or agent.

参数Parameters

名称Name	类型Type	说明Description
`scope`	IsolationScope	范围（类型 `IsolationScope`）。isolation scope

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:204–207

getIsolationScope

public IsolationScope getIsolationScope()

获取隔离范围。

Returns the configured isolation scope, or null to use the default.

返回Returns IsolationScope

返回IsolationScope。Returns isolation scope.

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:210–212

addRoot

public LocalFilesystemSpec addRoot(Path root)

添加根。

Adds an extra host directory the agent is allowed to access by absolute path under LocalFsMode#ROOTED.

参数Parameters

名称Name	类型Type	说明Description
`root`	Path	根（类型 `Path`）。extra root to allow

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:221–226

projectWritable

public LocalFilesystemSpec projectWritable(boolean writable)

设置该参数。

Enables or disables project-writable mode.

参数Parameters

名称Name	类型Type	说明Description
`writable`	boolean	writable（类型 `boolean`）。whether non-workspace writes go to the project directory

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:235–238

isProjectWritable

public boolean isProjectWritable()

判断是否 isProjectWritable。

Returns whether project-writable mode is enabled.

返回Returns boolean

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

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:241–243

additionalRoots

public LocalFilesystemSpec additionalRoots(Collection<Path> roots)

设置该参数。

Replaces the list of extra host directories.

参数Parameters

名称Name	类型Type	说明Description
`roots`	Collection<Path>	roots（类型 `Collection`）。extra roots (`null` clears)

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:251–261

project

public LocalFilesystemSpec project(Path project)

设置该参数。

Sets the user project root used as the lower layer of the resulting OverlayFilesystem.

参数Parameters

名称Name	类型Type	说明Description
`project`	Path	project（类型 `Path`）。project root path

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:274–277

getProject

public Path getProject()

获取 getProject。

Project root explicitly configured, or null to fall back to ${user.dir}.

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:291–293

getMode

public LocalFsMode getMode()

获取模式。

Currently configured path-resolution policy mode.

返回Returns LocalFsMode

返回LocalFsMode。Returns local fs mode.

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:296–298

sharedLocalWorkspace

public LocalFilesystemSpec sharedLocalWorkspace(boolean shared)

设置共享本地工作区。

Enables or disables the shared workspace root for non-routed paths; see the field javadoc.

参数Parameters

名称Name	类型Type	说明Description
`shared`	boolean	共享（类型 `boolean`）。whether non-routed paths resolve against the shared workspace root

返回Returns LocalFilesystemSpec

返回LocalFilesystemSpec。this spec

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:308–311

getAdditionalRoots

public List<Path> getAdditionalRoots()

获取 getAdditionalRoots。

Snapshot of configured extra roots.

返回Returns List<Path>

返回列出。Returns list.

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:314–316

toFilesystem

public AbstractFilesystem toFilesystem(Path workspace, NamespaceFactory localNamespaceFactory)

执行到文件系统相关操作。

Performs the to filesystem operation.

参数Parameters

名称Name	类型Type	说明Description
`workspace`	Path	工作区（类型 `Path`）。The workspace.
`localNamespaceFactory`	NamespaceFactory	本地命名空间工厂（类型 `NamespaceFactory`）。The local namespace factory.

返回Returns AbstractFilesystem

返回AbstractFilesystem。Returns abstract filesystem.

源码Source io/agentscope/harness/agent/filesystem/spec/LocalFilesystemSpec.java:318–354