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

LocalFilesystemWithShell

public class LocalFilesystemWithShell extends LocalFilesystem implements AbstractSandboxFilesystem

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:50–505

本地文件系统使用 Shell，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.filesystem.local 包，继承自 LocalFilesystem，实现 AbstractSandboxFilesystem。核心成员包括 id、getShellCwd、execute、LocalFilesystemWithShell、DEFAULT_EXECUTE_TIMEOUT。

Filesystem with unrestricted local shell command execution.

This implementation extends LocalFilesystem to add shell command execution capabilities. Commands are executed directly on the host system without any sandboxing, process isolation, or security restrictions.

WARNING: This implementation grants agents BOTH direct filesystem access AND unrestricted shell execution on your local machine. Use with extreme caution and only in appropriate environments (local dev, CI/CD with proper secret management).

字段摘要Field Summary

字段Field	类型Type	说明Description
`DEFAULT_EXECUTE_TIMEOUT` staticfinal	int	默认执行超时字段。 Default timeout in seconds for shell command execution.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `LocalFilesystemWithShell(Path rootDir)`	创建抽象文件系统使用默认设置。 Creates an abstract filesystem with default settings.
`public` `LocalFilesystemWithShell(String rootDir)`	初始化 `LocalFilesystemWithShell` 实例。 Same as `#LocalFilesystemWithShell(Path)` with a path string; see `LocalFilesystem#LocalFilesystem(String)` for `null` / blank rules.
`public` `LocalFilesystemWithShell(Path rootDir, NamespaceFactory namespaceFactory)`	初始化 `LocalFilesystemWithShell` 实例。 Creates an abstract filesystem with default settings and namespace support.
`public` `LocalFilesystemWithShell(String rootDir, NamespaceFactory namespaceFactory)`	初始化 `LocalFilesystemWithShell` 实例。 Same as `#LocalFilesystemWithShell(Path, NamespaceFactory)` with a path string; see `LocalFilesystem#LocalFilesystem(String)` for `null` / blank rules.
`public` `LocalFilesystemWithShell(Path rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv)`	初始化 `LocalFilesystemWithShell` 实例。 Creates a abstract filesystem with full configuration.
`public` `LocalFilesystemWithShell(String rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv)`	初始化 `LocalFilesystemWithShell` 实例。 Same as `#LocalFilesystemWithShell(Path, boolean, int, int, Map, boolean)` with a path string; see `LocalFilesystem#LocalFilesystem(String)` for `null` / blank rules.
`public` `LocalFilesystemWithShell(Path rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory)`	初始化 `LocalFilesystemWithShell` 实例。 Creates a abstract filesystem with full configuration and namespace support.
`public` `LocalFilesystemWithShell(Path rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory, Path shellCwd)`	初始化 `LocalFilesystemWithShell` 实例。 Creates a abstract filesystem with full configuration, namespace support, and a custom shell working directory.
`public` `LocalFilesystemWithShell(Path rootDir, LocalFsMode mode, PathPolicy pathPolicy, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory, Path shellCwd)`	初始化 `LocalFilesystemWithShell` 实例。 Most-complete constructor: filesystem operations follow `mode` and `pathPolicy` (see `LocalFilesystem#LocalFilesystem(Path, LocalFsMode, PathPolicy, int, NamespaceFactory)`); shell commands run with `pwd = shellCwd` when set, otherwise the filesystem root.
`public` `LocalFilesystemWithShell(String rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory)`	初始化 `LocalFilesystemWithShell` 实例。 Same as `#LocalFilesystemWithShell(Path, boolean, int, int, Map, boolean, NamespaceFactory)` with a path string; see `LocalFilesystem#LocalFilesystem(String)` for `null` / blank rules.

方法摘要Method Summary

方法Method	说明Description
`public String id()`	返回标识。 Returns the id.
`public Path getShellCwd()`	获取 `getShellCwd`。 Returns the working directory configured for shell `execute()` calls, or `null` when shell falls back to the filesystem root (with namespace prefix).
`public` `ExecuteResponse execute(RuntimeContext runtimeContext, String command, Integer timeoutSeconds)`	执行执行相关操作。 Performs the execute operation.

字段详情Field Detail

DEFAULT_EXECUTE_TIMEOUT

public static final int DEFAULT_EXECUTE_TIMEOUT

staticfinal

默认执行超时字段。声明为 public static final int DEFAULT_EXECUTE_TIMEOUT。

Default timeout in seconds for shell command execution.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:55

构造器详情Constructor Detail

LocalFilesystemWithShell

public LocalFilesystemWithShell(Path rootDir)

创建抽象文件系统使用默认设置。

Creates an abstract filesystem with default settings.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。working directory for both filesystem and shell operations

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:85–87

LocalFilesystemWithShell

public LocalFilesystemWithShell(String rootDir)

初始化 LocalFilesystemWithShell 实例。

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

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	String	根目录（类型 `String`）。The root dir.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:93–102

LocalFilesystemWithShell

public LocalFilesystemWithShell(Path rootDir, NamespaceFactory namespaceFactory)

初始化 LocalFilesystemWithShell 实例。

Creates an abstract filesystem with default settings and namespace support.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。working directory for both filesystem and shell operations
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。optional namespace factory for path scoping (`null` for none)

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:110–112

LocalFilesystemWithShell

public LocalFilesystemWithShell(String rootDir, NamespaceFactory namespaceFactory)

初始化 LocalFilesystemWithShell 实例。

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

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	String	根目录（类型 `String`）。The root dir.
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。The namespace factory.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:118–127

LocalFilesystemWithShell

public LocalFilesystemWithShell(Path rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv)

初始化 LocalFilesystemWithShell 实例。

Creates a abstract filesystem with full configuration.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。working directory for both filesystem and shell operations
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。enable virtual path mode for filesystem operations
`timeout`	int	超时时间（类型 `int`）。default maximum time in seconds for shell command execution
`maxOutputBytes`	int	最大输出字节（类型 `int`）。maximum number of bytes to capture from command output
`env`	Map<String, String>	env（类型 `Map`）。environment variables for shell commands (`null` for empty)
`inheritEnv`	boolean	inherit Env（类型 `boolean`）。whether to inherit the parent process's environment variables

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:139–147

LocalFilesystemWithShell

public LocalFilesystemWithShell(String rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv)

初始化 LocalFilesystemWithShell 实例。

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

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	String	根目录（类型 `String`）。The root dir.
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。The virtual mode.
`timeout`	int	超时时间（类型 `int`）。The timeout.
`maxOutputBytes`	int	最大输出字节（类型 `int`）。The max output bytes.
`env`	Map<String, String>	env（类型 `Map`）。The env.
`inheritEnv`	boolean	inherit Env（类型 `boolean`）。The inherit env.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:153–168

LocalFilesystemWithShell

public LocalFilesystemWithShell(Path rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory)

初始化 LocalFilesystemWithShell 实例。

Creates a abstract filesystem with full configuration and namespace support.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。working directory for both filesystem and shell operations
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。enable virtual path mode for filesystem operations
`timeout`	int	超时时间（类型 `int`）。default maximum time in seconds for shell command execution
`maxOutputBytes`	int	最大输出字节（类型 `int`）。maximum number of bytes to capture from command output
`env`	Map<String, String>	env（类型 `Map`）。environment variables for shell commands (`null` for empty)
`inheritEnv`	boolean	inherit Env（类型 `boolean`）。whether to inherit the parent process's environment variables
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。optional namespace factory for path scoping (`null` for none)

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:181–198

LocalFilesystemWithShell

public LocalFilesystemWithShell(Path rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory, Path shellCwd)

初始化 LocalFilesystemWithShell 实例。

Creates a abstract filesystem with full configuration, namespace support, and a custom shell working directory.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。working directory for filesystem operations (read/write/edit/glob/...)
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。enable virtual path mode for filesystem operations
`timeout`	int	超时时间（类型 `int`）。default maximum time in seconds for shell command execution
`maxOutputBytes`	int	最大输出字节（类型 `int`）。maximum number of bytes to capture from command output
`env`	Map<String, String>	env（类型 `Map`）。environment variables for shell commands (`null` for empty)
`inheritEnv`	boolean	inherit Env（类型 `boolean`）。whether to inherit the parent process's environment variables
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。optional namespace factory for path scoping (`null` for none)
`shellCwd`	Path	shell Cwd（类型 `Path`）。working directory for shell command execution; when `null`, falls back to `rootDir` (with namespace prefix when configured)

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:214–233

LocalFilesystemWithShell

public LocalFilesystemWithShell(Path rootDir, LocalFsMode mode, PathPolicy pathPolicy, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory, Path shellCwd)

初始化 LocalFilesystemWithShell 实例。

Most-complete constructor: filesystem operations follow mode and pathPolicy (see LocalFilesystem#LocalFilesystem(Path, LocalFsMode, PathPolicy, int, NamespaceFactory)); shell commands run with pwd = shellCwd when set, otherwise the filesystem root.

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	Path	根目录（类型 `Path`）。filesystem root for relative-path operations
`mode`	LocalFsMode	模式（类型 `LocalFsMode`）。path-resolution policy (`null` treated as `LocalFsMode#UNRESTRICTED`)
`pathPolicy`	PathPolicy	路径策略（类型 `PathPolicy`）。allow-list for `LocalFsMode#ROOTED`; ignored otherwise
`timeout`	int	超时时间（类型 `int`）。default shell timeout (seconds, must be positive)
`maxOutputBytes`	int	最大输出字节（类型 `int`）。byte cap for captured shell output
`env`	Map<String, String>	env（类型 `Map`）。environment variables for shell commands (`null` for empty)
`inheritEnv`	boolean	inherit Env（类型 `boolean`）。whether to inherit the parent process environment
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。optional per-user/session namespace factory
`shellCwd`	Path	shell Cwd（类型 `Path`）。shell `pwd`; `null` falls back to `rootDir` (with namespace prefix when configured)

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:251–281

LocalFilesystemWithShell

public LocalFilesystemWithShell(String rootDir, boolean virtualMode, int timeout, int maxOutputBytes, Map<String, String> env, boolean inheritEnv, NamespaceFactory namespaceFactory)

初始化 LocalFilesystemWithShell 实例。

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

参数Parameters

名称Name	类型Type	说明Description
`rootDir`	String	根目录（类型 `String`）。The root dir.
`virtualMode`	boolean	virtual 模式（类型 `boolean`）。The virtual mode.
`timeout`	int	超时时间（类型 `int`）。The timeout.
`maxOutputBytes`	int	最大输出字节（类型 `int`）。The max output bytes.
`env`	Map<String, String>	env（类型 `Map`）。The env.
`inheritEnv`	boolean	inherit Env（类型 `boolean`）。The inherit env.
`namespaceFactory`	NamespaceFactory	命名空间工厂（类型 `NamespaceFactory`）。The namespace factory.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:288–304

方法详情Method Detail

id

public String id()

返回标识。

Returns the id.

返回Returns String

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

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:306–309

getShellCwd

public Path getShellCwd()

获取 getShellCwd。

Returns the working directory configured for shell execute() calls, or null when shell falls back to the filesystem root (with namespace prefix).

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/harness/agent/filesystem/local/LocalFilesystemWithShell.java:316–318

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/local/LocalFilesystemWithShell.java:320–433

继承成员Inherited Members

继承自Methods inherited from LocalFilesystem

getCwd, getMode, getPathPolicy, ls, read, write, edit, grep, glob, uploadFiles, downloadFiles, delete, move, exists, getNamespaceFactory, resolvePath, toVirtualPath

继承自Methods inherited from AbstractFilesystem

validatePath