handlers

package
v1.6.0 Latest Latest
Warning

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

 Go to latest Published: Mar 6, 2026 License: MIT Imports: 47 Imported by: 0

README

API Handlers

api/handlers 负责 HTTP 协议适配：请求解析、参数校验、错误映射、响应序列化。
业务执行统一下沉到 service/usecase（如 agent_service.go、rag_service.go、workflow_service.go），由 cmd/agentflow + internal/app/bootstrap 完成运行时装配。

当前职责边界

  • Handler：HTTP 入参校验、JSON 解码、SSE 写出、统一响应格式。
  • Service：执行领域用例（Agent/RAG/Workflow/APIKey/Multimodal）。
  • Bootstrap：构建 Provider/Store/Facade/Registry，并注入 Handler。

路由前缀（真实链路）

路由注册在 api/routes/routes.go，统一挂载到 /api/v1/*：

  • Chat: /api/v1/chat/capabilities、/api/v1/chat/completions、/api/v1/chat/completions/stream
  • OpenAI 兼容入站：/v1/chat/completions、/v1/responses（协议适配到同一 ChatService/gateway 链路）
  • Agent: /api/v1/agents、/api/v1/agents/capabilities、/api/v1/agents/execute、/api/v1/agents/execute/stream、/api/v1/agents/plan、/api/v1/agents/health
  • RAG: /api/v1/rag/query、/api/v1/rag/index
  • Workflow: /api/v1/workflows/execute、/api/v1/workflows/parse、/api/v1/workflows
  • Multimodal: /api/v1/multimodal/*
  • Protocol: /api/v1/mcp/*、/api/v1/a2a/*
  • Provider API Key: /api/v1/providers/*
  • Tool Registry: /api/v1/tools*
    • Tool Provider Config: /api/v1/tools/providers、/api/v1/tools/providers/{provider}、/api/v1/tools/providers/reload
  • Config API: /api/v1/config*

工具共用与自动生效

  • 对外工具注册入口：/api/v1/tools*（列表/创建/更新/删除/targets/reload）。
  • 对外工具 Provider 配置入口：/api/v1/tools/providers/*（按 provider 持久化 web_search 配置并触发 runtime reload）。
  • chat 与 agent 共享同一套 runtime ToolManager（同一注册中心，不是两套独立工具池）。
  • 当 DB 中工具注册发生变更时，服务层会触发 runtime reload；成功后会重置 agent resolver 缓存，确保新工具白名单立即生效（无需重启进程）。
  • 关键链路：cmd/agentflow/server_handlers_runtime.go（toolRegistryRuntimeAdapter.ReloadBindings -> onReload -> resolver.ResetCache）。

关键构造示例

Chat Handler
chatHandler := handlers.NewChatHandler(provider, policyManager, logger)
http.HandleFunc("/api/v1/chat/completions", chatHandler.HandleCompletion)
http.HandleFunc("/api/v1/chat/completions/stream", chatHandler.HandleStream)

说明：ChatHandler 通过 ChatService 统一路由参数并调用 llm/gateway Invoke/Stream，不在 handler 层拼装 provider 细节。

Agent Handler
agentHandler := handlers.NewAgentHandler(discoveryRegistry, agentRegistry, logger, resolver)
http.HandleFunc("GET /api/v1/agents", agentHandler.HandleListAgents)
http.HandleFunc("POST /api/v1/agents/execute", agentHandler.HandleExecuteAgent)

说明：AgentHandler 的执行、规划、流式调用统一走 AgentService。

统一响应与错误

  • 成功响应：WriteSuccess(w, data)
  • 错误响应：WriteError(w, err, logger)（types.Error）
  • 入参解析：DecodeJSONBody(...)
  • Content-Type 校验：ValidateContentType(...)

当前测试覆盖

已包含 chat/agent/apikey/multimodal/rag/workflow/common/health 等 handler 与 service 测试文件（*_test.go）。

Documentation

Overview

Package handlers: OpenAI 兼容层

设计说明（C-005/C-006）：OpenAI 兼容端点（/v1/chat/completions、/v1/responses）与自有接口 使用两套错误/响应格式，此为有意设计： - OpenAI 兼容：writeOpenAICompatError / writeOpenAICompatJSON，输出 OpenAI 规范格式（error.type/code/message） - 自有接口：WriteError / WriteSuccess，输出 api.Response 统一格式（success/error/data） 两套格式分别满足不同客户端契约，不做统一。

TODO(C-002): OpenAI 兼容错误格式与主 API 的 api.ErrorInfo 不一致， 需要在文档中说明或增加适配层统一。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeJSONBody 

func DecodeJSONBody(w http.ResponseWriter, r *http.Request, dst any, logger *zap.Logger) error

DecodeJSONBody 解码 JSON 请求体

func ValidateContentType 

func ValidateContentType(w http.ResponseWriter, r *http.Request, logger *zap.Logger) bool

ValidateContentType 验证 Content-Type 使用 mime.ParseMediaType 进行宽松解析，正确处理大小写变体 （如 "application/json; charset=UTF-8"）和额外参数。

func ValidateEnum added in v1.0.0 

func ValidateEnum(value string, allowed []string) bool

ValidateEnum checks whether value is one of the allowed values.

func ValidateNonNegative added in v1.0.0 

func ValidateNonNegative(value float64) bool

ValidateNonNegative checks that value is >= 0.

func ValidateRequest added in v1.6.0 

func ValidateRequest(w http.ResponseWriter, r *http.Request, dst any, logger *zap.Logger) bool

ValidateRequest 统一请求校验：Content-Type 检查 + JSON 解码。 适用于需要 application/json 的 POST/PUT 请求。 返回 false 表示校验失败，调用方应直接 return；dst 为解码目标。

func ValidateURL added in v1.0.0 

func ValidateURL(s string) bool

ValidateURL validates that s is a well-formed HTTP or HTTPS URL.

func WriteError 

func WriteError(w http.ResponseWriter, err *types.Error, logger *zap.Logger)

WriteError 写入错误响应（从 types.Error）

func WriteErrorMessage 

func WriteErrorMessage(w http.ResponseWriter, status int, code types.ErrorCode, message string, logger *zap.Logger)

WriteErrorMessage 写入简单错误消息

func WriteJSON 

func WriteJSON(w http.ResponseWriter, status int, data any)

WriteJSON 写入 JSON 响应

func WriteSuccess 

func WriteSuccess(w http.ResponseWriter, data any)

WriteSuccess 写入成功响应

Types

type APIKeyHandler added in v1.0.0 

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

APIKeyHandler 处理 API Key 管理的 CRUD 操作

func NewAPIKeyHandler added in v1.0.0 

func NewAPIKeyHandler(store APIKeyStore, logger *zap.Logger) *APIKeyHandler

NewAPIKeyHandler 创建 APIKeyHandler

func (*APIKeyHandler) HandleAPIKeyStats added in v1.0.0 

func (h *APIKeyHandler) HandleAPIKeyStats(w http.ResponseWriter, r *http.Request)

HandleAPIKeyStats GET /api/v1/providers/{id}/api-keys/stats

func (*APIKeyHandler) HandleCreateAPIKey added in v1.0.0 

func (h *APIKeyHandler) HandleCreateAPIKey(w http.ResponseWriter, r *http.Request)

HandleCreateAPIKey POST /api/v1/providers/{id}/api-keys

func (*APIKeyHandler) HandleDeleteAPIKey added in v1.0.0 

func (h *APIKeyHandler) HandleDeleteAPIKey(w http.ResponseWriter, r *http.Request)

HandleDeleteAPIKey DELETE /api/v1/providers/{id}/api-keys/{keyId}

func (*APIKeyHandler) HandleListAPIKeys added in v1.0.0 

func (h *APIKeyHandler) HandleListAPIKeys(w http.ResponseWriter, r *http.Request)

HandleListAPIKeys GET /api/v1/providers/{id}/api-keys Upper bound is enforced by store layer Limit; no handler-level pagination.

func (*APIKeyHandler) HandleListProviders added in v1.0.0 

func (h *APIKeyHandler) HandleListProviders(w http.ResponseWriter, r *http.Request)

HandleListProviders GET /api/v1/providers

func (*APIKeyHandler) HandleUpdateAPIKey added in v1.0.0 

func (h *APIKeyHandler) HandleUpdateAPIKey(w http.ResponseWriter, r *http.Request)

HandleUpdateAPIKey PUT /api/v1/providers/{id}/api-keys/{keyId}

type APIKeyService added in v1.4.6 

type APIKeyService interface {
	ListProviders() ([]llm.LLMProvider, *types.Error)
	ListAPIKeys(providerID uint) ([]apiKeyResponse, *types.Error)
	CreateAPIKey(providerID uint, req createAPIKeyRequest) (*apiKeyResponse, *types.Error)
	UpdateAPIKey(providerID, keyID uint, req updateAPIKeyRequest) (*apiKeyResponse, *types.Error)
	DeleteAPIKey(providerID, keyID uint) *types.Error
	ListAPIKeyStats(providerID uint) ([]apiKeyStatsResponse, *types.Error)
}

APIKeyService encapsulates API key CRUD/use-case logic for API handlers.

type APIKeyStore added in v1.0.0 

type APIKeyStore interface {
	// ListProviders returns all LLM providers ordered by ID.
	ListProviders() ([]llm.LLMProvider, error)

	// ListAPIKeys returns all API keys for a given provider, ordered by priority then ID.
	ListAPIKeys(providerID uint) ([]llm.LLMProviderAPIKey, error)

	// CreateAPIKey persists a new API key record.
	CreateAPIKey(key *llm.LLMProviderAPIKey) error

	// GetAPIKey retrieves a single API key by key ID and provider ID.
	GetAPIKey(keyID, providerID uint) (llm.LLMProviderAPIKey, error)

	// UpdateAPIKey applies partial updates to an existing API key.
	UpdateAPIKey(key *llm.LLMProviderAPIKey, updates map[string]any) error

	// ReloadAPIKey refreshes the API key record from the database.
	ReloadAPIKey(key *llm.LLMProviderAPIKey) error

	// DeleteAPIKey removes an API key by key ID and provider ID.
	// Returns the number of rows affected.
	DeleteAPIKey(keyID, providerID uint) (int64, error)
}

APIKeyStore defines the data access operations required by APIKeyHandler.

type AgentHandler 

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

AgentHandler Agent management handler

func NewAgentHandler 

func NewAgentHandler(registry discovery.Registry, agentRegistry *agent.AgentRegistry, logger *zap.Logger, resolver ...usecase.AgentResolver) *AgentHandler

NewAgentHandler creates an Agent handler. The resolver parameter is optional — if nil, execute/stream endpoints return 501.

func (*AgentHandler) HandleAgentHealth 

func (h *AgentHandler) HandleAgentHealth(w http.ResponseWriter, r *http.Request)

HandleAgentHealth checks agent health status @Summary Agent health check @Description Check if an agent is healthy and ready @Tags agent @Produce json @Param id query string true "Agent ID" @Success 200 {object} Response{data=AgentHealthResponse} "Agent health" @Failure 404 {object} Response "Agent not found" @Failure 503 {object} Response "Agent not ready" @Security ApiKeyAuth @Router /api/v1/agents/health [get]

func (*AgentHandler) HandleAgentStream added in v1.0.0 

func (h *AgentHandler) HandleAgentStream(w http.ResponseWriter, r *http.Request)

HandleAgentStream executes an agent with streaming SSE output. The agent's RuntimeStreamEmitter is wired to write SSE events to the response. SSE event types: token, tool_call, tool_result, error, and [DONE] terminator. @Summary Stream agent execution @Description Execute an agent and stream results via SSE @Tags agent @Accept json @Produce text/event-stream @Param request body AgentExecuteRequest true "Execution request" @Success 200 {string} string "SSE stream" @Failure 400 {object} Response "Invalid request" @Failure 404 {object} Response "Agent not found" @Failure 500 {object} Response "Execution failed" @Security ApiKeyAuth @Router /api/v1/agents/execute/stream [post]

func (*AgentHandler) HandleCapabilities added in v1.4.6 

func (h *AgentHandler) HandleCapabilities(w http.ResponseWriter, r *http.Request)

HandleCapabilities handles GET /api/v1/agents/capabilities

func (*AgentHandler) HandleExecuteAgent 

func (h *AgentHandler) HandleExecuteAgent(w http.ResponseWriter, r *http.Request)

HandleExecuteAgent executes an agent @Summary Execute agent @Description Execute an agent with the given input @Tags agent @Accept json @Produce json @Param request body AgentExecuteRequest true "Execution request" @Success 200 {object} Response{data=AgentExecuteResponse} "Execution result" @Failure 400 {object} Response "Invalid request" @Failure 404 {object} Response "Agent not found" @Failure 500 {object} Response "Execution failed" @Security ApiKeyAuth @Router /api/v1/agents/execute [post]

func (*AgentHandler) HandleGetAgent 

func (h *AgentHandler) HandleGetAgent(w http.ResponseWriter, r *http.Request)

HandleGetAgent gets a single agent's information @Summary Get agent @Description Get information about a specific agent @Tags agent @Produce json @Param id path string true "Agent ID" @Success 200 {object} Response{data=AgentInfo} "Agent info" @Failure 404 {object} Response "Agent not found" @Security ApiKeyAuth @Router /api/v1/agents/{id} [get]

func (*AgentHandler) HandleListAgents 

func (h *AgentHandler) HandleListAgents(w http.ResponseWriter, r *http.Request)

HandleListAgents lists all registered agents @Summary List agents @Description Get a list of all registered agents @Tags agent @Produce json @Success 200 {object} Response{data=[]AgentInfo} "Agent list" @Failure 500 {object} Response "Internal error" @Security ApiKeyAuth @Router /api/v1/agents [get]

func (*AgentHandler) HandlePlanAgent 

func (h *AgentHandler) HandlePlanAgent(w http.ResponseWriter, r *http.Request)

HandlePlanAgent plans agent execution @Summary Plan agent execution @Description Get an execution plan for an agent @Tags agent @Accept json @Produce json @Param request body AgentExecuteRequest true "Plan request" @Success 200 {object} Response{data=map[string]any} "Execution plan" @Failure 400 {object} Response "Invalid request" @Failure 404 {object} Response "Agent not found" @Failure 500 {object} Response "Plan failed" @Security ApiKeyAuth @Router /api/v1/agents/plan [post]

type AgentHealthResponse 

type AgentHealthResponse struct {
	AgentID   string  `json:"agent_id"`
	Status    string  `json:"status"`
	Healthy   bool    `json:"healthy"`
	Endpoint  string  `json:"endpoint,omitempty"`
	Load      float64 `json:"load"`
	CheckedAt string  `json:"checked_at"`
}

AgentHealthResponse Agent health check response

type AgentInfo 

type AgentInfo struct {
	ID          string          `json:"id"`
	Name        string          `json:"name"`
	Type        agent.AgentType `json:"type"`
	State       string          `json:"state"`
	Description string          `json:"description,omitempty"`
	Model       string          `json:"model,omitempty"`
	CreatedAt   string          `json:"created_at,omitempty"`
}

AgentInfo Agent information returned by the API

type ChatConverter added in v1.4.6 

type ChatConverter interface {
	ToLLMRequest(req *api.ChatRequest) *llm.ChatRequest
	ToAPIResponse(resp *llm.ChatResponse) *api.ChatResponse
	ToAPIChoices(choices []llm.ChatChoice) []api.ChatChoice
	ToAPIUsage(usage llm.ChatUsage) api.ChatUsage
	ToAPIStreamChunk(chunk *llm.StreamChunk) *api.StreamChunk
}

ChatConverter centralizes request/response conversion between API and LLM layers. Implements usecase.ChatConverter (ToLLMRequest, ToAPIResponse) and extends with stream/choices/usage.

type ChatHandler 

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

ChatHandler 聊天接口处理器

func NewChatHandler 

func NewChatHandler(provider llm.Provider, policyManager *llmpolicy.Manager, logger *zap.Logger) *ChatHandler

NewChatHandler 创建聊天处理器

func NewChatHandlerWithRuntime added in v1.4.6 

func NewChatHandlerWithRuntime(
	provider llm.Provider,
	policyManager *llmpolicy.Manager,
	toolManager agent.ToolManager,
	ledger observability.Ledger,
	logger *zap.Logger,
) *ChatHandler

NewChatHandlerWithRuntime creates a chat handler with routing runtime dependencies.

func NewChatHandlerWithService added in v1.4.6 

func NewChatHandlerWithService(service usecase.ChatService, logger *zap.Logger) *ChatHandler

NewChatHandlerWithService creates a chat handler with an explicit service.

func (*ChatHandler) HandleCapabilities added in v1.4.6 

func (h *ChatHandler) HandleCapabilities(w http.ResponseWriter, r *http.Request)

HandleCapabilities handles GET /api/v1/chat/capabilities

func (*ChatHandler) HandleCompletion 

func (h *ChatHandler) HandleCompletion(w http.ResponseWriter, r *http.Request)

HandleCompletion 处理聊天补全请求 @Summary 聊天完成 @Description 发送聊天完成请求 @Tags 聊天 @Accept json @Produce json @Param request body api.ChatRequest true "聊天请求" @Success 200 {object} api.ChatResponse "聊天响应" @Failure 400 {object} Response "无效请求" @Failure 500 {object} Response "内部错误" @Security ApiKeyAuth @Router /api/v1/chat/completions [post]

func (*ChatHandler) HandleOpenAICompatChatCompletions added in v1.5.0 

func (h *ChatHandler) HandleOpenAICompatChatCompletions(w http.ResponseWriter, r *http.Request)

func (*ChatHandler) HandleOpenAICompatResponses added in v1.5.0 

func (h *ChatHandler) HandleOpenAICompatResponses(w http.ResponseWriter, r *http.Request)

func (*ChatHandler) HandleStream 

func (h *ChatHandler) HandleStream(w http.ResponseWriter, r *http.Request)

HandleStream 处理流式聊天请求 @Summary 流式聊天完成 @Description 发送流式聊天完成请求 @Tags 聊天 @Accept json @Produce text/event-stream @Param request body api.ChatRequest true "聊天请求" @Success 200 {string} string "SSE 流" @Failure 400 {object} Response "无效请求" @Failure 500 {object} Response "内部错误" @Security ApiKeyAuth @Router /api/v1/chat/completions/stream [post]

type CheckResult 

type CheckResult struct {
	Status  string `json:"status"` // "pass", "fail"
	Message string `json:"message,omitempty"`
	Latency string `json:"latency,omitempty"`
}

CheckResult 单个检查结果

type CostHandler added in v1.6.0 

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

func NewCostHandler added in v1.6.0 

func NewCostHandler(tracker *observability.CostTracker, logger *zap.Logger) *CostHandler

func (*CostHandler) HandleRecords added in v1.6.0 

func (h *CostHandler) HandleRecords(w http.ResponseWriter, r *http.Request)

func (*CostHandler) HandleReset added in v1.6.0 

func (h *CostHandler) HandleReset(w http.ResponseWriter, r *http.Request)

func (*CostHandler) HandleSummary added in v1.6.0 

func (h *CostHandler) HandleSummary(w http.ResponseWriter, r *http.Request)

type DatabaseHealthCheck 

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

DatabaseHealthCheck 数据库健康检查

func NewDatabaseHealthCheck 

func NewDatabaseHealthCheck(name string, ping func(ctx context.Context) error) *DatabaseHealthCheck

NewDatabaseHealthCheck 创建数据库健康检查

func (*DatabaseHealthCheck) Check 

func (c *DatabaseHealthCheck) Check(ctx context.Context) error

func (*DatabaseHealthCheck) Name 

func (c *DatabaseHealthCheck) Name() string

type DefaultAPIKeyService added in v1.4.6 

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

func NewDefaultAPIKeyService added in v1.4.6 

func NewDefaultAPIKeyService(store APIKeyStore) *DefaultAPIKeyService

func (*DefaultAPIKeyService) CreateAPIKey added in v1.4.6 

func (s *DefaultAPIKeyService) CreateAPIKey(providerID uint, req createAPIKeyRequest) (*apiKeyResponse, *types.Error)

func (*DefaultAPIKeyService) DeleteAPIKey added in v1.4.6 

func (s *DefaultAPIKeyService) DeleteAPIKey(providerID, keyID uint) *types.Error

func (*DefaultAPIKeyService) ListAPIKeyStats added in v1.4.6 

func (s *DefaultAPIKeyService) ListAPIKeyStats(providerID uint) ([]apiKeyStatsResponse, *types.Error)

func (*DefaultAPIKeyService) ListAPIKeys added in v1.4.6 

func (s *DefaultAPIKeyService) ListAPIKeys(providerID uint) ([]apiKeyResponse, *types.Error)

func (*DefaultAPIKeyService) ListProviders added in v1.4.6 

func (s *DefaultAPIKeyService) ListProviders() ([]llm.LLMProvider, *types.Error)

func (*DefaultAPIKeyService) UpdateAPIKey added in v1.4.6 

func (s *DefaultAPIKeyService) UpdateAPIKey(providerID, keyID uint, req updateAPIKeyRequest) (*apiKeyResponse, *types.Error)

type DefaultChatConverter added in v1.4.6 

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

DefaultChatConverter is the default converter implementation used by ChatHandler.

func NewDefaultChatConverter added in v1.4.6 

func NewDefaultChatConverter(defaultTimeout time.Duration) *DefaultChatConverter

NewDefaultChatConverter creates a default converter with fallback timeout.

func (*DefaultChatConverter) ToAPIChoices added in v1.4.6 

func (c *DefaultChatConverter) ToAPIChoices(choices []llm.ChatChoice) []api.ChatChoice

ToAPIChoices converts llm choices to API choices.

func (*DefaultChatConverter) ToAPIResponse added in v1.4.6 

func (c *DefaultChatConverter) ToAPIResponse(resp *llm.ChatResponse) *api.ChatResponse

ToAPIResponse converts llm.ChatResponse to api.ChatResponse.

func (*DefaultChatConverter) ToAPIStreamChunk added in v1.4.6 

func (c *DefaultChatConverter) ToAPIStreamChunk(chunk *llm.StreamChunk) *api.StreamChunk

ToAPIStreamChunk converts llm stream chunk to API chunk.

func (*DefaultChatConverter) ToAPIUsage added in v1.4.6 

func (c *DefaultChatConverter) ToAPIUsage(usage llm.ChatUsage) api.ChatUsage

ToAPIUsage converts llm usage to API usage.

func (*DefaultChatConverter) ToLLMRequest added in v1.4.6 

func (c *DefaultChatConverter) ToLLMRequest(req *api.ChatRequest) *llm.ChatRequest

ToLLMRequest converts api.ChatRequest to llm.ChatRequest.

type DefaultRAGService added in v1.4.6 

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

func NewDefaultRAGService added in v1.4.6 

func NewDefaultRAGService(store rag.VectorStore, embedding rag.EmbeddingProvider) *DefaultRAGService

func (*DefaultRAGService) Index added in v1.4.6 

func (s *DefaultRAGService) Index(ctx context.Context, docs []rag.Document) error

func (*DefaultRAGService) Query added in v1.4.6 

func (s *DefaultRAGService) Query(ctx context.Context, query string, topK int, opts RAGQueryOptions) (*RAGQueryResponse, error)

func (*DefaultRAGService) SupportedStrategies added in v1.4.6 

func (s *DefaultRAGService) SupportedStrategies() []string

type DefaultToolProviderService added in v1.5.0 

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

func NewDefaultToolProviderService added in v1.5.0 

func NewDefaultToolProviderService(store ToolProviderStore, runtime ToolRegistryRuntime) *DefaultToolProviderService

func (*DefaultToolProviderService) Delete added in v1.5.0 

func (s *DefaultToolProviderService) Delete(provider string) *types.Error

func (*DefaultToolProviderService) List added in v1.5.0 

func (s *DefaultToolProviderService) List() ([]toolProviderResponse, *types.Error)

func (*DefaultToolProviderService) Reload added in v1.5.0 

func (s *DefaultToolProviderService) Reload() *types.Error

func (*DefaultToolProviderService) Upsert added in v1.5.0 

func (s *DefaultToolProviderService) Upsert(provider string, req upsertToolProviderRequest) (*toolProviderResponse, *types.Error)

type DefaultToolRegistryService added in v1.4.6 

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

func NewDefaultToolRegistryService added in v1.4.6 

func NewDefaultToolRegistryService(store hosted.ToolRegistryStore, runtime ToolRegistryRuntime) *DefaultToolRegistryService

func (*DefaultToolRegistryService) Create added in v1.4.6 

func (s *DefaultToolRegistryService) Create(req createToolRegistrationRequest) (*hosted.ToolRegistration, *types.Error)

func (*DefaultToolRegistryService) Delete added in v1.4.6 

func (s *DefaultToolRegistryService) Delete(id uint) *types.Error

func (*DefaultToolRegistryService) List added in v1.4.6 

func (s *DefaultToolRegistryService) List() ([]hosted.ToolRegistration, *types.Error)

func (*DefaultToolRegistryService) ListTargets added in v1.4.6 

func (s *DefaultToolRegistryService) ListTargets() ([]string, *types.Error)

func (*DefaultToolRegistryService) Reload added in v1.4.6 

func (s *DefaultToolRegistryService) Reload() *types.Error

func (*DefaultToolRegistryService) Update added in v1.4.6 

func (s *DefaultToolRegistryService) Update(ctx context.Context, id uint, req updateToolRegistrationRequest) (*hosted.ToolRegistration, *types.Error)

type GormAPIKeyStore added in v1.0.0 

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

GormAPIKeyStore implements APIKeyStore using gorm.DB.

func NewGormAPIKeyStore added in v1.0.0 

func NewGormAPIKeyStore(db *gorm.DB) *GormAPIKeyStore

NewGormAPIKeyStore creates a new GormAPIKeyStore.

func (*GormAPIKeyStore) CreateAPIKey added in v1.0.0 

func (s *GormAPIKeyStore) CreateAPIKey(key *llm.LLMProviderAPIKey) error

func (*GormAPIKeyStore) DeleteAPIKey added in v1.0.0 

func (s *GormAPIKeyStore) DeleteAPIKey(keyID, providerID uint) (int64, error)

func (*GormAPIKeyStore) GetAPIKey added in v1.0.0 

func (s *GormAPIKeyStore) GetAPIKey(keyID, providerID uint) (llm.LLMProviderAPIKey, error)

func (*GormAPIKeyStore) ListAPIKeys added in v1.0.0 

func (s *GormAPIKeyStore) ListAPIKeys(providerID uint) ([]llm.LLMProviderAPIKey, error)

func (*GormAPIKeyStore) ListProviders added in v1.0.0 

func (s *GormAPIKeyStore) ListProviders() ([]llm.LLMProvider, error)

func (*GormAPIKeyStore) ReloadAPIKey added in v1.0.0 

func (s *GormAPIKeyStore) ReloadAPIKey(key *llm.LLMProviderAPIKey) error

func (*GormAPIKeyStore) UpdateAPIKey added in v1.0.0 

func (s *GormAPIKeyStore) UpdateAPIKey(key *llm.LLMProviderAPIKey, updates map[string]any) error

type GormToolProviderStore added in v1.5.0 

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

func NewGormToolProviderStore added in v1.5.0 

func NewGormToolProviderStore(db *gorm.DB) *GormToolProviderStore

func (*GormToolProviderStore) Create added in v1.5.0 

func (s *GormToolProviderStore) Create(row *hosted.ToolProviderConfig) error

func (*GormToolProviderStore) DeleteByProvider added in v1.5.0 

func (s *GormToolProviderStore) DeleteByProvider(provider string) (int64, error)

func (*GormToolProviderStore) GetByProvider added in v1.5.0 

func (s *GormToolProviderStore) GetByProvider(provider string) (hosted.ToolProviderConfig, error)

func (*GormToolProviderStore) List added in v1.5.0 

func (s *GormToolProviderStore) List() ([]hosted.ToolProviderConfig, error)

func (*GormToolProviderStore) Reload added in v1.5.0 

func (s *GormToolProviderStore) Reload(row *hosted.ToolProviderConfig) error

func (*GormToolProviderStore) Update added in v1.5.0 

func (s *GormToolProviderStore) Update(row *hosted.ToolProviderConfig, updates map[string]any) error

type HealthCheck 

type HealthCheck interface {
	Name() string
	Check(ctx context.Context) error
}

HealthCheck 健康检查接口

type HealthHandler 

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

HealthHandler 健康检查处理器

func NewHealthHandler 

func NewHealthHandler(logger *zap.Logger) *HealthHandler

NewHealthHandler 创建健康检查处理器

func (*HealthHandler) HandleHealth 

func (h *HealthHandler) HandleHealth(w http.ResponseWriter, r *http.Request)

HandleHealth 处理 /health 请求（简单健康检查） @Summary 健康检查 @Description 简单的健康检查端点 @Tags 健康 @Produce json @Success 200 {object} api.Response "服务正常，data 为 ServiceHealthResponse" @Failure 503 {object} api.Response "服务不健康" @Router /health [get]

func (*HealthHandler) HandleHealthz 

func (h *HealthHandler) HandleHealthz(w http.ResponseWriter, r *http.Request)

HandleHealthz 处理 /healthz 请求（Kubernetes 风格） @Summary Kubernetes 活跃度探针 @Description Kubernetes 的活跃度探针 @Tags 健康 @Produce json @Success 200 {object} api.Response "服务处于活动状态，data 为 ServiceHealthResponse" @Router /healthz [get]

func (*HealthHandler) HandleReady 

func (h *HealthHandler) HandleReady(w http.ResponseWriter, r *http.Request)

HandleReady 处理 /ready 或 /readyz 请求（就绪检查） @Summary 准备情况检查 @Description 检查服务是否准备好接受流量 @Tags 健康 @Produce json @Success 200 {object} ServiceHealthResponse "服务已准备就绪" @Failure 503 {object} ServiceHealthResponse "服务尚未准备好" @Router /ready [get]

func (*HealthHandler) HandleVersion 

func (h *HealthHandler) HandleVersion(version, buildTime, gitCommit string) http.HandlerFunc

HandleVersion 处理 /version 请求 @Summary 版本信息 @Description 返回版本信息 @Tags 健康 @Produce json @Success 200 {object} map[string]string "版本信息" @Router /version [get]

func (*HealthHandler) RegisterCheck 

func (h *HealthHandler) RegisterCheck(check HealthCheck)

RegisterCheck 注册健康检查

type MultimodalHandler added in v1.2.0 

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

func NewMultimodalHandlerFromConfig added in v1.3.0 

func NewMultimodalHandlerFromConfig(cfg MultimodalHandlerConfig, logger *zap.Logger) *MultimodalHandler

func NewMultimodalHandlerWithProviders added in v1.3.0 

func NewMultimodalHandlerWithProviders(
	chatProvider llm.Provider,
	policyManager *llmpolicy.Manager,
	ledger observability.Ledger,
	imageProviders map[string]image.Provider,
	videoProviders map[string]video.Provider,
	defaultImage string,
	defaultVideo string,
	pipeline multimodal.PromptPipeline,
	referenceMaxSize int64,
	referenceTTL time.Duration,
	referenceStore storage.ReferenceStore,
	logger *zap.Logger,
) *MultimodalHandler

func (*MultimodalHandler) HandleCapabilities added in v1.3.0 

func (h *MultimodalHandler) HandleCapabilities(w http.ResponseWriter, r *http.Request)

func (*MultimodalHandler) HandleChat added in v1.3.0 

func (h *MultimodalHandler) HandleChat(w http.ResponseWriter, r *http.Request)

func (*MultimodalHandler) HandleImage added in v1.3.0 

func (h *MultimodalHandler) HandleImage(w http.ResponseWriter, r *http.Request)

func (*MultimodalHandler) HandlePlan added in v1.3.0 

func (h *MultimodalHandler) HandlePlan(w http.ResponseWriter, r *http.Request)

func (*MultimodalHandler) HandleUploadReference added in v1.3.0 

func (h *MultimodalHandler) HandleUploadReference(w http.ResponseWriter, r *http.Request)

func (*MultimodalHandler) HandleVideo added in v1.3.0 

func (h *MultimodalHandler) HandleVideo(w http.ResponseWriter, r *http.Request)

type MultimodalHandlerConfig added in v1.3.0 

type MultimodalHandlerConfig struct {
	ChatProvider         llm.Provider
	PolicyManager        *llmpolicy.Manager
	Ledger               observability.Ledger
	OpenAIAPIKey         string
	OpenAIBaseURL        string
	GoogleAPIKey         string
	GoogleBaseURL        string
	RunwayAPIKey         string
	RunwayBaseURL        string
	VeoAPIKey            string
	VeoBaseURL           string
	SoraAPIKey           string
	SoraBaseURL          string
	KlingAPIKey          string
	KlingBaseURL         string
	LumaAPIKey           string
	LumaBaseURL          string
	MiniMaxAPIKey        string
	MiniMaxBaseURL       string
	DefaultImageProvider string
	DefaultVideoProvider string
	ReferenceMaxSize     int64
	ReferenceTTL         time.Duration
	ReferenceStore       storage.ReferenceStore
	Pipeline             multimodal.PromptPipeline
}

type ProtocolHandler added in v1.2.0 

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

ProtocolHandler handles MCP and A2A protocol API requests.

func NewProtocolHandler added in v1.2.0 

func NewProtocolHandler(mcpServer mcp.MCPServer, a2aServer a2a.A2AServer, logger *zap.Logger) *ProtocolHandler

NewProtocolHandler creates a new protocol handler.

func (*ProtocolHandler) HandleA2AAgentCard added in v1.2.0 

func (h *ProtocolHandler) HandleA2AAgentCard(w http.ResponseWriter, r *http.Request)

HandleA2AAgentCard handles GET /api/v1/a2a/.well-known/agent.json

func (*ProtocolHandler) HandleA2ASendTask added in v1.2.0 

func (h *ProtocolHandler) HandleA2ASendTask(w http.ResponseWriter, r *http.Request)

HandleA2ASendTask handles POST /api/v1/a2a/tasks

func (*ProtocolHandler) HandleMCPCallTool added in v1.2.0 

func (h *ProtocolHandler) HandleMCPCallTool(w http.ResponseWriter, r *http.Request)

HandleMCPCallTool handles POST /api/v1/mcp/tools/{name}

func (*ProtocolHandler) HandleMCPGetResource added in v1.2.0 

func (h *ProtocolHandler) HandleMCPGetResource(w http.ResponseWriter, r *http.Request)

HandleMCPGetResource handles GET /api/v1/mcp/resources/{uri}

func (*ProtocolHandler) HandleMCPListResources added in v1.2.0 

func (h *ProtocolHandler) HandleMCPListResources(w http.ResponseWriter, r *http.Request)

HandleMCPListResources handles GET /api/v1/mcp/resources

func (*ProtocolHandler) HandleMCPListTools added in v1.2.0 

func (h *ProtocolHandler) HandleMCPListTools(w http.ResponseWriter, r *http.Request)

HandleMCPListTools handles GET /api/v1/mcp/tools

type RAGHandler added in v1.2.0 

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

RAGHandler handles RAG (Retrieval-Augmented Generation) API requests.

func NewRAGHandler added in v1.2.0 

func NewRAGHandler(store rag.VectorStore, embedding rag.EmbeddingProvider, logger *zap.Logger) *RAGHandler

NewRAGHandler creates a new RAG handler.

func NewRAGHandlerWithService added in v1.4.6 

func NewRAGHandlerWithService(service RAGService, logger *zap.Logger) *RAGHandler

func (*RAGHandler) HandleCapabilities added in v1.4.6 

func (h *RAGHandler) HandleCapabilities(w http.ResponseWriter, r *http.Request)

HandleCapabilities handles GET /api/v1/rag/capabilities

func (*RAGHandler) HandleIndex added in v1.2.0 

func (h *RAGHandler) HandleIndex(w http.ResponseWriter, r *http.Request)

HandleIndex handles POST /api/v1/rag/index

func (*RAGHandler) HandleQuery added in v1.2.0 

func (h *RAGHandler) HandleQuery(w http.ResponseWriter, r *http.Request)

HandleQuery handles POST /api/v1/rag/query

type RAGQueryOptions added in v1.4.6 

type RAGQueryOptions struct {
	Strategy string
}

type RAGQueryResponse added in v1.4.6 

type RAGQueryResponse struct {
	Results           []rag.VectorSearchResult
	RequestedStrategy string
	EffectiveStrategy string
}

type RAGService added in v1.4.6 

type RAGService interface {
	Query(ctx context.Context, query string, topK int, opts RAGQueryOptions) (*RAGQueryResponse, error)
	Index(ctx context.Context, docs []rag.Document) error
	SupportedStrategies() []string
}

RAGService defines the use-case boundary for RAG handler.

type RedisHealthCheck 

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

RedisHealthCheck Redis 健康检查

func NewRedisHealthCheck 

func NewRedisHealthCheck(name string, ping func(ctx context.Context) error) *RedisHealthCheck

NewRedisHealthCheck 创建 Redis 健康检查

func (*RedisHealthCheck) Check 

func (c *RedisHealthCheck) Check(ctx context.Context) error

func (*RedisHealthCheck) Name 

func (c *RedisHealthCheck) Name() string

type Response 

type Response = api.Response

Response is kept as a package-level alias for handler tests and docs.

type ResponseWriter 

type ResponseWriter struct {
	http.ResponseWriter
	StatusCode int
	Written    bool
}

ResponseWriter 包装 http.ResponseWriter 以捕获状态码

func NewResponseWriter 

func NewResponseWriter(w http.ResponseWriter) *ResponseWriter

NewResponseWriter 创建新的 ResponseWriter

func (*ResponseWriter) Flush added in v1.4.6 

func (rw *ResponseWriter) Flush()

Flush implements http.Flusher by forwarding to the underlying writer when supported.

func (*ResponseWriter) Hijack added in v1.1.0 

func (rw *ResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)

Hijack implements http.Hijacker so WebSocket upgrades work through wrapped ResponseWriters.

func (*ResponseWriter) Write 

func (rw *ResponseWriter) Write(b []byte) (int, error)

Write 重写 Write 以标记已写入

func (*ResponseWriter) WriteHeader 

func (rw *ResponseWriter) WriteHeader(code int)

WriteHeader 重写 WriteHeader 以捕获状态码

type ServiceHealthResponse 

type ServiceHealthResponse struct {
	Status    string                 `json:"status"` // "healthy", "degraded", "unhealthy"
	Timestamp time.Time              `json:"timestamp"`
	Version   string                 `json:"version,omitempty"`
	Checks    map[string]CheckResult `json:"checks,omitempty"`
}

ServiceHealthResponse 服务级别的健康状态响应（HTTP 健康端点 DTO）。 注意：这是 HTTP 健康检查端点的响应类型，与 llm.HealthStatus（Provider 级别） 和 agent.HealthStatus（Agent 级别）是不同概念。

type ToolProviderHandler added in v1.5.0 

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

func NewToolProviderHandler added in v1.5.0 

func NewToolProviderHandler(store ToolProviderStore, runtime ToolRegistryRuntime, logger *zap.Logger) *ToolProviderHandler

func (*ToolProviderHandler) HandleDelete added in v1.5.0 

func (h *ToolProviderHandler) HandleDelete(w http.ResponseWriter, r *http.Request)

func (*ToolProviderHandler) HandleList added in v1.5.0 

func (h *ToolProviderHandler) HandleList(w http.ResponseWriter, r *http.Request)

func (*ToolProviderHandler) HandleReload added in v1.5.0 

func (h *ToolProviderHandler) HandleReload(w http.ResponseWriter, r *http.Request)

func (*ToolProviderHandler) HandleUpsert added in v1.5.0 

func (h *ToolProviderHandler) HandleUpsert(w http.ResponseWriter, r *http.Request)

type ToolProviderService added in v1.5.0 

type ToolProviderService interface {
	List() ([]toolProviderResponse, *types.Error)
	Upsert(provider string, req upsertToolProviderRequest) (*toolProviderResponse, *types.Error)
	Delete(provider string) *types.Error
	Reload() *types.Error
}

type ToolProviderStore added in v1.5.0 

type ToolProviderStore interface {
	List() ([]hosted.ToolProviderConfig, error)
	GetByProvider(provider string) (hosted.ToolProviderConfig, error)
	Create(row *hosted.ToolProviderConfig) error
	Update(row *hosted.ToolProviderConfig, updates map[string]any) error
	Reload(row *hosted.ToolProviderConfig) error
	DeleteByProvider(provider string) (int64, error)
}

ToolProviderStore defines DB access for hosted tool provider configs.

type ToolRegistryHandler added in v1.4.6 

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

ToolRegistryHandler manages DB-backed hosted tool registrations.

func NewToolRegistryHandler added in v1.4.6 

func NewToolRegistryHandler(store hosted.ToolRegistryStore, runtime ToolRegistryRuntime, logger *zap.Logger) *ToolRegistryHandler

func (*ToolRegistryHandler) HandleCreate added in v1.4.6 

func (h *ToolRegistryHandler) HandleCreate(w http.ResponseWriter, r *http.Request)

func (*ToolRegistryHandler) HandleDelete added in v1.4.6 

func (h *ToolRegistryHandler) HandleDelete(w http.ResponseWriter, r *http.Request)

func (*ToolRegistryHandler) HandleList added in v1.4.6 

func (h *ToolRegistryHandler) HandleList(w http.ResponseWriter, r *http.Request)

HandleList returns tool registrations. No pagination: config data is typically small.

func (*ToolRegistryHandler) HandleListTargets added in v1.4.6 

func (h *ToolRegistryHandler) HandleListTargets(w http.ResponseWriter, r *http.Request)

func (*ToolRegistryHandler) HandleReload added in v1.4.6 

func (h *ToolRegistryHandler) HandleReload(w http.ResponseWriter, r *http.Request)

func (*ToolRegistryHandler) HandleUpdate added in v1.4.6 

func (h *ToolRegistryHandler) HandleUpdate(w http.ResponseWriter, r *http.Request)

type ToolRegistryRuntime added in v1.4.6 

type ToolRegistryRuntime interface {
	ReloadBindings(ctx context.Context) error
	BaseToolNames() []string
}

TODO(refactor): ToolRegistryService should be moved to internal/app/service or a domain layer package. It currently resides in api/handlers but contains business logic that belongs in Layer 2-3.

ToolRegistryRuntime describes runtime hooks used by tool registration API.

type ToolRegistryService added in v1.4.6 

type ToolRegistryService interface {
	List() ([]hosted.ToolRegistration, *types.Error)
	ListTargets() ([]string, *types.Error)
	Create(req createToolRegistrationRequest) (*hosted.ToolRegistration, *types.Error)
	Update(ctx context.Context, id uint, req updateToolRegistrationRequest) (*hosted.ToolRegistration, *types.Error)
	Delete(id uint) *types.Error
	Reload() *types.Error
}

type WorkflowExecutor added in v1.4.6 

type WorkflowExecutor interface {
	ExecuteDAG(ctx context.Context, wf *workflow.DAGWorkflow, input any) (any, error)
}

WorkflowExecutor defines the workflow execution facade contract used by handlers.

type WorkflowHandler added in v1.2.0 

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

WorkflowHandler handles workflow API requests.

func NewWorkflowHandler added in v1.2.0 

func NewWorkflowHandler(executor WorkflowExecutor, parser *dsl.Parser, logger *zap.Logger) *WorkflowHandler

NewWorkflowHandler creates a new workflow handler.

func (*WorkflowHandler) HandleCapabilities added in v1.4.6 

func (h *WorkflowHandler) HandleCapabilities(w http.ResponseWriter, r *http.Request)

HandleCapabilities handles GET /api/v1/workflows/capabilities

func (*WorkflowHandler) HandleExecute added in v1.2.0 

func (h *WorkflowHandler) HandleExecute(w http.ResponseWriter, r *http.Request)

HandleExecute handles POST /api/v1/workflows/execute

func (*WorkflowHandler) HandleList added in v1.2.0 

func (h *WorkflowHandler) HandleList(w http.ResponseWriter, r *http.Request)

HandleList handles GET /api/v1/workflows

func (*WorkflowHandler) HandleParse added in v1.2.0 

func (h *WorkflowHandler) HandleParse(w http.ResponseWriter, r *http.Request)

HandleParse handles POST /api/v1/workflows/parse (validate DSL)

type WorkflowService added in v1.4.6 

type WorkflowService interface {
	BuildDAGWorkflow(req workflowExecuteRequest) (*workflow.DAGWorkflow, string, *types.Error)
	Execute(ctx context.Context, wf *workflow.DAGWorkflow, input any, streamEmitter workflow.WorkflowStreamEmitter, nodeEmitter workflowobs.NodeEventEmitter) (any, *types.Error)
	ValidateDSL(rawDSL string) workflowDSLValidationResult
}

WorkflowService encapsulates workflow parsing, validation and execution use-cases.

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.