एजेंट के लिए ऐप बनाना

एजेंट ऐसा Laze ऐप कैसे बनाता है जिसे लोग इस्तेमाल करना चाहें: डिज़ाइन नियम, किट, पिन और शेयरिंग, trunk pushes और अपने काम की जांच।

यह पेज उस AI एजेंट के लिए लिखा गया है जिसे Laze ऐप बनाने या बदलने के लिए कहा गया है। अपने पहले laze app create से पहले इसे पढ़ें। लोग ऐप को पहले पांच सेकंड में परख लेते हैं: इसे पूरा दिखाएं, इसे वहीं रखें जहां उन्होंने कहा था, और तैयार बताने से पहले खुद जांच लें।

वर्कफ़्लो#

1. इसे उसी बातचीत में बनाएं जहां कहा गया था:

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

   ऐप खाली शुरू होता है, आपके अपने फ़ोल्डर के साथ: इसे शुरू से बनाएं, index.html से शुरू करें, फिर laze app push। --channel ऐप को उस बातचीत के टैब के रूप में पिन करता है। उसमें मौजूद हर व्यक्ति और उनके एजेंट इसे खोल सकते हैं और इस पर आगे काम कर सकते हैं (बिल्डर)। ऐप का नाम ऐसे शब्दों में रखें जिन्हें लोग पढ़ते हैं, स्लग में नहीं।

   अपने पेज से प्लेटफ़ॉर्म किट और क्लाइंट लिंक करें:

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

   स्लाइड, डेक या टॉक एकमात्र अपवाद हैं: वे --template slides से शुरू होते हैं, जो इकलौता टेम्पलेट है। इसकी फ़ाइलें ऐप का पहला लाइव वर्ज़न होती हैं, जिन्हें आप बदल सकते हैं। हर स्लाइड slides/ में एक फ़ाइल है, और slides/deck.json में क्रम से सूचीबद्ध है। टेम्पलेट का README.md बताता है कि स्लाइड कैसे जोड़ें, उनका क्रम कैसे बदलें और उन्हें कैसे स्टाइल करें। डेक में स्लाइड रेल, कीबोर्ड नेविगेशन, फुल स्क्रीन Present, और Export PDF और Export HTML बटन होते हैं, इसलिए इन्हें फिर से न बनाएं। MCP पर, create_app को template: "slides" के साथ चलाने से यही होता है, और write_app_files एक बार में एक स्लाइड बदलता है।

   स्लाइड टेम्पलेट केवल नए डेक के लिए है। जब कोई व्यक्ति ऐसी फ़ाइलें भेजता है जो पहले से ही पेज या डेक हैं (HTML export, index.html वाला zip, static site), तो उन्हें जैसे हैं वैसे ही लगा दें: ऐप को बिना --template के बनाएं, फ़ाइलों को उसके फ़ोल्डर में अनपैक करें और index.html को सबसे ऊपर रखें, CDN से लोड होने वाली किसी भी script को कॉपी करें, और पुश करें। "Move them here" या "put this here" के साथ attachment का मतलब बिल्कुल वही है: यह करें, इसका मतलब न पूछें।

2. जो ऐप पहले से मौजूद है वह पिन के साथ बातचीत में जाता है, लिंक वाले मैसेज में नहीं:

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

   --role editor सदस्यों को डेटा बदलने देता है, लेकिन कोड नहीं। --view-only उन्हें केवल देखने देता है। laze app pins <channel> टैब सूचीबद्ध करता है। जिस ऐप को किसी व्यक्ति ने अनपिन किया है, उसे फिर कभी पिन न करें।

3. डेटा को आकार दें laze.app.json में: हर तरह की चीज़ के लिए एक कलेक्शन, टाइप किए गए फ़ील्ड और कुछ शुरुआती रिकॉर्ड। डेटा रिकॉर्ड में रहता है, पेज के कोड में कभी नहीं। जो पेज अपने नंबर, रो या टेक्स्ट हार्ड-कोड करता है, वह गलत है: डेटा बदलने पर ऐप को बिना पुश के बदलना चाहिए।

4. पेज बदलें, फिर लाइव होने से पहले उसे लोकल रूप से देखें (अपना काम जांचें देखें)।

5. पुश करें:

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

   हर पुश तुरंत लाइव ऐप होता है। कोई ड्राफ़्ट, ब्रांच या pull request नहीं है: ऐप ट्रंक आधारित होते हैं। मैसेज को एक साधारण वाक्य की तरह लिखें कि लोगों के लिए क्या बदला। --seed केवल उन कलेक्शन को भरता है जिनमें अभी कोई रिकॉर्ड नहीं है।

6. वापस जाएं जब कोई पुश गलत था: laze app versions, फिर laze app revert <version> -m "<why>"। यह एक नया लाइव वर्ज़न है। कोई रिकॉर्ड खोता नहीं है। ऐप के अंदर git हिस्ट्री सिर्फ इसी के लिए है।

इसे कौन खोल सकता है#

नया ऐप प्रतिबंधित होता है। बातचीत में पिन किया गया ऐप वहां मौजूद सभी लोगों के लिए खुलता है, इसलिए टीम ऐप के लिए आम तौर पर पिन ही पर्याप्त शेयरिंग है। अगर किसी ने चैनल में ऐप मांगा है, तो ऐप को केवल पूछने वाले व्यक्ति के साथ शेयर न करें: उसे वहीं पिन करें। laze app access visibility internal|public से दायरा केवल तब बढ़ाएं जब कहा जाए। कमांड बताता है कि एडमिन को कब मंज़ूर करना होगा। laze app members दिखाता है कि अभी इसे कौन खोल सकता है। लोगों को ऐप तैयार बताने से पहले इसे जांचें।

डिज़ाइन नियम#

ऐप किस बारे में है, वहां से शुरू करें, लेआउट से नहीं। पूछें कि जिस व्यक्ति को विषय की परवाह है वह इसे व्हाइटबोर्ड पर कैसे बनाएगा, और वही बनाएं: threat model एक attack map है, roadmap एक timeline है, budget पैसे का flow है, process एक diagram है। stat tiles और bullet lists वाला पेज रिपोर्ट जैसा लगता है, और ऐसा ऐप बनाने से बचना है।

बहुत विज़ुअल रहें: जहां हो सके मोशन ग्राफ़िक्स और फ़्लो का इस्तेमाल करें, और लोगों को एक-एक कदम करके तब तक ले जाएं जब तक वे पूरी तरह समझ न जाएं। कभी भी टेक्स्ट की दीवारें न लिखें: जहां शब्द चाहिए, वहां सरल और छोटे वाक्य लिखें। ऐप लोगों को समझाने के लिए है, आपके दिमाग में जो कुछ है उसे उड़ेलने के लिए नहीं।

Laze kit प्लेटफ़ॉर्म से आता है (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js)। यह टूलबॉक्स है, भरने के लिए लेआउट नहीं: इसके tokens और वे controls लें जिनकी आपको जरूरत है, और अपनी CSS अपनी फ़ाइल में ऊपर रखें। kit को कभी ऐप में कॉपी न करें।

• पहले विज़ुअल। विषय की तस्वीर को ही ऐप बनाएं: inline SVG, canvas, map, timeline, diagram, कुछ ऐसा जिस पर लोग क्लिक करें और explore करें। kit के tokens पर अपनी layout और motion के साथ इसे अपनी अलग पहचान दें।
• हर स्क्रीन पर एक काम। पहली स्क्रीन उस सवाल का जवाब देती है जिसके लिए ऐप मौजूद है। दूसरा काम पहले के नीचे नहीं, टैब (lz-tabs) पर रखें।
• सही रूप। जब लोग रो स्कैन करते हैं या उन्हें move करते हैं, तो table (lz-table) या board (lz-board) का उपयोग करें। जब एक नंबर ही मुख्य बात हो, तो stat tile (lz-stats, lz-stat-value) का उपयोग करें। समय के साथ नंबरों के लिए chart (lz-chart), और छोटे sequence के लिए numbered steps (lz-steps) का उपयोग करें। तीन lines से लंबा टेक्स्ट doc में होता है, ऐप में नहीं।
• असली डेटा। लोगों के काम के रिकॉर्ड दिखाएं, उनके असली नाम और तारीखों के साथ। कोई "Lorem", "Item 1" या placeholder charts नहीं। पेज पर हर दावा किसी रिकॉर्ड या लिंक से आता है।
• टाइप स्केल। एक page title (lz-title), उसके नीचे एक line (lz-lede), section titles (lz-h2 या lz-card-title), body text। अन्य sizes न जोड़ें।
• स्पेसिंग। page (lz-page), card (lz-card lz-card-body) और grid (lz-grid, lz-row) classes का उपयोग करें। वे 12 से 20 px rhythm बनाए रखते हैं। cards के अंदर cards stack न करें।
• दोनों themes। रंग केवल tokens (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) और lz-badge-* tones) से आते हैं। hex रंग dark mode तोड़ता है।
• कम चौड़ाई। ऐप लगभग 380 px चौड़े side panel में खुलते हैं। table cells को data-label दें ताकि rows stack हों, और headers को एक line में रखें।
• खाली और error states। खाली list बताती है कि क्या दिखाई देगा और पहला item कैसे जोड़ें। failed call Laze.fail(error) दिखाता है, कभी blank page नहीं।
• Status को badges के रूप में दिखाएं। states को lz-badge और tone (-success, -warning, -danger, -info, -primary) के साथ दिखाएं, रंगीन text से नहीं।
• Forms रास्ते में न आएं। "New item" को button के पीछे रखें। list मुख्य content है।

Kit reference#

Scripts केवल ऐप के अपने origin से load होते हैं: CDN <script> अस्वीकार कर दिया जाता है, इसलिए जिस library की जरूरत है उसे ऐप folder में copy करें। claude.ai artifact या किसी अन्य React page को port करते समय, push करने से पहले उसका JSX compile करें (उदाहरण के लिए npx esbuild app.jsx --bundle --minify --outfile=app.js) और built file को link करें। In-browser Babel भी काम करता है, लेकिन वह हर बार open करने पर megabytes load करता है।

Page script में, Laze.records("<collection>") records को list, create, update और remove करता है, Laze.subscribe changes पर reload करता है, Laze.h elements बनाता है और Laze.mount उन्हें draw करता है।

Keyboard shortcuts#

Laze आपके ऐप से अपने shortcuts Laze को पास करता है, जब तक आपका ऐप उन्हें handle न करे, ताकि लोग Cmd+K (Windows और Linux पर Ctrl+K) दबाकर ऐप से बाहर निकल सकें, बिना पहले उसके बाहर click किए। आगे पास किए जाने वाले shortcuts हैं Cmd+K, Cmd+[ और Cmd+], Cmd+1 से Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. और Cmd+/, साथ ही text fields के बाहर Alt+Up और Alt+Down। बाकी हर key आपके ऐप में रहती है।

इनमें से किसी एक को अपने ऐप के लिए रखने के लिए, key handle करें और event.preventDefault() call करें। फिर Laze उसे नहीं छेड़ता:

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

अपना काम जांचें#

Push करने से पहले हर change देखें:

laze app serve --port 4173

यह आपके folder को http://127.0.0.1:4173/ पर platform kit और live app के records के साथ serve करता है, read only। इसके लिए live version चाहिए, इसलिए पहले एक बार laze app push चलाएं। इसे अपने browser tool से खोलें और दोनों themes में और panel width पर screenshot लें, उदाहरण के लिए:

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

हर image देखें। overflow होने वाला text, fit न होने वाले columns, dark mode में गायब होने वाले colours और वह सब ठीक करें जिसमें अभी भी "demo" लिखा है।

ऐप post करने से पहले:

• यह वहीं pin है जहां इसके लिए कहा गया था, और laze app members उन लोगों को list करता है जिन्हें इसे खोलना चाहिए।
• पहली screen बिना scroll किए request का जवाब देती है।
• Light, dark और 390 px screenshots तैयार दिखते हैं।
• आपका message ऐप का नाम और यह क्या करता है, इस पर एक line देता है। बातचीत में tab ही link है।

जब पक्का न हो तो पूछें#

गलत चीज़ बनाने के बजाय व्यक्ति से एक छोटा सवाल पूछें। जिन steps के लिए वे पहले ही कह चुके हैं, उन पर "go" का इंतज़ार न करें: अगर उन्होंने इस channel में ऐप मांगा है, तो उसे वहीं बनाएं, pin करें और उन्हें बताएं।