refactor(*): 平台架构 - 拆分后端领域模块并同步插件协议与模型能力

This commit is contained in:
ddCat committed 2026-09-11 14:02:49 +08:00
1 parent 0945115e53
commit 7ce967df0f
644 files changed
+62731 -2320

No files matched your search

+57
View File
@@ -0,0 +1,57 @@
package generation
import (
"context"
"time"
"infinite-canvas/backend/internal/model"
"infinite-canvas/backend/internal/protocol"
)
// MediaResolver 水合参考媒体(资源 URL / data URL),由组合根注入,避免 generation → service 回环。
type MediaResolver interface {
HydrateGenerationMedia(userID string, input *Input, preferURL bool) error
}
// UpstreamPolicy 控制私网/本机上游放行。
type UpstreamPolicy interface {
WithOutboundPolicy(ctx context.Context, allowLocal bool) context.Context
}
// TaskProgress 写入任务进度/日志。
type TaskProgress interface {
SyncProviderTaskProgress(taskID string, responseBody []byte)
Log(userID, taskID, level, message, payload string) error
}
// BillingHooks 生成路径上的计费终态钩子。
type BillingHooks interface {
MarkBillingUncertain(taskID, reason string) error
Settle(taskID string) error
Refund(taskID, reason string) error
RestoreRefunded(taskID, reason string) error
}
// ChannelLimiter 渠道并发槽与熔断结果。
type ChannelLimiter interface {
AcquireChannelSlot(ctx context.Context, channelID string) (release func(), err error)
RecordChannelResult(channelID string, success bool)
}
// MediaPersister 持久化生成结果与资源 URL。
type MediaPersister interface {
PersistGeneratedMediaResult(ctx context.Context, userID, taskID string, result map[string]interface{}) (map[string]interface{}, error)
DirectResourceURL(resource *model.Resource, expiresAt time.Time) (string, error)
}
// Deps 是 Engine 的外部端口集合;禁止持有组合根或回环到 service。
type Deps struct {
Media MediaResolver
Upstream UpstreamPolicy
Progress TaskProgress
Billing BillingHooks
Channel ChannelLimiter
Persist MediaPersister
// Registry 可选;为空时 Engine 使用官方插件包回退表。
Registry *protocol.Registry
}
+4
View File
@@ -0,0 +1,4 @@
package generation
// 本包是画布生成域:声明式协议执行、text/image/video/audio 上游调用与任务恢复/取消。
// 组合根在 internal/service;本包不得 import internal/service。
+24
View File
@@ -0,0 +1,24 @@
package generation
import (
"infinite-canvas/backend/internal/protocol"
)
// Engine 是 generation 域的入口;由 service 组合根构造并注入 Deps。
type Engine struct {
deps Deps
}
func NewEngine(deps Deps) *Engine {
return &Engine{deps: deps}
}
func (e *Engine) ProtocolRegistry() *protocol.Registry {
if e == nil {
return nil
}
if e.deps.Registry != nil {
return e.deps.Registry
}
return loadOfficialFallbackRegistry()
}
@@ -0,0 +1,21 @@
package generation_test
import (
"testing"
"infinite-canvas/backend/internal/generation"
)
func TestGenerationPackageHasEngineAndOfficialRegistry(t *testing.T) {
engine := generation.NewEngine(generation.Deps{})
if engine == nil {
t.Fatal("NewEngine returned nil")
}
if name, ok := generation.OfficialDeclarativeImageInterface("openai-image"); !ok || name == "" {
t.Fatalf("openai-image whitelist = %q %v", name, ok)
}
registry := generation.LoadOfficialFallbackRegistry()
if registry == nil {
t.Fatal("LoadOfficialFallbackRegistry returned nil")
}
}
+241
View File
@@ -0,0 +1,241 @@
package generation
import (
"context"
"fmt"
"os"
"path/filepath"
"strings"
"sync"
"infinite-canvas/backend/internal/model"
"infinite-canvas/backend/internal/protocol"
)
type protocolRegistryContextKey struct{}
var emptyProtocolRegistry, _ = protocol.NewRegistry()
var officialFallbackRegistryMu sync.Mutex
var officialFallbackRegistryLoaded bool
var officialFallbackRegistry = emptyProtocolRegistry
func WithProtocolRegistry(ctx context.Context, registry *protocol.Registry) context.Context {
return context.WithValue(ctx, protocolRegistryContextKey{}, registry)
}
func ProtocolRegistryFromContext(ctx context.Context) (*protocol.Registry, bool) {
registry, ok := ctx.Value(protocolRegistryContextKey{}).(*protocol.Registry)
return registry, ok && registry != nil
}
func ProtocolAdapterForContext(ctx context.Context, id string) (protocol.Adapter, bool) {
registry, _ := ctx.Value(protocolRegistryContextKey{}).(*protocol.Registry)
if registry == nil {
registry = emptyProtocolRegistry
}
return registry.Resolve(strings.TrimSpace(id))
}
// EnsureOfficialProtocolAdapter 让未注入 registry 的调用(主要是单测)与生产一样
// 使用官方插件包。调用方若显式放入空 registry,表示要测“插件未安装”。
func EnsureOfficialProtocolAdapter(ctx context.Context, interfaceType string) context.Context {
if _, present := ProtocolRegistryFromContext(ctx); present {
return ctx
}
interfaceType = strings.TrimSpace(interfaceType)
if interfaceType == "" {
return ctx
}
registry := LoadOfficialFallbackRegistry()
adapter, ok := registry.Resolve(interfaceType)
if !ok || adapter.Metadata().Execution != "declarative" {
return ctx
}
return WithProtocolRegistry(ctx, registry)
}
func OfficialDeclarativeVideoInterface(interfaceType string) (string, bool) {
switch strings.TrimSpace(interfaceType) {
case string(model.ChannelInterfaceAgnesVideo):
return "Agnes", true
case string(model.ChannelInterfaceMiniMaxVideo):
return "MiniMax", true
case string(model.ChannelInterfaceGeminiVeo):
return "Gemini Veo", true
case string(model.ChannelInterfaceNovitaVideo):
return "Novita", true
case string(model.ChannelInterfaceNewAPIChannel2):
return "NewAPI Video Generations", true
case string(model.ChannelInterfaceNewAPIChannel1):
return "NewAPI 媒体任务", true
case string(model.ChannelInterfaceXAIVideo):
return "xAI", true
case string(model.ChannelInterfaceVolcengineArkVideo):
return "火山方舟", true
case string(model.ChannelInterfaceVolcengineJiMengVideo):
return "即梦", true
case string(model.ChannelInterfaceNewAPIVideo):
return "OpenAI Videos", true
default:
return "", false
}
}
func OfficialDeclarativeImageInterface(interfaceType string) (string, bool) {
switch strings.TrimSpace(interfaceType) {
case string(model.ChannelInterfaceGeminiImage):
return "Gemini Images", true
case string(model.ChannelInterfaceOpenAIImage):
return "OpenAI Images", true
case string(model.ChannelInterfaceGrokImage):
return "Grok Images", true
case string(model.ChannelInterfaceVolcengineArkImage):
return "火山方舟图片", true
case string(model.ChannelInterfaceVolcengineJiMengImage):
return "即梦图片", true
default:
return "", false
}
}
func OfficialDeclarativeAudioInterface(interfaceType string) (string, bool) {
switch strings.TrimSpace(interfaceType) {
case string(model.ChannelInterfaceOpenAIAudio):
return "OpenAI Audio", true
case string(model.ChannelInterfaceAsyncAudio):
return "异步音频", true
default:
return "", false
}
}
func DeclarativeProtocolAdapterForContext(ctx context.Context, id string) (protocol.Adapter, bool) {
adapter, ok := ProtocolAdapterForContext(ctx, id)
if !ok || adapter.Metadata().Execution != "declarative" {
return nil, false
}
return adapter, true
}
func AgentProtocolAdapterForContext(ctx context.Context, id string) (protocol.AgentAdapter, bool) {
registry, _ := ctx.Value(protocolRegistryContextKey{}).(*protocol.Registry)
if registry == nil {
registry = emptyProtocolRegistry
}
adapter, ok := registry.Resolve(strings.TrimSpace(id))
if !ok || adapter.Metadata().Execution != "declarative" {
return nil, false
}
agentAdapter, ok := adapter.(protocol.AgentAdapter)
if !ok {
return nil, false
}
capability, ok := adapter.(protocol.AgentCapability)
return agentAdapter, ok && capability.AgentAvailable()
}
func LoadOfficialFallbackRegistry() *protocol.Registry {
officialFallbackRegistryMu.Lock()
defer officialFallbackRegistryMu.Unlock()
if officialFallbackRegistryLoaded {
return officialFallbackRegistry
}
load := func() {
directory, err := OfficialPluginPackageDir()
if err != nil {
return
}
entries, err := os.ReadDir(directory)
if err != nil {
return
}
adapters := make([]protocol.Adapter, 0, len(entries))
for _, entry := range entries {
if entry.IsDir() || !strings.HasSuffix(strings.ToLower(entry.Name()), ".yingce-plugin") {
continue
}
data, err := os.ReadFile(filepath.Join(directory, entry.Name()))
if err != nil {
return
}
pkg, err := protocol.ParsePluginPackage(data)
if err != nil {
return
}
providers, err := protocol.LoadInstalledProviders(pkg.ManifestRaw, nil)
if err != nil {
return
}
adapters = append(adapters, providers...)
}
registry, err := protocol.NewRegistry(adapters...)
if err == nil {
officialFallbackRegistry = registry
officialFallbackRegistryLoaded = true
}
}
load()
return officialFallbackRegistry
}
func OfficialPluginPackageDir() (string, error) {
if configured := strings.TrimSpace(os.Getenv("CANVAS_OFFICIAL_PLUGIN_DIR")); configured != "" {
info, err := os.Stat(configured)
if err != nil || !info.IsDir() {
return "", fmt.Errorf("CANVAS_OFFICIAL_PLUGIN_DIR 不是可读目录:%s", configured)
}
return configured, nil
}
workingDir, err := os.Getwd()
if err != nil {
return "", err
}
candidates := []string{"/app/plugin-packages"}
current := workingDir
for range 8 {
candidates = append(candidates, filepath.Join(current, "plugin-packages"))
parent := filepath.Dir(current)
if parent == current {
break
}
current = parent
}
for _, candidate := range candidates {
if info, err := os.Stat(candidate); err == nil && info.IsDir() {
return candidate, nil
}
}
return "", fmt.Errorf("未找到官方插件目录 plugin-packages")
}
// 兼容包内未导出旧名(service 薄包装与未改调用点)。
func withProtocolRegistry(ctx context.Context, registry *protocol.Registry) context.Context {
return WithProtocolRegistry(ctx, registry)
}
func protocolRegistryFromContext(ctx context.Context) (*protocol.Registry, bool) {
return ProtocolRegistryFromContext(ctx)
}
func protocolAdapterForContext(ctx context.Context, id string) (protocol.Adapter, bool) {
return ProtocolAdapterForContext(ctx, id)
}
func ensureOfficialProtocolAdapter(ctx context.Context, interfaceType string) context.Context {
return EnsureOfficialProtocolAdapter(ctx, interfaceType)
}
func officialDeclarativeVideoInterface(interfaceType string) (string, bool) {
return OfficialDeclarativeVideoInterface(interfaceType)
}
func officialDeclarativeImageInterface(interfaceType string) (string, bool) {
return OfficialDeclarativeImageInterface(interfaceType)
}
func officialDeclarativeAudioInterface(interfaceType string) (string, bool) {
return OfficialDeclarativeAudioInterface(interfaceType)
}
func declarativeProtocolAdapterForContext(ctx context.Context, id string) (protocol.Adapter, bool) {
return DeclarativeProtocolAdapterForContext(ctx, id)
}
func agentProtocolAdapterForContext(ctx context.Context, id string) (protocol.AgentAdapter, bool) {
return AgentProtocolAdapterForContext(ctx, id)
}
func loadOfficialFallbackRegistry() *protocol.Registry {
return LoadOfficialFallbackRegistry()
}
+312
View File
@@ -0,0 +1,312 @@
package generation
import (
"fmt"
"net/http"
"time"
"infinite-canvas/backend/internal/outbound"
)
// Input 是画布生成任务的统一输入合同。
type Input struct {
Mode string `json:"mode"`
Prompt string `json:"prompt"`
Config Config `json:"config"`
ReferenceImages []Media `json:"referenceImages"`
ReferenceVideos []Media `json:"referenceVideos"`
ReferenceAudios []Media `json:"referenceAudios"`
TextHistory []TextMessage `json:"textHistory"`
Mask *Media `json:"mask"`
Metadata map[string]interface{} `json:"metadata"`
AgentRequests *AgentToolRequests `json:"agentRequests"`
TextOptions TextOptions `json:"textOptions"`
ImageCapability *ImageCapabilityConfig `json:"-"`
StreamText bool `json:"-"`
MaxOutputTokens int `json:"-"`
OnTextDelta func(string) `json:"-"`
VideoCapability *VideoCapabilityConfig `json:"-"`
}
type TextOptions struct {
Stream *bool `json:"stream"`
Thinking bool `json:"thinking"`
}
type AgentToolRequests struct {
Canonical *CanonicalAgentRequest `json:"canonical,omitempty"`
Responses map[string]interface{} `json:"responses"`
ChatCompletion map[string]interface{} `json:"chatCompletion"`
Claude map[string]interface{} `json:"claude"`
Gemini map[string]interface{} `json:"gemini"`
}
// CanonicalAgentRequest 是协议无关的画布 Agent 会话合同(域类型;service 侧仍有同结构实现期间兼容)。
type CanonicalAgentRequest struct {
Messages []map[string]interface{} `json:"messages"`
Tools []map[string]interface{} `json:"tools"`
ToolChoice interface{} `json:"toolChoice"`
SystemPrompt string `json:"systemPrompt"`
}
type TextMessage struct {
Role string `json:"role"`
Content string `json:"content"`
}
type Config struct {
ChannelID string `json:"channelId"`
ChannelModelKey string `json:"channelModelKey,omitempty"`
PriceTierID string `json:"priceTierId,omitempty"`
ProviderModelKey string `json:"providerModelKey,omitempty"`
APIFormat string `json:"apiFormat"`
InterfaceType string `json:"interfaceType"`
BaseURL string `json:"baseUrl"`
AllowLocalChannel bool `json:"allowLocalChannel"`
APIKey string `json:"apiKey"`
SecretKey string `json:"secretKey"`
Headers []outbound.OutboundHeader `json:"headers"`
Model string `json:"model"`
Size string `json:"size"`
Quality string `json:"quality"`
TransparentBackground string `json:"transparentBackground"`
Count string `json:"count"`
VideoSeconds string `json:"videoSeconds"`
VQuality string `json:"vquality"`
VideoGenerateAudio string `json:"videoGenerateAudio"`
VideoWatermark string `json:"videoWatermark"`
ArkPrivateAssetUpload string `json:"videoArkPrivateAssetUpload"`
AudioVoice string `json:"audioVoice"`
AudioFormat string `json:"audioFormat"`
AudioSpeed string `json:"audioSpeed"`
AudioInstructions string `json:"audioInstructions"`
SystemPrompt string `json:"systemPrompt"`
CapabilityConfig *ModelCapabilityConfig `json:"capabilityConfig"`
WorkflowID string `json:"workflowId"`
WebappID string `json:"webappId"`
WorkflowJSON map[string]interface{} `json:"workflowJson"`
WorkflowFields []WorkflowField `json:"workflowFields"`
BridgeID string `json:"bridgeId"`
RunningHubUseWallet bool `json:"runningHubUseWallet"`
RunningHubWalletKey string `json:"runningHubWalletApiKey"`
RunningHubUploadKey string `json:"runningHubUploadApiKey"`
}
type Media struct {
ID string `json:"id"`
Name string `json:"name"`
Type string `json:"type"`
DataURL string `json:"dataUrl"`
URL string `json:"url"`
StorageKey string `json:"storageKey"`
MimeType string `json:"mimeType"`
Bytes int64 `json:"bytes"`
Width int `json:"width"`
Height int `json:"height"`
DurationMs int64 `json:"durationMs"`
}
// WorkflowField 是 RunningHub/ComfyUI 共用的字段描述。完整工作流执行仍在 service。
type WorkflowField struct {
ID string `json:"id"`
NodeID string `json:"nodeId"`
ClassType string `json:"classType,omitempty"`
FieldName string `json:"fieldName"`
Value interface{} `json:"value,omitempty"`
FieldValue interface{} `json:"fieldValue,omitempty"`
FieldType string `json:"fieldType,omitempty"`
Label string `json:"label,omitempty"`
Role string `json:"role,omitempty"`
SafeToOverride *bool `json:"safeToOverride,omitempty"`
OptionsSource string `json:"optionsSource,omitempty"`
Options []interface{} `json:"options,omitempty"`
Min interface{} `json:"min,omitempty"`
Max interface{} `json:"max,omitempty"`
Step interface{} `json:"step,omitempty"`
RandomEnabled bool `json:"randomEnabled,omitempty"`
BindPrompt bool `json:"bindPrompt,omitempty"`
Enabled *bool `json:"enabled,omitempty"`
Source string `json:"source,omitempty"`
SourceIndex int `json:"sourceIndex,omitempty"`
ImageOrder int `json:"imageOrder,omitempty"`
SourceFromUpstream bool `json:"sourceFromUpstream,omitempty"`
Required bool `json:"required,omitempty"`
SourceAutomatic *bool `json:"sourceAutomatic,omitempty"`
sourceConfigured bool
}
// SourceConfigured 暴露反序列化期间的来源配置标记,供 service 工作流逻辑使用。
func (f WorkflowField) SourceConfigured() bool { return f.sourceConfigured }
// SetSourceConfigured 供 service 在归一化路径写入来源配置标记。
func (f *WorkflowField) SetSourceConfigured(v bool) { f.sourceConfigured = v }
type MediaHydrationPolicy struct {
RequireURL bool
PreferURL bool
}
// ModelCapabilityConfig 是模型能力声明,不包含供应商字段名。
type ModelCapabilityConfig struct {
Version int `json:"version"`
Text *TextCapabilityConfig `json:"text,omitempty"`
Image *ImageCapabilityConfig `json:"image,omitempty"`
Video *VideoCapabilityConfig `json:"video,omitempty"`
}
type TextCapabilityConfig struct {
References TextReferenceConfig `json:"references"`
}
type TextReferenceConfig struct {
PromptMaxChars int `json:"promptMaxChars"`
MaxImages int `json:"maxImages"`
MaxImageBytes int64 `json:"maxImageBytes"`
MaxVideos int `json:"maxVideos"`
MaxVideoBytes int64 `json:"maxVideoBytes"`
}
type ImageCapabilityConfig struct {
References ImageReferenceConfig `json:"references"`
Size ImageSizeConfig `json:"size"`
Quality ImageQualityConfig `json:"quality"`
TransparentBackground VideoBooleanConfig `json:"transparentBackground"`
ResponseFormat ParameterSupport `json:"responseFormat"`
OutputFormat ParameterSupport `json:"outputFormat"`
MaxOutputs int `json:"maxOutputs"`
}
type ImageReferenceConfig struct {
PromptMaxChars int `json:"promptMaxChars"`
MaxImages int `json:"maxImages"`
MaxImageBytes int64 `json:"maxImageBytes"`
MaskSupported bool `json:"maskSupported"`
}
type ImageSizeConfig struct {
Parameter string `json:"parameter"`
Values []string `json:"values"`
Default string `json:"default"`
AllowCustom bool `json:"allowCustom"`
Presets []ImageSizePreset `json:"presets,omitempty"`
}
type ImageSizePreset struct {
Tier string `json:"tier"`
Ratio string `json:"ratio"`
Size string `json:"size"`
Width int `json:"width"`
Height int `json:"height"`
}
type ImageQualityConfig struct {
Supported bool `json:"supported"`
Values []string `json:"values"`
Default string `json:"default"`
}
type ParameterSupport struct {
Supported bool `json:"supported"`
}
type VideoCapabilityConfig struct {
References VideoReferenceConfig `json:"references"`
Duration VideoDurationConfig `json:"duration"`
DurationSupported *bool `json:"durationSupported,omitempty"`
Ratios []string `json:"ratios"`
DefaultRatio string `json:"defaultRatio"`
Resolutions []string `json:"resolutions"`
DefaultResolution string `json:"defaultResolution"`
GenerateAudio VideoBooleanConfig `json:"generateAudio"`
Watermark VideoBooleanConfig `json:"watermark"`
Operations []string `json:"operations"`
DefaultOperation string `json:"defaultOperation"`
}
type VideoReferenceConfig struct {
PromptMaxChars int `json:"promptMaxChars"`
MinImages int `json:"minImages"`
MaxImages int `json:"maxImages"`
MaxImageBytes int64 `json:"maxImageBytes"`
MaxVideos int `json:"maxVideos"`
MaxVideoBytes int64 `json:"maxVideoBytes"`
MaxVideoDuration int `json:"maxVideoDurationSeconds"`
MaxAudios int `json:"maxAudios"`
MaxAudioBytes int64 `json:"maxAudioBytes"`
MaxAudioDuration int `json:"maxAudioDurationSeconds"`
}
type VideoDurationConfig struct {
Selection string `json:"selection"`
Min int `json:"min,omitempty"`
Max int `json:"max,omitempty"`
Step int `json:"step,omitempty"`
Values []int `json:"values,omitempty"`
Default int `json:"default"`
}
type VideoBooleanConfig struct {
Supported bool `json:"supported"`
Default bool `json:"default"`
}
type imageResponse struct {
Data []map[string]interface{} `json:"data"`
Error *UpstreamError `json:"error"`
Code *int `json:"code"`
Msg string `json:"msg"`
}
type UpstreamError struct {
Message string `json:"message"`
}
// PayloadError 在进程内保留上游原始原因;对调用方只暴露归类后的稳定文案。
type PayloadError struct {
raw string
message string
}
func (e PayloadError) Error() string { return e.message }
func (e PayloadError) Raw() string { return e.raw }
// HTTPError 是上游 HTTP 失败的结构化错误。
type HTTPError struct {
StatusCode int
Status string
Body string
RetryAfter time.Duration
}
func (e HTTPError) Error() string {
switch e.StatusCode {
case 524:
return "上游网关超时(524):模型请求可能仍在服务端执行并产生费用,请勿立即重试,请先到供应商后台核对任务或账单"
case http.StatusBadRequest, http.StatusUnprocessableEntity:
return "模型服务拒绝了请求,请检查模型和参数"
case http.StatusUnauthorized, http.StatusForbidden:
return "模型服务鉴权失败,请检查 API Key 和模型权限"
case http.StatusNotFound:
return "模型或模型接口不存在,请检查渠道配置"
case http.StatusRequestTimeout, http.StatusGatewayTimeout:
return "模型服务响应超时,请稍后重试"
case http.StatusTooManyRequests:
return "模型服务请求过于频繁或额度不足,请稍后重试"
}
if e.StatusCode >= http.StatusInternalServerError {
return fmt.Sprintf("模型服务暂时不可用(HTTP %d)", e.StatusCode)
}
return fmt.Sprintf("模型服务请求失败(HTTP %d)", e.StatusCode)
}
// StatePendingError 表示上游任务状态尚未同步,应继续查询原任务。
type StatePendingError struct {
TaskID string
Cause error
}
func (e StatePendingError) Error() string {
return fmt.Sprintf("上游任务状态尚未同步,将继续查询原任务(任务 %s)", e.TaskID)
}
func (e StatePendingError) Unwrap() error { return e.Cause }