fix(agent): 媒体准入参数结构化纠错

backend/internal/app/model_capability_argument.go

@@ -0,0 +1,67 @@
+package app
+
+import "errors"
+
+// modelCapabilityArgumentError preserves the machine-readable field that caused
+// a capability rejection while keeping the normal 400 AppError projection for
+// non-Agent task callers.
+type modelCapabilityArgumentError struct {
+	*AppError
+	Field string
+	Issue string
+}
+
+func (e *modelCapabilityArgumentError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.AppError
+}
+
+func newModelCapabilityArgumentError(field, issue string, cause error) error {
+	if cause == nil {
+		cause = BadAuthRequest("模型能力参数无效")
+	}
+	return &modelCapabilityArgumentError{AppError: BadAuthRequest(cause.Error()), Field: field, Issue: issue}
+}
+
+func modelCapabilityMismatchError(match CapabilityMatch) error {
+	details := map[string]any{"capabilityIssues": match.Issues}
+	for _, issue := range match.Issues {
+		if issue.Kind != "option" {
+			continue
+		}
+		field := issue.Name
+		if field == "vquality" {
+			field = "quality"
+		}
+		details["field"] = field
+		details["issue"] = "unsupported_value"
+		details["message"] = issue.Reason
+		break
+	}
+	return NewModelError(ErrCodeModelCapabilityNotSupported, "所选模型不支持当前请求").WithDetails(details)
+}
+
+func cloudAgentMediaCapabilityArgumentError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var argumentErr *modelCapabilityArgumentError
+	if errors.As(err, &argumentErr) && argumentErr != nil && argumentErr.Field != "" {
+		return cloudAgentFieldError(argumentErr.Field, argumentErr.Issue, argumentErr.Error())
+	}
+	var modelErr *ModelError
+	if errors.As(err, &modelErr) && modelErr != nil {
+		field, _ := modelErr.Details["field"].(string)
+		issue, _ := modelErr.Details["issue"].(string)
+		if field != "" && issue != "" {
+			message, _ := modelErr.Details["message"].(string)
+			if message == "" {
+				message = modelErr.Error()
+			}
+			return cloudAgentFieldError(field, issue, message+"；请按本回合 model_list 返回的能力参数修正后重试")
+		}
+	}
+	return nil
+}