AI Catalog (ai-catalog.json): co to jest i jak skonfigurować
Krok po kroku: po co jest ai-catalog.json, jakie pola są wymagane, jak podać katalog z językiem i pers_shop, gdzie zarządzać stroną ai_catalog na BooStore i jak działa walidacja JSON.
Spis treści
1. Czym jest ai-catalog.json i po co jest potrzebny
ai-catalog.json to maszynowy katalog kluczowych zasobów strony dla agentów AI i LLM. Uzupełnia llms.txt: llms.txt daje opis tekstowy, a AI Catalog wymienia konkretne strony z identyfikatorami i typowymi zapytaniami użytkowników.
- Pomaga wyszukiwaniu AI i agentom zrozumieć strukturę sklepu i znaleźć właściwe sekcje.
- Nie zastępuje sitemap.xml ani robots.txt — pełnią inne funkcje.
- Publikowany pod /.well-known/ai-catalog.json i dostępny bez autoryzacji.
2. Specyfikacja 1.0: wymagane zasady
Walidacja uruchamia się przy zapisie strony ai_catalog. Jeśli JSON nie spełnia zasad, strona nie zostanie zapisana.
- specVersion — dokładnie ciąg "1.0" (sama liczba to błąd).
- host — tylko displayName.
- entries — co najmniej jeden wpis.
- identifier — urn:air:
: : , tylko łacińskie znaki. - url — pełny adres https:// zwracający 200.
- representativeQueries — od 2 do 5 ciągów.
3. Minimalny przykład
Domyślne wartości BooStore dla zwykłej strony to tylko strona główna własnej domeny z językiem. Pozostałe zasoby dodaj ręcznie.
{
"specVersion": "1.0",
"host": {
"displayName": "Nazwa strony"
},
"entries": [
{
"identifier": "urn:air:example.com:site:home",
"displayName": "Strona główna",
"type": "text/html",
"url": "https://example.com/pl/",
"representativeQueries": [
"o stronie i jej sekcjach",
"kontakt i warunki"
]
}
]
}
4. Rozszerzony przykład: różne typy danych
Rozszerzony przykład obejmuje różne typy danych: stronę, artykuł, kategorię produktów, produkt, kategorię bloga i producenta. Adresy katalogu zawierają język i pers_shop: /<lang>/pers_shop/, /<lang>/pers_shop/<category>/, /<lang>/pers_shop/<category>/<slug>_<id>.htm.
{
"specVersion": "1.0",
"host": { "displayName": "Mój sklep" },
"entries": [
{
"identifier": "urn:air:example.com:page:about",
"displayName": "Strona „O nas”",
"type": "text/html",
"url": "https://example.com/pl/about.htm",
"representativeQueries": ["o firmie i warunkach", "kontakt i dane"]
},
{
"identifier": "urn:air:example.com:article:how-to-choose",
"displayName": "Artykuł „Jak wybrać produkt”",
"type": "text/html",
"url": "https://example.com/pl/blog/news_pl/how-to-choose.htm",
"representativeQueries": ["jak wybrać produkt", "porady przed zakupem"]
},
{
"identifier": "urn:air:example.com:category:laptops",
"displayName": "Kategoria produktów „Laptopy”",
"type": "text/html",
"url": "https://example.com/pl/pers_shop/laptops/",
"representativeQueries": ["laptopy w katalogu", "ceny laptopów"]
},
{
"identifier": "urn:air:example.com:product:437544",
"displayName": "Produkt „Laptop model 437544”",
"type": "text/html",
"url": "https://example.com/pl/pers_shop/laptops/laptop-model_437544.htm",
"representativeQueries": ["specyfikacja i cena laptopa", "opinie o modelu"]
},
{
"identifier": "urn:air:example.com:blog:news",
"displayName": "Kategoria bloga „Aktualności”",
"type": "text/html",
"url": "https://example.com/pl/blog/news_pl/",
"representativeQueries": ["aktualności sklepu", "przydatne artykuły"]
},
{
"identifier": "urn:air:example.com:producer:brand",
"displayName": "Producent „Brand”",
"type": "text/html",
"url": "https://example.com/pl/producer/brand/",
"representativeQueries": ["produkty producenta Brand", "marka i jej modele"]
}
]
}
5. Funkcjonalna strona AI Catalog
AI Catalog to funkcjonalna strona w sekcji „Strony”. Służy do wypełnienia publicznego /.well-known/ai-catalog.json: podajesz nazwę strony i kluczowe strony, które agenci AI powinni znać.
- Główna strona BooStore.pro ma już wypełniony katalog platformy: możliwości, llms.txt i dokumentacja.
- Dla Twojej strony katalog wypełnia się ręcznie na stronie AI Catalog.
- Domyślnie dla zwykłej strony podawana jest tylko strona główna z językiem; resztę dodaj samodzielnie.
Publiczny adres pliku to /.well-known/ai-catalog.json.
6. Jak wypełnić /.well-known/ai-catalog.json
Otwórz „Strony” → „Utwórz stronę funkcjonalną” → AI Catalog. Wklej własny JSON w pole tekstowe i zapisz. Pole nie zawiera gotowego przykładu — skorzystaj z przykładów powyżej.
7. Zalecenia
- Podawaj tylko rzeczywiste adresy URL zwracające 200.
- Używaj 2–5 naturalnych zapytań na wpis.
- Nie duplikuj wpisów i nie mieszaj języków w adresach.
- Aktualizuj katalog przy zmianie struktury sklepu.
- Sprawdzaj JSON przed zapisem: błędy są pokazywane w panelu.
8. Pełna instrukcja: umiejscowienie, robots/sitemap i walidacja
Co to jest. AI Catalog to maszynowy manifest strony dla agentów AI. Szczegóły — w tym artykule: AI Catalog.
Gdzie umieścić. Publiczny plik powinien odpowiadać pod /.well-known/ai-catalog.json w katalogu głównym domeny. Na BooStore działają też /ai-catalog.json (301 do well-known) i wersje językowe /{lang}/ai-catalog.json dla zgodności.
Jak utworzyć na BooStore. Otwórz „Strony” → „Utwórz stronę funkcjonalną” → AI Catalog, wklej JSON w pole tekstowe i zapisz. Przy zapisie sprawdzane są specVersion, host.displayName, entries, identifier, adresy https i representativeQueries. Nie ma sztywnego limitu liczby wpisów — zalecane jest do 500. Jeśli JSON jest większy niż 512 KB, pojawia się ostrzeżenie, ale zapis jest dozwolony.
Sitemap i robots. Nie dodawaj ai-catalog.json ani llms.txt do sitemap.xml: mapa strony jest dla stron HTML. W robots.txt nie trzeba ich blokować; warto jawnie zezwolić: Allow: /.well-known/ai-catalog.json i Allow: /llms.txt.
Zalecane razem z llms.txt. Dodaj /llms.txt: daje AI opis tekstowy, a AI Catalog — uporządkowaną listę kluczowych zasobów. Więcej: przewodnik po llms.txt.
Przykład llms.txt
Plik tworzy się tak samo jak AI Catalog: „Strony” → „Utwórz stronę funkcjonalną” → typ „LLM / llms.txt”. W polu tekstowym wklej krótki opis strony i linki do kluczowych sekcji.
# Nazwa strony > Krótki opis strony i sklepu. ## Sklep - Katalog: https://example.com/pl/pers_shop/ - Dostawa: https://example.com/pl/delivery.htm - Płatność: https://example.com/pl/payment.htm ## Firma - O nas: https://example.com/pl/about.htm - Kontakt: https://example.com/pl/contacts.htm
Publiczny adres pliku to /llms.txt w katalogu głównym domeny.
/.well-known/ai-catalog.json i upewnij się, że zwraca 200, application/json, poprawny JSON, a adresy w entries działają. Błędy walidacji są pokazywane w panelu przy zapisie strony.- Używaj tylko rzeczywistych adresów
https://zwracających 200. - Stosuj 2–5 naturalnych zapytań w
representativeQueries. - Używaj łacińskich znaków w
identifierw formacieurn:air:domena:kategoria:nazwa. - Aktualizuj katalog przy zmianie struktury sklepu.
- Nie duplikuj wpisów i nie mieszaj języków w adresach bez potrzeby.
9. FAQ
Czym ai-catalog.json różni się od llms.txt?
llms.txt to tekstowa baza wiedzy, ai-catalog.json to ustrukturyzowana lista kluczowych zasobów.
Czy katalog jest wymagany w domyślnych wartościach?
Nie. Domyślnie podawana jest tylko strona główna; resztę dodaj samodzielnie.
Co się stanie, jeśli JSON będzie nieprawidłowy?
Strona nie zostanie zapisana, a w panelu pojawi się komunikat o błędzie.
Czy potrzebny jest osobny plik w katalogu głównym?
Nie. Wszystko wypełnia się na funkcjonalnej stronie AI Catalog.
Gdzie powinien znajdować się ai-catalog.json?
Prawidłowa ścieżka to /.well-known/ai-catalog.json w katalogu głównym domeny. BooStore przekierowuje /ai-catalog.json na tę ścieżkę, a wersje językowe są dostępne pod /{lang}/ai-catalog.json.
Czy dodawać ai-catalog.json i llms.txt do sitemap.xml?
Nie. Sitemap jest dla stron HTML; manifesty i opisy tekstowe nie powinny się tam znajdować.
Jak powiązane są ai-catalog.json i robots.txt?
Nie blokuj pliku w robots.txt. Warto jawnie zezwolić na /.well-known/ai-catalog.json i /llms.txt, aby roboty wyszukiwarek i AI mogły je czytać.
Czy można utworzyć AI Catalog na BooStore bez kodu?
Tak: „Strony” → „Utwórz stronę funkcjonalną” → AI Catalog. JSON jest walidowany przy zapisie, a błędy są pokazywane w panelu. Nie ma sztywnego limitu wpisów; zalecane jest do 500.
Czy trzeba wskazywać llms.txt w ai-catalog.json?
Nie jest to konieczne. AI Catalog wymienia kluczowe strony HTML serwisu, a llms.txt to osobny plik tekstowy pod adresem /llms.txt, który agenci AI znajdują pod standardową ścieżką. Można go dodać do entries jako dodatkowy zasób, ale nie jest to wymagane.
Po co llms.txt razem z AI Catalog?
llms.txt daje AI opis tekstowy, a AI Catalog — uporządkowaną listę zasobów. Najlepiej używać ich razem. Przewodnik: llms.txt.