// Package pivot 灵枢 - 紧急制动与治理层 // // 取自《灵枢经》(黄帝内经下半部), // 讲的是针灸经络之枢纽。 // 这是整个协议的"总闸"与"方向盘", // 不轻易触发,但触发时能以最小代价 // 重置整个 Synapse 网络的状态。 package pivot import ( "context" "encoding/json" "fmt" "log" "sync" "time" "synapse/pkg/types" ) // ============================================================================= // Circuit Breaker - 熔断器 // ============================================================================= // CircuitState 熔断器状态 type CircuitState string const ( CircuitClosed CircuitState = "closed" // 关闭:正常流通 CircuitOpen CircuitState = "open" // 打开:熔断,拒绝请求 CircuitHalfOpen CircuitState = "half_open" // 半开:尝试恢复 ) // CircuitBreaker 熔断器 type CircuitBreaker struct { mu sync.RWMutex name string state CircuitState failureCount int successCount int threshold int // 失败阈值 timeout time.Duration // 熔断超时 lastFailure time.Time lastSuccess time.Time } // CircuitBreakerConfig 熔断器配置 type CircuitBreakerConfig struct { Threshold int Timeout time.Duration } // DefaultCircuitBreakerConfig 返回默认熔断器配置 func DefaultCircuitBreakerConfig() *CircuitBreakerConfig { return &CircuitBreakerConfig{ Threshold: 5, Timeout: 30 * time.Second, } } // NewCircuitBreaker 创建熔断器 func NewCircuitBreaker(name string, config *CircuitBreakerConfig) *CircuitBreaker { if config == nil { config = DefaultCircuitBreakerConfig() } return &CircuitBreaker{ name: name, state: CircuitClosed, threshold: config.Threshold, timeout: config.Timeout, } } // Allow 是否允许请求通过 func (cb *CircuitBreaker) Allow() bool { cb.mu.RLock() defer cb.mu.RUnlock() switch cb.state { case CircuitClosed: return true case CircuitOpen: // 检查是否超时,可以进入半开状态 if time.Since(cb.lastFailure) > cb.timeout { cb.mu.RUnlock() cb.mu.Lock() if cb.state == CircuitOpen && time.Since(cb.lastFailure) > cb.timeout { cb.state = CircuitHalfOpen cb.successCount = 0 log.Printf("[灵枢] 熔断器 %s 进入半开状态", cb.name) } cb.mu.Unlock() cb.mu.RLock() return cb.state == CircuitHalfOpen } return false case CircuitHalfOpen: return true default: return false } } // RecordSuccess 记录成功 func (cb *CircuitBreaker) RecordSuccess() { cb.mu.Lock() defer cb.mu.Unlock() cb.lastSuccess = time.Now() switch cb.state { case CircuitHalfOpen: cb.successCount++ // 连续成功几次后关闭熔断 if cb.successCount >= 3 { cb.state = CircuitClosed cb.failureCount = 0 cb.successCount = 0 log.Printf("[灵枢] 熔断器 %s 恢复关闭", cb.name) } case CircuitClosed: cb.failureCount = 0 } } // RecordFailure 记录失败 func (cb *CircuitBreaker) RecordFailure() { cb.mu.Lock() defer cb.mu.Unlock() cb.failureCount++ cb.lastFailure = time.Now() switch cb.state { case CircuitClosed: if cb.failureCount >= cb.threshold { cb.state = CircuitOpen log.Printf("[灵枢] 熔断器 %s 触发熔断 (失败: %d次)", cb.name, cb.failureCount) } case CircuitHalfOpen: cb.state = CircuitOpen log.Printf("[灵枢] 熔断器 %s 半开失败,重新熔断", cb.name) } } // State 获取当前状态 func (cb *CircuitBreaker) State() CircuitState { cb.mu.RLock() defer cb.mu.RUnlock() return cb.state } // Reset 重置熔断器 func (cb *CircuitBreaker) Reset() { cb.mu.Lock() defer cb.mu.Unlock() cb.state = CircuitClosed cb.failureCount = 0 cb.successCount = 0 log.Printf("[灵枢] 熔断器 %s 已重置", cb.name) } // ============================================================================= // Governance - 治理 // ============================================================================= // GovernanceLevel 治理级别 type GovernanceLevel int const ( GovLevelNormal GovernanceLevel = iota // 正常运行 GovLevelWatch // 观察模式 GovLevelRestricted // 受限模式 GovLevelEmergency // 紧急模式 GovLevelShutdown // 停机模式 ) func (l GovernanceLevel) String() string { switch l { case GovLevelNormal: return "normal" case GovLevelWatch: return "watch" case GovLevelRestricted: return "restricted" case GovLevelEmergency: return "emergency" case GovLevelShutdown: return "shutdown" default: return "unknown" } } // GovernanceManager 治理管理器 type GovernanceManager struct { mu sync.RWMutex level GovernanceLevel policies map[string]GovernancePolicy blacklist map[string]bool // 被封禁的 agent_id whitelist map[string]bool // 白名单 config *GovernanceConfig } // GovernancePolicy 治理策略 type GovernancePolicy struct { ID string Name string Description string Enabled bool Level GovernanceLevel Evaluate func(ctx context.Context, msg *types.UnifiedSynapseMessage) (bool, string) } // GovernanceConfig 治理配置 type GovernanceConfig struct { InitialLevel GovernanceLevel } // DefaultGovernanceConfig 返回默认治理配置 func DefaultGovernanceConfig() *GovernanceConfig { return &GovernanceConfig{ InitialLevel: GovLevelNormal, } } // NewGovernanceManager 创建治理管理器 func NewGovernanceManager(config *GovernanceConfig) *GovernanceManager { if config == nil { config = DefaultGovernanceConfig() } return &GovernanceManager{ level: config.InitialLevel, policies: make(map[string]GovernancePolicy), blacklist: make(map[string]bool), whitelist: make(map[string]bool), config: config, } } // SetLevel 设置治理级别 func (gm *GovernanceManager) SetLevel(level GovernanceLevel) { gm.mu.Lock() defer gm.mu.Unlock() gm.level = level log.Printf("[灵枢] 治理级别调整为: %s", level.String()) } // GetLevel 获取治理级别 func (gm *GovernanceManager) GetLevel() GovernanceLevel { gm.mu.RLock() defer gm.mu.RUnlock() return gm.level } // AddPolicy 添加治理策略 func (gm *GovernanceManager) AddPolicy(policy GovernancePolicy) { gm.mu.Lock() defer gm.mu.Unlock() gm.policies[policy.ID] = policy } // RemovePolicy 移除治理策略 func (gm *GovernanceManager) RemovePolicy(policyID string) { gm.mu.Lock() defer gm.mu.Unlock() delete(gm.policies, policyID) } // BanAgent 封禁 Agent func (gm *GovernanceManager) BanAgent(agentID, reason string) { gm.mu.Lock() defer gm.mu.Unlock() gm.blacklist[agentID] = true log.Printf("[灵枢] 封禁 Agent: %s (%s)", agentID, reason) } // UnbanAgent 解封 Agent func (gm *GovernanceManager) UnbanAgent(agentID string) { gm.mu.Lock() defer gm.mu.Unlock() delete(gm.blacklist, agentID) log.Printf("[灵枢] 解封 Agent: %s", agentID) } // IsBanned 检查是否被封禁 func (gm *GovernanceManager) IsBanned(agentID string) bool { gm.mu.RLock() defer gm.mu.RUnlock() return gm.blacklist[agentID] } // AllowMessage 检查是否允许消息通过 func (gm *GovernanceManager) AllowMessage(ctx context.Context, msg *types.UnifiedSynapseMessage) (bool, string) { gm.mu.RLock() defer gm.mu.RUnlock() // 停机模式,全部拒绝 if gm.level >= GovLevelShutdown { return false, "system shutdown" } // 检查黑名单 if gm.blacklist[msg.Sender.AgentID] { return false, "sender banned" } // 紧急模式,仅允许白名单 if gm.level >= GovLevelEmergency { if !gm.whitelist[msg.Sender.AgentID] { return false, "emergency mode, whitelist only" } } // 执行策略检查 for _, policy := range gm.policies { if !policy.Enabled || policy.Level > gm.level { continue } allowed, reason := policy.Evaluate(ctx, msg) if !allowed { return false, fmt.Sprintf("policy %s: %s", policy.Name, reason) } } return true, "" } // ============================================================================= // Protocol Upgrade - 协议升级 // ============================================================================= // UpgradeManager 升级管理器 type UpgradeManager struct { mu sync.RWMutex currentVersion string upgrades map[string]ProtocolUpgrade config *UpgradeConfig } // ProtocolUpgrade 协议升级 type ProtocolUpgrade struct { Version string Description string ReleasedAt time.Time Mandatory bool Apply func() error Rollback func() error } // UpgradeConfig 升级配置 type UpgradeConfig struct { AutoUpgrade bool } // DefaultUpgradeConfig 返回默认升级配置 func DefaultUpgradeConfig() *UpgradeConfig { return &UpgradeConfig{ AutoUpgrade: false, } } // NewUpgradeManager 创建升级管理器 func NewUpgradeManager(initialVersion string, config *UpgradeConfig) *UpgradeManager { if config == nil { config = DefaultUpgradeConfig() } return &UpgradeManager{ currentVersion: initialVersion, upgrades: make(map[string]ProtocolUpgrade), config: config, } } // CurrentVersion 当前版本 func (um *UpgradeManager) CurrentVersion() string { um.mu.RLock() defer um.mu.RUnlock() return um.currentVersion } // RegisterUpgrade 注册升级 func (um *UpgradeManager) RegisterUpgrade(upgrade ProtocolUpgrade) { um.mu.Lock() defer um.mu.Unlock() um.upgrades[upgrade.Version] = upgrade } // ApplyUpgrade 应用升级 func (um *UpgradeManager) ApplyUpgrade(version string) error { um.mu.Lock() defer um.mu.Unlock() upgrade, ok := um.upgrades[version] if !ok { return fmt.Errorf("upgrade %s not found", version) } if upgrade.Apply == nil { um.currentVersion = version log.Printf("[灵枢] 协议升级到: %s", version) return nil } if err := upgrade.Apply(); err != nil { return fmt.Errorf("upgrade failed: %w", err) } um.currentVersion = version log.Printf("[灵枢] 协议升级成功: %s", version) return nil } // RollbackUpgrade 回滚升级 func (um *UpgradeManager) RollbackUpgrade(version string) error { um.mu.Lock() defer um.mu.Unlock() upgrade, ok := um.upgrades[version] if !ok { return fmt.Errorf("upgrade %s not found", version) } if upgrade.Rollback == nil { return fmt.Errorf("no rollback function for version %s", version) } if err := upgrade.Rollback(); err != nil { return fmt.Errorf("rollback failed: %w", err) } log.Printf("[灵枢] 协议回滚: %s", version) return nil } // ============================================================================= // Pivot - 灵枢整体入口 // ============================================================================= // Pivot 灵枢 - 紧急制动与治理 type Pivot struct { CircuitBreakers map[string]*CircuitBreaker Governance *GovernanceManager Upgrade *UpgradeManager mu sync.RWMutex } // NewPivot 创建灵枢 func NewPivot() *Pivot { return &Pivot{ CircuitBreakers: make(map[string]*CircuitBreaker), Governance: NewGovernanceManager(nil), Upgrade: NewUpgradeManager("1.0.0", nil), } } // GetCircuitBreaker 获取或创建熔断器 func (p *Pivot) GetCircuitBreaker(name string) *CircuitBreaker { p.mu.Lock() defer p.mu.Unlock() if cb, ok := p.CircuitBreakers[name]; ok { return cb } cb := NewCircuitBreaker(name, nil) p.CircuitBreakers[name] = cb return cb } // EmergencyStop 紧急停止(一键熔断所有) func (p *Pivot) EmergencyStop(reason string) { log.Printf("[灵枢] ⚠️ 紧急制动启动: %s", reason) p.Governance.SetLevel(GovLevelEmergency) for name, cb := range p.CircuitBreakers { cb.RecordFailure() log.Printf("[灵枢] 熔断器 %s 已熔断", name) } } // Resume 恢复正常 func (p *Pivot) Resume() { log.Printf("[灵枢] 系统恢复正常") p.Governance.SetLevel(GovLevelNormal) for _, cb := range p.CircuitBreakers { cb.Reset() } } // ToJSON 导出为 JSON func (gm *GovernanceManager) ToJSON() string { data, _ := json.MarshalIndent(map[string]interface{}{ "level": gm.level.String(), "policies": len(gm.policies), "blacklist": len(gm.blacklist), "whitelist": len(gm.whitelist), }, "", " ") return string(data) }