middleware

type BaseToolMiddleware ¶

type BaseToolMiddleware struct {
	// contains filtered or unexported fields
}

BaseToolMiddleware 提供中间件接口的默认实现。

所有方法都是空操作（no-op），子类可以选择性重写需要的方法。 这遵循了 Go 的组合模式，避免强制实现所有接口方法。

使用示例:

type LoggingMiddleware struct {
    *BaseToolMiddleware
    logger Logger
}

func NewLoggingMiddleware(logger Logger) *LoggingMiddleware {
    return &LoggingMiddleware{
        BaseToolMiddleware: NewBaseToolMiddleware("logging"),
        logger: logger,
    }
}

// 只需重写需要的方法
func (m *LoggingMiddleware) OnBeforeInvoke(ctx context.Context, tool interfaces.Tool, input *interfaces.ToolInput) (*interfaces.ToolInput, error) {
    m.logger.Info("Tool invoked", "tool", tool.Name())
    return input, nil
}

func NewBaseToolMiddleware(name string) *BaseToolMiddleware

func (m *BaseToolMiddleware) Name() string

func (m *BaseToolMiddleware) OnAfterInvoke(ctx context.Context, tool interfaces.Tool, output *interfaces.ToolOutput) (*interfaces.ToolOutput, error)

func (m *BaseToolMiddleware) OnBeforeInvoke(ctx context.Context, tool interfaces.Tool, input *interfaces.ToolInput) (*interfaces.ToolInput, error)

func (m *BaseToolMiddleware) OnError(ctx context.Context, tool interfaces.Tool, err error) error

type CachingConfig ¶

type CachingConfig struct {
	Cache   cache.Cache
	TTL     time.Duration
	KeyFunc func(string, map[string]interface{}) string
	Logger  loggercore.Logger
}

CachingConfig 缓存中间件配置

type CachingMiddleware ¶

type CachingMiddleware struct {
	// contains filtered or unexported fields
}

CachingMiddleware 提供工具调用结果的缓存功能（使用函数式实现）。

它通过缓存成功的工具执行结果来提高性能，避免重复计算。 使用可配置的 TTL（生存时间）和缓存键生成函数。

使用示例:

cachingMW := Caching(
    WithCache(myCache),
    WithTTL(10 * time.Minute),
)
wrappedTool := tools.WithMiddleware(myTool, cachingMW)

func NewCachingMiddleware(opts ...CachingOption) *CachingMiddleware

func (m *CachingMiddleware) GetStats() (hits, misses int64)

func (m *CachingMiddleware) Wrap(tool interfaces.Tool, next ToolInvoker) ToolInvoker

type CachingOption ¶

type CachingOption func(*CachingConfig)

CachingOption 缓存中间件选项

func WithCache(c cache.Cache) CachingOption

func WithCacheKeyFunc(f func(string, map[string]interface{}) string) CachingOption

func WithCacheLogger(logger loggercore.Logger) CachingOption

func WithTTL(ttl time.Duration) CachingOption

type LoggingMiddleware ¶

type LoggingMiddleware struct {
	*BaseToolMiddleware
	// contains filtered or unexported fields
}

LoggingMiddleware 提供工具调用的日志记录功能。

它记录：

• 工具名称和描述
• 输入参数（可配置是否记录）
• 输出结果（可配置是否记录）
• 执行耗时
• 错误信息

使用示例:

logger := core.GetLogger("tools")
loggingMW := NewLoggingMiddleware(
    WithLogger(logger),
    WithoutInputLogging(),  // 不记录输入（保护敏感数据）
)
wrappedTool := tools.WithMiddleware(myTool, loggingMW)

func NewLoggingMiddleware(opts ...LoggingOption) *LoggingMiddleware

func (m *LoggingMiddleware) OnAfterInvoke(ctx context.Context, tool interfaces.Tool, output *interfaces.ToolOutput) (*interfaces.ToolOutput, error)

func (m *LoggingMiddleware) OnBeforeInvoke(ctx context.Context, tool interfaces.Tool, input *interfaces.ToolInput) (*interfaces.ToolInput, error)

func (m *LoggingMiddleware) OnError(ctx context.Context, tool interfaces.Tool, err error) error

type LoggingOption ¶

type LoggingOption func(*LoggingMiddleware)

LoggingOption 定义日志中间件的配置选项

func WithLogger(logger loggerCore.Logger) LoggingOption

func WithMaxArgBytes(maxBytes int) LoggingOption

func WithoutInputLogging() LoggingOption

func WithoutOutputLogging() LoggingOption

type RateLimitConfig ¶

type RateLimitConfig struct {
	// QPS 每秒请求数限制
	QPS float64
	// Burst 突发请求数（令牌桶容量）
	Burst int
	// PerTool 是否按工具名限流（false=全局限流）
	PerTool bool
	// Logger 日志记录器
	Logger loggercore.Logger
	// WaitTimeout 等待令牌的超时时间（0表示不等待，直接拒绝）
	WaitTimeout time.Duration
}

RateLimitConfig 限流中间件配置

type RateLimitMiddleware ¶

type RateLimitMiddleware struct {
	// contains filtered or unexported fields
}

RateLimitMiddleware 提供工具调用的限流功能（使用函数式实现）。

它使用令牌桶算法限制工具调用的速率，支持：

• 全局限流：所有工具共享限流配额
• 按工具限流：每个工具独立的限流配额
• 可配置的 QPS 和突发容量
• 可选的等待超时（阻塞或立即拒绝）

使用示例:

rateLimitMW := RateLimit(
    WithQPS(10),           // 每秒 10 个请求
    WithBurst(20),         // 允许突发 20 个请求
    WithPerToolRateLimit(), // 每个工具独立限流
)
wrappedTool := tools.WithMiddleware(myTool, rateLimitMW)

func NewRateLimitMiddleware(opts ...RateLimitOption) *RateLimitMiddleware

func (m *RateLimitMiddleware) GetStats() (allowed, rejected int64)

func (m *RateLimitMiddleware) Wrap(tool interfaces.Tool, next ToolInvoker) ToolInvoker

type RateLimitOption ¶

type RateLimitOption func(*RateLimitConfig)

RateLimitOption 限流中间件选项

func WithBurst(burst int) RateLimitOption

func WithPerToolRateLimit() RateLimitOption

func WithQPS(qps float64) RateLimitOption

func WithRateLimitLogger(logger loggercore.Logger) RateLimitOption

func WithWaitTimeout(timeout time.Duration) RateLimitOption

type ToolInvoker ¶

type ToolInvoker func(context.Context, *interfaces.ToolInput) (*interfaces.ToolOutput, error)

ToolInvoker 是工具调用函数的类型定义。

它封装了工具的实际执行逻辑，中间件通过包装 ToolInvoker 来添加功能。

func Chain(tool interfaces.Tool, invoker ToolInvoker, middlewares ...ToolMiddleware) ToolInvoker

middlewares := []ToolMiddleware{logging, caching, rateLimit}
Chain(middlewares, baseInvoker)

执行流程:
  logging.OnBeforeInvoke
    -> caching.OnBeforeInvoke
      -> rateLimit.OnBeforeInvoke
        -> baseInvoker (实际工具执行)
      <- rateLimit.OnAfterInvoke
    <- caching.OnAfterInvoke
  <- logging.OnAfterInvoke

type ToolMiddleware ¶

type ToolMiddleware interface {
	// Name 返回中间件的名称，用于日志和调试
	Name() string

	// OnBeforeInvoke 在工具调用前执行
	//
	// 可以修改输入、验证参数、记录日志等。
	// 如果返回错误，则中止工具执行。
	OnBeforeInvoke(ctx context.Context, tool interfaces.Tool, input *interfaces.ToolInput) (*interfaces.ToolInput, error)

	// OnAfterInvoke 在工具调用后执行
	//
	// 可以修改输出、记录日志、更新缓存等。
	// 如果返回错误，则覆盖原始结果。
	OnAfterInvoke(ctx context.Context, tool interfaces.Tool, output *interfaces.ToolOutput) (*interfaces.ToolOutput, error)

	// OnError 在工具执行出错时调用
	//
	// 可以处理、包装或记录错误。
	// 返回的错误将作为最终错误返回给调用者。
	OnError(ctx context.Context, tool interfaces.Tool, err error) error
}

ToolMiddleware 定义了工具中间件的接口。

中间件可以在工具执行前后添加横切关注点，如日志记录、缓存、限流等。 采用洋葱模型，多个中间件可以链式组合。

使用示例:

// 创建自定义中间件
type MyMiddleware struct {
    *BaseToolMiddleware
}

func (m *MyMiddleware) OnBeforeInvoke(ctx context.Context, tool interfaces.Tool, input *interfaces.ToolInput) (*interfaces.ToolInput, error) {
    // 前置处理
    return input, nil
}

// 应用中间件到工具
wrappedTool := tools.WithMiddleware(myTool, NewMyMiddleware())

type ToolMiddlewareFunc ¶

type ToolMiddlewareFunc func(interfaces.Tool, ToolInvoker) ToolInvoker

ToolMiddlewareFunc 是中间件函数的类型定义。

它接收一个工具和下一个 invoker，返回包装后的 invoker。 这允许中间件链式组合，形成洋葱模型。

使用示例:

func MyMiddlewareFunc(tool interfaces.Tool, next ToolInvoker) ToolInvoker {
    return func(ctx context.Context, input *interfaces.ToolInput) (*interfaces.ToolOutput, error) {
        // 前置处理
        output, err := next(ctx, input)  // 调用下一层
        // 后置处理
        return output, err
    }
}

func Caching(opts ...CachingOption) ToolMiddlewareFunc

func RateLimit(opts ...RateLimitOption) ToolMiddlewareFunc