artifacts

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Feb 24, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

包 artifacts 为智能体提供产物的生成、存储与生命周期管理能力。

概述

artifacts 解决的核心问题是：智能体在执行过程中产生的文件、数据、 代码片段、模型输出等中间或最终产物，需要统一的存储、检索、版本控制 与自动清理机制。本包提供从创建到归档的完整生命周期管理。

核心接口

  • ArtifactStore：产物存储抽象接口，定义 Save / Load / Delete / List / Archive 等操作，支持可插拔的后端实现
  • Artifact：产物元数据模型，包含 ID、类型、状态、校验和、 标签、版本号、过期时间等完整描述信息

主要能力

  • 类型化存储：支持 file / data / image / code / output / model 六种产物类型，通过 ArtifactType 枚举区分
  • 生命周期状态：pending → uploading → ready → archived → deleted， 由 ArtifactStatus 驱动状态流转
  • 版本管理：通过 CreateVersion 基于已有产物创建新版本， 自动维护 ParentID 与 Version 链
  • 自动清理：Manager.Cleanup 定期扫描并删除过期产物， 基于 TTL 与 ExpiresAt 判定
  • 查询过滤：ArtifactQuery 支持按 SessionID、Type、Status、 Tags、CreatedBy 等维度组合检索
  • Functional Options：通过 WithMetadata / WithTags / WithTTL 等选项灵活配置产物创建参数

内置实现

FileStore 提供基于本地文件系统的 ArtifactStore 实现， 每个产物存储为独立目录（含 data 文件与 metadata.json）， 并维护全局 index.json 索引。适用于单机部署与开发调试场景。

与其他包协同

artifacts 通常由 Agent 执行流程中的工具调用产生， Manager 作为统一入口注入到 Agent 运行时， 使得产物管理与业务逻辑解耦。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Artifact 

type Artifact struct {
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	Type        ArtifactType   `json:"type"`
	Status      ArtifactStatus `json:"status"`
	MimeType    string         `json:"mime_type,omitempty"`
	Size        int64          `json:"size"`
	Checksum    string         `json:"checksum"`
	StoragePath string         `json:"storage_path"`
	URL         string         `json:"url,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	Tags        []string       `json:"tags,omitempty"`
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
	ExpiresAt   *time.Time     `json:"expires_at,omitempty"`
	CreatedBy   string         `json:"created_by"`
	SessionID   string         `json:"session_id,omitempty"`
	ParentID    string         `json:"parent_id,omitempty"`
	Version     int            `json:"version"`
}

人工活性代表系统中的受管文物.

type ArtifactQuery 

type ArtifactQuery struct {
	SessionID string         `json:"session_id,omitempty"`
	Type      ArtifactType   `json:"type,omitempty"`
	Status    ArtifactStatus `json:"status,omitempty"`
	Tags      []string       `json:"tags,omitempty"`
	CreatedBy string         `json:"created_by,omitempty"`
	Limit     int            `json:"limit,omitempty"`
	Offset    int            `json:"offset,omitempty"`
}

ArtifactQuery定义了列出文物的查询参数.

type ArtifactStatus 

type ArtifactStatus string

人工活性状态代表文物的生命周期状态。 

const (
	StatusPending   ArtifactStatus = "pending"
	StatusUploading ArtifactStatus = "uploading"
	StatusReady     ArtifactStatus = "ready"
	StatusArchived  ArtifactStatus = "archived"
	StatusDeleted   ArtifactStatus = "deleted"
)

type ArtifactStore 

type ArtifactStore interface {
	Save(ctx context.Context, artifact *Artifact, data io.Reader) error
	Load(ctx context.Context, artifactID string) (*Artifact, io.ReadCloser, error)
	GetMetadata(ctx context.Context, artifactID string) (*Artifact, error)
	Delete(ctx context.Context, artifactID string) error
	List(ctx context.Context, query ArtifactQuery) ([]*Artifact, error)
	Archive(ctx context.Context, artifactID string) error
}

ArtifactStore定义了文物的存储界面.

type ArtifactType 

type ArtifactType string

工艺品Type定义了文物的类型. 

const (
	ArtifactTypeFile   ArtifactType = "file"
	ArtifactTypeData   ArtifactType = "data"
	ArtifactTypeImage  ArtifactType = "image"
	ArtifactTypeCode   ArtifactType = "code"
	ArtifactTypeOutput ArtifactType = "output"
	ArtifactTypeModel  ArtifactType = "model"
)

type CreateOption 

type CreateOption func(*createOptions)

创建可选配置文物创建 。

func WithCreatedBy 

func WithCreatedBy(createdBy string) CreateOption

func WithMetadata 

func WithMetadata(metadata map[string]any) CreateOption

func WithMimeType 

func WithMimeType(mimeType string) CreateOption

func WithSessionID 

func WithSessionID(sessionID string) CreateOption

func WithTTL 

func WithTTL(ttl time.Duration) CreateOption

func WithTags 

func WithTags(tags ...string) CreateOption

type FileStore 

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

FileStore使用本地文件系统执行ArtifactStore.

func NewFileStore 

func NewFileStore(basePath string) (*FileStore, error)

NewFileStore创建了一个新的基于文件的文物商店.

func (*FileStore) Archive 

func (s *FileStore) Archive(ctx context.Context, artifactID string) error

func (*FileStore) Delete 

func (s *FileStore) Delete(ctx context.Context, artifactID string) error

func (*FileStore) GetMetadata 

func (s *FileStore) GetMetadata(ctx context.Context, artifactID string) (*Artifact, error)

func (*FileStore) List 

func (s *FileStore) List(ctx context.Context, query ArtifactQuery) ([]*Artifact, error)

func (*FileStore) Load 

func (s *FileStore) Load(ctx context.Context, artifactID string) (*Artifact, io.ReadCloser, error)

func (*FileStore) Save 

func (s *FileStore) Save(ctx context.Context, artifact *Artifact, data io.Reader) error

type Manager 

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

经理处理文物生命周期管理.

func NewManager 

func NewManager(config ManagerConfig, store ArtifactStore, logger *zap.Logger) *Manager

NewManager创建了新的文物管理器.

func (*Manager) Archive 

func (m *Manager) Archive(ctx context.Context, artifactID string) error

档案馆收藏了一件文物

func (*Manager) Cleanup 

func (m *Manager) Cleanup(ctx context.Context) (int, error)

清理清除过期文物.

func (*Manager) Create 

func (m *Manager) Create(ctx context.Context, name string, artifactType ArtifactType, data io.Reader, opts ...CreateOption) (*Artifact, error)

从数据创建出新的文物 。

func (*Manager) CreateVersion 

func (m *Manager) CreateVersion(ctx context.Context, parentID string, data io.Reader) (*Artifact, error)

CreateVersion 创建了新版本的已有文物.

func (*Manager) Delete 

func (m *Manager) Delete(ctx context.Context, artifactID string) error

删除一个文物。

func (*Manager) Get 

func (m *Manager) Get(ctx context.Context, artifactID string) (*Artifact, io.ReadCloser, error)

凭身份证取回文物

func (*Manager) GetMetadata 

func (m *Manager) GetMetadata(ctx context.Context, artifactID string) (*Artifact, error)

GetMetadata检索没有数据的文物元数据.

func (*Manager) List 

func (m *Manager) List(ctx context.Context, query ArtifactQuery) ([]*Artifact, error)

列表列出符合查询的文物.

type ManagerConfig 

type ManagerConfig struct {
	BasePath   string        `json:"base_path"`
	MaxSize    int64         `json:"max_size"`
	DefaultTTL time.Duration `json:"default_ttl"`
}

Manager Config 配置了文物管理器 。

func DefaultManagerConfig 

func DefaultManagerConfig() ManagerConfig

默认管理器 Config 返回合理的默认值 。

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.