Uygulamalar geliştirmek, ajanlar için

Bir ajanın kişilerin kullanmak isteyeceği bir Laze uygulamasını nasıl geliştirdiği: tasarım kuralları, kit, sabitlemeler ve paylaşım, trunk push'ları ve kendi işini kontrol etmesi.

Bu sayfa, bir Laze uygulaması oluşturması veya değiştirmesi istenen bir AI ajanı için yazılmıştır. İlk laze app create öncesinde okuyun. Kişiler bir uygulamayı ilk beş saniyede değerlendirir: bitmiş gibi görünmesini sağlayın, istedikleri yere koyun ve hazır olduğunu söylemeden önce kendiniz kontrol edin.

İş akışı#

1. İsteyen sohbette oluşturun:

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

   Uygulama boş başlar ve size ait bir klasörü olur: index.html ile başlayıp ardından laze app push ile sıfırdan oluşturun. --channel uygulamayı o sohbetin sekmesi olarak sabitler. Sohbetteki herkes ve ajanları onu açabilir ve üzerinde geliştirme yapabilir (Geliştirici). Uygulamaya kişilerin okuyacağı kelimelerle ad verin, slug kullanmayın.

   Platform kitini ve istemciyi sayfanızdan bağlayın:

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

   Slaytlar, sunum destesi veya konuşma tek istisnadır: tek şablon olan --template slides ile başlarlar. Dosyaları uygulamanın ilk canlı sürümüdür ve değiştirmek sizindir. Her slayt slides/ içinde bir dosyadır, slides/deck.json içinde sırayla listelenir; şablonun README.md dosyası slaytların nasıl ekleneceğini, yeniden sıralanacağını ve stillendirileceğini anlatır. Destede slayt rayı, klavye gezintisi, tam ekran Sun, PDF Dışa Aktar ve HTML Dışa Aktar düğmeleri vardır, bu yüzden bunları tekrar oluşturmayın. MCP üzerinden template: "slides" ile create_app aynı şeyi yapar ve write_app_files her seferinde bir slaytı değiştirir.

   Slayt şablonu yalnızca yeni bir deste içindir. Bir kişi zaten sayfa veya deste olan dosyalar gönderirse (HTML dışa aktarımı, index.html içeren bir zip, statik site), dosyaları olduğu gibi yayınlayın: uygulamayı --template olmadan oluşturun, dosyaları klasörüne en üstte index.html olacak şekilde açın, CDN'den yüklediği komut dosyalarını içeri kopyalayın ve push edin. Ekli dosyayla birlikte "Bunları buraya taşı" veya "bunu buraya koy" tam olarak bunu ifade eder: yapın, ne anlama geldiğini sormayın.

2. Zaten var olan bir uygulama, bağlantı içeren bir mesaja değil, sabitleme ile bir sohbete girer:

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

   --role editor üyelerin verileri değiştirmesine izin verir ama kodu değiştirmesine izin vermez, --view-only yalnızca bakmalarına izin verir. laze app pins <channel> sekmeleri listeler. Bir kişinin sabitlemesini kaldırdığı uygulamayı asla tekrar sabitlemeyin.

3. Veriyi şekillendirin: laze.app.json içinde her tür şey için bir koleksiyon, tipli alanlar ve birkaç başlangıç kaydı oluşturun. Veri kayıtlarda yaşar, asla sayfanın kodunda değil. Sayılarını, satırlarını veya metnini koda gömen bir sayfa yanlıştır: veri değiştiğinde uygulama push olmadan değişmelidir.

4. Sayfayı değiştirin, sonra canlıya geçmeden önce yerelde bakın (Kendi çalışmanızı kontrol edin bölümüne bakın).

5. Push edin:

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

   Her push canlı uygulamayı hemen değiştirir. Taslak, dal veya pull request yoktur: uygulamalar ana dal tabanlıdır. Mesajı kişiler için neyin değiştiğini anlatan düz bir cümle olarak yazın. --seed yalnızca henüz kaydı olmayan koleksiyonları doldurur.

6. Geri dön bir push yanlış olduğunda: laze app versions, sonra laze app revert <version> -m "<why>". Bu yeni canlı sürümdür; hiçbir kayıt kaybolmaz. Bir uygulamanın içindeki git geçmişi yalnızca bunun içindir.

Kim açabilir#

Yeni bir uygulama Kısıtlı olur. Bir sohbette sabitlenen uygulama oradaki herkes için açılır, bu yüzden bir ekip uygulamasının genellikle ihtiyaç duyduğu tek paylaşım sabitlemedir. Bir kanalda istenen uygulamayı yalnızca isteyen kişiyle paylaşmayın: oraya sabitleyin. Yalnızca istendiğinde laze app access visibility internal|public ile genişletin; komut ne zaman yönetici onayı gerektiğini söyler. laze app members şu anda kimin açabileceğini gösterir. Uygulamanın hazır olduğunu kişilere söylemeden önce kontrol edin.

Tasarım kuralları#

Bir düzenden değil, uygulamanın konusundan başlayın. Konuyla ilgilenen birinin bunu beyaz tahtada nasıl çizeceğini sorun ve onu oluşturun: tehdit modeli bir saldırı haritasıdır, yol haritası bir zaman çizelgesidir, bütçe para akışıdır, süreç bir diyagramdır. İstatistik kutuları ve madde listelerinden oluşan bir sayfa rapor gibi okunur. Kaçınılması gereken uygulama budur.

Çok görsel olun: mümkün olan her yerde hareketli grafikler ve akışlar kullanın, insanları tam olarak anlayana kadar adım adım yönlendirin. Asla metin duvarları yazmayın: kelimeye ihtiyaç duyduğunuz yerde basit, kısa cümleler kullanın. Uygulama insanların anlaması içindir, kafanızdaki her şeyi dökmek için değil.

Laze kiti platformdan gelir (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). Doldurulacak bir düzen değil, bir araç kutusudur: tokenlarını ve ihtiyacınız olan kontrolleri alın, üstüne kendi CSS'inizi kendi dosyanıza koyun. Kiti asla uygulamaya kopyalamayın.

• Önce görsel. Konunun görselini uygulamanın kendisi yapın: satır içi SVG, canvas, harita, zaman çizelgesi, diyagram, kişilerin tıklayıp keşfedeceği bir şey. Kitin tokenları üzerinde kendi düzeniniz ve hareketinizle ona kendine özgü bir görünüm verin.
• Her ekranda tek iş. İlk ekran, uygulamanın var olma nedenindeki soruyu yanıtlar. İkinci bir işi ilkinin altına değil, bir sekmeye (lz-tabs) koyun.
• Doğru biçim. Kişiler satırları tarıyor veya taşıyorsa tablo (lz-table) ya da pano (lz-board), odak tek bir sayıysa istatistik kutusu (lz-stats, lz-stat-value), zaman içindeki sayılar için grafik (lz-chart) ve kısa bir sıra için numaralı adımlar (lz-steps) kullanın. Üç satırdan uzun metin uygulamada değil, dokümanda yer alır.
• Gerçek veri. Kişilerin önemsediği kayıtları, gerçek adları ve tarihleriyle gösterin. "Lorem", "Item 1" veya yer tutucu grafik kullanmayın. Sayfadaki her iddia bir kayıttan veya bağlantıdan gelir.
• Yazı ölçeği. Bir sayfa başlığı (lz-title), altında bir satır (lz-lede), bölüm başlıkları (lz-h2 veya lz-card-title), gövde metni. Başka boyut eklemeyin.
• Aralıklar. Sayfa (lz-page), kart (lz-card lz-card-body) ve ızgara (lz-grid, lz-row) sınıflarını kullanın; 12 ila 20 px ritmini korurlar. Kartların içine kart yığmayın.
• İki tema da. Renkler yalnızca tokenlardan gelir (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) ve lz-badge-* tonları). Hex renk koyu modu bozar.
• Dar genişlik. Uygulamalar yaklaşık 380 px genişliğinde bir yan panelde açılır. Satırların yığılması için tablo hücrelerine data-label verin ve başlıkları tek satırda tutun.
• Boş ve hata durumları. Boş liste, neyin görüneceğini ve ilk öğenin nasıl ekleneceğini söyler. Başarısız bir çağrı boş sayfa değil, Laze.fail(error) gösterir.
• Durumları rozet olarak gösterin. Durumları renkli metinle değil, lz-badge ve bir tonla (-success, -warning, -danger, -info, -primary) gösterin.
• Formlar aradan çekilsin. "Yeni öğe"yi bir düğmenin arkasına koyun; ana içerik listedir.

Kit referansı#

Komut dosyaları yalnızca uygulamanın kendi origin'inden yüklenir: CDN <script> reddedilir, bu yüzden ihtiyacınız olan kitaplığı uygulama klasörüne kopyalayın. Bir claude.ai artifact'ını veya başka bir React sayfasını taşırken, push etmeden önce JSX'ini derleyin (örneğin npx esbuild app.jsx --bundle --minify --outfile=app.js) ve oluşturulan dosyayı bağlayın. Tarayıcı içi Babel de çalışır, ancak her açılışta megabaytlarca veri yükler.

Sayfa komut dosyasında Laze.records("<collection>") kayıtları listeler, oluşturur, günceller ve kaldırır, Laze.subscribe değişikliklerde yeniden yükler, Laze.h öğeleri oluşturur ve Laze.mount onları çizer.

Klavye kısayolları#

Laze, uygulamanız işlemediği sürece kendi kısayollarını uygulamanızdan Laze'e geçirir. Böylece kişiler önce uygulamanın dışına tıklamadan Cmd+K'ye (Windows ve Linux'ta Ctrl+K) basarak uygulamadan çıkabilir. Aktarılan kısayollar Cmd+K, Cmd+[ ve Cmd+], Cmd+1 ile Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. ve Cmd+/, ayrıca metin alanları dışında Alt+Up ve Alt+Down'dır. Diğer tüm tuşlar uygulamanızda kalır.

Bunlardan birini uygulamanız için tutmak için tuşu işleyin ve event.preventDefault() çağırın; Laze sonra ona dokunmaz:

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

Kendi çalışmanızı kontrol edin#

Push etmeden önce her değişikliğe bakın:

laze app serve --port 4173

Klasörünüzü http://127.0.0.1:4173/ adresinde platform kiti ve canlı uygulamanın kayıtlarıyla, salt okunur olarak sunar. Canlı bir sürüm gerekir, bu yüzden önce bir kez laze app push çalıştırın. Tarayıcı aracınızla açın ve iki temada ve panel genişliğinde ekran görüntüsü alın, örneğin:

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

Her görüntüye bakın. Taşan metni, sığmayan sütunları, koyu modda kaybolan renkleri ve hâlâ "demo" diyen her şeyi düzeltin.

Uygulamayı paylaşmadan önce:

• İstendiği yerde sabitlenmiş olmalı ve laze app members açması gereken kişileri listelemeli.
• İlk ekran isteği kaydırma olmadan yanıtlamalı.
• Açık, koyu ve 390 px ekran görüntüleri bitmiş görünmeli.
• Mesajınız uygulamanın adını ve ne yaptığını anlatan tek satırı içermeli. Sohbetteki sekme bağlantıdır.

Emin değilseniz sorun#

Yanlış şeyi oluşturmak yerine kişiye kısa bir soru sorun. Zaten istedikleri adımlar için "devam" beklemeyin: bu kanalda bir uygulama istedilerse, orada oluşturun, sabitleyin ve onlara söyleyin.