# Tworzenie bloków z myślą o AI

Pliki i brak etapu budowania — z tym agenci radzą sobie dobrze.

[Przeczytaj dokumentację](https://blockstudio.dev/pl/docs/dev/ai/)

Nieme nagranie ekranu: agent kodujący tworzy kompletną witrynę WordPress z 10 niestandardowymi blokami i 6 stronami na podstawie jednego promptu.

## Opisz blok, otrzymaj blok

Agenci AI do kodowania mogą tworzyć szkielety bloków, stron i wzorców na podstawie jednego promptu. Bez graficznego interfejsu i bazy danych, tylko pliki.

~/starter-theme

❯ Utwórz blok cenowy z trzema poziomami, przełącznikiem miesięcznie/rocznie i wezwaniem do działania dla każdego poziomu.

✓ Utworzono pricing/block.json

✓ Utworzono pricing/index.php

✓ Utworzono pricing/style.css

❯ Teraz utwórz stronę cennika z sekcją główną i FAQ.

✓ Utworzono pages/pricing/page.json

✓ Utworzono pages/pricing/index.php

Pliki

blockstudio/

├── pricing/ Nowe

├── block.json

├── index.php

└── style.css

pages/

├── pricing/ Nowe

├── page.json

└── index.php

## Wszystko oparte na plikach

Bloki, strony, wzorce i rozszerzenia to katalogi z konfiguracją JSON i szablonami. Agenci natywnie je odczytują i zapisują.

## Konfiguracja bez bazy danych

Koniec z klikaniem w panelach administracyjnych. Każde ustawienie to klucz JSON, więc agent może utworzyć szkielet biblioteki bez przeglądarki.

## Przewidywalna struktura

Każdy blok ma tę samą konwencję: block.json, szablon i opcjonalne style. Wystarczy raz poznać ten schemat.

## Kontekst zamiast zgadywania

Zwięzły indeks dokumentacji oraz pełny tekst dla narzędzi, które potrzebują całości.

### Indeks, od którego agent zaczyna

`blockstudio-llm.txt` zawiera listę każdego dokumentu wraz z jego trasą, plikiem źródłowym, przeznaczeniem oraz ustawieniami, hookami, funkcjami PHP i poleceniami CLI. Przy około 11k tokenach agent odczytuje go w całości, a potem otwiera tylko potrzebną stronę.

`blockstudio-llm-full.txt` zawiera wszystkie dokumenty i wszystkie schematy JSON w jednym pliku, około 169k tokenów, dla narzędzi, które potrzebują całego zbioru. Włącz `ai.enableContextGeneration`, a Twoja witryna udostępni oba.

[Dokumentacja integracji AI](https://blockstudio.dev/pl/docs/dev/ai/)

blockstudio-llm.txt

```
# Blockstudio documentation index

This is the primary context file for coding assistants. It is an index, not
the documentation itself. Each entry names one document, what it is for, and
the identifiers that document owns. Read this index, then open only the
document you need.

Every document is addressable two ways: as a URL on https://blockstudio.dev,
and as a Markdown file in the Blockstudio repository. The full text of every
document and schema is also available in one file at /blockstudio-llm-full.txt
for tools that want everything at once.
```

## Umowa dla Twojego projektu

Dokumentacja opisuje Blockstudio. AGENTS.md opisuje projekt, który agent ma właśnie zmienić.

### Jedno polecenie tworzy AGENTS.md

`vendor/bin/blockstudio-agents` opisuje projekt, w którym działa: jego zawartość, funkcje włączane przez `blockstudio.json`, to, co analiza odrzuci, oraz obowiązujące polecenia.

Każdy wiersz pochodzi z Twoich plików, ustawień lub wybranego profilu analizy. Ponowne generowanie zachowuje ręcznie dodane notatki, a `--check` zgłasza błąd, gdy umowa jest nieaktualna.

[Umowa projektu](https://blockstudio.dev/pl/docs/dev/phpstan/#project-contract-for-coding-agents)

AGENTS.md

```
# Blockstudio contract for Acme

## Project

- Kind: WordPress theme `Acme`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.

## What this project contains

- Blocks: 1 in `blockstudio`.
- Pages: 1 in `pages`.
- Block namespaces: `acme`.
- Block templates are written in PHP.
```

## Błędy wykrywane przed zatwierdzeniem

Cztery presety analizy, z których każdy obejmuje poprzedni, oraz hak uruchamiający je przy każdym zatwierdzeniu zmian.

### Analiza uwzględniająca block.json

Profile `blockstudio/phpstan` analizują bloki, strony i ustawienia. Szablon odczytujący pole, którego nie zadeklarowała jego `block.json`, lub wyświetlający je bez zabezpieczenia, nie przejdzie analizy.

Szablony odczytują typowany `$a` z pliku `block.json` znajdującego się obok; każdy typ pola ma konkretny typ PHP, a `Db::get()` zwraca rekordy w kształcie określonym przez `db.php`. Błędna ścieżka ustawień lub nazwa hooka powoduje błąd z sugestią najbliższej poprawnej nazwy.

Ustaw `githooks.commit` i uruchom `vendor/bin/blockstudio-githooks sync`: zarządzany hook przed zatwierdzeniem uruchamia tę samą analizę, więc błędny blok nie trafi do zatwierdzenia.

[Profile analizy](https://blockstudio.dev/pl/docs/dev/phpstan/#analysis-presets)

blockstudio.json

```
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": { "preset": "extreme-theme" },
  "githooks": { "commit": true }
}
```

## [base](https://blockstudio.dev/pl/docs/dev/phpstan/#analysis-presets)

Każdy klucz $a odczytywany przez szablon istnieje w block.json; hooki, ścieżki ustawień i znaczniki bloków są rzeczywiste.

## [theme](https://blockstudio.dev/pl/docs/dev/phpstan/#analysis-presets)

Nagłówki motywów, zadeklarowane zasoby, zakres %selector%, domyślne wartości pól i limity pól powtarzalnych.

## [extreme-theme](https://blockstudio.dev/pl/docs/dev/phpstan/#analysis-presets)

Maksymalna wartość PHPStan, zabezpieczone wyjście, bez uruchamiania poleceń powłoki, poprawne klasy Tailwind i czysty JavaScript.

## [wordpress-render](https://blockstudio.dev/pl/docs/dev/phpstan/#live-wordpress-rendering)

Motyw Extreme oraz dostarczana przez Ciebie sonda renderowania na żywo WordPress. Działa bez powłoki, a nieudane renderowanie jest zgłaszane jako problem.

## [Twig, Blade i skrypty](https://blockstudio.dev/pl/docs/dev/phpstan/#what-it-checks)

Twig, Blade i tagi bloków są sprawdzane względem tych samych pól. Warstwa Extreme sprawdza też JavaScript oraz dyrektywy Interactivity względem Twojego kodu i zapisów.

## [Istniejące projekty](https://blockstudio.dev/pl/docs/dev/phpstan/#adopting-analysis-on-an-existing-project)

Punkt odniesienia PHPStan wstrzymuje zgłoszone wcześniej problemy, a nowy kod musi spełniać pełny zestaw reguł. blockstudioScanRoots odczytuje biblioteki bloków spoza katalogu głównego, a dołączone pliki zastępcze typują publiczne API.

## Inwentaryzacja i renderowanie z PHP

Kilka wywołań pozwala agentowi sprawdzić, co rejestruje projekt, wyrenderować dowolny jego element i sprawdzić zapisane dane.

### Zapytaj o projekt, wyrenderuj odpowiedź

`Canvas::inventory()` zwraca każdą zarejestrowaną przez projekt stronę, blok, wzorzec, szablon edytora witryny, część szablonu i przykład UI — bez renderowania.

`Render::document()` renderuje dowolny z nich jako kompletny dokument HTML wraz dokładnie z użytymi zasobami, dzięki czemu agent może sprawdzić wynik poza edytorem.

`Canvas::documents()` renderuje dokładnie wybrane przez Ciebie rekordy. `Render::composition()` i `Render::content()` zwracają zagnieżdżone deklaracje lub zserializowaną zawartość bloków jako HTML, a `Ui::inventory()` i `Ui::examples()` wyświetlają rodziny dołączonych komponentów, po jednej renderowalnej deklaracji dla każdej.

W przypadku pojedynczego bloku `bs_block_fields()`, `bs_block_extension_fields()`, `bs_block_values()` i `bs_block_assets()` zwracają jego pola, wartości i zasoby bez renderowania go, a `bs_validate_block()` sprawdza zapisane atrybuty przed ich zapisaniem.

[Renderowanie programowe](https://blockstudio.dev/pl/docs/blocks/rendering/#structured-compositions-and-complete-documents)

inspect.php

```
use Blockstudio\Canvas;
use Blockstudio\Render;

$project = Canvas::inventory(['blocks' => true]);

foreach ($project['inventory']['blocks'] as $block) {
  echo $block['name'] . "\n";
}

$doc = Render::document(
  ['name' => 'acme/hero', 'data' => ['heading' => 'Hello']],
  ['title' => 'Hero preview']
);

file_put_contents('hero.html', $doc['html']);
```

## Mniej niż połowa tokenów na stronę

Agenci zapisują zwykły HTML. Przy synchronizacji Blockstudio zamienia go na serializowany znacznik bloku WordPress: mniej do wygenerowania i mniej okazji do błędu.

### Blockstudio

Co zapisują agenci

Około 135 tokenów

index.php

```
<h1>Build Websites That Convert</h1>
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>

<block name="core/columns">
  <block name="core/column">
    <h3>Lightning Fast</h3>
    <p>Pages load in under one second.</p>
  </block>
  <block name="core/column">
    <h3>Easy to Use</h3>
    <p>No technical skills required.</p>
  </block>
  <block name="core/column">
    <h3>SEO Optimized</h3>
    <p>Built-in best practices from day one.</p>
  </block>
</block>

<img src="/dashboard.jpg" alt="Dashboard" />
```

### WordPress

Co zapisuje dla niego parser

Około 310 tokenów

post_content

```
<!-- wp:heading {"level":1} -->
<h1 class="wp-block-heading">Build Websites That Convert</h1>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>The all-in-one platform for creating
beautiful, high-performance landing pages.</p>
<!-- /wp:paragraph -->
<!-- wp:columns -->
<div class="wp-block-columns">
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Lightning Fast</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Pages load in under one second.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">Easy to Use</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>No technical skills required.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
  <!-- wp:column -->
  <div class="wp-block-column">
    <!-- wp:heading {"level":3} -->
    <h3 class="wp-block-heading">SEO Optimized</h3>
    <!-- /wp:heading -->
    <!-- wp:paragraph -->
    <p>Built-in best practices from day one.</p>
    <!-- /wp:paragraph -->
  </div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->
<!-- wp:image {"alt":"Dashboard","url":"/dashboard.jpg"} -->
<figure class="wp-block-image"><img src="/dashboard.jpg" alt="Dashboard"/></figure>
<!-- /wp:image -->
```

Pomiar na podstawie dwóch paneli powyżej: 540 znaków HTML wobec 1,233 znaków znaczników bloku zapisywanych dla niego przez standardowy parser, podzielonych przez cztery, czyli typową szacunkową liczbę znaków na token. Znaczniki pokazano z dodanymi podziałami wierszy, aby ułatwić czytanie.

## Mniej tekstu do wygenerowania

Agenci zapisują HTML bez delimitatorów bloków, generowanych klas ani znaczników opakowujących.

## Mniej okazji do błędu

Parser gwarantuje poprawny wynik bloku na podstawie prostszego wejścia.

## Szybciej i taniej

Mniej tokenów w wyniku oznacza szybsze odpowiedzi i niższe koszty modeli.

## Działa z każdym narzędziem AI do programowania

Każdy agent, który potrafi czytać i zapisywać pliki, działa z Blockstudio od razu.

Claude Code

Codex CLI

Gemini CLI

Cursor

Windsurf

Amp

## Stworzone z myślą o pracy z AI

Bloki, strony, wzorce, ustawienia. Wszystko jest plikiem, który agent może czytać, zapisywać i modyfikować.

## Dwa pliki na blok

Konfiguracja JSON i szablon tworzą cały blok. Niewielki zakres ułatwia niezawodne generowanie za pierwszym razem.

## 27 typów pól

Tekst, pliki, pola powtarzalne, kolory, daty i więcej — zdefiniowane w JSON. Listy wyboru pobierają opcje z wpisów, terminów i użytkowników.

## Walidacja schematu JSON

Każda konfiguracja ma schemat, który zapewnia agentom precyzyjne reguły i natychmiast wykrywa błędy.

## Automatyczna rejestracja

Umieść pliki w katalogu, a bloki zarejestrują się automatycznie, bez dodatkowej listy konfiguracji.

## Widok kanwy

Każda zarządzana strona albo każdy blok z wartościami domyślnymi — wszystko w jednym widoku z możliwością powiększania.

## Podgląd na żywo

Tryb na żywo odświeża zmienione obszary robocze przez Server-Sent Events około sekundy po zapisaniu. Kliknij etykietę, aby ustawić fokus na jednym obszarze roboczym.

## Wbudowany Tailwind

TailwindPHP kompiluje klasy używane na każdej stronie bez konfiguracji Node.js.

## Element Grabber

Skopiuj ścieżkę szablonu i znacznik elementu, aby natychmiast przekazać agentowi kontekst.

## HTML do bloków

Strony i wzorce to zwykłe pliki, które stają się natywnymi blokami WordPress.

## Test poprawności renderowania

wp bs blocks render renderuje każdy blok tak jak stronę i zwraca kod 1, gdy szablon zgłosi notice, warning lub error.

## Sprawdzanie zapisanej zawartości

wp bs blocks validate sprawdza zapisane pola wpisów, a pages sync ostrzega o atrybutach zapisywanych przez blok, ale nigdy przez niego nierenderowanych.

## Sprawdzaj z poziomu terminala

Wyświetlaj ustawienia, pola niestandardowe i zasoby za pomocą wp bs, a fragment kodu lub plik kompiluj poleceniem wp bs tailwind compile albo wp bs scss compile.

Plus

## Oficjalny zestaw rozszerzeń

Wysokiej jakości szablony witryn, systemowe instrukcje AI i prywatna społeczność Discord. Jednorazowy zakup, dożywotnie aktualizacje.

- 500+ szablonów stron
- Instrukcje systemowe AI
- Dożywotnie aktualizacje
- Prywatna społeczność Discord

[Uzyskaj Plus](https://blockstudio.dev/pl/plus/)
