程序包 io.agentscope.core.skill

类 SkillBox.CodeExecutionBuilder

java.lang.Object
io.agentscope.core.skill.SkillBox.CodeExecutionBuilder
封闭类:
SkillBox
public static class SkillBox.CodeExecutionBuilder extends Object
Fluent builder for configuring code execution with custom options.

This builder provides a flexible way to enable code execution capabilities with selective tool enabling and custom ShellCommandTool configuration.

Key features:

  • Selective tool enabling: choose which tools (shell/read/write) to enable
  • Custom ShellCommandTool: provide your own tool with custom security policies
  • WorkDir enforcement: all tools use the same working directory
  • Tool cloning: custom ShellCommandTool is cloned with workDir override

  • 方法详细资料

    • workDir

      public SkillBox.CodeExecutionBuilder workDir(String workDir)
      Set the working directory for code execution.

      All code execution tools (shell, read, write) will use this directory. If not set, a temporary directory will be created when files are uploaded.

      参数:
      workDir - The working directory path (null or empty for temporary directory)
      返回:
      This builder for chaining

    • uploadDir

      public SkillBox.CodeExecutionBuilder uploadDir(String uploadDir)
      Set the upload directory for skill files.

      If not set, the upload directory defaults to workDir/skills.

      参数:
      uploadDir - The upload directory path
      返回:
      This builder for chaining

    • fileFilter

      public SkillBox.CodeExecutionBuilder fileFilter(SkillFileFilter filter)
      Set a custom file filter for skill file uploads.
      参数:
      filter - The custom filter to use
      返回:
      This builder for chaining
      抛出:
      IllegalArgumentException - if filter is null

    • includeFolders

      public SkillBox.CodeExecutionBuilder includeFolders(Set<String> folders)
      Set the folders to include for uploads.
      参数:
      folders - Folder paths to include
      返回:
      This builder for chaining

    • includeExtensions

      public SkillBox.CodeExecutionBuilder includeExtensions(Set<String> extensions)
      Set the file extensions to include for uploads.
      参数:
      extensions - File extensions to include
      返回:
      This builder for chaining

    • withShell

      public SkillBox.CodeExecutionBuilder withShell()
      Enable shell command execution with default configuration.

      Default configuration:

      • Allowed commands: python, python3, node, nodejs
      • No approval callback
      • Platform-specific validator (Unix or Windows)
      返回:
      This builder for chaining

    • withShell

      public SkillBox.CodeExecutionBuilder withShell(ShellCommandTool shellTool)
      Enable shell command execution with a custom ShellCommandTool.

      The provided tool will be cloned with the following behavior:

      • allowedCommands: copied from the source tool
      • approvalCallback: copied from the source tool
      • commandValidator: copied from the source tool
      • baseDir: OVERRIDDEN with the builder's workDir

      This ensures all code execution tools use the same working directory while preserving your custom security policies.

      参数:
      shellTool - The custom ShellCommandTool to clone (must not be null)
      返回:
      This builder for chaining
      抛出:
      IllegalArgumentException - if shellTool is null

    • withRead

      public SkillBox.CodeExecutionBuilder withRead()
      Enable file reading capabilities.

      Registers ReadFileTool with the builder's workDir as base directory.

      返回:
      This builder for chaining

    • withWrite

      public SkillBox.CodeExecutionBuilder withWrite()
      Enable file writing capabilities.

      Registers WriteFileTool with the builder's workDir as base directory.

      返回:
      This builder for chaining

    • codeExecutionInstruction

      public SkillBox.CodeExecutionBuilder codeExecutionInstruction(String instruction)
      Set a custom code execution instruction for the system prompt.

      The instruction is appended to the skill system prompt when code execution is enabled. Use %s as a placeholder for the upload directory absolute path — every occurrence will be replaced with the actual path.

      Pass null or blank to use the default instruction.

      参数:
      instruction - Custom code execution instruction template
      返回:
      This builder for chaining

    • enable

      public void enable()
      Apply the configuration and enable code execution.

      This method:

      • Validates toolkit is bound
      • Removes existing code execution configuration if present
      • Creates the code execution tool group
      • Registers selected tools (shell, read, write)
      抛出:
      IllegalStateException - if toolkit is not bound