agent

type AssistantClient = model.AssistantClient

type Attachment struct {
	// Name 附件名称，用于提示词中展示给模型。
	Name string `json:"name"`
	// Size 附件大小，模型无法直接读取文件时会作为辅助说明。
	Size int64 `json:"size"`
	// URL 附件地址，用于追踪来源；不会直接作为远端图片地址传给模型。
	URL string `json:"url"`
	// MIMEType 附件 MIME 类型，决定文本提取和图片输入路径。
	MIMEType string `json:"mimeType"`
	// Content 附件文本内容，通常来自文本、JSON、XML、CSV 等可直接读取的文件。
	Content string `json:"content"`
	// Bytes 附件原始字节，图片类附件会通过该字段作为视觉输入传给模型。
	Bytes []byte `json:"-"`
}

type ChatClient = model.ChatClient

type Message struct {
	// Role 消息角色，只允许 user 或 ai。
	Role string `json:"role"`
	// Content 消息正文，进入模型前会再次过滤空白内容。
	Content string `json:"content"`
	// Tools 当前历史轮次实际使用过的工具，仅用于短追问时延续候选工具。
	Tools []ToolUsage `json:"tools"`
}

type MessageLocalizer func(ctx context.Context, key string, args map[string]any, fallback string) string

type Part = structured.Part

type Response struct {
	// Content 回复正文，面向前端展示。
	Content string `json:"content"`
	// Token 本次调用 token 消耗。
	Token TokenUsage `json:"token"`
	// Tools 本轮回复实际使用的工具列表。
	Tools []ToolUsage `json:"tools"`
	// Source 回复来源，例如 llm 或 fallback。
	Source string `json:"source"`
	// Model 使用的模型名称，便于前端展示和排障。
	Model string `json:"model"`
	// Fallback 标记本次回复是否由本地兜底逻辑生成。
	Fallback bool `json:"fallback"`
	// FallbackReason 记录触发降级的底层错误信息，仅用于排障和后台展示。
	FallbackReason string `json:"fallbackReason"`
	// Flow 记录本次回复所属的模块固定流程。
	Flow string `json:"flow"`
	// Step 记录本次回复所属的流程步骤。
	Step string `json:"step"`
	// BlocksJSON 记录模块定义的结构化内容 JSON。
	BlocksJSON string `json:"blocksJson"`
}

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

type RuntimeConfig struct {
	// Client 是 AI 助手模型客户端。
	Client *AssistantClient
	// ClientResolver 根据请求选择数据库配置的模型客户端。
	ClientResolver model.AssistantClientResolver
	// Checker 是可选的工具权限检查器；为 nil 时全部注册工具默认启用。
	Checker ToolAccessChecker
	// AdminTools 是管理端工具集合。
	AdminTools []Tool
	// AppTools 是应用端工具集合。
	AppTools []Tool
	// LocalizeMessage 是可选消息本地化器；未提供时使用消息的英文兜底文案。
	LocalizeMessage MessageLocalizer
}

type RuntimeInput struct {
	// Terminal 终端标识，例如 admin 或 app，会注入到系统提示词。
	Terminal string
	// UserName 当前用户展示名称，会注入到系统提示词供模型理解上下文。
	UserName string
	// SessionTitle 当前会话标题，会注入到系统提示词供模型理解会话语境。
	SessionTitle string
	// SessionID 当前会话编号，预留给后续追踪、工具调用或日志串联。
	SessionID string
	// ProviderID 当前选择的AI供应商编号。
	ProviderID int64
	// ModelName 当前选择的模型名称。
	ModelName string
	// Summary 当前会话摘要，会注入到系统提示词作为压缩后的长期上下文。
	Summary string
	// KnowledgeContext 知识库检索注入的上下文，非空时追加到系统提示词。
	KnowledgeContext string
	// Content 本轮用户文本内容。
	Content string
	// Attachments 本轮用户附件列表，已经由业务层读取过可用内容。
	Attachments []Attachment
	// History 会话历史消息，按时间正序传入。
	History []Message
}

type Schema = structured.Schema

type StructuredRunner = structured.Runner

type TokenUsage struct {
	// Input 输入 token 数。
	Input int32 `json:"input"`
	// Output 输出 token 数。
	Output int32 `json:"output"`
	// Cache 命中缓存 token 数。
	Cache int32 `json:"cache"`
	// Total 总 token 数。
	Total int32 `json:"total"`
}

type Tool = tool.InvokableTool

type ToolAccessChecker interface {
	// ToolConfigs 返回当前终端允许暴露给 Agent 的工具配置。
	ToolConfigs(ctx context.Context, terminal string, names []string) (map[string]ToolConfig, error)
}

type ToolConfig struct {
	// Enabled 表示工具是否允许暴露给 Agent。
	Enabled bool
	// Prompts 表示覆盖生成工具描述和命中判断的业务提示词。
	Prompts []string
}

type ToolInvokeResult struct {
	// Output 工具原始输出 JSON。
	Output string
	// Usage 本次工具调用的后台展示记录。
	Usage ToolUsage
}

type ToolUsage struct {
	// Type 工具类型，例如 function 或 server。
	Type string `json:"type"`
	// Name 工具名称，用于排障和唯一识别。
	Name string `json:"name"`
	// Title 工具展示名称，优先使用生成工具描述。
	Title string `json:"title"`
	// Status 工具状态，例如 success、error。
	Status string `json:"status"`
	// Input 工具原始入参 JSON，用于后台展开排障。
	Input string `json:"input"`
	// Output 工具原始出参 JSON，用于后台展开排障。
	Output string `json:"output"`
}