灵隙(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,351 @@
// Package meridian 灵脉 - 寻址与路由层
//
// 取中医"经脉"之意。Agent 之间虽有空隙(灵隙),
// 但暗中有能量流动的轨迹(脉)。
//
// 此层负责维护全局路由表,让新 Agent "通脉"入网,
// 旧 Agent "断脉"离场,不死不休。
package meridian
import (
"context"
"encoding/json"
"fmt"
"log"
"sync"
"time"
"synapse/pkg/types"
)
// =============================================================================
// Agent Registry - Agent 注册发现
// =============================================================================
// AgentRegistry Agent 注册表
type AgentRegistry struct {
mu sync.RWMutex
agents map[string]*types.AgentEndpoint // agent_id -> endpoint
ttl map[string]time.Time // agent_id -> 过期时间
config *RegistryConfig
}
// RegistryConfig 注册表配置
type RegistryConfig struct {
DefaultTTL time.Duration // 默认存活时间
}
// DefaultRegistryConfig 返回默认注册表配置
func DefaultRegistryConfig() *RegistryConfig {
return &RegistryConfig{
DefaultTTL: 5 * time.Minute,
}
}
// NewAgentRegistry 创建 Agent 注册表
func NewAgentRegistry(config *RegistryConfig) *AgentRegistry {
if config == nil {
config = DefaultRegistryConfig()
}
return &AgentRegistry{
agents: make(map[string]*types.AgentEndpoint),
ttl: make(map[string]time.Time),
config: config,
}
}
// Register 注册 Agent(通脉)
func (r *AgentRegistry) Register(endpoint types.AgentEndpoint) error {
if endpoint.AgentID == "" {
return fmt.Errorf("agent_id is required")
}
r.mu.Lock()
defer r.mu.Unlock()
r.agents[endpoint.AgentID] = &endpoint
r.ttl[endpoint.AgentID] = time.Now().Add(r.config.DefaultTTL)
log.Printf("[灵脉] Agent 通脉入网: %s (%s)", endpoint.AgentID, endpoint.AgentName)
return nil
}
// Unregister 注销 Agent(断脉)
func (r *AgentRegistry) Unregister(agentID string) error {
r.mu.Lock()
defer r.mu.Unlock()
if _, ok := r.agents[agentID]; !ok {
return fmt.Errorf("agent %s not found", agentID)
}
delete(r.agents, agentID)
delete(r.ttl, agentID)
log.Printf("[灵脉] Agent 断脉离场: %s", agentID)
return nil
}
// GetAgent 获取 Agent 端点
func (r *AgentRegistry) GetAgent(agentID string) (*types.AgentEndpoint, error) {
r.mu.RLock()
defer r.mu.RUnlock()
agent, ok := r.agents[agentID]
if !ok {
return nil, fmt.Errorf("agent %s not found", agentID)
}
// 检查是否过期
if time.Now().After(r.ttl[agentID]) {
return nil, fmt.Errorf("agent %s has expired", agentID)
}
return agent, nil
}
// ListAgents 列出所有活跃 Agent
func (r *AgentRegistry) ListAgents() []types.AgentEndpoint {
r.mu.RLock()
defer r.mu.RUnlock()
agents := make([]types.AgentEndpoint, 0, len(r.agents))
now := time.Now()
for id, agent := range r.agents {
if now.Before(r.ttl[id]) {
agents = append(agents, *agent)
}
}
return agents
}
// Heartbeat 心跳保活
func (r *AgentRegistry) Heartbeat(agentID string) error {
r.mu.Lock()
defer r.mu.Unlock()
if _, ok := r.agents[agentID]; !ok {
return fmt.Errorf("agent %s not registered", agentID)
}
r.ttl[agentID] = time.Now().Add(r.config.DefaultTTL)
return nil
}
// FindByCapability 按能力查找 Agent
func (r *AgentRegistry) FindByCapability(capability string) []types.AgentEndpoint {
r.mu.RLock()
defer r.mu.RUnlock()
var result []types.AgentEndpoint
now := time.Now()
for id, agent := range r.agents {
if now.Before(r.ttl[id]) {
// 简化处理,实际需要查询能力
result = append(result, *agent)
}
}
return result
}
// =============================================================================
// Message Router - 消息路由
// =============================================================================
// Router 消息路由器
type Router struct {
registry *AgentRegistry
// 协议处理器
handlers map[string]MessageHandler
mu sync.RWMutex
config *RouterConfig
}
// MessageHandler 消息处理器接口
type MessageHandler interface {
HandleMessage(ctx context.Context, msg *types.UnifiedSynapseMessage) (*types.UnifiedSynapseMessage, error)
}
// RouterConfig 路由器配置
type RouterConfig struct {
MaxHops int // 最大跳数
EnableCaching bool // 启用路由缓存
}
// DefaultRouterConfig 返回默认路由器配置
func DefaultRouterConfig() *RouterConfig {
return &RouterConfig{
MaxHops: 10,
EnableCaching: true,
}
}
// NewRouter 创建消息路由器
func NewRouter(registry *AgentRegistry, config *RouterConfig) *Router {
if config == nil {
config = DefaultRouterConfig()
}
if registry == nil {
registry = NewAgentRegistry(nil)
}
return &Router{
registry: registry,
handlers: make(map[string]MessageHandler),
config: config,
}
}
// RegisterHandler 注册消息类型处理器
func (r *Router) RegisterHandler(msgType string, handler MessageHandler) {
r.mu.Lock()
defer r.mu.Unlock()
r.handlers[msgType] = handler
}
// Route 路由消息
func (r *Router) Route(ctx context.Context, msg *types.UnifiedSynapseMessage) (*types.UnifiedSynapseMessage, error) {
if msg.Receiver == nil {
return nil, fmt.Errorf("receiver is required")
}
// 查找接收方
_, err := r.registry.GetAgent(msg.Receiver.AgentID)
if err != nil {
return nil, fmt.Errorf("route failed: agent not found: %w", err)
}
// 查找处理器
r.mu.RLock()
handler, ok := r.handlers[msg.Type]
r.mu.RUnlock()
if !ok {
return nil, fmt.Errorf("no handler for message type: %s", msg.Type)
}
log.Printf("[灵脉] 路由消息: %s -> %s (类型: %s)",
msg.Sender.AgentID, msg.Receiver.AgentID, msg.Type)
return handler.HandleMessage(ctx, msg)
}
// =============================================================================
// Topology Manager - 拓扑管理
// =============================================================================
// TopologyType 拓扑类型
type TopologyType string
const (
TopologyStar TopologyType = "star" // 星型拓扑
TopologyMesh TopologyType = "mesh" // 网状拓扑
TopologyRing TopologyType = "ring" // 环形拓扑
TopologyTree TopologyType = "tree" // 树形拓扑
TopologyHybrid TopologyType = "hybrid" // 混合拓扑
)
// TopologyManager 拓扑管理器
type TopologyManager struct {
mu sync.RWMutex
topologies map[string]*NetworkTopology
}
// NetworkTopology 网络拓扑
type NetworkTopology struct {
ID string `json:"id"`
Name string `json:"name"`
Type TopologyType `json:"type"`
Nodes map[string]bool `json:"nodes"`
Edges map[string][]string `json:"edges"` // node_id -> connected_nodes
Config map[string]interface{} `json:"config"`
}
// NewTopologyManager 创建拓扑管理器
func NewTopologyManager() *TopologyManager {
return &TopologyManager{
topologies: make(map[string]*NetworkTopology),
}
}
// CreateTopology 创建拓扑
func (tm *TopologyManager) CreateTopology(id, name string, topologyType TopologyType) *NetworkTopology {
tm.mu.Lock()
defer tm.mu.Unlock()
topo := &NetworkTopology{
ID: id,
Name: name,
Type: topologyType,
Nodes: make(map[string]bool),
Edges: make(map[string][]string),
Config: make(map[string]interface{}),
}
tm.topologies[id] = topo
log.Printf("[灵脉] 创建拓扑: %s (%s, %s)", id, name, topologyType)
return topo
}
// AddNode 添加节点
func (tm *TopologyManager) AddNode(topologyID, nodeID string) error {
tm.mu.Lock()
defer tm.mu.Unlock()
topo, ok := tm.topologies[topologyID]
if !ok {
return fmt.Errorf("topology %s not found", topologyID)
}
topo.Nodes[nodeID] = true
if _, ok := topo.Edges[nodeID]; !ok {
topo.Edges[nodeID] = []string{}
}
return nil
}
// AddEdge 添加边
func (tm *TopologyManager) AddEdge(topologyID, from, to string) error {
tm.mu.Lock()
defer tm.mu.Unlock()
topo, ok := tm.topologies[topologyID]
if !ok {
return fmt.Errorf("topology %s not found", topologyID)
}
if !topo.Nodes[from] || !topo.Nodes[to] {
return fmt.Errorf("node not found in topology")
}
topo.Edges[from] = append(topo.Edges[from], to)
topo.Edges[to] = append(topo.Edges[to], from)
return nil
}
// GetNeighbors 获取邻居节点
func (tm *TopologyManager) GetNeighbors(topologyID, nodeID string) ([]string, error) {
tm.mu.RLock()
defer tm.mu.RUnlock()
topo, ok := tm.topologies[topologyID]
if !ok {
return nil, fmt.Errorf("topology %s not found", topologyID)
}
neighbors, ok := topo.Edges[nodeID]
if !ok {
return []string{}, nil
}
return neighbors, nil
}
// ToJSON 导出为 JSON
func (t *NetworkTopology) ToJSON() string {
data, _ := json.MarshalIndent(t, "", " ")
return string(data)
}