# LLMs.txt i AEO Shopware: kompletny przewodnik

> Wprowadzenie DataFirefly LLMs.txt i AEO to plugin dla Shopware 6.7, który sprawia, że Twój sklep jest widoczny i zrozumiały dla silników odpowiedzi AI (ChatGPT, Claude, Perplexity, Gemini). Działa na trzech…

- Strona: <https://www.datafirefly.com/pl/documentation/df-llms-aeo/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/df-llms-aeo/index.md), [en](https://www.datafirefly.com/en/documentation/df-llms-aeo/index.md), [es](https://www.datafirefly.com/es/documentation/df-llms-aeo/index.md), [de](https://www.datafirefly.com/de/documentation/df-llms-aeo/index.md), [it](https://www.datafirefly.com/it/documentation/df-llms-aeo/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-llms-aeo/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-llms-aeo/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## Wprowadzenie

DataFirefly LLMs.txt i AEO to plugin dla Shopware 6.7, który sprawia, że Twój sklep jest widoczny i zrozumiały dla silników odpowiedzi AI (ChatGPT, Claude, Perplexity, Gemini). Działa na trzech uzupełniających się poziomach:

- **llms.txt / llms-full.txt**: dwa pliki zgodne ze specyfikacją [llmstxt.org](https://llmstxt.org), generowane automatycznie w katalogu głównym każdego sales-channelu, w każdym aktywnym języku.
- **Schema.org JSON-LD**: automatyczne wstrzykiwanie danych strukturalnych na wszystkich stronach: Organization, wzbogacony Product, BreadcrumbList, FAQPage, HowTo i Speakable.
- **Sterowanie crawlerami AI**: endpoint `/robots-ai.txt` z indywidualną kontrolą 9 botów (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, Bingbot, Meta-ExternalAgent, CCBot, cohere-ai).

**Wymagania:** Shopware 6.7.0+, PHP 8.2+, MySQL 8.0+ lub MariaDB 10.6+. Plugin działa na standardowym storefroncie i na motywach niestandardowych (dziedziczenie Twig).

## Instalacja

### Przez ZIP (zalecane)

1. Pobierz `DataFireflyLlmsAeo.zip` ze swojego konta klienta.
2. Administracja Shopware → **Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie**.
3. Kliknij **Zainstaluj**, a następnie **Aktywuj**.
4. Wyczyść cache: **Ustawienia → System → Cache i indeksy** albo w CLI:

```
bin/console cache:clear
```

### Przez CLI

```
unzip DataFireflyLlmsAeo.zip -d custom/plugins/
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyLlmsAeo
bin/console cache:clear
```

Przy aktywacji plugin instaluje automatycznie zestaw pól niestandardowych `datafirefly_aeo` na produktach, kategoriach, stronach CMS i producentach. Żadna ręczna migracja nie jest potrzebna.

### Kompilacja zasobów administracji

Jeśli moduł administracji nie pojawia się w sekcji Marketing po aktywacji:

```
bin/console bundle:dump
./bin/build-administration.sh
bin/console cache:clear
```

## Konfiguracja

Konfiguracja znajduje się w **Ustawienia → System → Rozszerzenia → DataFirefly llms.txt i AEO**. Jest zawężona per sales-channel: wybierz konkretny kanał w selektorze u góry, aby nadpisać wartości globalne.

### Karta "Ogólne"

- **Włącz moduł**: globalny przełącznik (per sales-channel).
- **Autor witryny**: używany w nagłówku pliku llms.txt.
- **Opis witryny**: blockquote nagłówka llms.txt; opisz swój sklep w 1-2 zdaniach nakierowanych na AI.
- **Czas życia cache**: TTL w sekundach (domyślnie: 3600).

### Karta "llms.txt"

- Uwzględnij **strony CMS**, **kategorie**, **marki** i/lub **produkty**.
- **Maksymalna liczba produktów** wymienionych w indeksie.
- **Uwzględnij produkty nieaktywne**: domyślnie wyłączone, zostaw wyłączone w produkcji.

### Karta "AEO i Schema.org"

- Indywidualne przełączniki: Organization, wzbogacony Product, BreadcrumbList, FAQPage, HowTo, Speakable.
- **Logo i adres URL organizacji**: nadpisują wartości sales-channelu.
- **Telefon, e-mail kontaktowy, profile społecznościowe**: zasilają schemat Organization (`contactPoint`, `sameAs`).

### Karta "Crawlery AI"

Dla każdego z 9 botów trzy tryby:

- **Dozwolony**: pełny dostęp (żadnej dyrektywy ograniczającej).
- **Odmowa**: `Disallow: /` dla tego bota.
- **Wybiórczy**: `Disallow` na wypisanych przez Ciebie ścieżkach (jedna na linię, np. `/checkout/`, `/account/`).

Zawartość `/robots-ai.txt` nie jest automatycznie scalana z Twoim głównym `robots.txt`. Skopiuj jej treść do swojego robots.txt albo dodaj regułę przepisywania na serwerze (zobacz sekcję [Integracja robots.txt](#robots-integracja)).

## Trzy endpointy

| URL | Zawartość | Nagłówki |
| --- | --- | --- |
| `/llms.txt` | Syntetyczny indeks: Strony, Kategorie, Marki, Produkty, Optional | `text/plain; charset=UTF-8`, `X-Robots-Tag: noindex`, cache publiczny |
| `/llms-full.txt` | Pełna treść: oczyszczone opisy, SKU, EAN, marka, pogrupowane cechy, FAQ | tak samo |
| `/robots-ai.txt` | Blok dyrektyw User-agent dla 9 crawlerów AI | tak samo |

Szybka weryfikacja po instalacji:

```
curl -I https://twoj-sklep.tld/llms.txt
curl -I https://twoj-sklep.tld/llms-full.txt
curl -I https://twoj-sklep.tld/robots-ai.txt
```

Każdy sales-channel udostępnia własne pliki na swojej domenie, w każdym aktywnym języku (zlokalizowane adresy URL podążają za konfiguracją domen kanału).

## Pola niestandardowe AEO

Zestaw `datafirefly_aeo` jest dostępny na **produktach, kategoriach, stronach CMS i producentach**, w zakładce Pola niestandardowe każdej encji.

| Pole | Typ | Zastosowanie |
| --- | --- | --- |
| `datafirefly_aeo_summary` | Tekst | Podsumowanie w 1-2 zdaniach używane w llms.txt zamiast skróconego opisu |
| `datafirefly_aeo_faq` | JSON | Strukturalne FAQ, wstrzykiwane jako FAQPage JSON-LD |
| `datafirefly_aeo_howto` | JSON | Strukturalny poradnik, wstrzykiwany jako HowTo JSON-LD |
| `datafirefly_aeo_speakable` | Tekst | Krótki tekst dla asystentów głosowych (30-40 słów do wypowiedzenia) |
| `datafirefly_aeo_exclude` | Boolean | Wyklucza encję z llms.txt i llms-full.txt |

### Format pola FAQ

```
[
  {
    "q": "Ile trwa dostawa?",
    "a": "Dostawa standardowa trwa od 2 do 4 dni roboczych na terenie Polski."
  },
  {
    "q": "Jaka jest polityka zwrotow?",
    "a": "Masz 30 dni na zwrot nieuzywanego produktu."
  }
]
```

### Format pola HowTo

```
{
  "name": "Jak zainstalowac produkt",
  "totalTime": "PT15M",
  "steps": [
    { "name": "Przygotowanie", "text": "Rozpakuj elementy." },
    { "name": "Montaz", "text": "Postepuj wedlug zalaczonego schematu." },
    { "name": "Sprawdzenie", "text": "Przetestuj dzialanie." }
  ]
}
```

Pola niestandardowe Shopware są tłumaczalne: uzupełnij FAQ w każdym języku przez selektor języka na karcie produktu. Plugin czyta wartość w języku kontekstu żądania.

## Dane strukturalne Schema.org

Plugin wstrzykuje JSON-LD do sekcji head przez szablon `storefront/layout/meta.html.twig` (dziedziczenie Twig, zgodne z motywami niestandardowymi). Generowane schematy:

- **Organization**: na wszystkich stronach: nazwa, logo, URL, `contactPoint`, `sameAs` (profile społecznościowe).
- **Wzbogacony Product**: na kartach produktów: `gtin13` (z EAN), `mpn`, `sku`, `brand` (producent), `additionalProperty` (cechy pogrupowane po grupach właściwości), `aggregateRating` (z natywnych opinii Shopware, jeśli są).
- **BreadcrumbList**: pełna ścieżka nawigacyjna bieżącej strony.
- **FAQPage**: jeśli pole `datafirefly_aeo_faq` jest uzupełnione na encji strony.
- **HowTo**: jeśli pole `datafirefly_aeo_howto` jest uzupełnione.
- **Speakable**: selektory CSS `h1`, `.product-detail-name`, `.product-detail-description-text`, `.cms-element-text`, `[data-speakable]` oraz tekst z dedykowanego pola.

Zalecana walidacja po wdrożeniu na produkcję:

- [Schema.org Validator](https://validator.schema.org/): wklej adres karty produktu.
- [Google Rich Results Test](https://search.google.com/test/rich-results).

## Moduł administracji

W **Marketing → DataFirefly llms.txt i AEO**:

- **Podgląd na żywo** pliku llms.txt albo llms-full.txt, w renderowaniu monospace.
- **Selektor sales-channelu**: podglądaj każdy kanał niezależnie.
- **Unieważnienie cache** jednym kliknięciem (per kanał albo globalnie).
- **Otwarcie publicznego adresu URL** i **kopiowanie do schowka**.

## Komendy CLI i automatyzacja

### datafirefly:llms-txt:generate

```
# Generate the llms.txt of a sales channel (printed to stdout)
bin/console datafirefly:llms-txt:generate --sales-channel=<id>

# Full version, written to a file, bypassing the cache
bin/console datafirefly:llms-txt:generate --sales-channel=<id> --full --output=/tmp/llms-full.txt --no-cache
```

### datafirefly:llms-txt:warm

```
# Warm the cache for all sales channels x all active languages
bin/console datafirefly:llms-txt:warm

# Force regeneration even if the cache is still valid
bin/console datafirefly:llms-txt:warm --force

# Warm only llms.txt (skip llms-full.txt)
bin/console datafirefly:llms-txt:warm --skip-full
```

### Zalecany cron

```
# Daily warm-up at 03:15
15 3 * * * cd /var/www/shopware && php bin/console datafirefly:llms-txt:warm --quiet
```

Przy aktywacji rejestrowane jest także **zadanie cykliczne Shopware**: jeśli Twój worker Messengera i runner zadań cyklicznych działają, cache rozgrzewa się automatycznie, bez crona systemowego.

## Integracja robots.txt

Dwa podejścia do udostępnienia dyrektyw AI w Twoim głównym robots.txt:

### Ręczne skopiowanie

Otwórz `/robots-ai.txt`, skopiuj wygenerowany blok i wklej go do istniejącego robots.txt. Do powtórzenia po każdej zmianie konfiguracji botów.

### Przepisywanie na serwerze (zalecane, gdy robots.txt jest w całości zarządzany przez plugin)

```
# nginx
location = /robots.txt {
    rewrite ^ /robots-ai.txt last;
}

# Apache (.htaccess)
RewriteRule ^robots.txt$ /robots-ai.txt [L]
```

Stosuj pełne przepisywanie tylko wtedy, gdy nie masz innych dyrektyw robots.txt do zachowania (sitemap, istniejące wykluczenia SEO). W razie wątpliwości wybierz ręczne skopiowanie bloku AI.

## Cache i wydajność

- Cache **PSR-6** na puli `cache.object` Shopware, tagowany `datafirefly_llms_aeo`.
- Klucze zawężone per **sales-channel + język**: każda kombinacja ma własny wpis.
- Konfigurowalny TTL (domyślnie 3600 s).
- Unieważnianie: przycisk w administracji (per kanał albo globalnie), komenda `warm --force` albo naturalne wygaśnięcie.
- Zgodny z cache klastrowanym (Redis): unieważnianie po tagach działa na wszystkich adapterach obsługujących tagi.

## Rozwiązywanie problemów

### Endpointy zwracają 404

1. Sprawdź, czy plugin jest **aktywowany** (nie tylko zainstalowany).
2. Wyczyść cache HTTP i cache aplikacji: `bin/console cache:clear`.
3. Jeśli używasz reverse proxy albo CDN, wyczyść je również.

### Błąd "Attempted to call an undefined method named getHeader" na stronach nawigacji

Błąd naprawiony w **wersji 1.0.1**: na niektórych instalacjach Shopware 6.7 `NavigationPage` nie udostępnia `getHeader()`. Zaktualizuj do 1.0.1 (defensywne pobieranie aktywnej kategorii). Jeśli masz już 1.0.1, a błąd nadal występuje, wyczyść cache opcode PHP (`opcache_reset` albo restart PHP-FPM).

### Moduł administracji nie pojawia się w sekcji Marketing

Skompiluj zasoby administracji (zobacz [Instalacja](#instalacja-assets)), a następnie wymuś przeładowanie przeglądarki (Ctrl+Shift+R).

### Plik llms.txt jest pusty albo niekompletny

1. Sprawdź przełączniki uwzględniania (strony CMS / kategorie / marki / produkty) w karcie "llms.txt".
2. Sprawdź, czy limit produktów nie wynosi 0.
3. Skontroluj pole `datafirefly_aeo_exclude` na brakujących encjach.
4. Unieważnij cache i przeładuj.

### JSON-LD nie pojawia się w kodzie źródłowym

1. Sprawdź, czy "Włącz moduł" i przełączniki Schema.org są aktywne dla właściwego sales-channelu.
2. Jeśli Twój motyw nadpisuje `storefront/layout/meta.html.twig` bez `{{ parent() }}` w danym bloku, wstrzyknięcie przepada: przywróć wywołanie rodzica.

## Changelog

### 1.0.1, 21.05.2026

- Poprawka: defensywne pobieranie aktywnej kategorii na stronach nawigacji (błąd `getHeader()` na niektórych instalacjach 6.7).

### 1.0.0, 21.05.2026

- Wersja początkowa: llms.txt + llms-full.txt, 6 schematów JSON-LD, robots-ai.txt (9 botów), pola niestandardowe AEO, moduł administracji Vue 3, 2 komendy CLI, zadanie cykliczne, snippety FR/EN/DE.