类class io.agentscope.core.tool.coding 2.x

ShellCommandTool

public class ShellCommandTool implements AgentTool

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:73–799

Shell 命令工具，封装可被智能体调用的能力。位于 io.agentscope.core.tool.coding 包，实现 AgentTool。核心成员包括 getAllowedCommands、addAllowedCommand、removeAllowedCommand、clearAllowedCommands、isCommandAllowed、getApprovalCallback。

Tool for executing shell commands with security validation.

Features: command whitelist, user approval callback, multiple command detection, timeout support (default 300s), platform-specific validation, customizable charset for decoding command output (default UTF-8).

Charset Support: The tool supports custom charset configuration for decoding command output streams (stdout/stderr). This is particularly useful when working with systems that use non-UTF-8 encodings (e.g., GBK, GB2312 for Chinese Windows systems). The charset can be configured at tool construction time or overridden per command execution.

Security Warning: new ShellCommandTool() allows arbitrary command execution. For production, ALWAYS use whitelist: new ShellCommandTool(allowedCommands) or with callback: new ShellCommandTool(allowedCommands, approvalCallback)

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `ShellCommandTool()`	初始化 `ShellCommandTool` 实例。 Creates a new instance.
`public` `ShellCommandTool(Set<String> allowedCommands)`	初始化 `ShellCommandTool` 实例。 Creates a new instance.
`public` `ShellCommandTool(Set<String> allowedCommands, Function<String, Boolean> approvalCallback)`	初始化 `ShellCommandTool` 实例。 Constructor with command whitelist and approval callback.
`public` `ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String, Boolean> approvalCallback)`	初始化 `ShellCommandTool` 实例。 Constructor with base directory, command whitelist, and approval callback.
`public` `ShellCommandTool(Set<String> allowedCommands, Function<String, Boolean> approvalCallback, CommandValidator commandValidator)`	初始化 `ShellCommandTool` 实例。 Constructor with command whitelist, approval callback, and custom validator.
`public` `ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String, Boolean> approvalCallback, CommandValidator commandValidator)`	初始化 `ShellCommandTool` 实例。 Constructor with base directory, command whitelist, approval callback, and custom validator.
`public` `ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String, Boolean> approvalCallback, CommandValidator commandValidator, Charset charset)`	初始化 `ShellCommandTool` 实例。 Full constructor with all configuration options including charset.

方法摘要Method Summary

方法Method	说明Description
`public Set<String> getAllowedCommands()`	获取 `getAllowedCommands`。 Get an unmodifiable view of the allowed commands.
`public boolean addAllowedCommand(String command)`	添加已允许命令。 Add a command to the whitelist in a thread-safe manner.
`public boolean removeAllowedCommand(String command)`	移除已允许命令。 Remove a command from the whitelist in a thread-safe manner.
`public void clearAllowedCommands()`	清空 `clearAllowedCommands`。 Clear all commands from the whitelist in a thread-safe manner.
`public boolean isCommandAllowed(String command)`	判断是否命令已允许。 Check if a command is in the whitelist.
`public Function<String, Boolean> getApprovalCallback()`	获取 `getApprovalCallback`。 Get the approval callback function.
`public` `CommandValidator getCommandValidator()`	获取命令校验器。 Get the command validator.
`public Path getBaseDir()`	获取基类目录用于命令执行。 Get the base directory for command execution.
`public Charset getCharset()`	获取 `getCharset`。 Get the charset used for decoding command output streams.
`public String getName()`	获取名称。 Returns the name.
`public String getDescription()`	获取 `getDescription`。 Returns the description.
`public Map<String, Object> getParameters()`	获取参数。 Returns the parameters.
`public Mono<ToolResultBlock> callAsync(ToolCallParam param)`	调用异步。 Calls the async.
`public Mono<ToolResultBlock> executeShellCommand(String command, Integer timeout)`	执行 `executeShellCommand`。 Execute a shell command and return the return code, standard output, and standard error within tags.
`public Mono<ToolResultBlock> executeShellCommand(String command, Integer timeout, Charset overrideCharset)`	执行 `executeShellCommand`。 Execute a shell command and return the return code, standard output, and standard error within tags.

构造器详情Constructor Detail

ShellCommandTool

public ShellCommandTool()

初始化 ShellCommandTool 实例。

Creates a new instance.

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:111–113

ShellCommandTool

public ShellCommandTool(Set<String> allowedCommands)

初始化 ShellCommandTool 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`allowedCommands`	Set<String>	已允许 Commands（类型 `Set`）。The allowed commands.

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:115–117

ShellCommandTool

public ShellCommandTool(Set<String> allowedCommands, Function<String, Boolean> approvalCallback)

初始化 ShellCommandTool 实例。

Constructor with command whitelist and approval callback.

参数Parameters

名称Name	类型Type	说明Description
`allowedCommands`	Set<String>	已允许 Commands（类型 `Set`）。Set of allowed command executables
`approvalCallback`	Function<String, Boolean>	approval 回调（类型 `Function`）。Callback function to request user approval

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:125–133

ShellCommandTool

public ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String, Boolean> approvalCallback)

初始化 ShellCommandTool 实例。

Constructor with base directory, command whitelist, and approval callback.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	String	基类目录（类型 `String`）。Base directory for command execution (null to use current directory)
`allowedCommands`	Set<String>	已允许 Commands（类型 `Set`）。Set of allowed command executables
`approvalCallback`	Function<String, Boolean>	approval 回调（类型 `Function`）。Callback function to request user approval

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:142–152

ShellCommandTool

public ShellCommandTool(Set<String> allowedCommands, Function<String, Boolean> approvalCallback, CommandValidator commandValidator)

初始化 ShellCommandTool 实例。

Constructor with command whitelist, approval callback, and custom validator.

参数Parameters

名称Name	类型Type	说明Description
`allowedCommands`	Set<String>	已允许 Commands（类型 `Set`）。Set of allowed command executables (null to allow all commands)
`approvalCallback`	Function<String, Boolean>	approval 回调（类型 `Function`）。Callback function to request user approval
`commandValidator`	CommandValidator	命令校验器（类型 `CommandValidator`）。Custom command validator

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:161–166

ShellCommandTool

public ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String, Boolean> approvalCallback, CommandValidator commandValidator)

初始化 ShellCommandTool 实例。

Constructor with base directory, command whitelist, approval callback, and custom validator.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	String	基类目录（类型 `String`）。Base directory for command execution (null to use current directory)
`allowedCommands`	Set<String>	已允许 Commands（类型 `Set`）。Set of allowed command executables (null to allow all commands)
`approvalCallback`	Function<String, Boolean>	approval 回调（类型 `Function`）。Callback function to request user approval
`commandValidator`	CommandValidator	命令校验器（类型 `CommandValidator`）。Custom command validator

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:178–184

ShellCommandTool

public ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String, Boolean> approvalCallback, CommandValidator commandValidator, Charset charset)

初始化 ShellCommandTool 实例。

Full constructor with all configuration options including charset.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	String	基类目录（类型 `String`）。Base directory for command execution (null to use current directory)
`allowedCommands`	Set<String>	已允许 Commands（类型 `Set`）。Set of allowed command executables (null to allow all commands)
`approvalCallback`	Function<String, Boolean>	approval 回调（类型 `Function`）。Callback function to request user approval
`commandValidator`	CommandValidator	命令校验器（类型 `CommandValidator`）。Custom command validator (null to use platform-specific default)
`charset`	Charset	charset（类型 `Charset`）。Charset used to decode command output streams (null to use UTF-8)

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:198–222

方法详情Method Detail

getAllowedCommands

public Set<String> getAllowedCommands()

获取 getAllowedCommands。

Get an unmodifiable view of the allowed commands.

返回Returns Set<String>

返回设置。An unmodifiable view of the allowed command executables

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:248–250

addAllowedCommand

public boolean addAllowedCommand(String command)

添加已允许命令。

Add a command to the whitelist in a thread-safe manner.

参数Parameters

名称Name	类型Type	说明Description
`command`	String	命令（类型 `String`）。The command executable to add

返回Returns boolean

返回布尔值，表示判断结果。true if the command was added, false if it was already present

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:258–267

removeAllowedCommand

public boolean removeAllowedCommand(String command)

移除已允许命令。

Remove a command from the whitelist in a thread-safe manner.

参数Parameters

名称Name	类型Type	说明Description
`command`	String	命令（类型 `String`）。The command executable to remove

返回Returns boolean

返回布尔值，表示判断结果。true if the command was removed, false if it was not present

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:275–281

clearAllowedCommands

public void clearAllowedCommands()

清空 clearAllowedCommands。

Clear all commands from the whitelist in a thread-safe manner.

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:286–289

isCommandAllowed

public boolean isCommandAllowed(String command)

判断是否命令已允许。

Check if a command is in the whitelist.

参数Parameters

名称Name	类型Type	说明Description
`command`	String	命令（类型 `String`）。The command executable to check

返回Returns boolean

返回布尔值，表示判断结果。true if the command is whitelisted

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:297–299

getApprovalCallback

public Function<String, Boolean> getApprovalCallback()

获取 getApprovalCallback。

Get the approval callback function.

返回Returns Function<String, Boolean>

返回函数。The approval callback function, or null if not configured

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:309–311

getCommandValidator

public CommandValidator getCommandValidator()

获取命令校验器。

Get the command validator.

返回Returns CommandValidator

命令校验器实例。The command validator instance

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:321–323

getBaseDir

public Path getBaseDir()

获取基类目录用于命令执行。

Get the base directory for command execution.

返回Returns Path

返回路径。The base directory path, or null if using current directory

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:333–335

getCharset

public Charset getCharset()

获取 getCharset。

Get the charset used for decoding command output streams.

返回Returns Charset

返回Charset。The charset used for decoding command output (never null)

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:346–348

getName

public String getName()

获取名称。

Returns the name.

返回Returns String

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

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:352–355

getDescription

public String getDescription()

获取 getDescription。

Returns the description.

返回Returns String

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

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:357–390

getParameters

public Map<String, Object> getParameters()

获取参数。

Returns the parameters.

返回Returns Map<String, Object>

返回映射。Returns map.

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:392–422

callAsync

public Mono<ToolResultBlock> callAsync(ToolCallParam param)

调用异步。

Calls the async.

参数Parameters

名称Name	类型Type	说明Description
`param`	ToolCallParam	参数（类型 `ToolCallParam`）。The param.

返回Returns Mono<ToolResultBlock>

返回Mono。Returns mono.

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:424–444

executeShellCommand

public Mono<ToolResultBlock> executeShellCommand(String command, Integer timeout)

执行 executeShellCommand。

Execute a shell command and return the return code, standard output, and standard error within tags.

参数Parameters

名称Name	类型Type	说明Description
`command`	String	命令（类型 `String`）。The shell command to execute
`timeout`	Integer	超时时间（类型 `Integer`）。The maximum time (in seconds) allowed for the command to run (default: 300)

返回Returns Mono<ToolResultBlock>

返回Mono。A ToolResultBlock containing the formatted output with returncode, stdout, and stderr

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:466–468

executeShellCommand

public Mono<ToolResultBlock> executeShellCommand(String command, Integer timeout, Charset overrideCharset)

执行 executeShellCommand。

Execute a shell command and return the return code, standard output, and standard error within tags.

参数Parameters

名称Name	类型Type	说明Description
`command`	String	命令（类型 `String`）。The shell command to execute
`timeout`	Integer	超时时间（类型 `Integer`）。The maximum time (in seconds) allowed for the command to run (default: 300)
`overrideCharset`	Charset	override Charset（类型 `Charset`）。Optional charset to use for decoding output (null to use default)

返回Returns Mono<ToolResultBlock>

返回Mono。A ToolResultBlock containing the formatted output with returncode, stdout, and stderr

源码Source io/agentscope/core/tool/coding/ShellCommandTool.java:487–542

继承成员Inherited Members

继承自Methods inherited from AgentTool

getStrict, getOutputSchema, isReadOnly, isReturnDirect