[Protocollo rivelato 1] Smantellamento del protocollo di comunicazione principale di AI Ready: verifica della sicurezza API Payload e Webhook

Risposta diretta: il protocollo AI Ready dovrebbe elevare le attività AI da "un prompt" a eventi API gestibili. Ogni richiesta deve contenere intento, origine, contesto, dati, vincoli e chiave di idempotenza; Il webhook deve avere timestamp, nonce, firma e protezione dalla riproduzione.

A chi è rivolto questo articolo?#

• Ingegnere di sviluppo del nucleo del sistema di e-commerce.

• Backend e architetto necessari per progettare l'API delle attività AI.

• Team tecnico responsabile della sicurezza, dei tentativi e del controllo del webhook.

Perché le attività dell'intelligenza artificiale richiedono protocolli di comunicazione?#

Se ciascun plugin invia un prompt al modello, sarà difficile per il sistema rispondere alle seguenti domande:

• Chi ha avviato questa missione?

• Quali informazioni può leggere l'intelligenza artificiale?

• L'intelligenza artificiale può rispondere?

• Quale lingua e negozio vengono utilizzati per l'attività?

• Qual è il budget dei token?

• È possibile riprovare dopo un fallimento?

• I webhook duplicati causeranno operazioni duplicate?

Lo scopo del protocollo AI Ready è inserire queste informazioni di gestione in ogni attività, anziché essere disperse nel codice e nelle istruzioni del programma.

Richiedi la struttura base del carico utile#

{
  "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"]
  }
}

Ogni campo dovrebbe avere un significato chiaro:

• event_id: identificativo univoco dell'evento.

• idempotency_key: evita operazioni ripetute causate da nuovi tentativi.

• "intento": tipo di attività.

• source: piattaforma di origine e negozio.

• "contesto": lingua, valuta, operatore e permessi.

• "dati": i dati necessari per l'attività.

• vincoli: vincoli di modello e di writeback.

Struttura di base del carico utile della risposta#

{
  "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 risposta non deve contenere solo testo, ma includere anche lo stato di verifica, i requisiti di revisione e l'utilizzo del token.

Design della firma del webhook#

Intestazione suggerita:

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

Il contenuto della firma può utilizzare la stringa canonica:

{timestamp}.{nonce}.{raw_body}

Quindi esegui HMAC SHA-256 con la chiave condivisa. L'estremità ricevente dovrebbe:

1. Controlla se il timestamp rientra nell'intervallo di tempo consentito.
2. Controllare se viene utilizzato il nonce.
3. Utilizzare il corpo grezzo per ricalcolare la firma.
4. Controllare l'ID evento e la chiave di idempotenza.
5. Salvare lo stato di elaborazione.

Codici di stato HTTP e tentativi#

• 200 / 204: elaborato con successo o già elaborato.

• "400": il formato del payload non è corretto e non deve essere riprovato.

• 401 / 403: errore di firma o autorizzazione, non riprovare finché le impostazioni non vengono corrette.

• "409": conflitto di idempotenza, è richiesta l'ispezione manuale.

• "422": la convalida dello schema non è riuscita e non deve essere riscritta automaticamente.

• "429": limitazione della velocità, il nuovo tentativo può essere ritardato.

• 500 / 503: errore temporaneo, puoi riprovare.

Domande frequenti#

Una firma HMAC è sufficientemente sicura?#

HMAC è una base importante, ma sono necessari anche timestamp, nonce, idempotenza, rotazione delle chiavi, TLS, privilegi minimi e logging. La semplice firma non può impedire la riproduzione e l'esecuzione ripetuta.

Webhook può modificare direttamente prodotti o ordini?#

Non è consigliabile modificare direttamente i dati ad alto rischio. I webhook devono essere scritti prima nella bozza, nella coda di revisione o nei campi a basso rischio. Operazioni come variazioni di prezzo, rimborsi ed emissione di coupon richiedono un'ulteriore approvazione.

Perché ho bisogno di una chiave di idempotenza?#

È possibile ritentare il webhook o l'attività in background. Senza una chiave di idempotenza, il sistema potrebbe inviare ripetutamente e-mail, creare ripetutamente codici sconto o riscrivere ripetutamente i contenuti.

Riferimenti#

• Linee guida sulla sicurezza del webhook OWASP, https://cheatsheetseries.owasp.org/
• Manuale dell'API REST di WordPress, https://developer.wordpress.org/rest-api/
• API Web di Adobe Commerce, https://developer.adobe.com/commerce/webapi/