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 ¶
- func RegisterFactoryGlobal(name string, factory PluginFactory) error
- func RegisterPlugin(plugin Plugin) error
- type BasePlugin
- func (p *BasePlugin) Config() map[string]any
- func (p *BasePlugin) GetConfigBool(key string, defaultVal bool) bool
- func (p *BasePlugin) GetConfigInt(key string, defaultVal int) int
- func (p *BasePlugin) GetConfigString(key string, defaultVal string) string
- func (p *BasePlugin) Health() HealthStatus
- func (p *BasePlugin) Info() PluginInfo
- func (p *BasePlugin) Init(ctx context.Context, config map[string]any) error
- func (p *BasePlugin) Start(ctx context.Context) error
- func (p *BasePlugin) Stop(ctx context.Context) error
- type BuiltinPlugins
- type Dependency
- type DependencyGraph
- type DependencyNode
- type DependencyResolver
- func (r *DependencyResolver) BuildDependencyTree(pluginName string) (*DependencyTree, error)
- func (r *DependencyResolver) CheckDependencies(plugin PluginInfo) error
- func (r *DependencyResolver) GetLoadOrder(plugins []PluginInfo) ([]PluginInfo, error)
- func (r *DependencyResolver) Resolve(plugins []PluginInfo) ([]string, error)
- func (r *DependencyResolver) ValidateDependencies(plugins []PluginInfo) error
- type DependencyTree
- type HealthState
- type HealthStatus
- type HotReloadCallback
- type HotReloadManager
- func (m *HotReloadManager) GetVersionHistory(name string) []PluginVersion
- func (m *HotReloadManager) GetWatchedPlugins() []string
- func (m *HotReloadManager) IsRunning() bool
- func (m *HotReloadManager) RollbackToVersion(ctx context.Context, name, version string) error
- func (m *HotReloadManager) Start() error
- func (m *HotReloadManager) Stats() map[string]any
- func (m *HotReloadManager) Stop()
- func (m *HotReloadManager) Unwatch(name string)
- func (m *HotReloadManager) UpdatePlugin(ctx context.Context, name, configPath string, opts UpdateOptions) error
- func (m *HotReloadManager) Watch(name, configPath string) error
- type HotReloadOption
- type Lifecycle
- func (l *Lifecycle) GetStartOrder() []string
- func (l *Lifecycle) HealthCheck(ctx context.Context) map[string]HealthStatus
- func (l *Lifecycle) Init(ctx context.Context, name string, config map[string]any) error
- func (l *Lifecycle) InitAll(ctx context.Context, configs map[string]map[string]any) error
- func (l *Lifecycle) Restart(ctx context.Context, name string) error
- func (l *Lifecycle) Start(ctx context.Context, name string) error
- func (l *Lifecycle) StartAll(ctx context.Context) error
- func (l *Lifecycle) StartHealthChecker(ctx context.Context)
- func (l *Lifecycle) Stop(ctx context.Context, name string) error
- func (l *Lifecycle) StopAll(ctx context.Context) error
- func (l *Lifecycle) StopHealthChecker()
- type LifecycleOption
- type Loader
- type LoaderOption
- type Plugin
- type PluginConfig
- type PluginEvent
- type PluginEventHandler
- type PluginEventType
- type PluginFactory
- type PluginHooks
- type PluginInfo
- type PluginInstance
- type PluginManager
- func (m *PluginManager) Disable(ctx context.Context, name string) error
- func (m *PluginManager) Enable(ctx context.Context, name string, config map[string]any) error
- func (m *PluginManager) Load(plugin Plugin) error
- func (m *PluginManager) LoadFromFactory(name string) error
- func (m *PluginManager) Stats() map[string]any
- func (m *PluginManager) Status() map[string]PluginState
- func (m *PluginManager) Unload(ctx context.Context, name string) error
- type PluginManifest
- type PluginState
- type PluginType
- type PluginUpdateStrategy
- type PluginVersion
- type PluginWithHooks
- type PluginsConfig
- type Registry
- func (r *Registry) Count() int
- func (r *Registry) CreateFromFactory(name string) (Plugin, error)
- func (r *Registry) Get(name string) (Plugin, error)
- func (r *Registry) GetInstance(name string) (*PluginInstance, error)
- func (r *Registry) Has(name string) bool
- func (r *Registry) List() []PluginInfo
- func (r *Registry) ListByState(state PluginState) []PluginInfo
- func (r *Registry) ListByType(pluginType PluginType) []PluginInfo
- func (r *Registry) ListFactories() []string
- func (r *Registry) OnEvent(handler PluginEventHandler)
- func (r *Registry) Register(plugin Plugin) error
- func (r *Registry) RegisterFactory(name string, factory PluginFactory) error
- func (r *Registry) SetState(name string, state PluginState) error
- func (r *Registry) Unregister(name string) error
- func (r *Registry) UnregisterFactory(name string)
- type UpdateOptions
- type VersionConstraint
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterFactoryGlobal ¶
func RegisterFactoryGlobal(name string, factory PluginFactory) error
RegisterFactory 注册插件工厂到全局注册表
Types ¶
type BasePlugin ¶
type BasePlugin struct {
// contains filtered or unexported fields
}
BasePlugin 基础插件实现 提供默认实现,方便扩展
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 获取字符串配置
type BuiltinPlugins ¶
type BuiltinPlugins struct {
// contains filtered or unexported fields
}
BuiltinPlugins 内置插件注册
func (*BuiltinPlugins) Add ¶
func (b *BuiltinPlugins) Add(name string, factory PluginFactory) *BuiltinPlugins
Add 添加内置插件工厂
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 (*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 依赖树
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) RollbackToVersion ¶
func (m *HotReloadManager) RollbackToVersion(ctx context.Context, name, version string) error
RollbackToVersion 回滚到指定版本
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) HealthCheck ¶
func (l *Lifecycle) HealthCheck(ctx context.Context) map[string]HealthStatus
HealthCheck 执行健康检查
func (*Lifecycle) StartHealthChecker ¶
StartHealthChecker 启动健康检查器
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) LoadFromConfig ¶
LoadFromConfig 从配置加载插件
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 是插件接口
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 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 插件信息
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 ¶
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) LoadFromFactory ¶
func (m *PluginManager) LoadFromFactory(name string) error
LoadFromFactory 从工厂加载插件
func (*PluginManager) Status ¶
func (m *PluginManager) Status() map[string]PluginState
Status 获取插件状态
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 插件清单
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 PluginsConfig ¶
type PluginsConfig struct {
Plugins []PluginConfig `yaml:"plugins"`
}
PluginsConfig 插件配置文件结构
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry 插件注册表
func (*Registry) CreateFromFactory ¶
CreateFromFactory 从工厂创建插件
func (*Registry) GetInstance ¶
func (r *Registry) GetInstance(name string) (*PluginInstance, error)
GetInstance 获取插件实例
func (*Registry) ListByState ¶
func (r *Registry) ListByState(state PluginState) []PluginInfo
ListByState 按状态列出插件
func (*Registry) ListByType ¶
func (r *Registry) ListByType(pluginType PluginType) []PluginInfo
ListByType 按类型列出插件
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) UnregisterFactory ¶
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 更新选项
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 检查版本是否满足约束