fix(gemini): 移除空返图占位并暴露失败原因

Gemini 图片响应未包含可提取资源时，不再返回伪造占位图，改为非重试失败并保留安全拦截、候选结束状态和上游错误等结构化诊断。\n\n同步将诊断写入 HTTP 错误、任务结果、attempt 指标和日志，确保任务失败时不结算，并补充单元及 PostgreSQL 验收测试。\n\n验证：gofmt、go test ./... -count=1、go vet ./...、迁移安全检查、pnpm openapi。

apps/api/internal/clients/clients_test.go

@@ -1533,6 +1533,94 @@ func TestGeminiClientImageGenerateBuildsNativeImageBody(t *testing.T) {
 	}
 }
 
+func TestGeminiClientImageGenerateRejectsPromptBlockedWithoutImage(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("X-Request-Id", "gemini-blocked-request")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"promptFeedback": map[string]any{
+				"blockReason":        "SAFETY",
+				"blockReasonMessage": "The request was blocked by the image safety policy.",
+			},
+			"usageMetadata": map[string]any{"promptTokenCount": 12, "totalTokenCount": 12},
+		})
+	}))
+	defer server.Close()
+
+	_, err := (GeminiClient{HTTPClient: server.Client()}).Run(context.Background(), Request{
+		Kind:      "images.generations",
+		ModelType: "image_generate",
+		Model:     "gemini-image",
+		Body:      map[string]any{"model": "gemini-image", "prompt": "blocked prompt"},
+		Candidate: store.RuntimeModelCandidate{
+			BaseURL:           server.URL,
+			ProviderModelName: "gemini-image",
+			ModelType:         "image_generate",
+			Credentials:       map[string]any{"apiKey": "gemini-key"},
+		},
+	})
+	if err == nil {
+		t.Fatal("missing Gemini image must fail instead of returning a placeholder")
+	}
+	if ErrorCode(err) != "gemini_image_output_missing" || IsRetryable(err) {
+		t.Fatalf("unexpected missing image error: code=%q retryable=%v err=%v", ErrorCode(err), IsRetryable(err), err)
+	}
+	meta := ErrorResponseMetadata(err)
+	if meta.RequestID != "gemini-blocked-request" || meta.ResponseDurationMS < 0 {
+		t.Fatalf("missing image error lost response metadata: %+v", meta)
+	}
+	details := ErrorDetails(err)
+	if details["reason"] != "prompt_blocked" || details["promptBlockReason"] != "SAFETY" || details["candidateCount"] != 0 {
+		t.Fatalf("unexpected prompt block details: %+v", details)
+	}
+	if !strings.Contains(err.Error(), "blockReason=SAFETY") || strings.Contains(err.Error(), "gemini-image-placeholder") {
+		t.Fatalf("missing image error should explain the upstream block without a placeholder: %v", err)
+	}
+}
+
+func TestGeminiMissingImageDetailsExplainEmptyImagePayload(t *testing.T) {
+	details := geminiMissingImageDetails(map[string]any{
+		"candidates": []any{map[string]any{
+			"finishReason": "STOP",
+			"content": map[string]any{"parts": []any{
+				map[string]any{"inlineData": map[string]any{"mimeType": "image/png", "data": ""}},
+				map[string]any{"text": "The model completed without producing an image."},
+			}},
+		}},
+	})
+	message := geminiMissingImageMessage(details)
+
+	if details["reason"] != "empty_image_payload" || details["candidateCount"] != 1 || details["partCount"] != 2 {
+		t.Fatalf("unexpected empty image payload details: %+v", details)
+	}
+	if !strings.Contains(message, "missing inline data or file URI") ||
+		!strings.Contains(message, "finishReason=STOP") ||
+		!strings.Contains(message, "The model completed without producing an image.") {
+		t.Fatalf("missing image message should preserve the concrete extraction reason: %s", message)
+	}
+}
+
+func TestGeminiMissingImageDetailsPreserveUpstreamErrorEnvelope(t *testing.T) {
+	details := geminiMissingImageDetails(map[string]any{
+		"error": map[string]any{
+			"code":    500,
+			"status":  "INTERNAL",
+			"message": "image backend returned no generated asset",
+		},
+	})
+	message := geminiMissingImageMessage(details)
+
+	if details["reason"] != "upstream_error" ||
+		details["upstreamErrorCode"] != "500" ||
+		details["upstreamErrorStatus"] != "INTERNAL" {
+		t.Fatalf("unexpected upstream error details: %+v", details)
+	}
+	if !strings.Contains(message, "upstreamErrorCode=500") ||
+		!strings.Contains(message, "upstreamErrorStatus=INTERNAL") ||
+		!strings.Contains(message, "image backend returned no generated asset") {
+		t.Fatalf("upstream error message should remain diagnostic: %s", message)
+	}
+}
+
 func TestGeminiGenerationConfigInitializesMissingImageConfig(t *testing.T) {
 	config := geminiGenerationConfig(map[string]any{
 		"aspect_ratio": "16:9",

apps/api/internal/clients/gemini.go

@@ -58,7 +58,13 @@ func (c GeminiClient) Run(ctx context.Context, request Request) (Response, error
 	if err != nil {
 		return Response{}, annotateResponseError(err, requestID, responseStartedAt, responseFinishedAt)
 	}
-	output := geminiResult(request, result)
+	output, err := geminiResult(request, result)
+	if err != nil {
+		if requestID == "" {
+			requestID = firstNonEmptyString(result["responseId"], result["response_id"])
+		}
+		return Response{}, annotateResponseError(err, requestID, responseStartedAt, responseFinishedAt)
+	}
 	if requestID == "" {
 		requestID = requestIDFromResult(output)
 	}
@@ -631,18 +637,24 @@ func geminiToolsFromOpenAITools(value any) []any {
 	return []any{map[string]any{"functionDeclarations": declarations}}
 }
 
-func geminiResult(request Request, raw map[string]any) map[string]any {
+func geminiResult(request Request, raw map[string]any) (map[string]any, error) {
 	if geminiImageModelType(request.ModelType) {
 		data := geminiImageData(raw)
 		if len(data) == 0 {
-			data = []any{map[string]any{"url": "/static/provider/gemini-image-placeholder.png"}}
+			details := geminiMissingImageDetails(raw)
+			return nil, &ClientError{
+				Code:      "gemini_image_output_missing",
+				Message:   geminiMissingImageMessage(details),
+				Details:   details,
+				Retryable: false,
+			}
 		}
 		return map[string]any{
 			"id":      "gemini-image",
 			"created": nowUnix(),
 			"model":   request.Model,
 			"data":    data,
-		}
+		}, nil
 	}
 	message, finishReason := geminiChatMessage(raw)
 	return map[string]any{
@@ -656,7 +668,7 @@ func geminiResult(request Request, raw map[string]any) map[string]any {
 			"message":       message,
 		}},
 		"usage": geminiUsageMap(raw),
-	}
+	}, nil
 }
 
 func textFromMessages(body map[string]any) string {
@@ -771,6 +783,250 @@ func geminiImageData(raw map[string]any) []any {
 	return out
 }
 
+func geminiMissingImageDetails(raw map[string]any) map[string]any {
+	details := map[string]any{
+		"provider":     "gemini",
+		"resourceType": "image",
+	}
+	upstreamError, _ := raw["error"].(map[string]any)
+	upstreamErrorCode := stringFromPathValue(upstreamError["code"])
+	upstreamErrorStatus := strings.TrimSpace(stringFromAny(upstreamError["status"]))
+	upstreamErrorMessage := compactGeminiDiagnosticText(stringFromAny(upstreamError["message"]), 320)
+	if upstreamErrorCode != "" {
+		details["upstreamErrorCode"] = upstreamErrorCode
+	}
+	if upstreamErrorStatus != "" {
+		details["upstreamErrorStatus"] = upstreamErrorStatus
+	}
+	if upstreamErrorMessage != "" {
+		details["upstreamErrorMessage"] = upstreamErrorMessage
+	}
+	promptFeedback, _ := raw["promptFeedback"].(map[string]any)
+	if promptFeedback == nil {
+		promptFeedback, _ = raw["prompt_feedback"].(map[string]any)
+	}
+	promptBlockReason := firstNonEmptyString(promptFeedback["blockReason"], promptFeedback["block_reason"])
+	promptBlockMessage := compactGeminiDiagnosticText(firstNonEmptyString(
+		promptFeedback["blockReasonMessage"],
+		promptFeedback["block_reason_message"],
+		promptFeedback["message"],
+	), 320)
+	if promptBlockReason != "" {
+		details["promptBlockReason"] = promptBlockReason
+	}
+	if promptBlockMessage != "" {
+		details["promptBlockMessage"] = promptBlockMessage
+	}
+
+	candidates, _ := raw["candidates"].([]any)
+	details["candidateCount"] = len(candidates)
+	finishReasons := make([]string, 0)
+	safetyCategories := make([]string, 0)
+	partKinds := make([]string, 0)
+	providerMessages := make([]string, 0)
+	partCount := 0
+	emptyImagePayload := false
+	for _, rawCandidate := range candidates {
+		candidate, _ := rawCandidate.(map[string]any)
+		if finishReason := strings.TrimSpace(stringFromAny(firstPresent(candidate["finishReason"], candidate["finish_reason"]))); finishReason != "" {
+			finishReasons = appendGeminiDiagnosticValue(finishReasons, finishReason)
+		}
+		safetyRatings, _ := candidate["safetyRatings"].([]any)
+		if safetyRatings == nil {
+			safetyRatings, _ = candidate["safety_ratings"].([]any)
+		}
+		for _, rawRating := range safetyRatings {
+			rating, _ := rawRating.(map[string]any)
+			blocked, _ := firstPresent(rating["blocked"], rating["isBlocked"], rating["is_blocked"]).(bool)
+			if !blocked {
+				continue
+			}
+			if category := strings.TrimSpace(stringFromAny(rating["category"])); category != "" {
+				safetyCategories = appendGeminiDiagnosticValue(safetyCategories, category)
+			}
+		}
+		content, _ := candidate["content"].(map[string]any)
+		parts, _ := content["parts"].([]any)
+		partCount += len(parts)
+		for _, rawPart := range parts {
+			part, _ := rawPart.(map[string]any)
+			if text := compactGeminiDiagnosticText(stringFromAny(part["text"]), 320); text != "" {
+				partKinds = appendGeminiDiagnosticValue(partKinds, "text")
+				providerMessages = appendGeminiDiagnosticValue(providerMessages, text)
+			}
+			inline, inlinePresent := part["inlineData"].(map[string]any)
+			if !inlinePresent {
+				inline, inlinePresent = part["inline_data"].(map[string]any)
+			}
+			if inlinePresent {
+				partKinds = appendGeminiDiagnosticValue(partKinds, "inlineData")
+				if strings.TrimSpace(stringFromAny(inline["data"])) == "" {
+					emptyImagePayload = true
+				}
+			}
+			fileData, filePresent := part["fileData"].(map[string]any)
+			if !filePresent {
+				fileData, filePresent = part["file_data"].(map[string]any)
+			}
+			if filePresent {
+				partKinds = appendGeminiDiagnosticValue(partKinds, "fileData")
+				if firstNonEmptyString(fileData["fileUri"], fileData["file_uri"], fileData["uri"]) == "" {
+					emptyImagePayload = true
+				}
+			}
+			for _, item := range []struct {
+				key  string
+				kind string
+			}{
+				{key: "thought", kind: "thought"},
+				{key: "functionCall", kind: "functionCall"},
+				{key: "function_call", kind: "functionCall"},
+				{key: "executableCode", kind: "executableCode"},
+				{key: "executable_code", kind: "executableCode"},
+				{key: "codeExecutionResult", kind: "codeExecutionResult"},
+				{key: "code_execution_result", kind: "codeExecutionResult"},
+			} {
+				if _, ok := part[item.key]; ok {
+					partKinds = appendGeminiDiagnosticValue(partKinds, item.kind)
+				}
+			}
+		}
+	}
+	details["partCount"] = partCount
+	if len(finishReasons) > 0 {
+		details["candidateFinishReasons"] = finishReasons
+	}
+	if len(safetyCategories) > 0 {
+		details["blockedSafetyCategories"] = safetyCategories
+	}
+	if len(partKinds) > 0 {
+		details["observedPartKinds"] = partKinds
+	}
+	if len(providerMessages) > 0 {
+		details["providerMessages"] = providerMessages
+	}
+
+	reason := "no_supported_image_parts"
+	switch {
+	case upstreamErrorCode != "" || upstreamErrorStatus != "" || upstreamErrorMessage != "":
+		reason = "upstream_error"
+	case promptBlockReason != "":
+		reason = "prompt_blocked"
+	case len(safetyCategories) > 0 || geminiFinishReasonsIndicateFiltering(finishReasons):
+		reason = "candidate_filtered"
+	case len(candidates) == 0:
+		reason = "no_candidates"
+	case emptyImagePayload:
+		reason = "empty_image_payload"
+	case partCount == 0:
+		reason = "no_content_parts"
+	}
+	details["reason"] = reason
+	return details
+}
+
+func geminiMissingImageMessage(details map[string]any) string {
+	message := "Gemini image response contains no extractable image"
+	switch stringFromAny(details["reason"]) {
+	case "upstream_error":
+		message += ": upstream returned an error envelope"
+	case "prompt_blocked":
+		message += ": prompt blocked"
+	case "candidate_filtered":
+		message += ": candidate filtered"
+	case "no_candidates":
+		message += ": upstream response contains no candidates"
+	case "empty_image_payload":
+		message += ": image part is missing inline data or file URI"
+	case "no_content_parts":
+		message += ": candidate content contains no parts"
+	default:
+		message += ": candidate parts contain no supported image resource"
+	}
+	if reason := stringFromAny(details["promptBlockReason"]); reason != "" {
+		message += " (blockReason=" + reason + ")"
+	}
+	if code := stringFromAny(details["upstreamErrorCode"]); code != "" {
+		message += "; upstreamErrorCode=" + code
+	}
+	if status := stringFromAny(details["upstreamErrorStatus"]); status != "" {
+		message += "; upstreamErrorStatus=" + status
+	}
+	if values := geminiDiagnosticStrings(details["candidateFinishReasons"]); len(values) > 0 {
+		message += "; finishReason=" + strings.Join(values, ",")
+	}
+	if values := geminiDiagnosticStrings(details["blockedSafetyCategories"]); len(values) > 0 {
+		message += "; blockedSafetyCategories=" + strings.Join(values, ",")
+	}
+	if values := geminiDiagnosticStrings(details["providerMessages"]); len(values) > 0 {
+		message += "; providerMessage=" + values[0]
+	} else if upstreamMessage := stringFromAny(details["upstreamErrorMessage"]); upstreamMessage != "" {
+		message += "; providerMessage=" + upstreamMessage
+	} else if blockMessage := stringFromAny(details["promptBlockMessage"]); blockMessage != "" {
+		message += "; providerMessage=" + blockMessage
+	}
+	if values := geminiDiagnosticStrings(details["observedPartKinds"]); len(values) > 0 {
+		message += "; observedPartKinds=" + strings.Join(values, ",")
+	}
+	return compactGeminiDiagnosticText(message, 1800)
+}
+
+func geminiFinishReasonsIndicateFiltering(values []string) bool {
+	for _, value := range values {
+		normalized := strings.ToUpper(strings.TrimSpace(value))
+		switch normalized {
+		case "SAFETY", "IMAGE_SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII":
+			return true
+		}
+	}
+	return false
+}
+
+func geminiDiagnosticStrings(value any) []string {
+	switch typed := value.(type) {
+	case []string:
+		return typed
+	case []any:
+		values := make([]string, 0, len(typed))
+		for _, item := range typed {
+			if text := strings.TrimSpace(stringFromAny(item)); text != "" {
+				values = append(values, text)
+			}
+		}
+		return values
+	default:
+		return nil
+	}
+}
+
+func appendGeminiDiagnosticValue(values []string, value string) []string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return values
+	}
+	for _, existing := range values {
+		if existing == value {
+			return values
+		}
+	}
+	if len(values) >= 8 {
+		return values
+	}
+	return append(values, value)
+}
+
+func compactGeminiDiagnosticText(value string, maxRunes int) string {
+	value = strings.Join(strings.Fields(value), " ")
+	if maxRunes <= 0 {
+		return ""
+	}
+	runes := []rune(value)
+	if len(runes) <= maxRunes {
+		return value
+	}
+	return string(runes[:maxRunes]) + "…"
+}
+
 func geminiUsage(raw map[string]any) Usage {
 	usageMap := geminiUsageMap(raw)
 	input := intFromAny(usageMap["prompt_tokens"])

apps/api/internal/clients/types.go

@@ -127,6 +127,7 @@ type ClientError struct {
 	Code               string
 	Message            string
 	Param              string
+	Details            map[string]any
 	StatusCode         int
 	RequestID          string
 	ResponseStartedAt  time.Time
@@ -152,6 +153,18 @@ func ErrorParam(err error) string {
 	return ""
 }
 
+func ErrorDetails(err error) map[string]any {
+	var clientErr *ClientError
+	if !errors.As(err, &clientErr) || len(clientErr.Details) == 0 {
+		return nil
+	}
+	details := make(map[string]any, len(clientErr.Details))
+	for key, value := range clientErr.Details {
+		details[key] = value
+	}
+	return details
+}
+
 func (e *ClientError) Error() string {
 	if e.Message != "" {
 		return e.Message