בניית אפליקציות, עבור סוכנים

איך סוכן בונה אפליקציית Laze שאנשים ירצו להשתמש בה: כללי עיצוב, ערכת הכלים, נעיצות ושיתוף, ביצוע push ל-trunk ובדיקת העבודה שלו.

הדף הזה נכתב עבור סוכן AI שהתבקש לבנות או לשנות אפליקציית Laze. קרא אותו לפני ה-laze app create הראשון שלך. אנשים שופטים אפליקציה בחמש השניות הראשונות: לגרום לה להיראות גמורה, לשים אותה במקום שבו ביקשו אותה, ולבדוק אותה בעצמך לפני שאומרים שהיא מוכנה.

תהליך העבודה

ליצור אותה בשיחה שביקשה אותה:
```
laze app create "Insights" --channel <channel>
```
האפליקציה מתחילה ריקה, עם תיקייה שהיא שלך: בנה אותה מאפס, החל מ-index.html, ואז laze app push. --channel נועץ את האפליקציה כטאב של השיחה הזאת. כל מי שנמצא בה, וגם הסוכנים שלהם, יכולים לפתוח אותה ולבנות עליה (עורך). תן לאפליקציה שם במילים שאנשים קוראים, לא slug.

קשר את ערכת הפלטפורמה ואת הלקוח מהדף שלך:
```
<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 של התבנית מסביר איך להוסיף שקפים, לשנות את הסדר שלהם ולעצב אותם. במצגת יש סרגל שקפים, ניווט במקלדת, הצגה במסך מלא, וכפתורי ייצוא PDF וייצוא HTML, לכן אל תבנה אותם שוב. דרך MCP, create_app עם template: "slides" עושה אותו דבר, ו-write_app_files משנה שקף אחד בכל פעם.

תבנית השקפים מיועדת רק למצגת חדשה. כשאדם שולח קבצים שהם כבר דף או מצגת (ייצוא HTML, קובץ zip עם index.html, אתר סטטי), העלה אותם כפי שהם: צור את האפליקציה בלי --template, חלץ את הקבצים לתיקייה שלה עם index.html בראש, העתק פנימה כל סקריפט שהיא טוענת מ-CDN, ובצע push. "להעביר אותם לכאן" או "לשים את זה כאן" עם קובץ מצורף פירושם בדיוק זה: לעשות את זה, לא לשאול מה זה אומר.
אפליקציה שכבר קיימת נכנסת לשיחה כנעיצה, לא כהודעה עם קישור:
```
laze app pin <app> --channel <channel>
```
--role editor מאפשר לחברים לשנות נתונים אבל לא את הקוד, --view-only מאפשר להם רק לצפות. laze app pins <channel> מציג את רשימת הטאבים. לעולם אל תנעץ שוב אפליקציה שאדם ביטל את הנעיצה שלה.
לעצב את הנתונים ב-laze.app.json: אוסף אחד לכל סוג של דבר, עם שדות מוקלדים וכמה רשומות התחלתיות. הנתונים חיים ברשומות, אף פעם לא בקוד של הדף. דף שמקודד מספרים, שורות או טקסט באופן קשיח הוא שגוי: כשהנתונים משתנים, האפליקציה חייבת להשתנות בלי push.
לשנות את הדף, ואז להסתכל עליו מקומית לפני שהוא עולה לאוויר (ראה לבדוק את העבודה שלך).
לבצע push:
```
laze app push -m "Added the pipeline board" --seed
```
כל push הופך מיד לאפליקציה החיה. אין טיוטות, ענפים או pull requests: אפליקציות מבוססות trunk. כתוב את ההודעה כמשפט פשוט על מה שהשתנה עבור אנשים. --seed ממלא רק אוספים שעדיין אין בהם רשומות.
לחזור כש-push היה שגוי: laze app versions, ואז laze app revert <version> -m "<why>". זאת גרסה חיה חדשה; אף רשומה לא הולכת לאיבוד. היסטוריית git בתוך אפליקציה מיועדת רק לזה.

מי יכול לפתוח אותה

נראות	מי יכול לפתוח אותה
מוגבלת	אנשים, סוכנים ושיחות שהיא שותפה איתם או נעוצה בהם, וגם בעלים ומנהלים של סביבת העבודה
ערוץ	חברי הערוץ של האפליקציה
פנימית	כולם בסביבת העבודה
ציבורית	כל מי שיש לו את הכתובת

אפליקציה חדשה היא מוגבלת. אפליקציה שנעוצה בשיחה נפתחת לכל מי שנמצא שם, לכן נעיצה היא בדרך כלל כל השיתוף שאפליקציית צוות צריכה. אל תשתף אפליקציה רק עם האדם שביקש אותה אם הוא ביקש אותה בערוץ: נעץ אותה שם. הרחב עם laze app access visibility internal|public רק כשמבקשים; הפקודה אומרת מתי מנהל חייב לאשר. laze app members מציג מי יכול לפתוח אותה עכשיו. בדוק את זה לפני שאתה אומר לאנשים שהאפליקציה מוכנה.

כללי עיצוב

התחל ממהות האפליקציה, לא מפריסה. שאל איך מישהו שאכפת לו מהנושא היה מצייר אותו על לוח, ובנה את זה: מודל איומים הוא מפת תקיפה, מפת דרכים היא ציר זמן, תקציב הוא זרימה של כסף, תהליך הוא תרשים. דף של אריחי נתונים ורשימות עם תבליטים נקרא כמו דוח, וזו האפליקציה שצריך להימנע ממנה.

היו ויזואליים מאוד: השתמשו בגרפיקה בתנועה ובתרשימי זרימה בכל מקום אפשרי, והובילו אנשים צעד אחר צעד עד שיבינו לגמרי. לעולם אל תכתבו קירות של טקסט: איפה שצריך מילים, השתמשו במשפטים פשוטים וקצרים. אפליקציה נועדה שאנשים יבינו, לא כדי לשפוך את כל מה שיש לכם בראש.

ערכת Laze מגיעה מהפלטפורמה (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). זו ארגז כלים, לא פריסה שצריך למלא: קח את ה-tokens שלה ואת הפקדים שאתה צריך, ושים מעליהם CSS משלך בקובץ משלך. לעולם אל תעתיק את הערכה לתוך האפליקציה.

חזות קודם. הפוך את התמונה של הנושא לאפליקציה עצמה: SVG מוטמע, canvas, מפה, ציר זמן, תרשים, משהו שאנשים לוחצים עליו וחוקרים. תן לה מראה משלה, עם פריסה ותנועה משלך על גבי ה-tokens של הערכה.
משימה אחת לכל מסך. המסך הראשון עונה על השאלה שלשמה האפליקציה קיימת. שים משימה שנייה בטאב (lz-tabs), לא מתחת לראשונה.
הצורה הנכונה. השתמש בטבלה (lz-table) או בלוח (lz-board) כשאנשים סורקים או מזיזים שורות, באריח נתון (lz-stats, lz-stat-value) כשמספר אחד הוא העיקר, בתרשים (lz-chart) למספרים לאורך זמן ובצעדים ממוספרים (lz-steps) לרצף קצר. טקסט ארוך משלוש שורות שייך למסמך, לא לאפליקציה.
נתונים אמיתיים. הצג את הרשומות שאכפת לאנשים מהן, עם השמות והתאריכים האמיתיים שלהן. בלי "Lorem", בלי "Item 1" ובלי תרשימי placeholder. כל טענה בדף מגיעה מרשומה או מקישור.
סולם טיפוגרפי. כותרת דף אחת (lz-title), שורה אחת מתחתיה (lz-lede), כותרות מקטעים (lz-h2 או lz-card-title), טקסט גוף. אל תוסיף גדלים אחרים.
ריווח. השתמש במחלקות הדף (lz-page), הכרטיס (lz-card lz-card-body) והגריד (lz-grid, lz-row); הן שומרות על קצב של 12 עד 20 px. אל תערום כרטיסים בתוך כרטיסים.
שתי ערכות הנושא. צבעים מגיעים רק מ-tokens (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) והגוונים של lz-badge-*). צבע hex שובר מצב כהה.
רוחב צר. אפליקציות נפתחות בלוח צד ברוחב של כ-380 px. תן לתאי טבלה data-label כדי ששורות ייערמו, ושמור כותרות בשורה אחת.
מצבים ריקים ושגיאות. רשימה ריקה אומרת מה יופיע ואיך להוסיף את הראשון. קריאה שנכשלה מציגה Laze.fail(error), אף פעם לא דף ריק.
סטטוס כתגים. הצג מצבים עם lz-badge וגוון (-success, -warning, -danger, -info, -primary), לא כטקסט צבעוני.
טפסים לא מפריעים. שים "פריט חדש" מאחורי כפתור; הרשימה היא התוכן הראשי.

עיון בערכה

צורך	מחלקות
דף וכותרת	`lz-page`, `lz-header`, `lz-title`, `lz-lede`
פריסה	`lz-row`, `lz-grow`, `lz-grid`, `lz-stats`
כרטיסים	`lz-card`, `lz-card-body`, `lz-card-title`, `lz-h2`
טבלאות	`lz-table-wrap`, `lz-table`, `lz-num` (מספרים מיושרים לימין)
לוחות	`lz-board`, `lz-column`, `lz-column-head`, `lz-tile`
מספרים	`lz-stat-value`, `lz-chart`, `lz-chart-col`, `lz-chart-track`, `lz-chart-bar`, `lz-chart-value`, `lz-chart-label`
צעדים	`ol.lz-steps` עם `li` אחד לכל צעד
פקדים	`lz-btn`, `lz-btn-primary`, `lz-btn-ghost`, `lz-input`, `lz-select`, `lz-textarea`, `lz-field`, `lz-form`, `lz-tabs`, `lz-tab`
מצבים	`lz-badge` (+ גוון), `lz-callout`, `lz-empty`, `lz-muted`

סקריפטים נטענים רק מה-origin של האפליקציה עצמה: CDN <script> נדחה, לכן העתק ספרייה שאתה צריך לתיקיית האפליקציה. כשמעבירים artifact של claude.ai או דף React אחר, יש לקמפל את ה-JSX שלו לפני push (לדוגמה npx esbuild app.jsx --bundle --minify --outfile=app.js) ולקשר את הקובץ הבנוי. Babel בתוך הדפדפן עובד גם, אבל הוא טוען מגה-בייטים בכל פתיחה.

בסקריפט הדף, Laze.records("<collection>") מציג רשימות, יוצר, מעדכן ומסיר רשומות, Laze.subscribe טוען מחדש כשיש שינויים, Laze.h בונה אלמנטים ו-Laze.mount מצייר אותם.

קיצורי מקלדת

Laze מעביר את קיצורי הדרך שלו מהאפליקציה שלך אל Laze, אלא אם האפליקציה שלך מטפלת בהם, כך שאנשים יכולים ללחוץ Cmd+K (‏Ctrl+K ב-Windows וב-Linux) כדי לצאת מאפליקציה בלי ללחוץ קודם מחוץ לה. קיצורי הדרך שמועברים הלאה הם Cmd+K, ‏Cmd+[ ו-Cmd+], ‏Cmd+1 עד Cmd+9, ‏Cmd+Shift+A, ‏Cmd+Shift+T, ‏Cmd+Shift+M, ‏Cmd+Shift+D, ‏Cmd+. ו-Cmd+/, וגם Alt+Up ו-Alt+Down מחוץ לשדות טקסט. כל מקש אחר נשאר באפליקציה שלך.

כדי לשמור אחד מהם לאפליקציה שלך, טפל במקש וקרא ל-event.preventDefault(); אז Laze משאיר אותו כפי שהוא:

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

לבדוק את העבודה שלך

הסתכל על כל שינוי לפני שאתה מבצע עליו push:

laze app serve --port 4173

זה מגיש את התיקייה שלך ב-http://127.0.0.1:4173/ עם ערכת הפלטפורמה והרשומות של האפליקציה החיה, לקריאה בלבד. צריך גרסה חיה, לכן הרץ קודם את laze app push פעם אחת. פתח אותה עם כלי הדפדפן שלך וצלם מסך בשתי ערכות הנושא וברוחב לוח, למשל:

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

הסתכל על כל תמונה. תקן טקסט שגולש, עמודות שלא נכנסות, צבעים שנעלמים במצב כהה וכל דבר שעדיין אומר "demo".

לפני שאתה מפרסם את האפליקציה:

היא נעוצה במקום שבו ביקשו אותה, ו-laze app members מציג את האנשים שאמורים לפתוח אותה.
המסך הראשון עונה לבקשה בלי גלילה.
צילומי המסך במצב בהיר, במצב כהה וברוחב 390 px נראים גמורים.
ההודעה שלך נותנת את שם האפליקציה ושורה אחת על מה שהיא עושה. הטאב בשיחה הוא הקישור.

לשאול כשלא בטוחים

שאל את האדם שאלה קצרה אחת במקום לבנות את הדבר הלא נכון. אל תחכה ל-"קדימה" על צעדים שכבר ביקשו ממך: אם ביקשו אפליקציה בערוץ הזה, צור אותה שם, נעץ אותה וספר להם.

בניית אפליקציות, עבור סוכנים

תהליך העבודה#

מי יכול לפתוח אותה#

כללי עיצוב#

עיון בערכה#

קיצורי מקלדת#

לבדוק את העבודה שלך#

לשאול כשלא בטוחים#