Documentation
¶
Overview ¶
checkpointer.go is intentionally empty. The Checkpointer interface, MemoryCheckpointer, ThreadManager, and related types were removed because they had zero external consumers. Use agent.CheckpointStore or workflow.CheckpointStore instead.
包 execution 提供安全隔离的代码沙箱执行能力。
概述 ¶
本包用于解决"智能体生成的代码如何在受控环境中安全执行"的问题。 通过 Docker 容器或本地进程两种后端，在资源限制、网络隔离与 代码验证的多重防护下执行用户代码，并收集执行结果。
核心接口 ¶
- ExecutionBackend：执行后端抽象，定义 Execute / Cleanup / Name 三项操作，由 DockerBackend 和 ProcessBackend 分别实现。
- SandboxExecutor：沙箱执行器，封装后端调用、请求校验、 超时控制与输出截断，并维护执行统计。
- CodeValidator：执行前代码安全检查，按语言匹配危险模式黑名单。
- SandboxTool：将沙箱执行器包装为 JSON 输入/输出的智能体工具。
主要能力 ¶
- 多语言支持：Python、JavaScript、TypeScript、Go、Rust、Bash。
- Docker 隔离：内存/CPU 限制、网络禁用、只读文件系统、权限降级。
- 进程后端：轻量级本地执行，需显式启用，适用于受信环境。
- 代码验证：针对各语言的危险 API 模式进行预执行拦截。
- 资源治理：超时自动终止、输出大小截断、容器自动清理。
- 执行统计：跟踪总执行数、成功/失败/超时计数与累计耗时。
与 agent 包协同 ¶
execution 作为智能体工具链的底层执行层：agent 通过 SandboxTool 将代码执行请求提交到沙箱，获取标准化的 ExecutionResult 后 继续后续推理，确保代码执行不会影响宿主环境安全。
Index ¶
- func EnsureImages(ctx context.Context, languages []Language, logger *zap.Logger) error
- func PullImage(ctx context.Context, image string, logger *zap.Logger) error
- type CodeValidator
- type DockerBackend
- type DockerBackendConfig
- type ExecutionBackend
- type ExecutionMode
- type ExecutionRequest
- type ExecutionResult
- type ExecutorStats
- type Language
- type ProcessBackend
- type ProcessBackendConfig
- type RealDockerBackend
- type RealProcessBackend
- type SandboxConfig
- type SandboxExecutor
- type SandboxTool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureImages ¶
保证图像为沙盒拉出所有所需的图像 。
Types ¶
type CodeValidator ¶
type CodeValidator struct {
// contains filtered or unexported fields
}
代码Validator执行前验证代码.
type DockerBackend ¶
type DockerBackend struct {
// contains filtered or unexported fields
}
DockerBackend使用Docker执行Backend.
func NewDockerBackend ¶
func NewDockerBackend(logger *zap.Logger) *DockerBackend
NewDockerBackend创建了多克执行后端.
func NewDockerBackendWithConfig ¶
func NewDockerBackendWithConfig(logger *zap.Logger, cfg DockerBackendConfig) *DockerBackend
NewDockerBackendWithConfig创建了自定义配置的多克后端.
func (*DockerBackend) Cleanup ¶
func (d *DockerBackend) Cleanup() error
func (*DockerBackend) Execute ¶
func (d *DockerBackend) Execute(ctx context.Context, req *ExecutionRequest, config SandboxConfig) (*ExecutionResult, error)
func (*DockerBackend) Name ¶
func (d *DockerBackend) Name() string
type DockerBackendConfig ¶
type DockerBackendConfig struct {
ContainerPrefix string // Prefix for container names
CleanupOnExit bool // Remove containers after execution
CustomImages map[Language]string // Override default images
}
DockerBackendConfig配置了多克后端.
type ExecutionBackend ¶
type ExecutionBackend interface {
Execute(ctx context.Context, req *ExecutionRequest, config SandboxConfig) (*ExecutionResult, error)
Cleanup() error
Name() string
}
ExecutiveBackend定义执行后端的接口.
type ExecutionMode ¶
type ExecutionMode string
ExecutiveMode定义了沙盒执行模式.
const ( ModeDocker ExecutionMode = "docker" ModeWASM ExecutionMode = "wasm" ModeNative ExecutionMode = "native" // For trusted environments only )
type ExecutionRequest ¶
type ExecutionRequest struct {
ID string `json:"id"`
Language Language `json:"language"`
Code string `json:"code"`
Stdin string `json:"stdin,omitempty"`
Args []string `json:"args,omitempty"`
EnvVars map[string]string `json:"env_vars,omitempty"`
Files map[string]string `json:"files,omitempty"` // filename -> content
Timeout time.Duration `json:"timeout,omitempty"`
}
执行请求代表代码执行请求.
type ExecutionResult ¶
type ExecutionResult struct {
ID string `json:"id"`
Success bool `json:"success"`
ExitCode int `json:"exit_code"`
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
Error string `json:"error,omitempty"`
Duration time.Duration `json:"duration"`
MemoryUsed int64 `json:"memory_used_bytes,omitempty"`
Truncated bool `json:"truncated,omitempty"`
}
执行Result代表代码执行的结果.
type ExecutorStats ¶
type ExecutorStats struct {
TotalExecutions int64 `json:"total_executions"`
SuccessExecutions int64 `json:"success_executions"`
FailedExecutions int64 `json:"failed_executions"`
TimeoutExecutions int64 `json:"timeout_executions"`
TotalDuration time.Duration `json:"total_duration"`
}
执行者Stats跟踪执行统计.
type ProcessBackend ¶
type ProcessBackend struct {
// contains filtered or unexported fields
}
processBackend使用本地进程执行 ElectionBackend. 警告: 不如多克安全 - 只在信任的环境中使用.
func NewProcessBackend ¶
func NewProcessBackend(logger *zap.Logger) *ProcessBackend
NewProcessBackend创建基于进程的执行后端.
func NewProcessBackendWithConfig ¶
func NewProcessBackendWithConfig(logger *zap.Logger, cfg ProcessBackendConfig) *ProcessBackend
NewProcessBackendWithConfig创建了自定义配置的流程后端.
func (*ProcessBackend) Cleanup ¶
func (p *ProcessBackend) Cleanup() error
func (*ProcessBackend) Execute ¶
func (p *ProcessBackend) Execute(ctx context.Context, req *ExecutionRequest, config SandboxConfig) (*ExecutionResult, error)
func (*ProcessBackend) Name ¶
func (p *ProcessBackend) Name() string
type ProcessBackendConfig ¶
type ProcessBackendConfig struct {
WorkDir string // Working directory for execution
Enabled bool // Must explicitly enable (security)
CustomInterpreters map[Language]string
}
processBackendConfig 配置进程后端.
type RealDockerBackend ¶
type RealDockerBackend struct {
*DockerBackend
}
RealDockerBackend使用实际的多克CLI执行ExecutiveBackend.
func NewRealDockerBackend ¶
func NewRealDockerBackend(logger *zap.Logger) *RealDockerBackend
NewReal DockerBackend创建了一个实际执行代码的Docker后端.
func (*RealDockerBackend) Execute ¶
func (d *RealDockerBackend) Execute(ctx context.Context, req *ExecutionRequest, config SandboxConfig) (*ExecutionResult, error)
执行在真正的多克容器中运行代码 。
type RealProcessBackend ¶
type RealProcessBackend struct {
*ProcessBackend
// contains filtered or unexported fields
}
RealProcessBackend 执行 ExecutiveBackend 使用实际的 os/ exec.
func NewRealProcessBackend ¶
func NewRealProcessBackend(logger *zap.Logger, enabled bool) *RealProcessBackend
New Real ProcessBackend 创建一个进程后端,可以实际执行代码. 警告(Warning):只在可信任的环境中使用,在OS级别有适当的沙箱.
func (*RealProcessBackend) Execute ¶
func (p *RealProcessBackend) Execute(ctx context.Context, req *ExecutionRequest, config SandboxConfig) (*ExecutionResult, error)
使用本地进程执行代码 。
type SandboxConfig ¶
type SandboxConfig struct {
Mode ExecutionMode `json:"mode"`
Timeout time.Duration `json:"timeout"`
MaxMemoryMB int `json:"max_memory_mb"`
MaxCPUPercent int `json:"max_cpu_percent"`
NetworkEnabled bool `json:"network_enabled"`
AllowedHosts []string `json:"allowed_hosts,omitempty"`
MountPaths map[string]string `json:"mount_paths,omitempty"` // host:container
EnvVars map[string]string `json:"env_vars,omitempty"`
MaxOutputBytes int `json:"max_output_bytes"`
AllowedLanguages []Language `json:"allowed_languages"`
}
Sandbox Config 配置了 sandbox 执行器 。
type SandboxExecutor ¶
type SandboxExecutor struct {
// contains filtered or unexported fields
}
SandboxExecutor在孤立的环境中执行代码.
func NewSandboxExecutor ¶
func NewSandboxExecutor(config SandboxConfig, backend ExecutionBackend, logger *zap.Logger) *SandboxExecutor
NewSandboxExecutor创建了新的沙盒执行器.
func (*SandboxExecutor) Execute ¶
func (s *SandboxExecutor) Execute(ctx context.Context, req *ExecutionRequest) (*ExecutionResult, error)
执行在沙盒中运行代码.
type SandboxTool ¶
type SandboxTool struct {
// contains filtered or unexported fields
}
Sandbox Tool将 sandbox 执行器包成代理工具.
func NewSandboxTool ¶
func NewSandboxTool(executor *SandboxExecutor, logger *zap.Logger) *SandboxTool
NewSandbox Tool创建了沙盒工具.
func (*SandboxTool) Execute ¶
func (t *SandboxTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
执行通过沙盒执行代码.
Source Files
Click to show internal directories.
Click to hide internal directories.