[Protocolo revelado 1] Desmantelamiento del protocolo de comunicación central de AI Ready: carga útil de API y verificación de seguridad de Webhook

Respuesta directa: El protocolo AI Ready debería elevar las tareas de IA de "un mensaje" a eventos API manejables. Cada solicitud debe contener intención, fuente, contexto, datos, restricciones y clave de idempotencia; El webhook debe tener marca de tiempo, nonce, firma y protección de reproducción.

¿A quién va dirigido este artículo?#

• Ingeniero de desarrollo del core del sistema de comercio electrónico.

• Se requiere backend y arquitecto para diseñar API de tareas de IA.

• Equipo técnico responsable de la seguridad, reintentos y auditoría del webhook.

¿Por qué las tareas de IA requieren protocolos de comunicación?#

Si cada complemento arroja un mensaje al modelo, será difícil para el sistema responder las siguientes preguntas:

• ¿Quién desencadenó esta misión?

• ¿Qué información puede leer la IA?

• ¿Puede la IA responder?

• ¿Qué idioma y tienda se utilizan para la tarea?

• ¿Cuál es el presupuesto simbólico?

• ¿Es posible volver a intentarlo después de un fracaso?

• ¿Los webhooks duplicados provocarán operaciones duplicadas?

El propósito del protocolo AI Ready es incluir esta información de administración en cada tarea, en lugar de estar dispersa en el código y las indicaciones del programa.

Solicitar estructura básica de carga útil#

{
  "event_id": "evt_20260415_001",
  "idempotency_key": "product-copy-1288-zhTW-v3",
  "intent": "generate_product_copy",
  "source": {
    "platform": "woocommerce",
    "store_id": "tw-store",
    "site_url": "https://example.com"
  },
  "context": {
    "locale": "zh-TW",
    "currency": "TWD",
    "actor": {
      "type": "admin",
      "id": "42"
    },
    "permissions": ["product:read", "draft:write"]
  },
  "data": {
    "product": {
      "sku": "BAG-18L-NAVY",
      "name": "18L 防潑水通勤背包",
      "attributes": {
        "capacity": "18L",
        "material": "recycled polyester"
      }
    }
  },
  "constraints": {
    "write_mode": "draft_only",
    "max_tokens": 1200,
    "do_not_change": ["sku", "price", "stock_quantity"]
  }
}

Cada campo debe tener un significado claro:

• event_id: identificación única del evento.

• idempotency_key: evita operaciones repetidas provocadas por reintentos.

• intención: tipo de tarea.

• source: plataforma fuente y tienda.

• contexto: idioma, moneda, operador y permisos.

• datos: los datos necesarios para la tarea.

• constraints: restricciones de modelo y reescritura.

Estructura básica de la carga útil de respuesta#

{
  "event_id": "evt_20260415_001",
  "status": "completed",
  "result": {
    "draft_short_description": "適合日常通勤的 18L 防潑水背包。",
    "meta_description": "18L 防潑水通勤背包，適合筆電收納與城市移動。"
  },
  "validation": {
    "schema_valid": true,
    "requires_review": true
  },
  "usage": {
    "model": "provider-model-name",
    "input_tokens": 680,
    "output_tokens": 220
  }
}

La respuesta no solo debe contener texto, sino también incluir el estado de verificación, los requisitos de revisión y el uso del token.

Diseño de firma de webhook#

Encabezado sugerido:

X-AI-Ready-Timestamp: 1776268800
X-AI-Ready-Nonce: 4a8f7c...
X-AI-Ready-Signature: sha256=...
X-AI-Ready-Event-Id: evt_20260415_001
Idempotency-Key: product-copy-1288-zhTW-v3

El contenido de la firma puede utilizar una cadena canónica:

{timestamp}.{nonce}.{raw_body}

Luego haga HMAC SHA-256 con la clave compartida. El extremo receptor debe:

1. Verifique si la marca de tiempo está dentro del período de tiempo permitido.
2. Compruebe si se utiliza el nonce.
3. Utilice cuerpo sin formato para volver a calcular la firma.
4. Verifique la identificación del evento y la clave de idempotencia.
5. Guarde el estado de procesamiento.

Códigos de estado HTTP y reintentos#

• 200 / 204: Procesado exitosamente o ya procesado.

• 400: el formato de carga útil es incorrecto y no se debe volver a intentar.

• 401 / 403: error de firma o permiso; no se debe volver a intentar hasta que se corrija la configuración.

• 409: conflicto de idempotencia, se requiere inspección manual.

• 422: la validación del esquema falló y no se debe reescribir automáticamente.

• 429: Limitación de velocidad, el reintento se puede retrasar.

• 500 / 503: Error temporal, puedes intentarlo nuevamente.

Preguntas frecuentes#

¿Es una firma HMAC lo suficientemente segura?#

HMAC es una base importante, pero también se necesitan marca de tiempo, nonce, idempotencia, rotación de claves, TLS, privilegios mínimos y registro. El simple hecho de firmar no puede impedir la repetición y la ejecución repetida.

¿Puede Webhook modificar directamente productos o pedidos?#

No se recomienda modificar directamente los datos de alto riesgo. Los webhooks deben escribirse primero en borradores, colas de revisión o campos de bajo riesgo. Operaciones como cambios de precios, reembolsos y emisión de cupones requieren aprobación adicional.

¿Por qué necesito una clave de idempotencia?#

Se puede volver a intentar el webhook o la tarea en segundo plano. Sin una clave de idempotencia, el sistema puede enviar correos electrónicos repetidamente, crear códigos de descuento repetidamente o escribir contenido repetidamente.

Referencias#

• Pautas de seguridad de OWASP Webhook, https://cheatsheetseries.owasp.org/
• Manual de API REST de WordPress, https://developer.wordpress.org/rest-api/
• API web de Adobe Commerce, https://developer.adobe.com/commerce/webapi/