core

package
v0.35.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 29, 2025 License: MIT Imports: 10 Imported by: 0

README

Core Package

Core 包提供 Aster 框架的核心抽象：Agent 池管理和多 Agent 协作。

组件

Pool - Agent 生命周期管理

Pool 负责管理多个 Agent 的生命周期，提供创建、获取、删除和列表功能。

// 创建 Pool
pool := core.NewPool(&core.PoolOptions{
    Dependencies: deps,
    MaxAgents:    50,
})
defer pool.Shutdown()

// 创建 Agent
config := &types.AgentConfig{
    AgentID:    "my-agent",
    TemplateID: "assistant",
    // ...
}
agent, err := pool.Create(ctx, config)

// 获取 Agent
agent, exists := pool.Get("my-agent")

// 列出所有 Agent
allAgents := pool.List("")

// 按前缀过滤
workers := pool.List("worker-")

// 移除 Agent
pool.Remove("my-agent")
Room - 多 Agent 协作空间

Room 提供多个 Agent 之间的消息路由、广播和点对点通信功能。

// 创建 Room
room := core.NewRoom(pool)

// 添加成员
room.Join("alice", "agent-1")
room.Join("bob", "agent-2")

// 发送消息（支持 @mention）
room.Say(ctx, "alice", "Hello @bob!")

// 广播消息
room.Broadcast(ctx, "Meeting starts now")

// 点对点消息
room.SendTo(ctx, "alice", "bob", "Private message")

// 查看成员
members := room.GetMembers()

// 查看历史
history := room.GetHistory()

使用场景

1. 多租户系统
pool := core.NewPool(&core.PoolOptions{
    Dependencies: deps,
    MaxAgents:    1000,
})

// 为每个用户创建独立的 Agent
for _, userID := range users {
    config := &types.AgentConfig{
        AgentID:    fmt.Sprintf("user-%s", userID),
        TemplateID: "assistant",
    }
    pool.Create(ctx, config)
}
2. 团队协作
// 创建团队 Room
team := core.NewRoom(pool)
team.Join("leader", "leader-1")
team.Join("dev1", "developer-1")
team.Join("dev2", "developer-2")

// 团队沟通
team.Say(ctx, "leader", "Let's start the sprint planning")
team.Say(ctx, "dev1", "@leader I have a question")
3. 任务队列
// 创建 Worker Pool
for i := 0; i < 10; i++ {
    config := &types.AgentConfig{
        AgentID:    fmt.Sprintf("worker-%d", i),
        TemplateID: "worker",
    }
    pool.Create(ctx, config)
}

// 分配任务
workers := pool.List("worker-")
for _, workerID := range workers {
    agent, _ := pool.Get(workerID)
    agent.Send(ctx, task)
}

设计原则

  1. 简洁性：Pool 和 Room 提供最小但完整的功能集
  2. 并发安全：所有操作都是线程安全的
  3. 灵活性：支持动态添加/移除成员
  4. 可扩展性：易于集成到更高层的抽象（如 AsterOS）

与其他包的关系

  • pkg/agent: Pool 管理 Agent 实例
  • pkg/asteros: AsterOS 使用 Pool 作为核心组件
  • pkg/types: 使用类型定义进行配置

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ApprovalFunc 

type ApprovalFunc func(ctx context.Context, call *types.ToolCallRecord) (PermissionDecision, string, error)

ApprovalFunc 审批函数 返回 (decision, reason, error)

type IntervalTask 

type IntervalTask struct {
	ID       string
	Interval time.Duration
	Callback TaskCallback
	// contains filtered or unexported fields
}

IntervalTask 时间间隔任务

type PermissionDecision 

type PermissionDecision string

PermissionDecision 权限决策 

const (
	PermissionAllow PermissionDecision = "allow" // 允许
	PermissionDeny  PermissionDecision = "deny"  // 拒绝
	PermissionAsk   PermissionDecision = "ask"   // 需要询问
)

type PermissionHook 

type PermissionHook struct {
	PreToolUse  PreToolUseHook  // 工具执行前
	PostToolUse PostToolUseHook // 工具执行后
}

PermissionHook 权限钩子

type PermissionManager 

type PermissionManager struct {
	// contains filtered or unexported fields
}

PermissionManager 权限管理器

func NewPermissionManager 

func NewPermissionManager(opts *PermissionManagerOptions) *PermissionManager

NewPermissionManager 创建权限管理器

func (*PermissionManager) AddHook 

func (pm *PermissionManager) AddHook(hook PermissionHook)

AddHook 添加权限钩子

func (*PermissionManager) AddToAllowList 

func (pm *PermissionManager) AddToAllowList(toolName string)

AddToAllowList 添加到白名单

func (*PermissionManager) AddToAskList 

func (pm *PermissionManager) AddToAskList(toolName string)

AddToAskList 添加到审批列表

func (*PermissionManager) AddToDenyList 

func (pm *PermissionManager) AddToDenyList(toolName string)

AddToDenyList 添加到黑名单

func (*PermissionManager) Check 

func (pm *PermissionManager) Check(ctx context.Context, call *types.ToolCallRecord) (PermissionDecision, string, error)

Check 检查工具权限

func (*PermissionManager) ClearStats 

func (pm *PermissionManager) ClearStats()

ClearStats 清空统计

func (*PermissionManager) GetDefaultMode 

func (pm *PermissionManager) GetDefaultMode() types.PermissionMode

GetDefaultMode 获取默认模式

func (*PermissionManager) GetStats 

func (pm *PermissionManager) GetStats() PermissionStats

GetStats 获取统计信息

func (*PermissionManager) IsInAllowList 

func (pm *PermissionManager) IsInAllowList(toolName string) bool

IsInAllowList 检查是否在白名单

func (*PermissionManager) IsInAskList 

func (pm *PermissionManager) IsInAskList(toolName string) bool

IsInAskList 检查是否在审批列表

func (*PermissionManager) IsInDenyList 

func (pm *PermissionManager) IsInDenyList(toolName string) bool

IsInDenyList 检查是否在黑名单

func (*PermissionManager) RemoveFromLists 

func (pm *PermissionManager) RemoveFromLists(toolName string)

RemoveFromLists 从所有列表中移除

func (*PermissionManager) RemoveRule 

func (pm *PermissionManager) RemoveRule(toolName string)

RemoveRule 移除工具规则

func (*PermissionManager) RequestApproval 

func (pm *PermissionManager) RequestApproval(ctx context.Context, call *types.ToolCallRecord) (PermissionDecision, string, error)

RequestApproval 请求审批

func (*PermissionManager) RunPostHooks 

func (pm *PermissionManager) RunPostHooks(ctx context.Context, call *types.ToolCallRecord, result any, callErr error) error

RunPostHooks 运行后置钩子

func (*PermissionManager) RunPreHooks 

func (pm *PermissionManager) RunPreHooks(ctx context.Context, call *types.ToolCallRecord) (*types.ToolCallRecord, error)

RunPreHooks 运行前置钩子

func (*PermissionManager) SetApprovalFunc 

func (pm *PermissionManager) SetApprovalFunc(f ApprovalFunc)

SetApprovalFunc 设置审批函数

func (*PermissionManager) SetDefaultMode 

func (pm *PermissionManager) SetDefaultMode(mode types.PermissionMode)

SetDefaultMode 设置默认模式

func (*PermissionManager) SetRule 

func (pm *PermissionManager) SetRule(toolName string, decision PermissionDecision, reason string)

SetRule 设置工具规则

type PermissionManagerOptions 

type PermissionManagerOptions struct {
	DefaultMode  types.PermissionMode
	AllowList    []string
	DenyList     []string
	AskList      []string
	ApprovalFunc ApprovalFunc
}

PermissionManagerOptions 权限管理器配置

type PermissionStats 

type PermissionStats struct {
	TotalChecks    int64
	AllowedCount   int64
	DeniedCount    int64
	ApprovalCount  int64
	HookErrorCount int64
}

PermissionStats 权限统计

type Pool 

type Pool struct {
	// contains filtered or unexported fields
}

Pool Agent 池 - 管理多个 Agent 的生命周期

func NewPool 

func NewPool(opts *PoolOptions) *Pool

NewPool 创建 Agent 池

func (*Pool) Create 

func (p *Pool) Create(ctx context.Context, config *types.AgentConfig) (*agent.Agent, error)

Create 创建新 Agent 并加入池

func (*Pool) Delete 

func (p *Pool) Delete(ctx context.Context, agentID string) error

Delete 删除 Agent (包括存储)

func (*Pool) ForEach 

func (p *Pool) ForEach(fn func(agentID string, ag *agent.Agent) error) error

ForEach 遍历所有 Agent

func (*Pool) Get 

func (p *Pool) Get(agentID string) (*agent.Agent, bool)

Get 获取指定 Agent

func (*Pool) List 

func (p *Pool) List(prefix string) []string

List 列出所有 Agent ID

func (*Pool) Remove 

func (p *Pool) Remove(agentID string) error

Remove 从池中移除 Agent (不删除存储)

func (*Pool) Resume 

func (p *Pool) Resume(ctx context.Context, agentID string, config *types.AgentConfig) (*agent.Agent, error)

Resume 从存储中恢复 Agent

func (*Pool) Shutdown 

func (p *Pool) Shutdown() error

Shutdown 关闭所有 Agent

func (*Pool) Size 

func (p *Pool) Size() int

Size 返回池中 Agent 数量

func (*Pool) Status 

func (p *Pool) Status(agentID string) (*types.AgentStatus, error)

Status 获取 Agent 状态

type PoolOptions 

type PoolOptions struct {
	Dependencies *agent.Dependencies
	MaxAgents    int // 最大 Agent 数量,默认 50
}

PoolOptions Agent 池配置

type PostToolUseHook 

type PostToolUseHook func(ctx context.Context, call *types.ToolCallRecord, result any, err error) error

PostToolUseHook 工具执行后钩子 可以检查结果或执行清理工作

type PreToolUseHook 

type PreToolUseHook func(ctx context.Context, call *types.ToolCallRecord) (*types.ToolCallRecord, error)

PreToolUseHook 工具执行前钩子 返回 (modified_call, error) 可以修改工具调用参数或返回错误来阻止执行

type Room 

type Room struct {
	// contains filtered or unexported fields
}

Room 多 Agent 协作空间 提供 Agent 间消息路由、广播和点对点通信功能

func NewRoom 

func NewRoom(pool *Pool) *Room

NewRoom 创建新的 Room

func (*Room) Broadcast 

func (r *Room) Broadcast(ctx context.Context, text string) error

Broadcast 广播消息给所有成员 (包括发送者)

func (*Room) ClearHistory 

func (r *Room) ClearHistory()

ClearHistory 清空消息历史

func (*Room) GetAgentID 

func (r *Room) GetAgentID(name string) (string, bool)

GetAgentID 获取成员对应的 Agent ID

func (*Room) GetHistory 

func (r *Room) GetHistory() []RoomMessage

GetHistory 获取消息历史

func (*Room) GetMemberCount 

func (r *Room) GetMemberCount() int

GetMemberCount 获取成员数量

func (*Room) GetMembers 

func (r *Room) GetMembers() []RoomMember

GetMembers 获取所有成员

func (*Room) IsMember 

func (r *Room) IsMember(name string) bool

IsMember 检查是否是成员

func (*Room) Join 

func (r *Room) Join(name string, agentID string) error

Join 加入 Room

func (*Room) Leave 

func (r *Room) Leave(name string) error

Leave 离开 Room

func (*Room) Say 

func (r *Room) Say(ctx context.Context, from string, text string) error

Say 在 Room 中发送消息 - 如果消息包含 @mention,则发送给被提及的成员 (点对点) - 否则广播给除发送者外的所有成员

func (*Room) SendTo 

func (r *Room) SendTo(ctx context.Context, from string, to string, text string) error

SendTo 发送消息给指定成员

type RoomMember 

type RoomMember struct {
	Name    string `json:"name"`
	AgentID string `json:"agent_id"`
}

RoomMember Room 成员信息

type RoomMessage 

type RoomMessage struct {
	From string   `json:"from"`
	To   []string `json:"to,omitempty"` // 空表示广播
	Text string   `json:"text"`
	Sent int64    `json:"sent"` // Unix timestamp
}

RoomMessage Room 消息记录

type ScheduledTask 

type ScheduledTask struct {
	ID           string
	Kind         TriggerKind
	Spec         string // 任务规格: "step:5", "interval:10s", "cron:* * * * *"
	Callback     TaskCallback
	Agent        *agent.Agent // 可选: 关联的 Agent
	LastTrigger  time.Time
	TriggerCount int64
	Enabled      bool
}

ScheduledTask 调度任务

type Scheduler 

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler 任务调度器 支持步骤触发、定时触发、Cron 表达式 (TODO)、文件监听 (TODO)

func NewScheduler 

func NewScheduler(opts *SchedulerOptions) *Scheduler

NewScheduler 创建调度器

func (*Scheduler) Cancel 

func (s *Scheduler) Cancel(taskID string) error

Cancel 取消任务

func (*Scheduler) Clear 

func (s *Scheduler) Clear()

Clear 清空所有任务

func (*Scheduler) EveryInterval 

func (s *Scheduler) EveryInterval(interval time.Duration, callback TaskCallback) (string, error)

EveryInterval 每隔一段时间执行

func (*Scheduler) EverySteps 

func (s *Scheduler) EverySteps(every int, callback StepCallback) (string, error)

EverySteps 每 N 步执行一次

func (*Scheduler) GetIntervalTaskCount 

func (s *Scheduler) GetIntervalTaskCount() int

GetIntervalTaskCount 获取时间间隔任务数量

func (*Scheduler) GetStepListenerCount 

func (s *Scheduler) GetStepListenerCount() int

GetStepListenerCount 获取步骤监听器数量

func (*Scheduler) GetStepTaskCount 

func (s *Scheduler) GetStepTaskCount() int

GetStepTaskCount 获取步骤任务数量

func (*Scheduler) NotifyStep 

func (s *Scheduler) NotifyStep(stepCount int)

NotifyStep 通知步骤变化 (由 Agent 调用)

func (*Scheduler) OnStep 

func (s *Scheduler) OnStep(callback StepCallback) func()

OnStep 监听每一步

func (*Scheduler) Schedule 

func (s *Scheduler) Schedule(spec string, callback TaskCallback) (string, error)

Schedule 使用调度规格创建任务

func (*Scheduler) Shutdown 

func (s *Scheduler) Shutdown()

Shutdown 关闭调度器

type SchedulerOptions 

type SchedulerOptions struct {
	// 触发回调 (用于监控和日志)
	OnTrigger func(taskID string, spec string, kind TriggerKind)
}

SchedulerOptions Scheduler 配置

type StepCallback 

type StepCallback func(ctx context.Context, stepCount int) error

StepCallback 步骤回调函数

type StepTask 

type StepTask struct {
	ID            string
	Every         int // 每 N 步触发一次
	Callback      StepCallback
	LastTriggered int
}

StepTask 步骤任务

type TaskCallback 

type TaskCallback func(ctx context.Context) error

TaskCallback 任务回调函数

type ToolPermissionRule 

type ToolPermissionRule struct {
	ToolName string
	Decision PermissionDecision
	Reason   string // 规则说明
}

ToolPermissionRule 工具权限规则

type TriggerKind 

type TriggerKind string

TriggerKind 触发类型 

const (
	TriggerKindStep      TriggerKind = "step"     // 步骤触发
	TriggerKindInterval  TriggerKind = "interval" // 时间间隔触发
	TriggerKindCron      TriggerKind = "cron"     // Cron 表达式触发 (未实现)
	TriggerKindFileWatch TriggerKind = "file"     // 文件变化触发 (未实现)
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.