plugin

package
v0.5.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2026 License: Apache-2.0 Imports: 13 Imported by: 1

Documentation

Overview

Package plugin 提供插件依赖管理能力

Package plugin 提供插件热更新能力

Package plugin 提供 Hexagon AI Agent 框架的插件系统

Package plugin 提供 Hexagon AI Agent 框架的插件系统

Package plugin 提供 Hexagon AI Agent 框架的插件系统

Plugin 系统允许动态扩展框架功能:

  • Plugin: 插件接口
  • Registry: 插件注册表
  • Loader: 插件加载器
  • Lifecycle: 插件生命周期管理

插件类型:

  • ProviderPlugin: LLM Provider 插件
  • ToolPlugin: 工具插件
  • MemoryPlugin: 记忆插件
  • RetrieverPlugin: 检索器插件
  • EvaluatorPlugin: 评估器插件

Package plugin 提供 Hexagon AI Agent 框架的插件系统

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterFactoryGlobal

func RegisterFactoryGlobal(name string, factory PluginFactory) error

RegisterFactory 注册插件工厂到全局注册表

func RegisterPlugin

func RegisterPlugin(plugin Plugin) error

Register 注册插件到全局注册表

Types

type BasePlugin

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

BasePlugin 基础插件实现 提供默认实现,方便扩展

func NewBasePlugin

func NewBasePlugin(info PluginInfo) *BasePlugin

NewBasePlugin 创建基础插件

func (*BasePlugin) Config

func (p *BasePlugin) Config() map[string]any

Config 获取配置

func (*BasePlugin) GetConfigBool

func (p *BasePlugin) GetConfigBool(key string, defaultVal bool) bool

GetConfigBool 获取布尔配置

func (*BasePlugin) GetConfigInt

func (p *BasePlugin) GetConfigInt(key string, defaultVal int) int

GetConfigInt 获取整数配置

func (*BasePlugin) GetConfigString

func (p *BasePlugin) GetConfigString(key string, defaultVal string) string

GetConfigString 获取字符串配置

func (*BasePlugin) Health

func (p *BasePlugin) Health() HealthStatus

Health 返回健康状态

func (*BasePlugin) Info

func (p *BasePlugin) Info() PluginInfo

Info 返回插件信息

func (*BasePlugin) Init

func (p *BasePlugin) Init(ctx context.Context, config map[string]any) error

Init 初始化插件

func (*BasePlugin) Start

func (p *BasePlugin) Start(ctx context.Context) error

Start 启动插件

func (*BasePlugin) Stop

func (p *BasePlugin) Stop(ctx context.Context) error

Stop 停止插件

type BuiltinPlugins

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

BuiltinPlugins 内置插件注册

func NewBuiltinPlugins

func NewBuiltinPlugins() *BuiltinPlugins

NewBuiltinPlugins 创建内置插件集合

func (*BuiltinPlugins) Add

func (b *BuiltinPlugins) Add(name string, factory PluginFactory) *BuiltinPlugins

Add 添加内置插件工厂

func (*BuiltinPlugins) List

func (b *BuiltinPlugins) List() []string

List 列出所有内置插件

func (*BuiltinPlugins) RegisterAll

func (b *BuiltinPlugins) RegisterAll(registry *Registry) error

RegisterAll 注册所有内置插件到注册表

type Dependency

type Dependency struct {
	// Name 插件名称
	Name string

	// Version 版本约束
	Version string

	// Optional 是否可选
	Optional bool
}

Dependency 依赖项

type DependencyGraph

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

DependencyGraph 依赖图

func NewDependencyGraph

func NewDependencyGraph() *DependencyGraph

NewDependencyGraph 创建依赖图

func (*DependencyGraph) AddNode

func (g *DependencyGraph) AddNode(name, version string, deps []Dependency)

AddNode 添加节点

func (*DependencyGraph) DetectCycle

func (g *DependencyGraph) DetectCycle() []string

DetectCycle 检测循环依赖

func (*DependencyGraph) TopologicalSort

func (g *DependencyGraph) TopologicalSort() ([]string, error)

TopologicalSort 拓扑排序

type DependencyNode

type DependencyNode struct {
	// Name 插件名称
	Name string

	// Version 版本
	Version string

	// Dependencies 依赖列表
	Dependencies []Dependency
}

DependencyNode 依赖节点

type DependencyResolver

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

DependencyResolver 依赖解析器

解析和验证插件依赖关系,确保:

  • 依赖存在
  • 版本兼容
  • 无循环依赖
  • 正确的加载顺序

func NewDependencyResolver

func NewDependencyResolver(registry *Registry) *DependencyResolver

NewDependencyResolver 创建依赖解析器

func (*DependencyResolver) BuildDependencyTree

func (r *DependencyResolver) BuildDependencyTree(pluginName string) (*DependencyTree, error)

BuildDependencyTree 构建依赖树

func (*DependencyResolver) CheckDependencies

func (r *DependencyResolver) CheckDependencies(plugin PluginInfo) error

CheckDependencies 检查依赖是否满足(存在性 + 版本约束)。

依赖声明支持 "name" 或 "name@constraint"(见 parseDependencySpec)。指定了约束时, 用 ParseVersionConstraint 解析并校验已注册依赖的实际版本(VersionConstraint.CheckVersion); 未指定约束时仅检查依赖存在(任意版本满足,保持向后兼容)。

func (*DependencyResolver) GetLoadOrder

func (r *DependencyResolver) GetLoadOrder(plugins []PluginInfo) ([]PluginInfo, error)

GetLoadOrder 获取插件加载顺序

func (*DependencyResolver) Resolve

func (r *DependencyResolver) Resolve(plugins []PluginInfo) ([]string, error)

Resolve 解析依赖顺序

返回按依赖顺序排列的插件列表(被依赖的在前)

func (*DependencyResolver) ValidateDependencies

func (r *DependencyResolver) ValidateDependencies(plugins []PluginInfo) error

ValidateDependencies 验证所有插件的依赖

type DependencyTree

type DependencyTree struct {
	// Plugin 插件信息
	Plugin PluginInfo

	// Dependencies 依赖子树
	Dependencies []*DependencyTree
}

DependencyTree 依赖树

func (*DependencyTree) String

func (t *DependencyTree) String() string

String 格式化依赖树

type HealthState

type HealthState string

HealthState 健康状态枚举

const (
	// HealthStateHealthy 健康
	HealthStateHealthy HealthState = "healthy"

	// HealthStateDegraded 降级
	HealthStateDegraded HealthState = "degraded"

	// HealthStateUnhealthy 不健康
	HealthStateUnhealthy HealthState = "unhealthy"

	// HealthStateUnknown 未知
	HealthStateUnknown HealthState = "unknown"
)

type HealthStatus

type HealthStatus struct {
	// Status 状态
	Status HealthState `json:"status"`

	// Message 状态消息
	Message string `json:"message,omitempty"`

	// Details 详细信息
	Details map[string]any `json:"details,omitempty"`

	// LastCheck 最后检查时间
	LastCheck time.Time `json:"last_check"`
}

HealthStatus 健康状态

type HotReloadCallback

type HotReloadCallback func(name string, oldVersion, newVersion *PluginVersion, err error)

HotReloadCallback 热更新回调

type HotReloadManager

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

HotReloadManager 插件热更新管理器

监控插件配置变化,自动重新加载插件。 支持:

  • 插件配置变更检测
  • 插件版本管理
  • 插件热更新(无需重启)
  • 依赖处理

线程安全:所有方法都是并发安全的

func NewHotReloadManager

func NewHotReloadManager(manager *PluginManager, opts ...HotReloadOption) *HotReloadManager

NewHotReloadManager 创建插件热更新管理器

func (*HotReloadManager) GetVersionHistory

func (m *HotReloadManager) GetVersionHistory(name string) []PluginVersion

GetVersionHistory 获取版本历史

func (*HotReloadManager) GetWatchedPlugins

func (m *HotReloadManager) GetWatchedPlugins() []string

GetWatchedPlugins 获取所有监控的插件

func (*HotReloadManager) IsRunning

func (m *HotReloadManager) IsRunning() bool

IsRunning 返回运行状态

func (*HotReloadManager) RollbackToVersion

func (m *HotReloadManager) RollbackToVersion(ctx context.Context, name, version string) error

RollbackToVersion 回滚到指定版本

func (*HotReloadManager) Start

func (m *HotReloadManager) Start() error

Start 启动热更新监控

func (*HotReloadManager) Stats

func (m *HotReloadManager) Stats() map[string]any

Stats 获取统计信息

func (*HotReloadManager) Stop

func (m *HotReloadManager) Stop()

Stop 停止热更新监控

func (*HotReloadManager) Unwatch

func (m *HotReloadManager) Unwatch(name string)

Unwatch 停止监控插件

func (*HotReloadManager) UpdatePlugin

func (m *HotReloadManager) UpdatePlugin(ctx context.Context, name, configPath string, opts UpdateOptions) error

UpdatePlugin 更新插件(带策略)

func (*HotReloadManager) Watch

func (m *HotReloadManager) Watch(name, configPath string) error

Watch 监控插件配置文件

type HotReloadOption

type HotReloadOption func(*HotReloadManager)

HotReloadOption 热更新选项

func WithHotReloadCallback

func WithHotReloadCallback(callback HotReloadCallback) HotReloadOption

WithHotReloadCallback 设置回调

func WithHotReloadInterval

func WithHotReloadInterval(interval time.Duration) HotReloadOption

WithHotReloadInterval 设置检查间隔

type Lifecycle

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

Lifecycle 插件生命周期管理器

func NewLifecycle

func NewLifecycle(registry *Registry, opts ...LifecycleOption) *Lifecycle

NewLifecycle 创建生命周期管理器

func (*Lifecycle) GetStartOrder

func (l *Lifecycle) GetStartOrder() []string

GetStartOrder 获取启动顺序

func (*Lifecycle) HealthCheck

func (l *Lifecycle) HealthCheck(ctx context.Context) map[string]HealthStatus

HealthCheck 执行健康检查

func (*Lifecycle) Init

func (l *Lifecycle) Init(ctx context.Context, name string, config map[string]any) error

Init 初始化插件

func (*Lifecycle) InitAll

func (l *Lifecycle) InitAll(ctx context.Context, configs map[string]map[string]any) error

InitAll 初始化所有插件

func (*Lifecycle) Restart

func (l *Lifecycle) Restart(ctx context.Context, name string) error

Restart 重启插件

func (*Lifecycle) Start

func (l *Lifecycle) Start(ctx context.Context, name string) error

Start 启动插件

func (*Lifecycle) StartAll

func (l *Lifecycle) StartAll(ctx context.Context) error

StartAll 启动所有插件(按依赖顺序)

func (*Lifecycle) StartHealthChecker

func (l *Lifecycle) StartHealthChecker(ctx context.Context)

StartHealthChecker 启动健康检查器

func (*Lifecycle) Stop

func (l *Lifecycle) Stop(ctx context.Context, name string) error

Stop 停止插件

func (*Lifecycle) StopAll

func (l *Lifecycle) StopAll(ctx context.Context) error

StopAll 停止所有插件(按启动的逆序) 即使某个插件停止失败,也会继续停止其他插件,最终返回所有错误的聚合。

func (*Lifecycle) StopHealthChecker

func (l *Lifecycle) StopHealthChecker()

StopHealthChecker 停止健康检查器

线程安全:此方法可以被多次调用,只有第一次会真正关闭 channel

type LifecycleOption

type LifecycleOption func(*Lifecycle)

LifecycleOption Lifecycle 选项

func WithHealthCheckInterval

func WithHealthCheckInterval(d time.Duration) LifecycleOption

WithHealthCheckInterval 设置健康检查间隔

type Loader

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

Loader 插件加载器

func NewLoader

func NewLoader(registry *Registry, lifecycle *Lifecycle, opts ...LoaderOption) *Loader

NewLoader 创建插件加载器

func (*Loader) Discover

func (l *Loader) Discover() ([]PluginInfo, error)

Discover 发现插件

func (*Loader) LoadAll

func (l *Loader) LoadAll(ctx context.Context) error

LoadAll 加载所有发现的插件

func (*Loader) LoadFromConfig

func (l *Loader) LoadFromConfig(ctx context.Context, configPath string) error

LoadFromConfig 从配置加载插件

func (*Loader) LoadFromDirectory

func (l *Loader) LoadFromDirectory(ctx context.Context, dir string) error

LoadFromDirectory 从目录加载插件配置

type LoaderOption

type LoaderOption func(*Loader)

LoaderOption Loader 选项

func WithSearchPaths

func WithSearchPaths(paths ...string) LoaderOption

WithSearchPaths 设置搜索路径

type Plugin

type Plugin interface {
	// Info 返回插件信息
	Info() PluginInfo

	// Init 初始化插件
	Init(ctx context.Context, config map[string]any) error

	// Start 启动插件
	Start(ctx context.Context) error

	// Stop 停止插件
	Stop(ctx context.Context) error

	// Health 返回健康状态
	Health() HealthStatus
}

Plugin 是插件接口

func GetPlugin

func GetPlugin(name string) (Plugin, error)

GetPlugin 从全局注册表获取插件

type PluginConfig

type PluginConfig struct {
	// Name 插件名称
	Name string `json:"name" yaml:"name"`

	// Enabled 是否启用
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Config 插件配置
	Config map[string]any `json:"config" yaml:"config"`

	// Priority 优先级(越小越优先)
	Priority int `json:"priority" yaml:"priority"`
}

PluginConfig 插件配置

func SortPluginsByPriority

func SortPluginsByPriority(configs []PluginConfig) []PluginConfig

SortPluginsByPriority 按优先级排序插件配置

type PluginEvent

type PluginEvent struct {
	// Type 事件类型
	Type PluginEventType `json:"type"`

	// Plugin 插件名称
	Plugin string `json:"plugin"`

	// Timestamp 时间戳
	Timestamp time.Time `json:"timestamp"`

	// Data 事件数据
	Data map[string]any `json:"data,omitempty"`
}

PluginEvent 插件事件

type PluginEventHandler

type PluginEventHandler func(event PluginEvent)

PluginEventHandler 插件事件处理器

type PluginEventType

type PluginEventType string

PluginEventType 插件事件类型

const (
	PluginEventLoaded      PluginEventType = "loaded"
	PluginEventUnloaded    PluginEventType = "unloaded"
	PluginEventInitialized PluginEventType = "initialized"
	PluginEventStarted     PluginEventType = "started"
	PluginEventStopped     PluginEventType = "stopped"
	PluginEventError       PluginEventType = "error"
	PluginEventHealthCheck PluginEventType = "health_check"
)

type PluginFactory

type PluginFactory func() Plugin

PluginFactory 插件工厂函数

type PluginHooks

type PluginHooks interface {
	// OnLoad 加载时调用
	OnLoad() error

	// OnUnload 卸载时调用
	OnUnload() error

	// OnConfigChange 配置变更时调用
	OnConfigChange(oldConfig, newConfig map[string]any) error
}

PluginHooks 插件钩子

type PluginInfo

type PluginInfo struct {
	// Name 插件名称(唯一标识)
	Name string `json:"name"`

	// Version 插件版本
	Version string `json:"version"`

	// Type 插件类型
	Type PluginType `json:"type"`

	// Description 插件描述
	Description string `json:"description"`

	// Author 作者
	Author string `json:"author,omitempty"`

	// License 许可证
	License string `json:"license,omitempty"`

	// Homepage 主页
	Homepage string `json:"homepage,omitempty"`

	// Dependencies 依赖的其他插件
	Dependencies []string `json:"dependencies,omitempty"`

	// Tags 标签
	Tags []string `json:"tags,omitempty"`

	// Metadata 额外元数据
	Metadata map[string]any `json:"metadata,omitempty"`
}

PluginInfo 插件信息

func ListPlugins

func ListPlugins() []PluginInfo

ListPlugins 列出全局注册表中的所有插件

type PluginInstance

type PluginInstance struct {
	// Plugin 插件实例
	Plugin Plugin

	// State 当前状态
	State PluginState

	// Config 配置
	Config map[string]any

	// LoadedAt 加载时间
	LoadedAt time.Time

	// StartedAt 启动时间
	StartedAt *time.Time

	// Error 错误信息
	Error error
}

PluginInstance 插件实例

type PluginManager

type PluginManager struct {
	Registry  *Registry
	Lifecycle *Lifecycle
}

PluginManager 插件管理器(组合 Registry 和 Lifecycle)

func NewPluginManager

func NewPluginManager(opts ...LifecycleOption) *PluginManager

NewPluginManager 创建插件管理器

func QuickLoad

func QuickLoad(ctx context.Context, configs []PluginConfig) (*PluginManager, error)

QuickLoad 快速加载插件

func (*PluginManager) Disable

func (m *PluginManager) Disable(ctx context.Context, name string) error

Disable 禁用插件

func (*PluginManager) Enable

func (m *PluginManager) Enable(ctx context.Context, name string, config map[string]any) error

Enable 启用插件(初始化 + 启动)

func (*PluginManager) Load

func (m *PluginManager) Load(plugin Plugin) error

Load 加载并注册插件

func (*PluginManager) LoadFromFactory

func (m *PluginManager) LoadFromFactory(name string) error

LoadFromFactory 从工厂加载插件

func (*PluginManager) Stats

func (m *PluginManager) Stats() map[string]any

Stats 获取统计信息

func (*PluginManager) Status

func (m *PluginManager) Status() map[string]PluginState

Status 获取插件状态

func (*PluginManager) Unload

func (m *PluginManager) Unload(ctx context.Context, name string) error

Unload 卸载插件

type PluginManifest

type PluginManifest struct {
	// Info 插件信息
	Info PluginInfo `yaml:"info"`

	// Config 默认配置
	Config map[string]any `yaml:"config,omitempty"`

	// ConfigSchema 配置 Schema
	ConfigSchema map[string]any `yaml:"config_schema,omitempty"`

	// Hooks 钩子配置
	Hooks map[string]string `yaml:"hooks,omitempty"`
}

PluginManifest 插件清单

func LoadManifest

func LoadManifest(path string) (*PluginManifest, error)

LoadManifest 从文件加载清单

func ParseManifest

func ParseManifest(data []byte) (*PluginManifest, error)

ParseManifest 解析插件清单

type PluginState

type PluginState string

PluginState 插件状态

const (
	// PluginStateUnloaded 未加载
	PluginStateUnloaded PluginState = "unloaded"

	// PluginStateLoaded 已加载
	PluginStateLoaded PluginState = "loaded"

	// PluginStateInitialized 已初始化
	PluginStateInitialized PluginState = "initialized"

	// PluginStateRunning 运行中
	PluginStateRunning PluginState = "running"

	// PluginStateStopped 已停止
	PluginStateStopped PluginState = "stopped"

	// PluginStateError 错误
	PluginStateError PluginState = "error"
)

type PluginType

type PluginType string

PluginType 插件类型

const (
	// PluginTypeProvider LLM Provider 插件
	PluginTypeProvider PluginType = "provider"

	// PluginTypeTool 工具插件
	PluginTypeTool PluginType = "tool"

	// PluginTypeMemory 记忆插件
	PluginTypeMemory PluginType = "memory"

	// PluginTypeRetriever 检索器插件
	PluginTypeRetriever PluginType = "retriever"

	// PluginTypeEvaluator 评估器插件
	PluginTypeEvaluator PluginType = "evaluator"

	// PluginTypeAgent Agent 插件
	PluginTypeAgent PluginType = "agent"

	// PluginTypeMiddleware 中间件插件
	PluginTypeMiddleware PluginType = "middleware"

	// PluginTypeExtension 扩展插件
	PluginTypeExtension PluginType = "extension"
)

type PluginUpdateStrategy

type PluginUpdateStrategy string

PluginUpdateStrategy 插件更新策略

const (
	// UpdateStrategyImmediate 立即更新
	UpdateStrategyImmediate PluginUpdateStrategy = "immediate"

	// UpdateStrategyGraceful 优雅更新(等待当前任务完成)
	UpdateStrategyGraceful PluginUpdateStrategy = "graceful"

	// UpdateStrategyScheduled 计划更新(在指定时间更新)
	UpdateStrategyScheduled PluginUpdateStrategy = "scheduled"
)

type PluginVersion

type PluginVersion struct {
	// Version 版本号
	Version string

	// LoadedAt 加载时间
	LoadedAt time.Time

	// Config 配置
	Config map[string]any

	// Hash 配置哈希
	Hash string
}

PluginVersion 插件版本信息

type PluginWithHooks

type PluginWithHooks interface {
	Plugin
	PluginHooks
}

PluginWithHooks 带钩子的插件

type PluginsConfig

type PluginsConfig struct {
	Plugins []PluginConfig `yaml:"plugins"`
}

PluginsConfig 插件配置文件结构

type Registry

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

Registry 插件注册表

func Global

func Global() *Registry

Global 返回全局插件注册表

func NewRegistry

func NewRegistry() *Registry

NewRegistry 创建插件注册表

func (*Registry) Count

func (r *Registry) Count() int

Count 返回插件数量

func (*Registry) CreateFromFactory

func (r *Registry) CreateFromFactory(name string) (Plugin, error)

CreateFromFactory 从工厂创建插件

func (*Registry) Get

func (r *Registry) Get(name string) (Plugin, error)

Get 获取插件

func (*Registry) GetInstance

func (r *Registry) GetInstance(name string) (*PluginInstance, error)

GetInstance 获取插件实例

func (*Registry) Has

func (r *Registry) Has(name string) bool

Has 检查插件是否存在

func (*Registry) List

func (r *Registry) List() []PluginInfo

List 列出所有插件

func (*Registry) ListByState

func (r *Registry) ListByState(state PluginState) []PluginInfo

ListByState 按状态列出插件

func (*Registry) ListByType

func (r *Registry) ListByType(pluginType PluginType) []PluginInfo

ListByType 按类型列出插件

func (*Registry) ListFactories

func (r *Registry) ListFactories() []string

ListFactories 列出所有工厂

func (*Registry) OnEvent

func (r *Registry) OnEvent(handler PluginEventHandler)

OnEvent 注册事件处理器

func (*Registry) Register

func (r *Registry) Register(plugin Plugin) error

Register 注册插件实例

func (*Registry) RegisterFactory

func (r *Registry) RegisterFactory(name string, factory PluginFactory) error

RegisterFactory 注册插件工厂

func (*Registry) SetState

func (r *Registry) SetState(name string, state PluginState) error

SetState 设置插件状态

func (*Registry) Unregister

func (r *Registry) Unregister(name string) error

Unregister 注销插件

func (*Registry) UnregisterFactory

func (r *Registry) UnregisterFactory(name string)

UnregisterFactory 注销插件工厂

type UpdateOptions

type UpdateOptions struct {
	// Strategy 更新策略
	Strategy PluginUpdateStrategy

	// GracePeriod 优雅期(用于 Graceful 策略)
	GracePeriod time.Duration

	// ScheduledTime 计划时间(用于 Scheduled 策略)
	ScheduledTime time.Time

	// BackupConfig 是否备份配置
	BackupConfig bool

	// RollbackOnError 错误时是否自动回滚
	RollbackOnError bool
}

UpdateOptions 更新选项

func DefaultUpdateOptions

func DefaultUpdateOptions() UpdateOptions

DefaultUpdateOptions 默认更新选项

type VersionConstraint

type VersionConstraint struct {
	// Operator 操作符 (=, >, >=, <, <=, ~>, ^)
	Operator string

	// Version 版本号
	Version string
}

VersionConstraint 版本约束

func ParseVersionConstraint

func ParseVersionConstraint(constraint string) (*VersionConstraint, error)

ParseVersionConstraint 解析版本约束

支持的格式:

  • "1.0.0" - 精确版本
  • ">=1.0.0" - 大于等于
  • "~>1.0" - 兼容版本(1.x)
  • "^1.0.0" - 次版本兼容(1.x.x)

func (*VersionConstraint) CheckVersion

func (c *VersionConstraint) CheckVersion(version string) bool

CheckVersion 检查版本是否满足约束

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL