wpmind/includes/API/Services/StructuredOutputService.php

<?php
/**
 * Structured Output Service
 *
 * 处理结构化输出（JSON Schema）和批量处理
 *
 * @package WPMind
 * @subpackage API\Services
 * @since 3.7.0
 */

declare(strict_types=1);

namespace WPMind\API\Services;

use WP_Error;

/**
 * Structured Output Service
 *
 * @since 3.7.0
 */
class StructuredOutputService extends AbstractService {

	private ChatService $chat_service;

	public function __construct(ChatService $chat_service) {
		$this->chat_service = $chat_service;
	}

	/**
	 * 结构化输出（JSON Schema）
	 *
	 * @since 2.6.0
	 * @param array|string $messages 消息
	 * @param array        $schema   JSON Schema
	 * @param array        $options  选项
	 * @return array|WP_Error
	 */
	public function structured($messages, array $schema, array $options = []) {
		$defaults = [
			'context'     => 'structured',
			'max_tokens'  => 2000,
			'temperature' => 0.3,
			'retries'     => 3,
		];
		$options = wp_parse_args($options, $defaults);

		$context = $options['context'];

		$schema_json = wp_json_encode($schema, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
		$schema_prompt = "你必须返回严格符合以下 JSON Schema 的 JSON 对象。不要返回其他内容，只返回 JSON：\n\n```json\n{$schema_json}\n```";

		if (is_string($messages)) {
			$messages = [
				['role' => 'system', 'content' => $schema_prompt],
				['role' => 'user', 'content' => $messages],
			];
		} else {
			array_unshift($messages, ['role' => 'system', 'content' => $schema_prompt]);
		}

		$max_retries = $options['retries'];
		$last_error = null;

		for ($attempt = 1; $attempt <= $max_retries; $attempt++) {
			$result = $this->chat_service->chat($messages, [
				'context'     => $context,
				'max_tokens'  => $options['max_tokens'],
				'temperature' => $options['temperature'],
				'json_mode'   => true,
				'cache_ttl'   => 0,
			]);

			if (is_wp_error($result)) {
				return $result;
			}

			$content = $result['content'];
			$parsed = json_decode($content, true);

			if (json_last_error() === JSON_ERROR_NONE) {
				if ($this->validate_schema($parsed, $schema)) {
					return [
						'data'     => $parsed,
						'provider' => $result['provider'],
						'model'    => $result['model'],
						'usage'    => $result['usage'],
						'attempts' => $attempt,
					];
				}
			}

			$last_error = json_last_error_msg();

			$messages[] = ['role' => 'assistant', 'content' => $content];
			$messages[] = [
				'role' => 'user',
				'content' => "JSON 解析失败或不符合 Schema: {$last_error}。请重新生成严格符合 Schema 的 JSON。",
			];
		}

		return new WP_Error(
			'wpmind_structured_failed',
			sprintf(__('结构化输出失败（尝试 %d 次）: %s', 'wpmind'), $max_retries, $last_error)
		);
	}

	/**
	 * 批量处理
	 *
	 * @since 2.6.0
	 * @param array  $items          要处理的项目数组
	 * @param string $prompt_template Prompt 模板
	 * @param array  $options         选项
	 * @return array|WP_Error
	 */
	public function batch(array $items, string $prompt_template, array $options = []) {
		$defaults = [
			'context'        => 'batch',
			'max_tokens'     => 500,
			'temperature'    => 0.7,
			'concurrency'    => 1,
			'delay_ms'       => 100,
			'stop_on_error'  => false,
		];
		$options = wp_parse_args($options, $defaults);

		$context = $options['context'];
		$results = [];
		$errors = [];

		do_action('wpmind_before_request', 'batch', compact('items', 'prompt_template', 'options'), $context);

		foreach ($items as $index => $item) {
			$item_str = is_array($item) ? wp_json_encode($item, JSON_UNESCAPED_UNICODE) : (string)$item;
			$prompt = str_replace('{{item}}', $item_str, $prompt_template);
			$prompt = str_replace('{{index}}', (string)$index, $prompt);

			$result = $this->chat_service->chat($prompt, [
				'context'     => $context . '_item_' . $index,
				'max_tokens'  => $options['max_tokens'],
				'temperature' => $options['temperature'],
				'cache_ttl'   => 0,
			]);

			if (is_wp_error($result)) {
				$errors[$index] = $result->get_error_message();
				if ($options['stop_on_error']) {
					break;
				}
				$results[$index] = null;
			} else {
				$results[$index] = [
					'content' => $result['content'],
					'usage'   => $result['usage'],
				];
			}

			if ($options['delay_ms'] > 0 && $index < count($items) - 1) {
				usleep($options['delay_ms'] * 1000);
			}
		}

		$total_tokens = array_sum(array_map(function($r) {
			return $r['usage']['total_tokens'] ?? 0;
		}, array_filter($results)));

		do_action('wpmind_after_request', 'batch', $results, compact('items', 'options'), ['total_tokens' => $total_tokens]);

		return [
			'results'      => $results,
			'errors'       => $errors,
			'total_items'  => count($items),
			'success_count'=> count(array_filter($results)),
			'error_count'  => count($errors),
			'total_tokens' => $total_tokens,
		];
	}

	/**
	 * 验证 JSON Schema（简化版）
	 *
	 * @param array $data   数据
	 * @param array $schema Schema
	 * @return bool
	 */
	public function validate_schema(array $data, array $schema): bool {
		if (isset($schema['required'])) {
			foreach ($schema['required'] as $field) {
				if (!isset($data[$field])) {
					return false;
				}
			}
		}

		if (isset($schema['properties'])) {
			foreach ($schema['properties'] as $key => $prop) {
				if (!isset($data[$key])) continue;

				$value = $data[$key];
				$type = $prop['type'] ?? null;

				if ($type === 'string' && !is_string($value)) return false;
				if ($type === 'integer' && !is_int($value)) return false;
				if ($type === 'number' && !is_numeric($value)) return false;
				if ($type === 'boolean' && !is_bool($value)) return false;
				if ($type === 'array' && !is_array($value)) return false;
				if ($type === 'object' && !is_array($value)) return false;
			}
		}

		return true;
	}
}