灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-28 03:24:26 +08:00
parent 88b606b9ca
commit 812f68d5aa
48 changed files with 5566 additions and 1499 deletions

View File

@@ -0,0 +1,503 @@
// 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)
}