persistence

type AsyncTask struct {
	// ID 是任务的唯一标识符
	ID string `json:"id"`

	// 会话ID 是此任务所属的会话
	SessionID string `json:"session_id,omitempty"`

	// AgentID 是执行此任务的代理
	AgentID string `json:"agent_id"`

	// 类型是任务类型
	Type string `json:"type"`

	// 状态是当前任务状态
	Status TaskStatus `json:"status"`

	// 输入包含任务输入数据
	Input map[string]any `json:"input,omitempty"`

	// 结果包含任务结果(完成后)
	Result any `json:"result,omitempty"`

	// 错误包含错误消息( 当失败时)
	Error string `json:"error,omitempty"`

	// 进展是任务进展(0-100)
	Progress float64 `json:"progress"`

	// 优先是任务优先(较高=更重要)
	Priority int `json:"priority"`

	// CreatedAt 是任务创建时
	CreatedAt time.Time `json:"created_at"`

	// 更新到上次更新任务时
	UpdatedAt time.Time `json:"updated_at"`

	// 开始是任务开始执行时
	StartedAt *time.Time `json:"started_at,omitempty"`

	// 任务完成时
	CompletedAt *time.Time `json:"completed_at,omitempty"`

	// 超时是任务超时的期限
	Timeout time.Duration `json:"timeout,omitempty"`

	// 重试请求是重试尝试的次数
	RetryCount int `json:"retry_count"`

	// MaxRetries 是允许的最大重试次数
	MaxRetries int `json:"max_retries"`

	// 元数据包含额外的任务元数据
	Metadata map[string]string `json:"metadata,omitempty"`

	// 父任务ID 是父任务ID( 用于子任务)
	ParentTaskID string `json:"parent_task_id,omitempty"`

	// 儿童任务ID是儿童任务ID
	ChildTaskIDs []string `json:"child_task_ids,omitempty"`
}

type CleanupConfig struct {
	// 启用后确定是否启用自动清理
	Enabled bool `json:"enabled" yaml:"enabled"`

	// 间断是清理运行的频率( 默认:1 h)
	Interval time.Duration `json:"interval" yaml:"interval"`

	// 保留信件是保留已确认信件的时间( 默认为 1h)
	MessageRetention time.Duration `json:"message_retention" yaml:"message_retention"`

	// 任务保留是保存已完成任务的时间( 默认: 24h)
	TaskRetention time.Duration `json:"task_retention" yaml:"task_retention"`
}

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

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

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

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

type Message struct {
	// ID 是信件的唯一标识符
	ID string `json:"id"`

	// 题目是信息主题/频道
	Topic string `json:"topic"`

	// FromID 是发送代理 ID
	FromID string `json:"from_id"`

	// ToID 是接收代理ID( 空来播放)
	ToID string `json:"to_id,omitempty"`

	// 类型是信件类型(提议、回应、表决等)
	Type string `json:"type"`

	// 内容是信件内容
	Content string `json:"content"`

	// 有效载荷包含额外的结构化数据
	Payload map[string]any `json:"payload,omitempty"`

	// 元数据包含信件元数据
	Metadata map[string]string `json:"metadata,omitempty"`

	// 创建到信件创建时
	CreatedAt time.Time `json:"created_at"`

	// AckedAt是消息被承认的时候(即使没有被承认也没有)
	AckedAt *time.Time `json:"acked_at,omitempty"`

	// 重试( Rettry Count) 是送货尝试的次数
	RetryCount int `json:"retry_count"`

	// Last RetryAt 是上次尝试重试时
	LastRetryAt *time.Time `json:"last_retry_at,omitempty"`

	// 过期是信件过期时( 可选)
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

type MessageFilter struct {
	// 按主题划分的专题过滤器
	Topic string `json:"topic,omitempty"`

	// 发送者从ID中过滤
	FromID string `json:"from_id,omitempty"`

	// 收件人的 ToID 过滤器
	ToID string `json:"to_id,omitempty"`

	// 按信件类型输入过滤器
	Type string `json:"type,omitempty"`

	// 通过承认状态进行状态过滤
	Status MessageStatus `json:"status,omitempty"`

	// 在此时间之后创建过滤信件
	CreatedAfter *time.Time `json:"created_after,omitempty"`

	// 在此之前创建过滤信件
	CreatedBefore *time.Time `json:"created_before,omitempty"`

	// 限定要返回的信件的最大数量
	Limit int `json:"limit,omitempty"`

	// 偏移为要跳过的信件数量
	Offset int `json:"offset,omitempty"`
}

type MessageStatus string

type MessageStore interface {
	Store

	// 保存Message 坚持给商店的单个消息
	SaveMessage(ctx context.Context, msg *Message) error

	// 保存消息在解剖上持续了多个消息
	SaveMessages(ctx context.Context, msgs []*Message) error

	// 通过 ID 获取信件
	GetMessage(ctx context.Context, msgID string) (*Message, error)

	// GetMessages 获取带有 pagination 主题的信息
	// 返回信件、 下个光标和错误
	GetMessages(ctx context.Context, topic string, cursor string, limit int) ([]*Message, string, error)

	// AckMessage 标记已确认/处理的信息
	AckMessage(ctx context.Context, msgID string) error

	// 获取未保存的邮件获取未确认的比指定时间长的信件
	// 这些留言是重试的候选人
	GetUnackedMessages(ctx context.Context, topic string, olderThan time.Duration) ([]*Message, error)

	// GetPendingMessages 检索需要发送的信件
	// 这包括需要重试的新信件和信件
	GetPendingMessages(ctx context.Context, topic string, limit int) ([]*Message, error)

	// 递增
	IncrementRetry(ctx context.Context, msgID string) error

	// 删除信件从存储处删除
	DeleteMessage(ctx context.Context, msgID string) error

	// 清理删除旧消息
	Cleanup(ctx context.Context, olderThan time.Duration) (int, error)

	// Stats 返回关于消息库的统计数据
	Stats(ctx context.Context) (*MessageStoreStats, error)
}

type MessageStoreStats struct {
	// TotalMessages 为商店中信件的总数
	TotalMessages int64 `json:"total_messages"`

	// 未决信件是未确认信件的数量
	PendingMessages int64 `json:"pending_messages"`

	// AckedMessages 是确认消息的数量
	AckedMessages int64 `json:"acked_messages"`

	// 过期信件是过期信件的数量
	ExpiredMessages int64 `json:"expired_messages"`

	// 主题计数为每个主题的信息数
	TopicCounts map[string]int64 `json:"topic_counts"`

	// 最老的PendingAge是最老的待发消息的年龄
	OldestPendingAge time.Duration `json:"oldest_pending_age"`
}

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

type RedisStoreConfig struct {
	// 主机是 Redis 服务器主机
	Host string `json:"host" yaml:"host"`

	// 端口是 Redis 服务器端口
	Port int `json:"port" yaml:"port"`

	// 密码是 Redis 密码( 可选)
	Password string `json:"password" yaml:"password"`

	// DB 为 Redis 数据库编号
	DB int `json:"db" yaml:"db"`

	// PoolSize 是连接池大小
	PoolSize int `json:"pool_size" yaml:"pool_size"`

	// 密钥前缀是所有 Redis 密钥的前缀
	KeyPrefix string `json:"key_prefix" yaml:"key_prefix"`
}

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

type RetryConfig struct {
	// Max Retries 是重试尝试的最大次数( 默认 3)
	MaxRetries int `json:"max_retries" yaml:"max_retries"`

	// 初始备份是初始备份期限( 默认:1s)
	InitialBackoff time.Duration `json:"initial_backoff" yaml:"initial_backoff"`

	// MaxBackoff 是最大后退持续时间( 默认: 30s)
	MaxBackoff time.Duration `json:"max_backoff" yaml:"max_backoff"`

	// 后置倍数是指数后置的乘数( 默认: 2. 0)
	BackoffMultiplier float64 `json:"backoff_multiplier" yaml:"backoff_multiplier"`
}

type Serializable interface {
	// 元帅JSON 返回对象的 JSON 编码
	json.Marshaler
	// UnmarshalJSON 解析 JSON 编码数据
	json.Unmarshaler
}

type Store interface {
	// 关闭存储并释放资源
	Close() error

	// 平平检查,如果商店是健康的
	Ping(ctx context.Context) error
}

type StoreConfig struct {
	// 类型是存储后端类型
	Type StoreType `json:"type" yaml:"type"`

	// BaseDir 是基于文件存储的基础目录
	BaseDir string `json:"base_dir" yaml:"base_dir"`

	// Redis 配置( 仅在类型为 “ redis” 时使用)
	Redis RedisStoreConfig `json:"redis" yaml:"redis"`

	// 重试配置
	Retry RetryConfig `json:"retry" yaml:"retry"`

	// 清理配置
	Cleanup CleanupConfig `json:"cleanup" yaml:"cleanup"`
}

type StoreType string

type TaskEvent struct {
	// TaskID 是此事件所属的任务
	TaskID string `json:"task_id"`

	// 类型是事件类型
	Type TaskEventType `json:"type"`

	// 旧状态是上一个状态( 对于状态变化事件)
	OldStatus TaskStatus `json:"old_status,omitempty"`

	// 新状态是新状态(用于改变状态事件)
	NewStatus TaskStatus `json:"new_status,omitempty"`

	// 进步是进步价值(对于进步活动)
	Progress float64 `json:"progress,omitempty"`

	// 信件是可选事件消息
	Message string `json:"message,omitempty"`

	// 时间戳是事件发生时
	Timestamp time.Time `json:"timestamp"`
}

type TaskEventType string

type TaskFilter struct {
	// 按会话排列的会话ID过滤器
	SessionID string `json:"session_id,omitempty"`

	// 通过代理代理ID过滤器
	AgentID string `json:"agent_id,omitempty"`

	// 按任务类型分类的过滤器
	Type string `json:"type,omitempty"`

	// 按状态进行状态过滤( 可以是多个)
	Status []TaskStatus `json:"status,omitempty"`

	// 父任务过滤器
	ParentTaskID string `json:"parent_task_id,omitempty"`

	// 在此次过滤后创建任务
	CreatedAfter *time.Time `json:"created_after,omitempty"`

	// 在此之前创建过滤器任务
	CreatedBefore *time.Time `json:"created_before,omitempty"`

	// 限制是返回的最大任务数
	Limit int `json:"limit,omitempty"`

	// 偏移为要跳过的任务数
	Offset int `json:"offset,omitempty"`

	// 顺序By 指定排序顺序
	OrderBy string `json:"order_by,omitempty"`

	// 命令代斯克指定了降序
	OrderDesc bool `json:"order_desc,omitempty"`
}

type TaskStatus string

type TaskStore interface {
	Store

	// 保存任务持续到存储( 创建或更新) 。
	SaveTask(ctx context.Context, task *AsyncTask) error

	// 通过 ID 获取任务
	GetTask(ctx context.Context, taskID string) (*AsyncTask, error)

	// ListTasks 检索匹配过滤标准的任务
	ListTasks(ctx context.Context, filter TaskFilter) ([]*AsyncTask, error)

	// 更新状态更新任务状态
	UpdateStatus(ctx context.Context, taskID string, status TaskStatus, result any, errMsg string) error

	// 更新进度更新任务进度
	UpdateProgress(ctx context.Context, taskID string, progress float64) error

	// 删除任务从商店中删除任务
	DeleteTask(ctx context.Context, taskID string) error

	// 获取可回收的任务检索重启后需要回收的任务
	// 这包括待决或运行状态中的任务
	GetRecoverableTasks(ctx context.Context) ([]*AsyncTask, error)

	// 清除完成/ 失败的任务超过指定期限
	Cleanup(ctx context.Context, olderThan time.Duration) (int, error)

	// Stats 返回关于任务存储的统计
	Stats(ctx context.Context) (*TaskStoreStats, error)
}

type TaskStoreStats struct {
	// 任务总数是存储中的任务总数
	TotalTasks int64 `json:"total_tasks"`

	// 待决 任务是待决任务的数量
	PendingTasks int64 `json:"pending_tasks"`

	// 运行 任务是运行中的任务数
	RunningTasks int64 `json:"running_tasks"`

	// 已完成 任务是已完成任务的数量
	CompletedTasks int64 `json:"completed_tasks"`

	// 失败的任务是失败的任务数
	FailedTasks int64 `json:"failed_tasks"`

	// 已取消 任务是已取消的任务的数量
	CancelledTasks int64 `json:"cancelled_tasks"`

	// 状态计数为每个状态的任务数
	StatusCounts map[TaskStatus]int64 `json:"status_counts"`

	// AgentCounts 是每个代理的任务数
	AgentCounts map[string]int64 `json:"agent_counts"`

	// 平均完成任务时间
	AverageCompletionTime time.Duration `json:"average_completion_time"`

	// 最老的Ping-Age是最老的待决任务年龄
	OldestPendingAge time.Duration `json:"oldest_pending_age"`
}