sdk

package
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package sdk 定义 AirGate 插件作者直接使用的 Go SDK。

本包只放稳定插件契约、共享类型、capability 辅助和日志辅助。 gRPC、go-plugin、broker、protobuf 转换等运行时细节属于 runtimego/grpc。

Index

Constants

View Source 
const (
	WSMessageText   = 1
	WSMessageBinary = 2
)

WebSocket 消息类型（与 gorilla/websocket 的 TextMessage / BinaryMessage 对齐）。

View Source 
const (
	HeaderRequestID = "X-Request-ID"

	LogFieldRequestID  = "request_id"
	LogFieldUserID     = "user_id"
	LogFieldGroupID    = "group_id"
	LogFieldAccountID  = "account_id"
	LogFieldAPIKeyID   = "api_key_id"
	LogFieldPluginID   = "plugin_id"
	LogFieldModel      = "model"
	LogFieldPlatform   = "platform"
	LogFieldStatus     = "status_code"
	LogFieldDurationMs = "duration_ms"
	LogFieldError      = "error"
	LogFieldMethod     = "method"
	LogFieldPath       = "path"
	LogFieldReason     = "reason"
)

日志相关 HTTP header 与字段名约定。

字段命名一律 snake_case，事件名一律 snake_case，由 slog 统一输出。 全局 module 字段由 InitLogger 注入（"core" 或 "plugin.<id>"）。

View Source 
const (
	DefaultMiddlewareDeadline    = 200 * time.Millisecond
	DefaultMiddlewareChainBudget = 500 * time.Millisecond
)

DefaultMiddlewareDeadline / DefaultMiddlewareChainBudget 单 hook / 整条链的默认超时预算。 Core 侧按此控制超时，middleware 超时不得 block 主流程，只会被跳过并 log warn。

View Source 
const (
	ModelCapChat            = "chat"             // 文本对话
	ModelCapReasoning       = "reasoning"        // 推理 / 思维链
	ModelCapImageGeneration = "image_generation" // 图像生成
	ModelCapImageEdit       = "image_edit"       // 图像编辑
	ModelCapVideoGeneration = "video_generation" // 视频生成
	ModelCapAudioGeneration = "audio_generation" // 音频/音乐生成
	ModelCapTTS             = "tts"              // 文本转语音
	ModelCapSTT             = "stt"              // 语音转文字
	ModelCapCodeExecution   = "code_execution"   // 代码执行
	ModelCapEmbedding       = "embedding"        // 向量嵌入
)

标准模型能力常量。网关插件在声明 Models() 时应为每个模型填充 Capabilities 字段。 Playground / Core 按此分类展示和过滤。新增能力类型在此追加即可，无需改 proto。

View Source 
const (
	SlotAccountIdentity    = "account-identity"
	SlotAccountCreate      = "account-create"
	SlotAccountEdit        = "account-edit"
	SlotAccountUsageWindow = "account-usage-window"
	SlotUsageMetricDetail  = "usage-metric-detail"
	SlotUsageCostDetail    = "usage-cost-detail"
)

前端组件插槽。

View Source 
const ConfigKeyLogLevel = "_log_level"

ConfigKeyLogLevel Core 通过此配置键把日志级别传给插件。

View Source 
const PluginDSNConfigKey = "plugin_dsn"

PluginDSNConfigKey Core 注入"插件专属数据库 DSN"时使用的 config key。 插件作者应通过 GetPluginDSN(ctx) 访问，而非直接拼字符串。

View Source 
const SDKVersion = "0.2.5"

SDKVersion 当前 SDK 版本，插件编译时嵌入到 PluginInfo。

Variables

View Source 
var ErrInvalidCredentials = errors.New("invalid credentials")

ErrInvalidCredentials ValidateAccount 判定凭证格式/语义不合法时返回。

View Source 
var ErrNotSupported = errors.New("not supported")

ErrNotSupported 插件不支持某项可选能力时返回（如 HandleWebSocket）。

Functions

func ExtractOrGenerateRequestID 

func ExtractOrGenerateRequestID(headers http.Header) string

ExtractOrGenerateRequestID 从 HTTP header 抽取 X-Request-ID；缺失则生成新 UUID。

用于 core 入口、插件 HTTP 处理器等所有"链路开始"的位置：

  • core 接到客户端请求 → 抽取/生成 → 写回 header → 透传给插件
  • 插件回调入口（webhook 等） → 同样抽取/生成

func GetPluginDSN 

func GetPluginDSN(ctx PluginContext) string

GetPluginDSN PluginDSNAware 的便利访问器。

func InitLogger 

func InitLogger(module, level, format string)

InitLogger 初始化全局 slog。 module 日志来源标识（如 "core"、"plugin.gateway-openai"）；level: debug/info/warn/error；format: text/json。

text 格式且 stdout 是 TTY 时自动启用 ANSI 颜色（按等级染色 + request_id 高亮）； 重定向到文件 / 管道、或设置 NO_COLOR=1 时自动退化为纯文本。

func IsKnownCapability 

func IsKnownCapability(c Capability) bool

IsKnownCapability 判断 capability 是否在当前 SDK 版本的已知集合内。

func LogFormat 

func LogFormat() string

LogFormat 返回当前日志格式。

func LoggerFromContext 

func LoggerFromContext(ctx context.Context) *slog.Logger

LoggerFromContext 从 context 取 logger；不存在则返回 slog.Default()。

该函数永远不返回 nil，调用方可直接 .Info/.Error。

func LoggerWithRequestID 

func LoggerWithRequestID(ctx context.Context) (context.Context, *slog.Logger)

LoggerWithRequestID 为 ctx 派生一个带 request_id 字段的 logger 并写回 ctx。

典型用法（HTTP 中间件）： 

rid := sdk.ExtractOrGenerateRequestID(r.Header)
ctx = sdk.WithRequestID(ctx, rid)
ctx, logger := sdk.LoggerWithRequestID(ctx)
logger.Info("http_request_received", "method", r.Method, "path", r.URL.Path)

func RequestIDFromContext 

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext 从 context 取 request_id；不存在返回空串。

func WithLogger 

func WithLogger(ctx context.Context, logger *slog.Logger) context.Context

WithLogger 把 logger 绑到 context；通常由 HTTP/gRPC 入口构造请求级 logger 后调用。

func WithRequestID 

func WithRequestID(ctx context.Context, id string) context.Context

WithRequestID 把 request_id 绑到 context（不修改 logger，仅作为独立 value）。

Types

type Account 

type Account struct {
	ID          int64             `json:"id"`
	Name        string            `json:"name"`
	Platform    string            `json:"platform"`
	Type        string            `json:"type"`        // 对应 AccountType.Key（apikey / oauth / ...）
	Credentials map[string]string `json:"credentials"` // JSONB 透传，结构由 Type 决定
	ProxyURL    string            `json:"proxy_url"`
}

Account 上游账户（Core 调度后传给插件的最小视图）。

type AccountType 

type AccountType struct {
	Key         string            `json:"key"`
	Label       string            `json:"label"`
	Description string            `json:"description"`
	Fields      []CredentialField `json:"fields"`
}

AccountType 账号类型声明。

type BackgroundTask 

type BackgroundTask struct {
	Name     string
	Interval time.Duration
	Handler  func(ctx context.Context) error
}

BackgroundTask 后台任务声明（Core 负责调度）。

type Capability 

type Capability string

Capability 类型化的能力标识符（命名规范：<domain>.<action>）。 所有 capability 常量必须用此类型以便编译期捕获拼写错误。

运行时授权由 Core 强制执行；SDK 只负责声明格式和基础类型自检。 

const (
	// CapabilityHostInvoke 允许插件通过 Host.Invoke / Host.InvokeStream 调用 Core 开放的方法。
	//
	// Core 可以进一步要求插件声明 method 级 capability：
	//
	//	host.invoke.<method>
	//
	// 例如：
	//
	//	host.invoke.scheduler.select_account
	//	host.invoke.tasks.update
	CapabilityHostInvoke Capability = "host.invoke"

	CapabilityMiddlewareReadBody Capability = "middleware.read_body"
)

func CapabilityForHostMethod 

func CapabilityForHostMethod(method string) Capability

CapabilityForHostMethod 返回某个 Core method 对应的细粒度 capability。

func KnownCapabilities 

func KnownCapabilities() []Capability

KnownCapabilities 返回 SDK 内置 capability，按字典序排序。 host.invoke.<method> 属于动态 capability，不会出现在此列表中。

func (Capability) String 

func (c Capability) String() string

type CapabilityValidationReport 

type CapabilityValidationReport struct {
	// Effective 当前 plugin type 下实际生效的 capability = 声明 ∩ 类型允许，去重+排序。
	Effective []Capability
	// Unknown SDK 不认识的 capability（多半是拼写错）。
	Unknown []Capability
	// Denied SDK 认识但当前 plugin type 不允许的 capability（配置错误）。
	Denied []Capability
}

CapabilityValidationReport ValidateCapabilities 的输出。

func ValidateCapabilities 

func ValidateCapabilities(typ PluginType, declared []Capability) CapabilityValidationReport

ValidateCapabilities 对一组声明做 self-check。授权决策仍由 Core 的方法注册表负责， 这里只做"声明 vs 已知 vs 类型允许"的纸面检查。

func (CapabilityValidationReport) HasIssues 

func (r CapabilityValidationReport) HasIssues() bool

HasIssues 报告是否检测到任何问题。

type ConfigField 

type ConfigField struct {
	Key         string `json:"key"`
	Label       string `json:"label"`
	Type        string `json:"type"` // string / int / bool / float / duration / password
	Required    bool   `json:"required"`
	Default     string `json:"default,omitempty"`
	Description string `json:"description,omitempty"`
	Placeholder string `json:"placeholder,omitempty"`
}

ConfigField 配置项声明。

type ConfigWatcher 

type ConfigWatcher interface {
	OnConfigUpdate(config PluginConfig) error
}

ConfigWatcher 可选：支持配置热更新的插件实现。

type CredentialField 

type CredentialField struct {
	Key          string `json:"key"`
	Label        string `json:"label"`
	Type         string `json:"type"` // text / password / textarea / select
	Required     bool   `json:"required"`
	Placeholder  string `json:"placeholder"`
	EditDisabled bool   `json:"edit_disabled,omitempty"`
}

CredentialField 凭证字段声明。

type DecisionAction 

type DecisionAction int32

DecisionAction 对应 proto MiddlewareDecision.Action。 

const (
	DecisionAllow  DecisionAction = 0
	DecisionDeny   DecisionAction = 1
	DecisionMutate DecisionAction = 2
)

type DispatchCandidate added in v0.2.3 

type DispatchCandidate struct {
	Scheduling string `json:"scheduling"`
	Wire       string `json:"wire,omitempty"`
}

DispatchCandidate 是一条可尝试的调度候选。

type DispatchDSL added in v0.2.3 

type DispatchDSL struct {
	Rules []DispatchRule `json:"rules,omitempty"`
}

DispatchDSL 声明插件默认的请求调度规则。

Core 会先用 group 级 DSL 覆盖/追加，再回退到插件默认 DSL，最终得到一次请求的 DispatchPlan 列表。每条规则既能声明模型选择，也能声明操作语义、分组开关和超时画像。

type DispatchGate added in v0.2.3 

type DispatchGate struct {
	RequiredOperation string `json:"required_operation,omitempty"`
	Status            int    `json:"status,omitempty"`
	ErrorType         string `json:"error_type,omitempty"`
	Code              string `json:"code,omitempty"`
	Message           string `json:"message,omitempty"`
}

DispatchGate 声明当前请求需要的分组操作开关，以及拒绝时的错误响应。

type DispatchModel added in v0.2.3 

type DispatchModel struct {
	StripSuffix string `json:"strip_suffix,omitempty"`
}

DispatchModel 描述规则命中后对客户端模型名的变换。

type DispatchPlan added in v0.2.3 

type DispatchPlan struct {
	ClientModel     string       `json:"client_model,omitempty"`
	SchedulingModel string       `json:"scheduling_model,omitempty"`
	WireModel       string       `json:"wire_model,omitempty"`
	RuleID          string       `json:"rule_id,omitempty"`
	Operation       string       `json:"operation,omitempty"`
	TimeoutProfile  string       `json:"timeout_profile,omitempty"`
	Gate            DispatchGate `json:"gate,omitempty"`
}

DispatchPlan 是一次请求经过 DSL 解析后的单个调度方案。

同一请求可能产生多个候选方案；Core 会按顺序尝试调度对应的 scheduling model， 并把最终选中的方案写回 ForwardRequest.DispatchPlan 传给插件。

func (DispatchPlan) UpstreamModel added in v0.2.3 

func (p DispatchPlan) UpstreamModel() string

UpstreamModel 返回本次请求真正要发给插件上游的模型名。

type DispatchRule added in v0.2.3 

type DispatchRule struct {
	ID             string              `json:"id,omitempty"`
	When           DispatchWhen        `json:"when,omitempty"`
	Model          DispatchModel       `json:"model,omitempty"`
	Operation      string              `json:"operation,omitempty"`
	TimeoutProfile string              `json:"timeout_profile,omitempty"`
	Gate           DispatchGate        `json:"gate,omitempty"`
	Candidates     []DispatchCandidate `json:"candidates,omitempty"`
}

DispatchRule 一条请求调度规则。

type DispatchWhen added in v0.2.3 

type DispatchWhen struct {
	Methods       []string `json:"methods,omitempty"`
	Paths         []string `json:"paths,omitempty"`
	PathPrefixes  []string `json:"path_prefixes,omitempty"`
	Models        []string `json:"models,omitempty"`
	ModelPrefixes []string `json:"model_prefixes,omitempty"`
	ModelSuffixes []string `json:"model_suffixes,omitempty"`
}

DispatchWhen 描述一条规则的匹配条件。

type EventHandler 

type EventHandler interface {
	EventSubscriptions() []EventSubscription
	HandleEvent(ctx context.Context, event PluginEvent) error
}

EventHandler 可选接口：插件实现后即可订阅并处理 Core 推送的事件。

type EventSchema 

type EventSchema struct {
	Type     string            `json:"type"`
	Source   string            `json:"source,omitempty"`
	Summary  string            `json:"summary,omitempty"`
	Payload  PayloadSchema     `json:"payload,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

EventSchema 描述插件订阅或发布的事件类型。

type EventSubscription 

type EventSubscription struct {
	Type     string            `json:"type"`
	Source   string            `json:"source,omitempty"`
	Filter   map[string]string `json:"filter,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

EventSubscription 声明插件希望接收的 Core 事件。

Type 支持精确事件名，也可由 Core 约定支持通配符，例如 "account.*"。 Filter 是弱契约过滤条件，只用于事件分发提示；安全过滤仍由 Core 负责。

type ExtensionPlugin 

type ExtensionPlugin interface {
	Plugin
	RegisterRoutes(r RouteRegistrar)
	Migrate() error
	BackgroundTasks() []BackgroundTask
}

ExtensionPlugin 通用扩展插件接口：注册自定义路由、执行迁移、声明后台任务。

type FailoverScope added in v0.2.3 

type FailoverScope string

FailoverScope 声明一次 ForwardOutcome 允许 Core 重试的边界。

零值表示不覆盖 OutcomeKind 自身语义。插件只有在能精确判断某类失败应该切换 Core 下发的 DispatchPlan 候选时，才应填写 DispatchCandidate。 

const (
	// FailoverScopeNone 表示不请求额外 failover。
	FailoverScopeNone FailoverScope = ""

	// FailoverScopeDispatchCandidate 表示当前 DispatchPlan 候选不可用，Core 可前进
	// 到下一候选重试；若没有下一候选，则按原 OutcomeKind 处理。
	FailoverScopeDispatchCandidate FailoverScope = "dispatch_candidate"
)

type ForwardOutcome 

type ForwardOutcome struct {
	Kind OutcomeKind

	FailoverScope FailoverScope

	Upstream UpstreamResponse

	Usage *Usage

	Duration   time.Duration
	RetryAfter time.Duration

	Reason string

	UpdatedCredentials map[string]string
}

ForwardOutcome 是插件对一次 Forward 的完整判决结果。

字段填写约定： 

Kind              必填，零值视为 Unknown（Core 保守处理）
Upstream          必填（StatusCode 至少填；Headers/Body 按 Kind 决定是否透传）
Usage             仅 Success（偶尔 ClientError）下非 nil
RetryAfter        仅 AccountRateLimited 下有意义
Duration          插件测得的耗时，Core 仅用于日志
Reason            人类可读原因，Core 仅落日志，不做任何判断
UpdatedCredentials 插件若在 Forward 中刷新了凭证（OAuth 轮转等）通过此字段带回
FailoverScope     可选，声明 OutcomeKind 之外的重试边界

type ForwardRequest 

type ForwardRequest struct {
	Account *Account
	Body    []byte
	Headers http.Header
	// Model 是客户端请求的原始模型；调度和上游模型由 DispatchPlan 表达。
	Model        string
	DispatchPlan DispatchPlan
	Stream       bool

	// Writer 流式响应写入目标。
	// Core 负责把写入内容转发给用户，并在调用结束后根据 ForwardOutcome 写记录和更新账号状态。
	Writer http.ResponseWriter
}

ForwardRequest 转发请求（Core → 插件）。

type FrontendPage 

type FrontendPage struct {
	Path        string `json:"path"`
	Title       string `json:"title"`
	Icon        string `json:"icon"`
	Description string `json:"description"`
	// Audience 决定页面可见范围：
	//   "admin" / ""  仅管理员（默认）
	//   "user"        仅普通登录用户
	//   "all"         所有登录用户
	Audience string `json:"audience,omitempty"`
}

FrontendPage 前端独立页面声明。

type FrontendWidget 

type FrontendWidget struct {
	Slot      string `json:"slot"`
	EntryFile string `json:"entry_file"`
	Title     string `json:"title"`
}

FrontendWidget 前端组件嵌入声明。

type GatewayPlugin 

type GatewayPlugin interface {
	Plugin

	Platform() string
	Models() []ModelInfo
	Routes() []RouteDefinition

	Forward(ctx context.Context, req *ForwardRequest) (ForwardOutcome, error)

	ValidateAccount(ctx context.Context, credentials map[string]string) error

	// HandleWebSocket 处理 WebSocket 双向通信。连接结束后返回 ForwardOutcome。
	// 不支持时返回 ErrNotSupported。
	HandleWebSocket(ctx context.Context, conn WebSocketConn) (ForwardOutcome, error)
}

GatewayPlugin 网关插件接口。

Core 负责：账号调度、并发/RPM 限流、结算记录、failover。 插件负责：声明模型/路由、转发请求、验证凭证；账号管理和使用记录页面通过 插件前端静态资源与插件私有 API 承接。

Forward 的返回契约：

  • ForwardOutcome 表达业务判决（成功 / 客户端错 / 账号限流 / 账号死 / 上游抖动 / 流中断）
  • error 仅表达"插件自身无法完成此次调用"（进程异常、gRPC 层故障），不承担业务语义

详见 outcome.go 的 OutcomeKind 文档。

type HealthChecker 

type HealthChecker interface {
	HealthCheck(ctx context.Context) error
}

HealthChecker 可选：Core 定期调用以探测插件存活。

type Host 

type Host interface {
	// Invoke 调用 Core 开放的方法。
	// Method 使用点分命名，例如 "scheduler.select_account"、"tasks.update"。
	// Payload 是 JSON 对象语义，运行时会通过 protobuf bytes 传输。
	Invoke(ctx context.Context, req HostInvokeRequest) (*HostInvokeResponse, error)

	// InvokeStream 调用 Core 开放的流式方法。
	// 首帧由 SDK 根据 req 自动发送；后续由返回的 HostStream 发送和接收。
	InvokeStream(ctx context.Context, req HostStreamRequest) (HostStream, error)
}

Host Core 暴露给插件的反向调用接口（plugin → core）。

通过 hashicorp/go-plugin 的 GRPCBroker 架起子进程隧道，插件无需 admin HTTP / Bearer 鉴权。 SDK 只定义通用调用通道，不定义 Core 方法清单；具体 method、入参和出参由 Core 的 方法注册表和插件 schema 共同约定，并由 Core 按 capability 强制授权。

在插件 Init 里通过 HostAware 拿到： 

func (p *MyPlugin) Init(ctx sdk.PluginContext) error {
    if h, ok := ctx.(sdk.HostAware); ok {
        p.host = h.Host() // 可能为 nil
    }
    return nil
}

type HostAware 

type HostAware interface {
	// Host 返回 Host 客户端；可能为 nil（Core 版本不支持 / 未启用）。
	Host() Host
}

HostAware 可选接口：PluginContext 实现它就能暴露 Host。

type HostInvokeRequest 

type HostInvokeRequest struct {
	Method string
	// Payload 是方法入参。SDK 不解释字段含义，Core method 自己校验 schema。
	Payload map[string]interface{}
	// IdempotencyKey 用于创建任务、下单等副作用方法的幂等控制；只读方法可留空。
	IdempotencyKey string
	// Metadata 是调用级辅助信息，不应用于替代权限、调度或核心业务字段。
	Metadata map[string]string
}

HostInvokeRequest 是插件调用 Core 方法的通用请求。

type HostInvokeResponse 

type HostInvokeResponse struct {
	// Status 是方法自己的业务状态；传输错误、鉴权错误和 schema 错误应通过 error 返回。
	Status string
	// Payload 是方法出参。SDK 不解释字段含义。
	Payload map[string]interface{}
	// Metadata 是调用级辅助信息。
	Metadata map[string]string
}

HostInvokeResponse 是 Core 方法调用的通用响应。

type HostStream 

type HostStream interface {
	Send(frame HostStreamFrame) error
	Recv() (*HostStreamFrame, error)
	CloseSend() error
}

HostStream 是插件与 Core 之间的双向流。

Recv 在流结束时返回 io.EOF。调用方不再发送数据时应调用 CloseSend。

type HostStreamFrame 

type HostStreamFrame struct {
	// Event 是 method 内部约定的帧类型，例如 "chunk"、"progress"、"error"、"result"。
	Event string
	// Status 是 method 自己的业务状态，通常只在最终帧使用。
	Status string
	// Payload 是当前帧的 JSON 对象语义数据。
	Payload map[string]interface{}
	// Metadata 是帧级辅助信息。
	Metadata map[string]string
	// Done 表示这是当前流的最终业务帧；传输层结束仍以 io.EOF 为准。
	Done bool
}

HostStreamFrame 是 InvokeStream 的单帧数据。

type HostStreamRequest 

type HostStreamRequest struct {
	Method string
	// Payload 是首帧入参。SDK 不解释字段含义，Core method 自己校验 schema。
	Payload map[string]interface{}
	// IdempotencyKey 用于副作用类流式方法的幂等控制；只读方法可留空。
	IdempotencyKey string
	// Metadata 是调用级辅助信息，不应用于替代权限、调度或核心业务字段。
	Metadata map[string]string
}

HostStreamRequest 是插件调用 Core 流式方法的起始请求。

type HostTask 

type HostTask struct {
	ID           int64
	PublicTaskID string
	PluginID     string
	TaskType     string
	Status       TaskStatus // pending, processing, completed, failed, cancelled
	UserID       int64
	Input        map[string]interface{}
	Output       map[string]interface{}
	Execution    map[string]interface{} // plugin internal state, survives retries
	ErrorMessage string
	Progress     int // 0-100
	Attempts     int
	MaxAttempts  int
	CreatedAt    time.Time
	UpdatedAt    time.Time
	StartedAt    *time.Time
	CompletedAt  *time.Time
}

HostTask 任务完整信息。

type InvokeSchema 

type InvokeSchema struct {
	Method  string `json:"method"`
	Summary string `json:"summary,omitempty"`
	// Transport 为空时等价于 unary。
	Transport InvokeTransport `json:"transport,omitempty"`
	Request   PayloadSchema   `json:"request,omitempty"`
	Response  PayloadSchema   `json:"response,omitempty"`
	// ClientFrame / ServerFrame 只用于 InvokeStream，描述双方 frame payload。
	ClientFrame PayloadSchema     `json:"client_frame,omitempty"`
	ServerFrame PayloadSchema     `json:"server_frame,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

InvokeSchema 描述通过 Host.Invoke 或 Host.InvokeStream 调用的扩展动作。

type InvokeTransport 

type InvokeTransport string

InvokeTransport 描述 Host.Invoke method 的传输模式。 

const (
	InvokeTransportUnary               InvokeTransport = "unary"
	InvokeTransportServerStream        InvokeTransport = "server_stream"
	InvokeTransportClientStream        InvokeTransport = "client_stream"
	InvokeTransportBidirectionalStream InvokeTransport = "bidirectional_stream"
)

type MiddlewareDecision 

type MiddlewareDecision struct {
	Action DecisionAction

	// DenyStatusCode / DenyMessage 仅 DecisionDeny 使用；默认 403。
	DenyStatusCode int32
	DenyMessage    string

	// SetHeaders 仅 DecisionMutate 使用：追加或覆盖的请求头。
	SetHeaders http.Header

	// Metadata 无论 Action 是什么都会 merge 进请求上下文的 bag。
	Metadata map[string]string
}

MiddlewareDecision OnForwardBegin 的返回值。nil 等价于 DecisionAllow 且不改任何东西。

type MiddlewareEvent 

type MiddlewareEvent struct {
	RequestID string
	UserID    int64
	GroupID   int64
	AccountID int64
	Platform  string
	Model     string
	Stream    bool

	StatusCode int32
	Duration   time.Duration
	Usage      *Usage
	ErrorKind  string // "" / "upstream_5xx" / "timeout" / "no_account" / ...
	ErrorMsg   string

	Metadata map[string]string

	// ResponseBody / ResponseHeaders 仅在插件声明 CapabilityMiddlewareReadBody 时填充。
	// 流式响应下 ResponseBody 只含摘要（首个非空 chunk）。
	ResponseBody    []byte
	ResponseHeaders http.Header
}

MiddlewareEvent OnForwardEnd 的入参。

type MiddlewarePlugin 

type MiddlewarePlugin interface {
	Plugin

	OnForwardBegin(ctx context.Context, req *MiddlewareRequest) (*MiddlewareDecision, error)
	OnForwardEnd(ctx context.Context, evt *MiddlewareEvent) error
}

MiddlewarePlugin 中间件插件接口。

PluginInfo.Type = PluginTypeMiddleware 时注册为"请求/响应拦截层"。Core 在每次 forward 的 前后回调 OnForwardBegin / OnForwardEnd，按 PluginInfo.Priority 升序进 Begin、降序出 End。

失败语义：Begin/End 返回 error 只会被 log warn，不 block 主流程。唯一例外是 OnForwardBegin 返回 DecisionDeny——此时请求被拒绝，用户看到的错误文案来自 Decision。

Payload：默认只给元数据；插件声明 CapabilityMiddlewareReadBody 才会收到 request_body / response_body。流式响应的 response_body 只给摘要。

type MiddlewareRequest 

type MiddlewareRequest struct {
	RequestID string
	UserID    int64
	GroupID   int64
	AccountID int64
	Platform  string
	Model     string
	Stream    bool

	// Metadata 贯穿 Begin/End 的 KV bag，多个 middleware 之间共享。
	Metadata map[string]string

	// RequestBody / RequestHeaders 仅在插件声明 CapabilityMiddlewareReadBody 时填充。
	RequestBody    []byte
	RequestHeaders http.Header
}

MiddlewareRequest OnForwardBegin 的入参。

type ModelInfo 

type ModelInfo struct {
	ID              string   `json:"id"`
	Name            string   `json:"name"`
	ContextWindow   int      `json:"context_window"`
	MaxOutputTokens int      `json:"max_output_tokens"`
	Capabilities    []string `json:"capabilities,omitempty"`

	// Metadata 保存展示、分类、供应商标签等非核心扩展信息。
	// Core 不应依赖这里做调度、计费或权限判断。
	Metadata map[string]string `json:"metadata,omitempty"`
}

ModelInfo 插件声明的模型信息。

Core 可用这些字段做展示、基础选择和能力过滤；具体价格、倍率、套餐和用量算法 由网关插件在 Forward 中计算后写入 Usage。

func (*ModelInfo) HasCapability 

func (m *ModelInfo) HasCapability(cap string) bool

HasCapability 检查模型是否具备指定能力。

type OutcomeKind 

type OutcomeKind int

OutcomeKind 一次 Forward 调用的判决类型。

插件必须在返回的 ForwardOutcome 里显式声明 Kind；零值 OutcomeUnknown 等于 "插件未声明"，Core 会按"可疑上游错误"保守处理（不透传响应给客户端、也不把账号标死）。 这是 SDK 契约的核心：插件只做判决，Core 只做执行。 

const (
	// OutcomeUnknown 保留给零值：插件未声明判决。Core 将保守处理。
	OutcomeUnknown OutcomeKind = iota

	// OutcomeSuccess 上游返回 2xx，Usage 必填。
	OutcomeSuccess

	// OutcomeClientError 4xx，错在客户端请求本身（context 过长、参数非法等）。
	// 换账号救不回来，Core 会把 Upstream 原样透传给客户端，不罚账号。
	OutcomeClientError

	// OutcomeAccountRateLimited 账号被上游限流（通常 429），冷却一段时间后可恢复。
	// Core 会把账号打入 RateLimited 状态 + 尝试 failover 到其它账号。
	OutcomeAccountRateLimited

	// OutcomeAccountDead 账号凭证失效（401/403，或上游语义化消息），需要人工处理。
	// Core 会把账号打入 Disabled 状态 + 尝试 failover。
	OutcomeAccountDead

	// OutcomeUpstreamTransient 上游抽风（5xx、连接抖动、超时），账号本身没问题。
	// Core 尝试 failover；累计多次后由状态机决定是否升级为 AccountDead。
	OutcomeUpstreamTransient

	// OutcomeStreamAborted 流式响应已经开始写入客户端，中途断开。
	// 不能 failover（字节已经发出去了），也不能把账号直接标死。
	OutcomeStreamAborted

	// OutcomeFamilyTransient 上游某个模型家族暂时过载（例如 model overloaded）。
	// Core 会把 (account, model-family) 写入短退避冷却并尝试 failover，不影响同账号其它 family。
	OutcomeFamilyTransient

	// OutcomeAccountUnavailable 账号暂时不可用（例如 OpenAI 账号临时 403）。
	// Core 会短暂降级并累计次数，连续达到阈值后再升级为 AccountDead。
	OutcomeAccountUnavailable
)

func (OutcomeKind) IsAccountFault 

func (k OutcomeKind) IsAccountFault() bool

IsAccountFault 本次判决是否需要避开当前选中的账号上下文。 FamilyTransient 只惩罚当前账号的当前模型家族，不会降级整个账号。

func (OutcomeKind) IsSuccess 

func (k OutcomeKind) IsSuccess() bool

IsSuccess 是否成功完成（2xx）。

func (OutcomeKind) ShouldFailover 

func (k OutcomeKind) ShouldFailover() bool

ShouldFailover 是否允许换账号重试。 ClientError 不应 failover（换号也救不回来）；StreamAborted 不能 failover（已写入）； Success / Unknown 显然不该 failover。

func (OutcomeKind) String 

func (k OutcomeKind) String() string

String 返回人类可读名称，用于日志。

type PayloadSchema 

type PayloadSchema struct {
	ContentType string            `json:"content_type,omitempty"`
	Schema      string            `json:"schema,omitempty"`
	Example     string            `json:"example,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

PayloadSchema 描述一个 JSON payload 的结构。

Schema 通常是 JSON Schema 字符串；Example 是 JSON 示例字符串。

type Plugin 

type Plugin interface {
	Info() PluginInfo
	Init(ctx PluginContext) error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

Plugin 所有插件的基础接口。

type PluginConfig 

type PluginConfig interface {
	GetString(key string) string
	GetInt(key string) int
	GetBool(key string) bool
	GetFloat64(key string) float64
	GetDuration(key string) time.Duration
	// GetAll 返回 JSONB 原始 map。
	GetAll() map[string]string
}

PluginConfig 配置读取接口。

type PluginContext 

type PluginContext interface {
	Logger() *slog.Logger
	Config() PluginConfig
}

PluginContext Core 注入给插件的最小上下文：Logger + Config。 其它能力（Host 反向调用、插件专属 DB DSN 等）通过可选接口暴露。

type PluginDSNAware 

type PluginDSNAware interface {
	// PluginDSN 返回 DSN；空字符串 = 未启用插件 DB。调用方需 nil/empty check。
	PluginDSN() string
}

PluginDSNAware 可选接口：实现它表示能拿到 Core 注入的插件专属 DB DSN。 DSN 已预设 search_path 到独立 schema（plugin_<id>），核心业务表在 PostgreSQL 层被 REVOKE。

type PluginEvent 

type PluginEvent struct {
	ID         string                 `json:"id,omitempty"`
	Type       string                 `json:"type"`
	Source     string                 `json:"source,omitempty"`
	Subject    string                 `json:"subject,omitempty"`
	UserID     int64                  `json:"user_id,omitempty"`
	GroupID    int64                  `json:"group_id,omitempty"`
	Payload    map[string]interface{} `json:"payload,omitempty"`
	Metadata   map[string]string      `json:"metadata,omitempty"`
	OccurredAt time.Time              `json:"occurred_at,omitempty"`
}

PluginEvent 是 Core 推送给插件的标准事件结构。

Payload 是事件类型相关的 JSON 对象；稳定事件应在插件 schema 中声明 payload schema。

type PluginInfo 

type PluginInfo struct {
	ID                 string           `json:"id"`
	Name               string           `json:"name"`
	Version            string           `json:"version"`
	SDKVersion         string           `json:"sdk_version"`
	Description        string           `json:"description"`
	Author             string           `json:"author"`
	Type               PluginType       `json:"type"`
	Dependencies       []string         `json:"dependencies"`
	ConfigSchema       []ConfigField    `json:"config_schema"`
	AccountTypes       []AccountType    `json:"account_types"`
	FrontendPages      []FrontendPage   `json:"frontend_pages"`
	FrontendWidgets    []FrontendWidget `json:"frontend_widgets"`
	InstructionPresets []string         `json:"instruction_presets"`
	Capabilities       []Capability     `json:"capabilities"`
	// DispatchDSL 声明插件默认的请求调度规则。Core 可在 group 级覆盖或追加，
	// 并把最终选中的 DispatchPlan 回传给插件。
	DispatchDSL DispatchDSL `json:"dispatch_dsl,omitempty"`
	// Metadata 保存插件声明层面的非核心扩展信息。
	// 只放展示、分类、市场索引等弱契约字段；需要 Core 授权或参与调度的字段必须进入显式 SDK 契约。
	Metadata map[string]string `json:"metadata,omitempty"`
	// Priority 仅对 type=middleware 生效：Begin 升序、End 降序（LIFO）。默认 100。
	Priority int32 `json:"priority"`
}

PluginInfo 插件元信息。

type PluginSchema 

type PluginSchema struct {
	Routes   []RouteSchema     `json:"routes,omitempty"`
	Tasks    []TaskSchema      `json:"tasks,omitempty"`
	Events   []EventSchema     `json:"events,omitempty"`
	Invokes  []InvokeSchema    `json:"invokes,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

PluginSchema 是插件的能力发现清单，用于 Core、管理后台和开发工具了解插件可用能力。

type PluginType 

type PluginType string

PluginType 插件扮演的角色。 

gateway    上游适配器（airgate-openai / claude 等）
extension  后台任务 + 自定义 HTTP 路由（airgate-health / epay 等）
middleware forward 路径上的旁路拦截层（审计 / 脱敏 / 记账等）

const (
	PluginTypeGateway    PluginType = "gateway"
	PluginTypeExtension  PluginType = "extension"
	PluginTypeMiddleware PluginType = "middleware"
)

type RequestHandler 

type RequestHandler interface {
	HandleRequest(ctx context.Context, method, path, query string, headers http.Header, body []byte) (statusCode int, respHeaders http.Header, respBody []byte, err error)
}

RequestHandler 可选：Core 将插件私有 API 请求透传给插件自行路由。

type RouteDefinition 

type RouteDefinition struct {
	Method      string `json:"method"`
	Path        string `json:"path"`
	Description string `json:"description"`
	// Metadata 保存路由展示、分类、文档链接等非核心扩展信息。
	Metadata map[string]string `json:"metadata,omitempty"`
}

RouteDefinition 网关插件声明的 API 端点。

type RouteRegistrar 

type RouteRegistrar interface {
	Handle(method, path string, handler http.HandlerFunc)
	Group(prefix string) RouteRegistrar
}

RouteRegistrar 扩展插件使用的路由注册器。

type RouteSchema 

type RouteSchema struct {
	Method   string            `json:"method"`
	Path     string            `json:"path"`
	Summary  string            `json:"summary,omitempty"`
	Request  PayloadSchema     `json:"request,omitempty"`
	Response PayloadSchema     `json:"response,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

RouteSchema 描述插件公开的自定义 HTTP API。

type SchemaProvider 

type SchemaProvider interface {
	Schema() PluginSchema
}

SchemaProvider 可选接口：插件实现后可向 Core 暴露结构化能力清单。

type TaskProcessor 

type TaskProcessor interface {
	// ProcessTask 处理一个异步任务。Context 带有超时。
	ProcessTask(ctx context.Context, task HostTask) error

	// TaskTypes 返回此插件能处理的任务类型列表。
	TaskTypes() []string
}

TaskProcessor 可选接口：扩展插件实现它来处理 Core 分发的异步任务。

Core 在后台轮询 pending 任务，按 plugin_id 找到对应插件调用 ProcessTask。 插件内部如需回写进度，应通过 Host.Invoke 调用 Core 开放的任务方法。

使用方式： 

func (p *MyPlugin) ProcessTask(ctx context.Context, task sdk.HostTask) error {
    _, _ = p.host.Invoke(ctx, sdk.HostInvokeRequest{
        Method: "tasks.update",
        Payload: map[string]interface{}{
            "task_id": task.ID,
            "status": sdk.TaskStatusProcessing.String(),
            "progress": 10,
        },
    })
    // ... 执行任务逻辑 ...
    _, _ = p.host.Invoke(ctx, sdk.HostInvokeRequest{
        Method: "tasks.update",
        Payload: map[string]interface{}{
            "task_id": task.ID,
            "status": sdk.TaskStatusCompleted.String(),
            "output": result,
        },
    })
    return nil
}

func (p *MyPlugin) TaskTypes() []string { return []string{"image_generation"} }

type TaskSchema 

type TaskSchema struct {
	Type     string            `json:"type"`
	Summary  string            `json:"summary,omitempty"`
	Input    PayloadSchema     `json:"input,omitempty"`
	Output   PayloadSchema     `json:"output,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

TaskSchema 描述插件支持的异步任务类型。

type TaskStatus 

type TaskStatus string
const (
	TaskStatusPending    TaskStatus = "pending"
	TaskStatusProcessing TaskStatus = "processing"
	TaskStatusCompleted  TaskStatus = "completed"
	TaskStatusFailed     TaskStatus = "failed"
	TaskStatusCancelled  TaskStatus = "cancelled"
)

func (TaskStatus) String 

func (s TaskStatus) String() string

type UpstreamResponse 

type UpstreamResponse struct {
	StatusCode int
	Headers    http.Header
	Body       []byte
}

UpstreamResponse 上游返回的原始 HTTP 快照。

语义：插件应尽量保存上游实际响应。Core 会先基于 Kind 组织调度 / failover； 最终不再重试时，若 Upstream 有可返回响应，则优先原样返回给客户端。 StreamAborted 场景 Body 通常为空（字节已经流给客户端）。

type Usage 

type Usage struct {
	Model                 string            `json:"model,omitempty"`
	AccountCost           float64           `json:"account_cost,omitempty"`
	UserCost              float64           `json:"user_cost,omitempty"`
	BillingMultiplier     float64           `json:"billing_multiplier,omitempty"`
	Currency              string            `json:"currency,omitempty"`
	Summary               string            `json:"summary,omitempty"`
	FirstTokenMs          int64             `json:"first_token_ms,omitempty"`
	InputTokens           int               `json:"input_tokens,omitempty"`
	OutputTokens          int               `json:"output_tokens,omitempty"`
	CachedInputTokens     int               `json:"cached_input_tokens,omitempty"`
	CacheCreationTokens   int               `json:"cache_creation_tokens,omitempty"`
	ReasoningOutputTokens int               `json:"reasoning_output_tokens,omitempty"`
	ReasoningEffort       string            `json:"reasoning_effort,omitempty"`
	InputPrice            float64           `json:"input_price,omitempty"`
	OutputPrice           float64           `json:"output_price,omitempty"`
	CachedInputPrice      float64           `json:"cached_input_price,omitempty"`
	CacheCreationPrice    float64           `json:"cache_creation_price,omitempty"`
	InputCost             float64           `json:"input_cost,omitempty"`
	OutputCost            float64           `json:"output_cost,omitempty"`
	CachedInputCost       float64           `json:"cached_input_cost,omitempty"`
	CacheCreationCost     float64           `json:"cache_creation_cost,omitempty"`
	Metadata              map[string]string `json:"metadata,omitempty"`
}

Usage 是插件计算后的单次调用用量与费用结果。

只有 OutcomeSuccess 下 Usage 必填；OutcomeClientError 如果上游也计费（如部分重置 context 后仍计 token）可填；其他 Kind 下应为 nil。

平台价格、token 拆分、图片分档等标准计费规则全部由网关插件自己实现。 插件填通用 token、单价和账号成本字段；Core 只读取这些通用标量字段并按用户、 分组、模型等倍率写入自己的 usage_log 标准列。插件特有维度（如 service_tier、 Claude cache TTL 拆分、OpenAI 图片尺寸/数量/单价）放入 Metadata。

type WebAssetsProvider 

type WebAssetsProvider interface {
	GetWebAssets() map[string][]byte
}

WebAssetsProvider 可选：插件通过此接口提供前端静态资源。

type WebSocketConn 

type WebSocketConn interface {
	ReadMessage() (messageType int, data []byte, err error)
	WriteMessage(messageType int, data []byte) error
	ConnectInfo() *WebSocketConnectInfo
	Close(code int, reason string) error
}

WebSocketConn 抽象的 WebSocket 连接，由 gRPC 双向流在 SDK 侧适配。

type WebSocketConnectInfo 

type WebSocketConnectInfo struct {
	Path         string
	Query        string
	Headers      http.Header
	RemoteAddr   string
	ConnectionID string
	Account      *Account
}

WebSocketConnectInfo WebSocket 连接建立时的元信息（由 Core 在 CONNECT 帧里下发）。

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.