程序包 io.agentscope.core.tool.coding

类 ShellCommandTool

java.lang.Object
io.agentscope.core.tool.coding.ShellCommandTool
所有已实现的接口:
AgentTool
public class ShellCommandTool extends Object implements AgentTool
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)

另请参阅:

  • 构造器详细资料

    • ShellCommandTool

      public ShellCommandTool()

    • ShellCommandTool

      public ShellCommandTool(Set<String> allowedCommands)

    • ShellCommandTool

      public ShellCommandTool(Set<String> allowedCommands, Function<String,Boolean> approvalCallback)
      Constructor with command whitelist and approval callback.
      参数:
      allowedCommands - Set of allowed command executables
      approvalCallback - Callback function to request user approval

    • ShellCommandTool

      public ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String,Boolean> approvalCallback)
      Constructor with base directory, command whitelist, and approval callback.
      参数:
      baseDir - Base directory for command execution (null to use current directory)
      allowedCommands - Set of allowed command executables
      approvalCallback - Callback function to request user approval

    • ShellCommandTool

      public ShellCommandTool(Set<String> allowedCommands, Function<String,Boolean> approvalCallback, CommandValidator commandValidator)
      Constructor with command whitelist, approval callback, and custom validator.
      参数:
      allowedCommands - Set of allowed command executables (null to allow all commands)
      approvalCallback - Callback function to request user approval
      commandValidator - Custom command validator

    • ShellCommandTool

      public ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String,Boolean> approvalCallback, CommandValidator commandValidator)
      Constructor with base directory, command whitelist, approval callback, and custom validator.

      Uses UTF-8 as the default charset for decoding command output.

      参数:
      baseDir - Base directory for command execution (null to use current directory)
      allowedCommands - Set of allowed command executables (null to allow all commands)
      approvalCallback - Callback function to request user approval
      commandValidator - Custom command validator

    • ShellCommandTool

      public ShellCommandTool(String baseDir, Set<String> allowedCommands, Function<String,Boolean> approvalCallback, CommandValidator commandValidator, Charset charset)
      Full constructor with all configuration options including charset.

      This is the most comprehensive constructor that allows setting all available options. All other constructors delegate to this one with default values.

      参数:
      baseDir - Base directory for command execution (null to use current directory)
      allowedCommands - Set of allowed command executables (null to allow all commands)
      approvalCallback - Callback function to request user approval
      commandValidator - Custom command validator (null to use platform-specific default)
      charset - Charset used to decode command output streams (null to use UTF-8)

  • 方法详细资料

    • getAllowedCommands

      public Set<String> getAllowedCommands()
      Get an unmodifiable view of the allowed commands. The returned set is thread-safe for reading but cannot be modified directly. Use addAllowedCommand(String), removeAllowedCommand(String), or clearAllowedCommands() to modify the whitelist.
      返回:
      An unmodifiable view of the allowed command executables

    • addAllowedCommand

      public boolean addAllowedCommand(String command)
      Add a command to the whitelist in a thread-safe manner.
      参数:
      command - The command executable to add
      返回:
      true if the command was added, false if it was already present

    • removeAllowedCommand

      public boolean removeAllowedCommand(String command)
      Remove a command from the whitelist in a thread-safe manner.
      参数:
      command - The command executable to remove
      返回:
      true if the command was removed, false if it was not present

    • clearAllowedCommands

      public void clearAllowedCommands()
      Clear all commands from the whitelist in a thread-safe manner.

    • isCommandAllowed

      public boolean isCommandAllowed(String command)
      Check if a command is in the whitelist.
      参数:
      command - The command executable to check
      返回:
      true if the command is whitelisted

    • getApprovalCallback

      public Function<String,Boolean> getApprovalCallback()
      Get the approval callback function. Returns the callback that is used to request user approval for non-whitelisted commands.

      This method is useful for cloning ShellCommandTool instances with the same configuration.

      返回:
      The approval callback function, or null if not configured

    • getCommandValidator

      public CommandValidator getCommandValidator()
      Get the command validator. Returns the validator used for command security validation.

      This method is useful for cloning ShellCommandTool instances with the same configuration.

      返回:
      The command validator instance

    • getBaseDir

      public Path getBaseDir()
      Get the base directory for command execution. Returns the directory where commands will be executed.

      This method is useful for cloning ShellCommandTool instances with a different base directory.

      返回:
      The base directory path, or null if using current directory

    • getCharset

      public Charset getCharset()
      Get the charset used for decoding command output streams. Returns the charset used to decode stdout and stderr from executed commands.

      This method is useful for cloning ShellCommandTool instances with the same configuration, or for inspecting the current charset setting.

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

    • getName

      public String getName()
      从接口复制的说明: AgentTool
      Gets the name of the tool.

      The name should be unique within a toolkit and follow snake_case convention for compatibility with various LLM providers.

      指定者:
      getName 在接口中 AgentTool
      返回:
      The tool name (never null)

    • getDescription

      public String getDescription()
      从接口复制的说明: AgentTool
      Gets the description of the tool.

      The description should clearly explain what the tool does, when it should be used, and what kind of results it returns. This helps the LLM decide when to invoke the tool.

      指定者:
      getDescription 在接口中 AgentTool
      返回:
      The tool description (never null)

    • getParameters

      public Map<String,Object> getParameters()
      从接口复制的说明: AgentTool
      Gets the parameters schema for this tool in JSON Schema format.

      The schema defines the structure of the input parameters that this tool accepts. It should include:

      • type: "object"
      • properties: Map of parameter names to their schemas
      • required: List of required parameter names
      指定者:
      getParameters 在接口中 AgentTool
      返回:
      Map representing the JSON Schema for tool parameters (never null)

    • callAsync

      public reactor.core.publisher.Mono<ToolResultBlock> callAsync(ToolCallParam param)
      从接口复制的说明: AgentTool
      Execute the tool with the given parameters (asynchronous).

      This method accepts a ToolCallParam object containing all necessary context for tool execution, including:

      • toolUseBlock: Contains tool call ID and name for tracking
      • input: Input parameters for the tool
      • agent: The calling agent (may be null), provides access to agent context
      指定者:
      callAsync 在接口中 AgentTool
      参数:
      param - The tool call parameters
      返回:
      Mono containing ToolResultBlock

    • executeShellCommand

      public reactor.core.publisher.Mono<ToolResultBlock> executeShellCommand(String command, Integer timeout)
      Execute a shell command and return the return code, standard output, and standard error within tags.

      Uses the default charset configured for this tool instance.

      Security features:

      • Command whitelist validation - only whitelisted commands execute directly
      • Multiple command detection - prevents command chaining attacks (&, |, ;)
      • User approval callback - requests permission for non-whitelisted commands
      • Platform-specific validation - different rules for Windows and Unix/Linux/macOS
      参数:
      command - The shell command to execute
      timeout - The maximum time (in seconds) allowed for the command to run (default: 300)
      返回:
      A ToolResultBlock containing the formatted output with returncode, stdout, and stderr

    • executeShellCommand

      public reactor.core.publisher.Mono<ToolResultBlock> executeShellCommand(String command, Integer timeout, Charset overrideCharset)
      Execute a shell command and return the return code, standard output, and standard error within tags.

      Security features:

      • Command whitelist validation - only whitelisted commands execute directly
      • Multiple command detection - prevents command chaining attacks (&, |, ;)
      • User approval callback - requests permission for non-whitelisted commands
      • Platform-specific validation - different rules for Windows and Unix/Linux/macOS
      参数:
      command - The shell command to execute
      timeout - The maximum time (in seconds) allowed for the command to run (default: 300)
      overrideCharset - Optional charset to use for decoding output (null to use default)
      返回:
      A ToolResultBlock containing the formatted output with returncode, stdout, and stderr