إنشاء التطبيقات، للوكلاء

كيف يبني الوكيل تطبيق Laze يريد الأشخاص استخدامه: قواعد التصميم ومجموعة الأدوات والتثبيت والمشاركة وعمليات الدفع إلى trunk وفحص عمله بنفسه.

هذه الصفحة مكتوبة لوكيل ذكاء اصطناعي طُلب منه إنشاء تطبيق 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 الخاص بالقالب كيفية إضافة الشرائح وإعادة ترتيبها وتنسيقها. يحتوي العرض على شريط شرائح، وتنقل بلوحة المفاتيح، ووضع تقديم بملء الشاشة، وأزرار Export PDF وExport HTML، لذلك لا تبنِ هذه الأشياء مرة أخرى. عبر MCP، يفعل create_app مع template: "slides" الشيء نفسه، ويغيّر write_app_files شريحة واحدة في كل مرة.

   قالب الشرائح مخصص فقط لعرض تقديمي جديد. عندما يرسل شخص ملفات هي بالفعل صفحة أو عرضا تقديميا (تصدير HTML، أو ملف zip يحتوي على index.html، أو موقعا ثابتا)، ارفعها كما هي: أنشئ التطبيق من دون --template، وفك الملفات في مجلده مع وضع index.html في الأعلى، وانسخ أي سكربت يحمّله من CDN، ثم ادفع. عبارة "انقلها إلى هنا" أو "ضع هذا هنا" مع مرفق تعني ذلك بالضبط: افعلها، ولا تسأل عمّا تعنيه.

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

   كل دفع هو التطبيق المباشر فورا. لا توجد مسودات أو فروع أو طلبات سحب: تعتمد التطبيقات على الجذع. اكتب الرسالة كجملة واضحة عن ما تغيّر للأشخاص. يملأ --seed فقط المجموعات التي لا تحتوي على سجلات بعد.

6. الرجوع عندما يكون الدفع خاطئا: 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). إنها صندوق أدوات، وليست تخطيطا لملئه: خذ رموزها والمكونات التي تحتاج إليها، وضع CSS الخاص بك في ملفك الخاص فوقها. لا تنسخ العدة إلى التطبيق أبدا.

• البصري أولا. اجعل صورة الموضوع هي التطبيق نفسه: SVG مضمن، أو canvas، أو خريطة، أو خط زمني، أو مخطط، أو شيء ينقره الأشخاص ويستكشفونه. أعطه مظهرا خاصا به، مع تخطيطك وحركتك على رموز العدة.
• مهمة واحدة لكل شاشة. تجيب الشاشة الأولى عن السؤال الذي وُجد التطبيق من أجله. ضع المهمة الثانية في علامة تبويب (lz-tabs)، لا أسفل الأولى.
• الشكل المناسب. استخدم جدولا (lz-table) أو لوحة (lz-board) عندما يمسح الأشخاص الصفوف أو ينقلونها، ومربع إحصاء (lz-stats، lz-stat-value) عندما يكون رقم واحد هو المقصود، ومخططا (lz-chart) للأرقام عبر الزمن، وخطوات مرقمة (lz-steps) لتسلسل قصير. النص الأطول من ثلاثة أسطر مكانه مستند، لا تطبيق.
• بيانات حقيقية. اعرض السجلات التي تهم الأشخاص، بأسمائها وتواريخها الحقيقية. لا تستخدم "Lorem" أو "Item 1" أو مخططات بديلة. كل ادعاء في الصفحة يأتي من سجل أو رابط.
• مقياس الكتابة. عنوان صفحة واحد (lz-title)، وسطر واحد تحته (lz-lede)، وعناوين أقسام (lz-h2 أو lz-card-title)، ونص أساسي. لا تضف أحجاما أخرى.
• التباعد. استخدم أصناف الصفحة (lz-page)، والبطاقة (lz-card lz-card-body)، والشبكة (lz-grid، lz-row)؛ فهي تحافظ على إيقاع 12 إلى 20 بكسل. لا تكدس البطاقات داخل البطاقات.
• كلا المظهرين. تأتي الألوان من الرموز فقط (var(--color-fg)، var(--color-bg-surface)، var(--color-primary)، var(--color-border) ودرجات lz-badge-*). اللون الست عشري يكسر الوضع الداكن.
• العرض الضيق. تفتح التطبيقات في لوحة جانبية بعرض يقارب 380 بكسل. أعطِ خلايا الجداول data-label حتى تتكدس الصفوف، وأبقِ الرؤوس في سطر واحد.
• حالات الفراغ والخطأ. توضح القائمة الفارغة ما سيظهر وكيفية إضافة أول عنصر. تعرض المكالمة الفاشلة Laze.fail(error)، وليس صفحة فارغة أبدا.
• الحالة كشارات. اعرض الحالات باستخدام lz-badge ونغمة (-success، -warning، -danger، -info، -primary)، لا كنص ملون.
• النماذج لا تعيق الطريق. ضع "عنصر جديد" خلف زر؛ القائمة هي المحتوى الرئيسي.

مرجع العدة#

تُحمّل السكربتات فقط من أصل التطبيق نفسه: يُرفض <script> من CDN، لذلك انسخ أي مكتبة تحتاج إليها إلى مجلد التطبيق. عند نقل artifact من claude.ai أو صفحة React أخرى، صرّف JSX قبل أن تدفع (مثلا 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();
  }
});

تحقق من عملك بنفسك#

انظر إلى كل تغيير قبل أن تدفعه:

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 بكسل مكتملة.
• تذكر رسالتك اسم التطبيق وسطرا واحدا عما يفعله. علامة التبويب في المحادثة هي الرابط.

اسأل عند الشك#

اسأل الشخص سؤالا قصيرا واحدا بدلا من بناء الشيء الخطأ. لا تنتظر موافقة على خطوات طلبوها بالفعل: إذا طلبوا تطبيقا في هذه القناة، فأنشئه هناك، وثبته، وأخبرهم.