Tworzenie aplikacji dla agentów

Jak agent tworzy aplikację Laze, z której osoby chcą korzystać: zasady projektowania, zestaw narzędzi, przypinanie i udostępnianie, pushy do trunka oraz sprawdzanie własnej pracy.

Ta strona jest napisana dla agenta AI, który ma zbudować lub zmienić aplikację Laze. Przeczytaj ją przed pierwszym laze app create. Osoby oceniają aplikację w pierwszych pięciu sekundach: spraw, aby wyglądała na gotową, umieść ją tam, gdzie poproszono, i sprawdź ją samodzielnie, zanim powiesz, że jest gotowa.

Proces pracy#

1. Utwórz ją w rozmowie, w której o nią poproszono:

   laze app create "Insights" --channel <channel>

   Aplikacja zaczyna jako pusta, z folderem należącym do ciebie: zbuduj ją od zera, zaczynając od index.html, potem laze app push. --channel przypina aplikację jako kartę tej rozmowy. Każda osoba w rozmowie i jej agenci mogą ją otworzyć i rozwijać (Twórca). Nazwij aplikację słowami, które osoby czytają, a nie slugiem.

   Podłącz zestaw platformy i klienta ze swojej strony:

   <link rel="stylesheet" href="/_laze/theme.css" />
   <link rel="stylesheet" href="/_laze/kit.css" />
   <script src="/_laze/laze.js"></script>

   Slajdy, prezentacja lub wystąpienie są jedynym wyjątkiem: zaczynają od --template slides, jedynego szablonu. Jego pliki są pierwszą działającą wersją aplikacji, którą możesz zmieniać. Każdy slajd jest jednym plikiem w slides/, wymienionym w kolejności w slides/deck.json; README.md szablonu mówi, jak dodawać, zmieniać kolejność i stylizować slajdy. Prezentacja ma pasek slajdów, nawigację klawiaturą, pełnoekranowy tryb Prezentuj oraz przyciski Eksportuj PDF i Eksportuj HTML, więc nie buduj ich ponownie. Przez MCP create_app z template: "slides" robi to samo, a write_app_files zmienia po jednym slajdzie naraz.

   Szablon slajdów służy tylko do nowej prezentacji. Gdy osoba wysyła pliki, które już są stroną lub prezentacją (eksport HTML, zip z index.html, statyczna strona), wystaw je tak, jak są: utwórz aplikację bez --template, rozpakuj pliki do jej folderu z index.html na górze, skopiuj każdy skrypt, który ładuje z CDN, i wypchnij. „Przenieś je tutaj” lub „umieść to tutaj” z załącznikiem znaczy dokładnie to: zrób to, nie pytaj, co to znaczy.

2. Istniejąca aplikacja trafia do rozmowy jako przypięcie, a nie jako wiadomość z linkiem:

   laze app pin <app> --channel <channel>

   --role editor pozwala członkom zmieniać dane, ale nie kod, a --view-only pozwala im tylko przeglądać. laze app pins <channel> wyświetla karty. Nigdy nie przypinaj ponownie aplikacji, którą osoba odpięła.

3. Ukształtuj dane w laze.app.json: jedna kolekcja na każdy rodzaj rzeczy, z typowanymi polami i kilkoma rekordami początkowymi. Dane są w rekordach, nigdy w kodzie strony. Strona, która ma liczby, wiersze lub tekst wpisane na sztywno, jest błędna: gdy zmieniają się dane, aplikacja musi zmienić się bez pushowania.

4. Zmień stronę, potem obejrzyj ją lokalnie, zanim trafi na live (zobacz Sprawdź własną pracę).

5. Wypchnij:

   laze app push -m "Added the pipeline board" --seed

   Każdy push od razu staje się działającą aplikacją. Nie ma szkiców, gałęzi ani pull requestów: aplikacje działają w modelu trunk-based. Napisz wiadomość jako proste zdanie o tym, co zmieniło się dla osób. --seed wypełnia tylko kolekcje, które nie mają jeszcze rekordów.

6. Wróć, gdy push był błędny: laze app versions, potem laze app revert <version> -m "<why>". To jest nowa działająca wersja; żaden rekord nie zostaje utracony. Historia git w aplikacji służy tylko do tego.

Kto może ją otworzyć#

Nowa aplikacja jest ograniczona. Aplikacja przypięta w rozmowie otwiera się dla wszystkich w tej rozmowie, więc przypięcie zwykle wystarcza do udostępnienia aplikacji zespołu. Nie udostępniaj aplikacji tylko osobie, która o nią poprosiła, jeśli poprosiła o nią w kanale: przypnij ją tam. Poszerz dostęp poleceniem laze app access visibility internal|public tylko na prośbę; polecenie powie, kiedy admin musi zatwierdzić. laze app members pokazuje, kto może ją teraz otworzyć. Sprawdź to, zanim powiesz osobom, że aplikacja jest gotowa.

Zasady projektowania#

Zacznij od tego, czego dotyczy aplikacja, a nie od układu. Zapytaj, jak ktoś, komu zależy na temacie, narysowałby go na tablicy, i zbuduj właśnie to: model zagrożeń to mapa ataków, roadmapa to oś czasu, budżet to przepływ pieniędzy, proces to diagram. Strona z kafelkami statystyk i listami punktowanymi wygląda jak raport, a tego typu aplikacji należy unikać.

Stawiaj na obraz: używaj animacji i schematów przepływu, gdzie tylko się da, i prowadź ludzi krok po kroku, aż wszystko zrozumieją. Nigdy nie pisz ścian tekstu: tam, gdzie potrzebujesz słów, używaj prostych, krótkich zdań. Aplikacja ma pomagać ludziom zrozumieć, a nie służyć do zrzucenia wszystkiego, co masz w głowie.

Zestaw Laze pochodzi z platformy (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). To skrzynka z narzędziami, a nie układ do wypełnienia: weź z niej tokeny i kontrolki, których potrzebujesz, i dodaj własny CSS w swoim pliku na wierzchu. Nigdy nie kopiuj zestawu do aplikacji.

• Najpierw obraz. Niech obraz tematu będzie samą aplikacją: inline SVG, canvas, mapa, oś czasu, diagram, coś, co osoby klikają i eksplorują. Nadaj temu własny wygląd, z własnym układem i ruchem na tokenach zestawu.
• Jedno zadanie na ekran. Pierwszy ekran odpowiada na pytanie, dla którego aplikacja istnieje. Drugie zadanie umieść na karcie (lz-tabs), a nie pod pierwszym.
• Właściwy kształt. Użyj tabeli (lz-table) lub tablicy (lz-board), gdy osoby przeglądają lub przenoszą wiersze, kafelka statystyki (lz-stats, lz-stat-value), gdy chodzi o jedną liczbę, wykresu (lz-chart) dla liczb w czasie i numerowanych kroków (lz-steps) dla krótkiej sekwencji. Tekst dłuższy niż trzy wiersze należy do dokumentu, nie do aplikacji.
• Prawdziwe dane. Pokazuj rekordy, na których osobom zależy, z prawdziwymi nazwami i datami. Bez „Lorem”, „Item 1” ani wykresów zastępczych. Każde stwierdzenie na stronie pochodzi z rekordu lub linku.
• Skala typografii. Jeden tytuł strony (lz-title), jeden wiersz pod nim (lz-lede), tytuły sekcji (lz-h2 lub lz-card-title), tekst podstawowy. Nie dodawaj innych rozmiarów.
• Odstępy. Używaj klas strony (lz-page), karty (lz-card lz-card-body) i siatki (lz-grid, lz-row); utrzymują rytm 12 do 20 px. Nie układaj kart w kartach.
• Oba motywy. Kolory pochodzą tylko z tokenów (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) i tonów lz-badge-*). Kolor hex psuje tryb ciemny.
• Wąska szerokość. Aplikacje otwierają się w panelu bocznym o szerokości około 380 px. Nadaj komórkom tabeli data-label, aby wiersze się układały, i trzymaj nagłówki w jednym wierszu.
• Stany puste i błędów. Pusta lista mówi, co się pojawi i jak dodać pierwszy element. Nieudane wywołanie pokazuje Laze.fail(error), nigdy pustą stronę.
• Status jako odznaki. Pokazuj stany za pomocą lz-badge i tonu (-success, -warning, -danger, -info, -primary), a nie kolorowego tekstu.
• Formularze nie przeszkadzają. Umieść „Nowy element” za przyciskiem; lista jest główną treścią.

Referencja zestawu#

Skrypty ładują się tylko z własnego originu aplikacji: CDN <script> jest odrzucane, więc skopiuj potrzebną bibliotekę do folderu aplikacji. Podczas przenoszenia artefaktu claude.ai lub innej strony React skompiluj jej JSX przed pushowaniem (na przykład npx esbuild app.jsx --bundle --minify --outfile=app.js) i podlinkuj zbudowany plik. Babel w przeglądarce też działa, ale ładuje megabajty przy każdym otwarciu.

W skrypcie strony Laze.records("<collection>") wyświetla, tworzy, aktualizuje i usuwa rekordy, Laze.subscribe przeładowuje przy zmianach, Laze.h buduje elementy, a Laze.mount je rysuje.

Skróty klawiaturowe#

Laze przekazuje własne skróty z aplikacji do Laze, chyba że aplikacja je obsłuży, więc osoby mogą nacisnąć Cmd+K (Ctrl+K w Windows i Linux), aby opuścić aplikację bez wcześniejszego klikania poza nią. Przekazywane skróty to Cmd+K, Cmd+[ i Cmd+], Cmd+1 do Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. i Cmd+/, plus Alt+Up i Alt+Down poza polami tekstowymi. Każdy inny klawisz zostaje w aplikacji.

Aby zachować jeden z nich dla aplikacji, obsłuż klawisz i wywołaj event.preventDefault(); wtedy Laze zostawi go w spokoju:

document.addEventListener("keydown", (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === "k") {
    event.preventDefault();
    openSearch();
  }
});

Sprawdź własną pracę#

Obejrzyj każdą zmianę, zanim ją wypchniesz:

laze app serve --port 4173

Udostępnia twój folder pod http://127.0.0.1:4173/ z zestawem platformy i rekordami działającej aplikacji, tylko do odczytu. Wymaga działającej wersji, więc najpierw uruchom raz laze app push. Otwórz ją narzędziem przeglądarki i zrób zrzuty ekranu w obu motywach oraz przy szerokości panelu, na przykład:

npx -y playwright install chromium   # once
npx -y playwright screenshot --viewport-size=1100,800 http://127.0.0.1:4173/ light.png
npx -y playwright screenshot --viewport-size=1100,800 "http://127.0.0.1:4173/?theme=dark" dark.png
npx -y playwright screenshot --viewport-size=390,800 http://127.0.0.1:4173/ narrow.png

Obejrzyj każdy obraz. Napraw tekst, który się przelewa, kolumny, które się nie mieszczą, kolory, które znikają w trybie ciemnym, i wszystko, co nadal mówi „demo”.

Zanim napiszesz o aplikacji:

• Jest przypięta tam, gdzie o nią poproszono, a laze app members wymienia osoby, które powinny ją otworzyć.
• Pierwszy ekran odpowiada na prośbę bez przewijania.
• Zrzuty ekranu w motywie jasnym, ciemnym i przy 390 px wyglądają jak gotowe.
• Twoja wiadomość podaje nazwę aplikacji i jedno zdanie o tym, co robi. Karta w rozmowie jest linkiem.

Pytaj, gdy nie masz pewności#

Zadaj osobie jedno krótkie pytanie, zamiast budować niewłaściwą rzecz. Nie czekaj na „go” przy krokach, o które już poproszono: jeśli poproszono o aplikację w tym kanale, utwórz ją tam, przypnij i powiedz o tym.