interfaces

package
v0.2.4 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package interfaces 定义 Agent 领域的 Repository / Service 端口。

端口与实现分离：本包只依赖 types，具体实现在 application/repository（持久化）与 application/service（编排）。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Agent 

type Agent interface {
	// Name 返回 Provider 唯一标识。
	Name() string
	// Invoke 执行一次性任务并同步返回最终结果。
	Invoke(ctx context.Context, req types.Request, rt Runtime) (*types.Result, error)
	// Stream 执行流式请求，通过 rt.Emit 逐块输出事件，返回最终聚合结果。
	Stream(ctx context.Context, req types.Request, rt Runtime) (*types.Result, error)
}

Agent 是统一 Agent 调用接口。 每个 Provider（claude_code / codex / copilot / custom ...）都需要实现该接口。

type CheckpointRuntime 

type CheckpointRuntime interface {
	Runtime
	// LoadCheckpoint 读取当前任务的检查点；不存在时返回 nil。
	LoadCheckpoint(ctx context.Context) *types.TaskResumeState
	// SaveCheckpoint 覆盖写入检查点（检查点必须可以在一次写入中完整表达）。
	SaveCheckpoint(ctx context.Context, state *types.TaskResumeState) error
	// ClearCheckpoint 在任务正常结束后清理检查点。
	ClearCheckpoint(ctx context.Context) error
}

CheckpointRuntime 是 Runtime 的可选扩展：Agent 循环通过它读写任务的持久化检查点。

taskRuntime 实现了该接口；native 包通过类型断言使用它，避免把持久化细节耦合进 Agent 循环本身。Runtime 未实现该接口时，Agent 循环退化为纯内存执行。

type EventBus 

type EventBus interface {
	// Publish 发布一个事件给订阅了该任务（或全部任务）的订阅者。
	Publish(ctx context.Context, event types.AgentEvent)
	// Subscribe 订阅某任务的事件；taskID 为空表示订阅全部任务。
	// 返回的 unsubscribe 用于取消订阅。
	Subscribe(taskID int64, handler types.EventHandler) (unsubscribe func())
}

EventBus 是实时通知层接口：只负责“告诉 UI 状态发生了变化”，不承担状态存储。

状态源是 agent_tasks（任务）与 agent_messages（时间线）；EventBus 之上接 WS / SSE 做实时推送。

type HistoryService 

type HistoryService interface {
	// Create 记录文件的初始版本。
	Create(ctx context.Context, sessionID int64, path, content string) (*types.File, error)
	// CreateVersion 记录文件的新版本（版本号自动递增）。
	CreateVersion(ctx context.Context, sessionID int64, path, content string) (*types.File, error)
	Get(ctx context.Context, id int64) (*types.File, error)
	GetByPathAndSession(ctx context.Context, path string, sessionID int64) (*types.File, error)
	ListBySession(ctx context.Context, sessionID int64) ([]*types.File, error)
	ListLatestSessionFiles(ctx context.Context, sessionID int64) ([]*types.File, error)
	Update(ctx context.Context, file *types.File) (*types.File, error)
	Delete(ctx context.Context, id int64) error
	DeleteSessionFiles(ctx context.Context, sessionID int64) error
}

HistoryService 暴露文件历史的读写能力。

type HistoryStore 

type HistoryStore interface {
	Create(ctx context.Context, file *types.File) error
	Update(ctx context.Context, file *types.File) error
	Get(ctx context.Context, id int64) (*types.File, error)
	GetByPathAndSession(ctx context.Context, path string, sessionID int64) (*types.File, error)
	ListBySession(ctx context.Context, sessionID int64) ([]*types.File, error)
	ListByPathAndSession(ctx context.Context, path string, sessionID int64) ([]*types.File, error)
	ListLatestBySession(ctx context.Context, sessionID int64) ([]*types.File, error)
	Delete(ctx context.Context, id int64) error
	DeleteBySession(ctx context.Context, sessionID int64) error
}

HistoryStore 是文件历史的持久化端口。

type MemoryRepository 

type MemoryRepository interface {
	Create(ctx context.Context, memory *types.Memory) error
	Get(ctx context.Context, id int64) (*types.Memory, error)
	Update(ctx context.Context, memory *types.Memory) error
	Delete(ctx context.Context, id int64) error
	// ListByUser 分页查询某用户的记忆（按 UpdatedAt 降序）；kinds 为空表示全部类别。
	ListByUser(ctx context.Context, userID int64, offset, limit int, kinds ...types.MemoryKind) ([]*types.Memory, int64, error)
	// ListByUserContext 分页查询某用户的记忆，并优先返回 projectID / sessionID 匹配的记录。
	// projectID <= 0 / sessionID <= 0 时退化为普通的分页查询。
	ListByUserContext(ctx context.Context, userID int64, projectID int64, sessionID int64, offset, limit int, kinds ...types.MemoryKind) ([]*types.Memory, int64, error)
	// Search 按关键词检索某用户的记忆（返回按相关度 + 重要度排序）。
	// 基础实现为子串 / LIKE 匹配，可被更高级的检索器（向量 / 语义）替换。
	Search(ctx context.Context, userID int64, query string, limit int) ([]*types.Memory, error)
}

MemoryRepository 持久化记忆。

type MessageService 

type MessageService interface {
	Create(ctx context.Context, params types.MessageCreateParams) (types.Message, error)
	Update(ctx context.Context, message types.Message) (types.Message, error)
	Get(ctx context.Context, id int64) (types.Message, error)
	List(ctx context.Context, sessionID int64) ([]types.Message, error)
	// ListPage 分页查询某会话的消息（按 Seq 升序）；beforeSeq 为向上翻页游标，
	// 0 表示取最新一页；hasMore 表示还有更早的消息。
	ListPage(ctx context.Context, sessionID int64, beforeSeq, limit int) ([]types.Message, bool, error)
	Delete(ctx context.Context, id int64) error
	DeleteSessionMessages(ctx context.Context, sessionID int64) error
}

MessageService 提供消息的增删改查。

type MessageStore 

type MessageStore interface {
	Create(ctx context.Context, m *types.Message) error
	Update(ctx context.Context, m *types.Message) error
	Get(ctx context.Context, id int64) (*types.Message, error)
	List(ctx context.Context, sessionID int64) ([]*types.Message, error)
	// ListPage 分页查询某会话的消息（按 Seq 升序返回）。
	//
	// beforeSeq > 0 时只返回 Seq 更小的消息（向上翻页），0 表示从最新消息开始。
	// hasMore 表示在本次返回的最早一条消息之前仍有消息。
	ListPage(ctx context.Context, sessionID int64, beforeSeq, limit int) ([]*types.Message, bool, error)
	Delete(ctx context.Context, id int64) error
	DeleteBySession(ctx context.Context, sessionID int64) error
}

MessageStore 是 Message 的持久化端口。

type PermissionPolicy 

type PermissionPolicy interface {
	Check(ctx context.Context, userID int64, operation types.Operation) types.PermissionDecision
}

PermissionPolicy 判断一个 Operation 应被允许、拒绝，还是需要人工确认。

Agent 在执行前把 Operation 交给策略；策略返回 ask 时，由 PermissionManager 持久化一个 pending 的 PermissionRequest 并等待 UI 确认。

type PermissionRepository 

type PermissionRepository interface {
	Create(ctx context.Context, permission *types.PermissionRequest) error
	Get(ctx context.Context, id int64) (*types.PermissionRequest, error)
	Update(ctx context.Context, permission *types.PermissionRequest) error
	ListPendingByTask(ctx context.Context, taskID int64) ([]*types.PermissionRequest, error)
	// ListByTask 返回某任务的全部权限请求（按创建时间倒序）。
	// 恢复执行时据此把已批准的权限与待执行的工具调用精确配对。
	ListByTask(ctx context.Context, taskID int64) ([]*types.PermissionRequest, error)
	// Page 分页查询权限请求（按 CreatedAt 升序）；taskID 为 0 表示全部任务，statuses 为空表示全部状态。
	Page(ctx context.Context, offset, limit int, taskID int64, statuses ...types.PermissionStatus) ([]*types.PermissionRequest, int64, error)
}

PermissionRepository 持久化权限请求。

type ProfileRepository 

type ProfileRepository interface {
	Create(ctx context.Context, profile *types.Profile) error
	Get(ctx context.Context, id int64) (*types.Profile, error)
	Update(ctx context.Context, profile *types.Profile) error
	Delete(ctx context.Context, id int64) error
	List(ctx context.Context) ([]*types.Profile, error)
	// ClearDefault 清除除 exceptID 以外所有 Profile 的默认标记。
	ClearDefault(ctx context.Context, exceptID int64) error
}

ProfileRepository 持久化 AgentProfile（内置 Profile 与自定义 Profile 统一存储）。

type QuestionRepository 

type QuestionRepository interface {
	Create(ctx context.Context, question *types.QuestionRequest) error
	Get(ctx context.Context, id int64) (*types.QuestionRequest, error)
	Update(ctx context.Context, question *types.QuestionRequest) error
	ListPendingByTask(ctx context.Context, taskID int64) ([]*types.QuestionRequest, error)
	// ListByTask 返回某任务的全部提问请求（按创建时间倒序）。
	ListByTask(ctx context.Context, taskID int64) ([]*types.QuestionRequest, error)
	// Page 分页查询提问请求（按 CreatedAt 升序）；taskID 为 0 表示全部任务，statuses 为空表示全部状态。
	Page(ctx context.Context, offset, limit int, taskID int64, statuses ...types.QuestionStatus) ([]*types.QuestionRequest, int64, error)
}

QuestionRepository 持久化用户提问（AskUser）。与 PermissionRepository 同构。

type Runtime 

type Runtime interface {
	// Emit 输出一个流式事件。
	Emit(ctx context.Context, event types.StreamEvent) error
	// RequestPermission 创建权限请求并阻塞等待决策（allow / deny）。
	// 归属用户是执行环境属性，由 Runtime 自己持有（见 TaskAware），不再逐层传参。
	RequestPermission(ctx context.Context, operation types.Operation) (types.PermissionDecision, error)
	// WaitPermission 等待一个已存在权限请求（permissionID）的决策。
	WaitPermission(ctx context.Context, permissionID int64) (types.PermissionDecision, error)
	// AskUser 向用户提问并阻塞等待作答（提问卡片由 UI 渲染）。
	// 无 UI 的独立调用返回 ErrNoUserInputResolver。
	AskUser(ctx context.Context, input types.AskUserInput) (types.AskUserAnswer, error)
}

Runtime 是 Agent 执行期间的运行时环境，由上层（Client 或 AgentService）注入。

Agent 通过它完成三件事：

  • Emit：向外输出流式事件（文本 / 推理 / 工具调用 / 权限通知等）；
  • RequestPermission：创建一个权限请求并阻塞等待用户 / 策略决策；
  • WaitPermission：等待一个已存在的权限请求的决策（用于恢复场景）。

该接口把 Agent 与“持久化、通知、权限决策”等业务关注点解耦： Agent 只描述“要做什么”，具体“能不能做”由 Runtime 背后的 PermissionManager / Policy 决定。

type SessionService 

type SessionService interface {
	Create(ctx context.Context, params types.SessionCreateParams) (types.Session, error)
	// CreateTitleSession 为 parentSessionID 创建一个「生成标题」子会话。
	CreateTitleSession(ctx context.Context, parentSessionID int64) (types.Session, error)
	// CreateTaskSession 以 toolCallID 作为会话 ID 创建子任务会话。
	CreateTaskSession(ctx context.Context, toolCallID, parentSessionID int64, title string) (types.Session, error)
	// CreateChildSession 创建 ParentSessionID 指向父会话的子会话（主键由雪花 ID 生成）。
	CreateChildSession(ctx context.Context, params types.SessionChildParams) (types.Session, error)
	Get(ctx context.Context, id int64) (types.Session, error)
	List(ctx context.Context, params types.SessionListParams) ([]types.Session, int64, error)
	Save(ctx context.Context, session types.Session) (types.Session, error)
	Delete(ctx context.Context, id int64) error
}

SessionService 提供会话的增删改查。

type SessionStore 

type SessionStore interface {
	Create(ctx context.Context, s *types.Session) error
	Get(ctx context.Context, id int64) (*types.Session, error)
	Update(ctx context.Context, s *types.Session) error
	Delete(ctx context.Context, id int64) error
	List(ctx context.Context, params types.SessionListParams) ([]*types.Session, int64, error)
}

SessionStore 是 Session 的持久化端口。

type TaskAware 

type TaskAware interface {
	Facts() types.TaskFacts
}

TaskAware 是 Runtime 的可选扩展：暴露本次执行绑定的任务事实快照（只读）。

需要用户 / 会话 / 项目事实的 Provider 可通过 agentruntime.FactsOf 读取， Runtime 未实现该接口时得到零值。

type TaskRepository 

type TaskRepository interface {
	Create(ctx context.Context, task *types.Task) error
	Get(ctx context.Context, id int64) (*types.Task, error)
	Update(ctx context.Context, task *types.Task) error
	// UpdateResumeState 只更新可恢复执行检查点，避免与状态迁移并发时互相覆盖。
	// state 为 nil 表示清理检查点。
	UpdateResumeState(ctx context.Context, id int64, state *types.TaskResumeState) error
	ListByStatus(ctx context.Context, statuses ...types.TaskStatus) ([]*types.Task, error)
	// Page 分页查询任务（按 CreatedAt 升序）；statuses 为空表示全部状态。
	Page(ctx context.Context, offset, limit int, statuses ...types.TaskStatus) ([]*types.Task, int64, error)
}

TaskRepository 持久化 Agent 任务。

type UserAgentConfigProvider 

type UserAgentConfigProvider interface {
	GetAgentConfig(ctx context.Context, userID int64) (types.UserAgentConfig, error)
}

UserAgentConfigProvider 按 userID 读取用户的 Agent 配置（用于权限决策）。

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.