feat(image): 以插件声明统一图片参数、尺寸选择与定价合同 (#760)

* feat(image): 图片参数 - 统一插件声明配置与生成合同

* docs(image): 图片参数 - 说明声明合同与验证边界

* fix(plugins): 图片声明 - 保留内联素材支持并同步制品文档

* fix(image): 参数合同 - 对齐审批意图和尺寸预检调用方

* fix(image): 调用链 - 保留公开意图并接通独立分辨率

* fix(image): 图片参数 - 补齐分辨率接线与目录价格投影
This commit is contained in:
huiku authored and GitHub committed 2026-10-13 19:18:21 +08:00
1 parent 88de4ce422
commit 7466119867
104 files changed
+6013 -568

No files matched your search

@@ -0,0 +1,292 @@
package protocol
import (
"encoding/json"
"fmt"
"math"
"regexp"
"slices"
"strings"
)
// ImageParameter is the image input contract shared by plugins, model
// configuration and generation. Binding is interpreted only at the provider
// boundary; names and values are never inferred from a model's display name.
type ImageParameter struct {
Name string `json:"name"`
Label string `json:"label"`
Type string `json:"type"`
Description string `json:"description,omitempty"`
Values []any `json:"values,omitempty"`
Min *float64 `json:"min,omitempty"`
Max *float64 `json:"max,omitempty"`
Step *float64 `json:"step,omitempty"`
MaxLength int `json:"maxLength,omitempty"`
Default any `json:"default,omitempty"`
Required bool `json:"required,omitempty"`
Pricing bool `json:"pricing,omitempty"`
Binding string `json:"binding,omitempty"`
Encoding string `json:"encoding,omitempty"`
Models []string `json:"models,omitempty"`
Enabled *bool `json:"enabled,omitempty"`
}
func (p ImageParameter) IsEnabled() bool { return p.Enabled == nil || *p.Enabled }
func (p ImageParameter) AppliesTo(model string) bool {
return len(p.Models) == 0 || slices.Contains(p.Models, strings.TrimPrefix(strings.TrimSpace(model), "models/"))
}
var imageParameterName = regexp.MustCompile(`^[A-Za-z][A-Za-z0-9_]{0,63}$`)
func ValidateImageParameters(parameters []ImageParameter) error {
seen := map[string]bool{}
bindings := map[string]bool{}
for _, p := range parameters {
if !imageParameterName.MatchString(p.Name) || seen[p.Name] || strings.TrimSpace(p.Label) == "" {
return fmt.Errorf("invalid or duplicate image parameter %q", p.Name)
}
seen[p.Name] = true
if p.Encoding != "" && (p.Binding != "aspectRatio" || p.Encoding != "pixels" && p.Encoding != "ratio") {
return fmt.Errorf("image parameter %s has invalid encoding", p.Name)
}
switch p.Type {
case "string", "number", "integer", "boolean":
default:
return fmt.Errorf("image parameter %s has unsupported type %s", p.Name, p.Type)
}
if p.Min != nil && (!finite(*p.Min) || p.Max != nil && *p.Min > *p.Max) || p.Max != nil && !finite(*p.Max) || p.Step != nil && (!finite(*p.Step) || *p.Step <= 0) || p.MaxLength < 0 {
return fmt.Errorf("image parameter %s has invalid bounds", p.Name)
}
if p.Binding != "" {
if !validImageParameterBinding(p.Binding) || bindings[p.Binding] {
return fmt.Errorf("image parameter %s has invalid or duplicate binding", p.Name)
}
bindings[p.Binding] = true
}
for _, value := range p.Values {
constraint := p
constraint.Values = nil
if !constraint.Accepts(value) {
return fmt.Errorf("image parameter %s has invalid enum value", p.Name)
}
}
if p.Default != nil && !p.Accepts(p.Default) {
return fmt.Errorf("image parameter %s default is outside its constraints", p.Name)
}
}
return nil
}
func finite(value float64) bool { return !math.IsNaN(value) && !math.IsInf(value, 0) }
func (p ImageParameter) Accepts(value any) bool {
if value == nil {
return !p.Required
}
switch p.Type {
case "string":
text, ok := value.(string)
if !ok || p.MaxLength > 0 && len([]rune(text)) > p.MaxLength {
return false
}
case "boolean":
if _, ok := value.(bool); !ok {
return false
}
case "number", "integer":
number, ok := imageParameterNumber(value)
if !ok || !finite(number) || p.Type == "integer" && math.Trunc(number) != number {
return false
}
if p.Min != nil && number < *p.Min || p.Max != nil && number > *p.Max {
return false
}
if p.Step != nil {
base := 0.0
if p.Min != nil {
base = *p.Min
}
steps := (number - base) / *p.Step
if math.Abs(steps-math.Round(steps)) > 1e-8 {
return false
}
}
default:
return false
}
if len(p.Values) == 0 {
return true
}
for _, candidate := range p.Values {
if ImageParameterValuesEqual(candidate, value) {
return true
}
}
return false
}
func imageParameterNumber(value any) (float64, bool) {
switch v := value.(type) {
case float64:
return v, true
case float32:
return float64(v), true
case int:
return float64(v), true
case int64:
return float64(v), true
case json.Number:
n, err := v.Float64()
return n, err == nil
default:
return 0, false
}
}
func ImageParameterValuesEqual(left, right any) bool {
l, lok := imageParameterNumber(left)
r, rok := imageParameterNumber(right)
if lok || rok {
return lok && rok && l == r
}
lb, _ := json.Marshal(left)
rb, _ := json.Marshal(right)
return string(lb) == string(rb)
}
func validImageParameterBinding(binding string) bool {
switch binding {
case "aspectRatio", "resolution", "quality", "imageCount", "transparentBackground":
return true
}
parts := strings.Split(binding, ".")
return len(parts) == 3 && parts[0] == "providerOptions" && validManifestIdentifier(parts[1]) && imageParameterName.MatchString(parts[2])
}
// ResolveImageParameters takes only channel-editable restrictions. Labels,
// types, pricing eligibility and bindings always come from the plugin.
func ResolveImageParameters(definitions, configured []ImageParameter, model string) ([]ImageParameter, error) {
if err := ValidateImageParameters(definitions); err != nil {
return nil, err
}
settings := map[string]ImageParameter{}
for _, p := range configured {
if _, duplicate := settings[p.Name]; duplicate {
return nil, fmt.Errorf("duplicate image parameter %s", p.Name)
}
settings[p.Name] = p
}
result := make([]ImageParameter, 0, len(definitions))
for _, definition := range definitions {
if !definition.AppliesTo(model) {
continue
}
p := definition
if setting, ok := settings[p.Name]; ok {
p.Enabled = setting.Enabled
if !p.IsEnabled() && p.Required {
return nil, fmt.Errorf("%s is required", p.Label)
}
if setting.Values != nil {
for _, value := range setting.Values {
if !definition.Accepts(value) {
return nil, fmt.Errorf("%s value exceeds plugin constraints", p.Label)
}
}
if len(setting.Values) == 0 && len(definition.Values) > 0 && p.IsEnabled() {
return nil, fmt.Errorf("%s requires supported values", p.Label)
}
p.Values = setting.Values
}
if setting.Min != nil {
if definition.Min != nil && *setting.Min < *definition.Min {
return nil, fmt.Errorf("%s minimum exceeds plugin constraints", p.Label)
}
p.Min = setting.Min
}
if setting.Max != nil {
if definition.Max != nil && *setting.Max > *definition.Max {
return nil, fmt.Errorf("%s maximum exceeds plugin constraints", p.Label)
}
p.Max = setting.Max
}
if setting.Step != nil {
if definition.Step != nil && (math.Abs(*setting.Step / *definition.Step - math.Round(*setting.Step / *definition.Step)) > 1e-8 || *setting.Step < *definition.Step) {
return nil, fmt.Errorf("%s step exceeds plugin constraints", p.Label)
}
p.Step = setting.Step
}
if definition.Step != nil && p.Min != nil {
base := 0.0
if definition.Min != nil {
base = *definition.Min
}
steps := (*p.Min - base) / *definition.Step
if math.Abs(steps-math.Round(steps)) > 1e-8 {
return nil, fmt.Errorf("%s minimum does not align with plugin step", p.Label)
}
}
p.Default = setting.Default
delete(settings, p.Name)
}
result = append(result, p)
}
for name, p := range settings {
if p.IsEnabled() {
return nil, fmt.Errorf("plugin does not declare image parameter %s for this model", name)
}
}
return result, ValidateImageParameters(result)
}
// ApplyImageParameters runs before building a request. It preserves false and
// zero, rejects undeclared values, and maps only plugin-declared destinations.
func ApplyImageParameters(request GenerationRequest, definitions []ImageParameter) (GenerationRequest, error) {
if request.Capability != CapabilityImage || request.ImageParameters == nil {
return request, nil
}
allowed := map[string]ImageParameter{}
for _, p := range definitions {
if p.AppliesTo(request.Model) {
allowed[p.Name] = p
}
}
if request.ProviderOptions == nil {
request.ProviderOptions = map[string]map[string]any{}
}
if request.Extra == nil {
request.Extra = map[string]any{}
}
for name, value := range request.ImageParameters {
p, ok := allowed[name]
if !ok || !p.Accepts(value) {
return request, fmt.Errorf("unsupported image parameter %s", name)
}
if value == nil {
continue
}
switch p.Binding {
case "aspectRatio":
request.AspectRatio = fmt.Sprint(value)
case "resolution":
request.Resolution = fmt.Sprint(value)
case "quality":
request.Quality = fmt.Sprint(value)
case "imageCount":
n, _ := imageParameterNumber(value)
request.ImageCount = int(n)
case "transparentBackground":
request.Extra["transparentBackground"] = fmt.Sprint(value)
default:
parts := strings.Split(p.Binding, ".")
if len(parts) != 3 || parts[0] != "providerOptions" {
return request, fmt.Errorf("image parameter %s has no request binding", name)
}
if request.ProviderOptions[parts[1]] == nil {
request.ProviderOptions[parts[1]] = map[string]any{}
}
request.ProviderOptions[parts[1]][parts[2]] = value
}
}
return request, nil
}
@@ -0,0 +1,67 @@
package protocol
import (
"context"
"testing"
)
func TestImageParametersPluginRequestPreservesValuesAndModelScope(t *testing.T) {
adapter := officialPackageAdapter(t, "kacang-midjourney.yingce-plugin", "kacang-midjourney")
if len(adapter.Metadata().ImageParameters) == 0 {
t.Fatal("packaged plugin is missing image parameter declarations")
}
request := GenerationRequest{Capability: CapabilityImage, Model: "mj-v8.2", Prompt: "portrait", ImageParameters: map[string]any{
"size": "1:1", "count": 1, "seed": 0, "raw": false, "chaos": 0, "stylize": 450, "mjQuality": 0.5,
}}
spec, err := adapter.BuildCreate(context.Background(), RequestContext{Request: request})
if err != nil {
t.Fatal(err)
}
body := manifestTestBody(t, spec)
for name, expected := range map[string]any{"size": "1:1", "seed": float64(0), "raw": false, "chaos": float64(0), "stylize": float64(450), "quality": 0.5} {
if body[name] != expected {
t.Fatalf("%s = %#v, want %#v", name, body[name], expected)
}
}
request.Model = "Midjourney v8.2 高速"
if _, err := adapter.BuildCreate(context.Background(), RequestContext{Request: request}); err == nil {
t.Fatal("fast model accepted unsupported stable-only parameters")
}
request.Model = "mj-v8.2"
request.ImageParameters["stylize"] = 1001
if _, err := adapter.BuildCreate(context.Background(), RequestContext{Request: request}); err == nil {
t.Fatal("out of range value accepted")
}
}
func TestImageParametersCannotExpandPluginConstraintsOrBindings(t *testing.T) {
minimum, maximum := 0.0, 100.0
definitions := []ImageParameter{{Name: "amount", Label: "Amount", Type: "number", Min: &minimum, Max: &maximum, Binding: "providerOptions.example.amount"}}
expanded := 101.0
if _, err := ResolveImageParameters(definitions, []ImageParameter{{Name: "amount", Max: &expanded}}, "model"); err == nil {
t.Fatal("channel expanded plugin bounds")
}
resolved, err := ResolveImageParameters(definitions, []ImageParameter{{Name: "amount", Binding: "providerOptions.evil.amount", Pricing: true, Default: 0}}, "model")
if err != nil {
t.Fatal(err)
}
if resolved[0].Binding != definitions[0].Binding || resolved[0].Pricing {
t.Fatalf("channel replaced trusted metadata: %#v", resolved[0])
}
if _, err := ResolveImageParameters(definitions, []ImageParameter{{Name: "invented"}}, "model"); err == nil {
t.Fatal("undeclared field accepted")
}
}
func TestImageParametersGeminiResolutionIsIndependentFromStaleQuality(t *testing.T) {
adapter := officialPackageAdapter(t, "google-gemini-image.yingce-plugin", "gemini-image")
request := GenerationRequest{Capability: CapabilityImage, Model: "image-model", Prompt: "portrait", ImageParameters: map[string]any{"imageResolution": "2k", "seed": 0}}
spec, err := adapter.BuildCreate(context.Background(), RequestContext{Request: request})
if err != nil {
t.Fatal(err)
}
config := manifestTestBody(t, spec)["generationConfig"].(map[string]any)
if config["imageConfig"].(map[string]any)["imageSize"] != "2K" || config["seed"] != float64(0) {
t.Fatalf("mapped request: %#v", config)
}
}
+12
View File
@@ -292,6 +292,17 @@ func ValidateManifest(manifest Manifest) error {
return fmt.Errorf("duplicate provider contribution %q", provider.ID)
}
providerIDs[provider.ID] = struct{}{}
if err := ValidateImageParameters(provider.ImageParameters); err != nil {
return fmt.Errorf("provider %q image parameters: %w", provider.ID, err)
}
for _, parameter := range provider.ImageParameters {
if parameter.Binding == "" {
return fmt.Errorf("provider %q image parameter %s requires a binding", provider.ID, parameter.Name)
}
if strings.HasPrefix(parameter.Binding, "providerOptions.") && !strings.HasPrefix(parameter.Binding, "providerOptions."+provider.ID+".") {
return fmt.Errorf("provider %q image parameter %s must use its own namespace", provider.ID, parameter.Name)
}
}
if len(provider.Capabilities) == 0 || len(provider.Scopes) == 0 {
return fmt.Errorf("provider contribution %q requires capabilities and scopes", provider.ID)
}
@@ -399,6 +410,7 @@ func normalizeManifestForProvider(manifest *Manifest, index int) error {
manifest.Metadata.Categories = provider.Capabilities
manifest.Metadata.Scopes = provider.Scopes
manifest.Metadata.Parameters = provider.Parameters
manifest.Metadata.ImageParameters = provider.ImageParameters
manifest.Metadata.Create = operationSummary(provider.Create)
manifest.Metadata.Poll = operationSummaryPtr(provider.Poll)
manifest.Metadata.Cancel = operationSummaryPtr(provider.Cancel)
@@ -32,10 +32,14 @@ func (a manifestAdapter) BuildCreate(_ context.Context, c RequestContext) (Reque
if len(a.manifest.Contributes.Providers) == 0 {
return RequestSpec{}, fmt.Errorf("plugin %s does not provide a provider", a.manifest.Metadata.ID)
}
if err := validateManifestRequest(a.manifest.Validations, c.Request); err != nil {
request, err := ApplyImageParameters(c.Request, a.manifest.Metadata.ImageParameters)
if err != nil {
return RequestSpec{}, err
}
return buildManifestOperation(a.manifest.Create, a.manifest.Auth, c.Request, "")
if err := validateManifestRequest(a.manifest.Validations, request); err != nil {
return RequestSpec{}, err
}
return buildManifestOperation(a.manifest.Create, a.manifest.Auth, request, "")
}
func (a manifestAdapter) BuildAgent(_ context.Context, c AgentRequestContext) (RequestSpec, error) {
+22 -19
View File
@@ -95,6 +95,7 @@ type GenerationRequest struct {
Operation string `json:"operation,omitempty"`
Output OutputOptions `json:"output,omitempty"`
ProviderOptions map[string]map[string]any `json:"providerOptions,omitempty"`
ImageParameters map[string]any `json:"imageParameters,omitempty"`
Extra map[string]any `json:"extra,omitempty"`
}
@@ -163,25 +164,26 @@ type Parameter struct {
}
type Metadata struct {
ID string `json:"id"`
Version string `json:"version"`
Name string `json:"name"`
Vendor string `json:"vendor"`
Description string `json:"description,omitempty"`
Categories []Capability `json:"categories"`
Scopes []Surface `json:"scopes"`
Parameters []Parameter `json:"parameters,omitempty"`
Create string `json:"-"`
Poll string `json:"-"`
Cancel string `json:"-"`
ContentType string `json:"-"`
Documentation string `json:"documentation,omitempty"`
LegacyAliases []string `json:"-"`
Enabled bool `json:"enabled"`
Installable bool `json:"installable"`
Execution string `json:"-"`
RequiresPublicMediaURLs bool `json:"-"`
UnavailableReason string `json:"-"`
ID string `json:"id"`
Version string `json:"version"`
Name string `json:"name"`
Vendor string `json:"vendor"`
Description string `json:"description,omitempty"`
Categories []Capability `json:"categories"`
Scopes []Surface `json:"scopes"`
Parameters []Parameter `json:"parameters,omitempty"`
ImageParameters []ImageParameter `json:"imageParameters,omitempty"`
Create string `json:"-"`
Poll string `json:"-"`
Cancel string `json:"-"`
ContentType string `json:"-"`
Documentation string `json:"documentation,omitempty"`
LegacyAliases []string `json:"-"`
Enabled bool `json:"enabled"`
Installable bool `json:"installable"`
Execution string `json:"-"`
RequiresPublicMediaURLs bool `json:"-"`
UnavailableReason string `json:"-"`
}
// Manifest is the single plugin contract. A plugin may contribute providers,
@@ -338,6 +340,7 @@ type ManifestProvider struct {
RequiresPublicMediaURLs bool `json:"requiresPublicMediaUrls,omitempty"`
Auth ManifestAuth `json:"auth,omitempty"`
Parameters []Parameter `json:"parameters,omitempty"`
ImageParameters []ImageParameter `json:"imageParameters,omitempty"`
Validations []ManifestValidation `json:"validations,omitempty"`
Create ManifestOperation `json:"create"`
Agent *ManifestOperation `json:"agent,omitempty"`