Leitfaden für KI-Seitenaufbau

Dieser Leitfaden definiert den sicheren Workflow für vertrauenswürdige KI-/Operator-Tools, die WebBlocks-CMS-Seiten über die interne Content-API erstellen. Es handelt sich um generische CMS-Produktanleitung. Fügen Sie dem CMS-Kern kein Site-spezifisches Import-, Synchronisierungs- oder Scraping-Verhalten hinzu.

Externe KI-/Operator-Tools benötigen keinen lokalen Dateisystemzugriff auf das CMS-Repository oder die installierte Paketdokumentation. Beginnen Sie mit dem Live-API-Discovery-Endpunkt:

GET /webadmin/api

In installierten paketnativen Sites wird dieser Leitfaden auch innerhalb des Composer-Pakets ausgeliefert, unter:

vendor/fklavyenet/webblocks-cms/docs/ai-page-building-guide.md

Zweck

Vertrauenswürdige KI-/Operator-Tools können eine CMS-Installation inspizieren, einen strukturierten Entwurfs-Content-Plan erstellen, ihn validieren, eine separate Entwurfsseite anlegen, nach ausdrücklicher Nutzerfreigabe bestimmte seiteneigene Slots auf einer bestehenden Entwurfsseite ersetzen oder explizite Veröffentlichungs-Endpunkte aufrufen, wenn das Token content.publish besitzt. Der normale Seitenaufbau-Workflow ist Entwurf-first und API-first. Content-Apply veröffentlicht keine Inhalte, überschreibt keine veröffentlichten Seiten, leert keine Shared-Slot-gestützten Slots, ruft keine entfernten Websites ab und importiert keine Medien.

Token-Einrichtung

Erstellen Sie API-Tokens im CMS-Admin-Panel:

System -> API Tokens

Das Klartext-Token wird nur einmal unmittelbar nach der Erstellung angezeigt. Speichern Sie es in einem vertrauenswürdigen Operator-Secret-Store und fügen Sie ein echtes Token niemals in Prompts, Dokumentation, Logs, Screenshots, Tickets oder Release-Berichte ein.

Verwenden Sie in der lokalen Tool-Konfiguration die API-Discovery-Basis-URL:

WEBBLOCKS_CMS_API_URL=https://example.com/webadmin/api
WEBBLOCKS_CMS_API_TOKEN=...

Für normale Seitenaufbau-Tools behalten Sie die standardmäßig ausgewählten Seitenaufbau-Capabilities bei. Gewähren Sie erweiterte Veröffentlichungs- oder Seitenlösch-Capabilities nur vertrauenswürdigen Operator-Tools, die sie ausdrücklich benötigen.

API-Anfragen verwenden:

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Erste Discovery-Aufrufe

Beginnen Sie mit API-Discovery. Der erste Aufruf ist:

GET /webadmin/api

Ohne gültiges Token liefert dieser Endpunkt nur minimales, öffentlich unbedenkliches Bootstrap-JSON. Mit einem gültigen Bearer-Token liefert er Links zum OpenAPI-Schema, zum KI-Leitfaden, zum Content-Vertrag, zu Beispielen, zu den Validate-/Apply-Endpunkten, zu Seiten, zur Navigation und zu Shared Slots.

Folgen Sie anschließend den zurückgegebenen Links. Gängige tokengeschützte Endpunkte liegen unter /webadmin/api:

GET /webadmin/api/openapi.json
GET /webadmin/api/ai-guide
GET /webadmin/api/examples/contact-page
GET /webadmin/api/sites
GET /webadmin/api/locales
GET /webadmin/api/page-layouts
GET /webadmin/api/block-types
GET /webadmin/api/content-contract
GET /webadmin/api/navigation-menus
GET /webadmin/api/shared-slots
GET /webadmin/api/pages

Verwenden Sie GET /webadmin/api/pages, wenn Sie bestehende Slugs, Live-Platzhalterseiten oder frühere Entwürfe prüfen müssen, bevor Sie eine neue Seite vorschlagen.

Block-Handles niemals raten

KI-Tools dürfen Block-Handles nicht erfinden oder raten. Die exakten Handles müssen vor dem Erstellen eines Plans für die aktuelle Installation über GET /webadmin/api/block-types oder GET /webadmin/api/content-contract ermittelt werden.

Beispiele für Handles, die häufig existieren, aber dennoch zur Laufzeit verifiziert werden müssen:

section
container
grid
card
card_body
hero
cta
plain_text
rich-text
button_link
sticky-navbar

Ersetzen Sie sie nicht durch ähnliche Schreibweisen wie plain-text, rich_text, button, navbar oder navigation_auto, sofern die Discovery diese exakten Handles nicht bestätigt.

Sicherer Workflow

Führen Sie eine rein lesende Discovery aus.
Lesen Sie OpenAPI, den Content-Vertrag und die Beispiele über die Live-API-Links.
Erstellen Sie einen Content-Plan ausschließlich mit ermittelten Handles und der aktuellen Site/dem aktuellen Layout/der aktuellen Sprache (Locale).
Validieren Sie mit POST /webadmin/api/content/validate.
Lesen Sie die Validierungsfehler und passen Sie den Plan an.
Bitten Sie den Nutzer um ausdrückliche Freigabe, den exakten finalen Plan anzuwenden.
Rufen Sie erst nach der Freigabe POST /webadmin/api/content/apply auf.
Lesen Sie die ID der erstellten Entwurfsseite aus der Apply-Antwort.
Erzeugen Sie die Admin-Vorschau-URL mit /webadmin/pages/{page}/preview.
Überlassen Sie das Veröffentlichen einem menschlichen Workflow, es sei denn, der Nutzer hat eine API-Veröffentlichung ausdrücklich genehmigt und das Token besitzt content.publish.

Sicherheitsregeln

Entwurf-first.
Anwenden nur nach ausdrücklicher Nutzerfreigabe.
Nicht über Content-Apply veröffentlichen.
Nicht davon ausgehen, dass eine Seitenveröffentlichung alle Blöcke öffentlich macht; include_page_owned_blocks: true nur nach ausdrücklicher Freigabe verwenden.
Keine Seiten über Content-Apply löschen.
Bestehende Seiten oder Blöcke nur mit dem expliziten Modus replace_existing_draft_page überschreiben.
Apply nicht aufrufen, wenn der Zielpfad bereits existiert, es sei denn, der Nutzer genehmigt ausdrücklich einen von der API unterstützten Konfliktbehandlungsplan.
Beim Ersetzen bestehender Entwürfe expected_path oder expected_updated_at angeben und nur seiteneigene Slots ersetzen.
page.path als kanonische öffentliche URL behandeln. /contact oder /docs/internal-content-api verwenden, nicht /p/contact; /p/... ist nur eine öffentliche Legacy-Weiterleitung.
Nicht versuchen, Shared-Slot-gestützte Slots zu ersetzen; geteilte Header-/Footer-Zuweisungen unangetastet lassen.
Keine entfernten Seiten abrufen.
Keine Browser-Automatisierung oder Admin-UI-Klicks verwenden, wenn API-Discovery verfügbar ist.
Keine Medien herunterladen oder importieren.
Keine API-Tokens aus Automatisierung heraus erstellen, es sei denn, der Nutzer verlangt ausdrücklich Token-Administration.
Token-Werte nicht ausgeben, loggen oder in Berichte aufnehmen.
Nur Statuscodes und sicher zusammengefasste Antwortdaten berichten.
401-, 403- und 422-JSON-Antworten als API-Feedback behandeln und den enthaltenen Discovery-/Dokumentationslinks folgen.

Gute Strukturen

Bevorzugen Sie strukturierte Blöcke gegenüber einem einzigen großen Content-Klumpen.

Marketing-Startseite:

section -> container -> hero
section -> container -> grid -> card -> card_body
section -> container -> cta

Header/Navbar:

shared_slot header
sticky-navbar -> container(flow:none) -> cluster -> navbar-brand + cluster -> navbar-navigation + header-actions

Platzieren Sie für die meisten öffentlichen Seiten breite Promo-Blöcke wie hero und cta innerhalb von section -> container. Direkte hero- oder cta-Blöcke in voller Breite unter main sollten bewusste Edge-to-Edge-Designentscheidungen sein, nicht der Standard.

Kontaktseite:

section -> hero + contact_form

Verwenden Sie für Kontaktseiten den nativen contact_form-Block, nachdem die Discovery bestätigt hat, dass das Handle verfügbar ist. Seine sichtbaren Texte werden über title, content, submit_label und success_message übersetzt; gemeinsame Einstellungen sind recipient_email, send_email_notification und store_submissions. Der Renderer erzeugt das native CSRF-geschützte öffentliche Formular, das CMS-eigene versteckte, generierte Anti-Spam-Prüffeld und den Submit-Endpunkt /contact-messages. KI-/Operator-Tools sollten das Prüffeld nicht manuell erstellen und weder Trusted HTML noch rohe Formulare oder mailto: als Ersatz verwenden.

Schlechte Strukturen

Packen Sie keine ganze Seite in einen einzigen rich-text-Block.
Packen Sie keine ganze Seite in einen einzigen vertrauenswürdigen html-Block, wenn strukturierte Blöcke sie abbilden können.
Bauen Sie keine Kontaktformulare mit Trusted HTML, rohem Formular-Markup oder mailto:-Links, wenn contact_form verfügbar ist.
Raten Sie keine Handles.
Überschreiben Sie keine veröffentlichten Inhalte.
Verändern Sie keine bestehende Live-Seite, wenn eine neue separate Entwurfsseite sicherer ist.
Fügen Sie keine Tokens in Prompts oder Berichte ein.

Minimales Entwurfsplan-Beispiel

Dieses Beispiel setzt voraus, dass die Discovery section, container, hero, grid, card, card_body, plain_text, button_link und cta bestätigt hat.

{
  "plan": {
    "site": "default",
    "locale": "en",
    "layout": "default",
    "page": {
      "title": "Example Homepage Draft",
      "path": "/example-homepage-draft",
      "status": "draft"
    },
    "slots": {
      "main": [
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "hero",
                  "translations": {
                    "title": "Build useful pages faster",
                    "subtitle": "A structured CMS workflow for practical content teams.",
                    "content": "Create focused draft pages from reusable blocks, then review them safely before publishing."
                  },
                  "children": [
                    {
                      "type": "button_link",
                      "translations": {
                        "title": "Start building"
                      },
                      "settings": {
                        "url": "/get-started",
                        "variant": "primary"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "grid",
                  "children": [
                    {
                      "type": "card",
                      "children": [
                        {
                          "type": "card_body",
                          "children": [
                            {
                              "type": "plain_text",
                              "translations": {
                                "content": "Create drafts from structured content plans."
                              }
                            }
                          ]
                        }
                      ]
                    },
                    {
                      "type": "card",
                      "children": [
                        {
                          "type": "card_body",
                          "children": [
                            {
                              "type": "plain_text",
                              "translations": {
                                "content": "Review safely through authenticated admin preview."
                              }
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "cta",
                  "translations": {
                    "title": "Ready for review?",
                    "content": "Validate the plan, apply only after approval, then open the admin preview."
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Zuerst validieren:

POST /webadmin/api/content/validate

Erst nach ausdrücklicher Freigabe anwenden:

POST /webadmin/api/content/apply

Dann die Vorschau öffnen:

/webadmin/pages/{page}/preview

Die Vorschau-URL ist eine Browser-/Admin-Route. Sie erfordert eine authentifizierte Admin-Browsersitzung und ist mit einem CMS-API-Bearer-Token nicht zugänglich. Landet ein Browser-Smoke-Test auf einer Login-Seite, berichten Sie, dass die Admin-Browsersitzung fehlt; behandeln Sie das nicht als JSON-API-Token-Fehler.

Slot-Ersetzung bestehender Entwürfe

Verwenden Sie diesen Modus nur, wenn der Nutzer ausdrücklich eine bestehende Entwurfsseite aktualisieren möchte, statt einen neuen Entwurf zu erstellen. Zuerst validieren, dann erst nach Freigabe anwenden:

{
  "plan": {
    "mode": "replace_existing_draft_page",
    "site": "default",
    "locale": "en",
    "page": {
      "id": 9,
      "expected_path": "/contact",
      "status": "draft"
    },
    "replace_slots": {
      "main": [
        {
          "type": "plain_text",
          "translations": {
            "content": "Updated draft page copy."
          }
        }
      ]
    }
  }
}

Validieren:

POST /webadmin/api/content/validate

Anwenden:

POST /webadmin/api/content/apply

Das CMS entfernt alte seiteneigene Blöcke nur aus den benannten Slots und schreibt den neuen Blockbaum in einer Transaktion. Shared-Slot-gestützte Slots werden von diesem Modus abgelehnt, sodass Header-/Footer-Zuweisungen unberührt bleiben, sofern nicht eine separate unterstützte API-Operation sie ändert.

Explizites Veröffentlichen

Das Veröffentlichen ist nicht Teil von Validate/Apply. Vertrauenswürdige Operator-Tools mit content.publish dürfen Folgendes aufrufen:

POST /webadmin/api/pages/{page}/publish
POST /webadmin/api/pages/{page}/publish-page-owned-blocks

POST /webadmin/api/pages/{page}/publish hat als Standard:

{
  "include_page_owned_blocks": false
}

Mit dem Standardwert veröffentlicht der Endpunkt nur den Seitendatensatz. Er veröffentlicht keine Entwurfs- oder In-Review-Blöcke. Setzen Sie include_page_owned_blocks: true nur, wenn der Nutzer ausdrücklich möchte, dass auch alle unveröffentlichten seiteneigenen Blöcke dieser Seite veröffentlicht werden. Die Kaskade umfasst verschachtelte Kind-Blöcke unter seiteneigenen Slots und schließt Shared-Slot-gestützte Slots aus.

POST /webadmin/api/pages/{page}/publish-page-owned-blocks veröffentlicht seiteneigene Entwurfs- oder In-Review-Blöcke, ohne den Workflow-Status der Seite zu ändern.

Fordern Sie niemals eine Shared-Slot-Kaskadenveröffentlichung über Seiten-Veröffentlichungs-Endpunkte an. Shared-Slot-Inhalte sind nicht enthalten und müssen separat geprüft und veröffentlicht werden.

Revisionen an realen Sites

Inspizieren Sie bei realen Sites zuerst die aktuellen Seiten und vorhandenen Entwürfe. Wenn bereits ein Entwurf existiert, sehen Sie ihn in der Vorschau an, bevor Sie neue Arbeit vorschlagen. Verwenden Sie replace_existing_draft_page nur für die explizite, entwurfssichere Ersetzung seiteneigener Slots. Erstellen Sie andernfalls eine neue separate Entwurfsseite, statt den bestehenden Entwurf oder die live veröffentlichte Startseite zu überschreiben.

Nutzen Sie bei Startseiten-Revisionen im QuizTem-Stil den bestehenden Entwurf nur als Referenzmaterial, es sei denn, der Nutzer genehmigt ausdrücklich einen unterstützten Update-Ablauf. Der sichere Standard für neue Arbeit ist:

Sehen Sie sich den bestehenden Entwurf in der Vorschau an.
Erstellen Sie einen besser strukturierten Plan mit ermittelten Block-Handles.
Validieren Sie den Plan.
Bitten Sie um ausdrückliche Apply-Freigabe.
Erstellen Sie eine neue separate Entwurfsseite.
Öffnen Sie /webadmin/pages/{page}/preview für die menschliche Prüfung.