orca.ai/pkg/actor/system.go

// Package actor 为 Orca 框架实现 Actor 模型。
package actor

import (
	"fmt"
	"sync"
	"sync/atomic"

	"github.com/orca/orca/pkg/tool"
)

// System 管理 Orca Actor 框架中所有智能体的生命周期。
//
// 它提供集中式的智能体创建、监控和关闭功能。
// 智能体通过唯一 ID 标识，并按角色组织。
type System struct {
	mu     sync.RWMutex
	agents map[string]Agent
	nextID int64
}

// NewSystem 创建一个新的空 Actor 系统。
func NewSystem() *System {
	return &System{
		agents: make(map[string]Agent),
	}
}

// AgentInfo 保存关于已管理智能体的摘要信息。
type AgentInfo struct {
	ID     string      `json:"id"`
	Role   string      `json:"role"`
	Status ActorStatus `json:"status"`
}

// CreateOrchestrator 创建一个新的 Orchestrator 智能体并注册它。
func (s *System) CreateOrchestrator(bus interface{}) (*Orchestrator, error) {
	id := s.nextAgentID("orch")
	return s.addOrchestrator(id, bus)
}

// CreateWorker 创建一个新的 Worker 智能体并注册它。
func (s *System) CreateWorker() (*Worker, error) {
	id := s.nextAgentID("worker")
	return s.addWorker(id)
}

// CreateToolWorker 使用给定的工具管理器创建一个新的 ToolWorker 智能体并注册它。
func (s *System) CreateToolWorker(manager *tool.Manager) (*ToolWorker, error) {
	id := s.nextAgentID("tool")
	return s.addToolWorker(id, manager)
}

// nextAgentID 使用给定前缀生成唯一的智能体 ID。
func (s *System) nextAgentID(prefix string) string {
	n := atomic.AddInt64(&s.nextID, 1)
	return fmt.Sprintf("%s-%d", prefix, n)
}

// addOrchestrator 创建并注册一个编排器。
func (s *System) addOrchestrator(id string, busInterface interface{}) (*Orchestrator, error) {
	mb, ok := busInterface.(interface{ Bus() })
	var orch *Orchestrator
	if ok {
		// If busInterface has a Bus() method, we could extract it here
		_ = mb
	}
	orch = NewOrchestrator(id, nil)

	s.mu.Lock()
	s.agents[id] = orch
	s.mu.Unlock()

	return orch, nil
}

// addWorker 创建并注册一个工作器。
func (s *System) addWorker(id string) (*Worker, error) {
	w := NewWorker(id)

	s.mu.Lock()
	s.agents[id] = w
	s.mu.Unlock()

	return w, nil
}

// addToolWorker 使用给定的工具管理器创建并注册一个工具工作器。
func (s *System) addToolWorker(id string, manager *tool.Manager) (*ToolWorker, error) {
	w := NewToolWorker(id, manager)

	s.mu.Lock()
	s.agents[id] = w
	s.mu.Unlock()

	return w, nil
}

// StopAgent 通过 ID 停止并移除单个智能体。
func (s *System) StopAgent(id string) error {
	s.mu.Lock()
	agent, ok := s.agents[id]
	if !ok {
		s.mu.Unlock()
		return fmt.Errorf("agent %s not found", id)
	}
	delete(s.agents, id)
	s.mu.Unlock()

	return agent.Stop()
}

// GetAgent 通过 ID 检索已注册的智能体。
func (s *System) GetAgent(id string) (Agent, bool) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	agent, ok := s.agents[id]
	return agent, ok
}

// ListAgents 返回所有已注册的智能体。
func (s *System) ListAgents() []Agent {
	s.mu.RLock()
	defer s.mu.RUnlock()

	agents := make([]Agent, 0, len(s.agents))
	for _, a := range s.agents {
		agents = append(agents, a)
	}
	return agents
}

// AgentInfos 返回所有已注册智能体的摘要信息。
func (s *System) AgentInfos() []AgentInfo {
	s.mu.RLock()
	defer s.mu.RUnlock()

	infos := make([]AgentInfo, 0, len(s.agents))
	for _, a := range s.agents {
		// Try to get status from BaseAgent
		status := StatusIdle
		if ba, ok := a.(*BaseAgent); ok {
			status = ba.Status()
		} else if orch, ok := a.(*Orchestrator); ok {
			status = orch.Status()
		} else if w, ok := a.(*Worker); ok {
			status = w.Status()
		} else if tw, ok := a.(*ToolWorker); ok {
			status = tw.Status()
		}

		infos = append(infos, AgentInfo{
			ID:     a.ID(),
			Role:   a.Role(),
			Status: status,
		})
	}
	return infos
}

// StopAll 优雅地停止所有已注册的智能体。
func (s *System) StopAll() error {
	s.mu.Lock()
	defer s.mu.Unlock()

	var lastErr error
	for id, agent := range s.agents {
		if err := agent.Stop(); err != nil {
			lastErr = err
		}
		delete(s.agents, id)
	}
	return lastErr
}

// AgentCount 返回已注册智能体的数量。
func (s *System) AgentCount() int {
	s.mu.RLock()
	defer s.mu.RUnlock()
	return len(s.agents)
}