خطة تحديث التطبيق

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

الهدف

​

المبادئ

• الحفاظ على البنية الحالية ما لم يكن هناك حدّ يثبت أنه يسبب تغييرات متكررة، أو تكلفة أداء، أو أخطاء ظاهرة للمستخدم.
• تفضيل أصغر تصحيح صحيح لكل مشكلة، ثم التكرار.
• فصل الإصلاحات المطلوبة عن التحسينات الاختيارية حتى يستطيع المشرفون دمج الأعمال عالية القيمة دون انتظار قرارات ذاتية.
• إبقاء السلوك الموجّه إلى Plugin موثقًا ومتوافقًا مع الإصدارات السابقة.
• التحقق من السلوك المشحون، وعقود الاعتماديات، والاختبارات قبل الادعاء بأن الانحدار قد أُصلح.
• تحسين مسار المستخدم الرئيسي أولًا: الإعداد الأولي، والمصادقة، والدردشة، وإعداد المزوّد، وإدارة Plugin، والتشخيصات.

​

المرحلة 1: تدقيق خط الأساس

• حدّد أهم سير عمل المستخدم وأسطح الشيفرة التي تملكها.
• اذكر الإمكانات الميتة، والإعدادات المكررة، وحالات الخطأ غير الواضحة، ومسارات التصيير المكلفة.
• التقط أوامر التحقق الحالية لكل سطح.
• علّم المشكلات باعتبارها مطلوبة، أو موصى بها، أو اختيارية.
• وثّق العوائق المعروفة التي تحتاج إلى مراجعة المالك، خصوصًا تغييرات API، والأمان، والإصدار، وعقد Plugin.

• قائمة مشكلات واحدة مع مراجع ملفات من جذر المستودع.
• لكل مشكلة شدة، وسطح مالك، وتأثير متوقع على المستخدم، ومسار تحقق مقترح.
• لا تُخلط عناصر التنظيف الافتراضية ضمن الإصلاحات المطلوبة.

​

المرحلة 2: تنظيف المنتج وتجربة المستخدم

• شدّد نص الإعداد الأولي والحالات الفارغة حول مصادقة النموذج، وحالة Gateway، وإعداد Plugin.
• أزل أو عطّل الإمكانات الميتة حيث لا يكون أي إجراء ممكنًا.
• أبقِ الإجراءات المهمة مرئية عبر العروض المتجاوبة بدل إخفائها خلف افتراضات تخطيط هشّة.
• وحّد لغة الحالة المتكررة بحيث يكون للأخطاء مصدر حقيقة واحد.
• أضف كشفًا تدريجيًا للإعدادات المتقدمة مع إبقاء الإعداد الأساسي سريعًا.

• مسار نجاح يدوي لإعداد التشغيل الأول وبدء تشغيل مستخدم موجود.
• اختبارات مركّزة لأي منطق توجيه، أو استمرار إعدادات، أو اشتقاق حالة.
• لقطات شاشة للمتصفح للأسطح المتجاوبة التي تغيّرت.

​

المرحلة 3: تشديد بنية الواجهة الأمامية

• انقل تحولات حالة واجهة المستخدم المتكررة إلى مساعدين ضيقين ومكتوبين الأنواع.
• أبقِ مسؤوليات جلب البيانات، والاستمرار، والعرض منفصلة.
• فضّل الخطافات، والمخازن، وأنماط المكونات الحالية على التجريدات الجديدة.
• قسّم المكونات كبيرة الحجم فقط عندما يقلل ذلك الترابط أو يوضح الاختبارات.
• تجنّب إدخال حالة عامة واسعة لتفاعلات اللوحات المحلية.

• لا تغيّر السلوك العام كنتيجة جانبية لتقسيم الملفات.
• أبقِ سلوك إمكانية الوصول سليمًا للقوائم، ومربعات الحوار، وعلامات التبويب، والتنقل بلوحة المفاتيح.
• تحقّق من أن حالات التحميل، والفارغة، والخطأ، والتفاؤل لا تزال تُعرض.

​

المرحلة 4: الأداء والموثوقية

• قِس تكاليف بدء التشغيل، والانتقال بين المسارات، والقوائم الكبيرة، ونصوص الدردشة.
• استبدل البيانات المشتقة المكلفة المتكررة بمحددات محفوظة أو مساعدين مخزنين مؤقتًا حيث يثبت القياس قيمة ذلك.
• قلّل عمليات فحص الشبكة أو نظام الملفات التي يمكن تجنبها في المسارات الساخنة.
• حافظ على ترتيب حتمي للمدخلات الخاصة بالموجه، والسجل، والملف، وPlugin، والشبكة قبل إنشاء حمولة النموذج.
• أضف اختبارات انحدار خفيفة للمساعدين الساخنين وحدود العقود.

• يسجل كل تغيير أداء خط الأساس، والتأثير المتوقع، والتأثير الفعلي، والفجوة المتبقية.
• لا يصل أي تصحيح أداء اعتمادًا على الحدس فقط عندما يكون القياس الرخيص متاحًا.

​

المرحلة 5: تقوية الأنواع والعقود والاختبارات

• استبدل سلاسل وقت التشغيل الفضفاضة باتحادات مميّزة أو قوائم رموز مغلقة.
• تحقّق من المدخلات الخارجية باستخدام مساعدين المخططات الحاليين أو zod.
• أضف اختبارات عقود حول بيانات Plugin، وكتالوجات المزوّدين، ورسائل بروتوكول Gateway، وسلوك ترحيل الإعدادات.
• أبقِ مسارات التوافق في تدفقات الطبيب أو الإصلاح بدل عمليات ترحيل مخفية وقت بدء التشغيل.
• تجنّب ترابط الاختبارات فقط مع داخليات Plugin؛ استخدم واجهات SDK والواجهات المجمّعة الموثقة.

• pnpm check:changed
• اختبارات مستهدفة لكل حدّ تغيّر.
• pnpm build عندما تتغير الحدود الكسولة، أو التغليف، أو الأسطح المنشورة.

​

المرحلة 6: التوثيق وجاهزية الإصدار

• حدّث الوثائق مع تغييرات السلوك، أو API، أو الإعدادات، أو الإعداد الأولي، أو Plugin.
• أضف إدخالات سجل التغييرات فقط للتغييرات المرئية للمستخدم.
• أبقِ مصطلحات Plugin موجّهة للمستخدم؛ استخدم أسماء الحزم الداخلية فقط حيث يحتاجها المساهمون.
• أكّد أن تعليمات الإصدار والتثبيت لا تزال تطابق سطح الأوامر الحالي.

• تُحدّث الوثائق ذات الصلة في الفرع نفسه كتغييرات السلوك.
• تنجح فحوصات الوثائق المولّدة أو انحراف API عند لمسها.
• يذكر التسليم أي تحقق تم تخطيه وسبب تخطيه.

​

الشريحة الأولى الموصى بها

• دقّق إعداد التشغيل الأول، وجاهزية مصادقة المزوّد، وحالة Gateway، وأسطح إعداد Plugin.
• أزل الإجراءات الميتة ووضّح حالات الفشل.
• أضف أو حدّث اختبارات مركّزة لاشتقاق الحالة واستمرار الإعدادات.
• شغّل pnpm check:changed.

​

تحديث مهارة الواجهة الأمامية

# Frontend Delivery Standards

Use this skill when implementing or reviewing user-facing React, Next.js,
desktop webview, or app UI work.

## Operating rules

- Start from the existing product workflow and code conventions.
- Prefer the smallest correct patch that improves the current user path.
- Separate required fixes from optional polish in the handoff.
- Do not build marketing pages when the request is for an application surface.
- Keep actions visible and usable across supported viewport sizes.
- Remove dead affordances instead of leaving controls that cannot act.
- Preserve loading, empty, error, success, and permission states.
- Use existing design-system components, hooks, stores, and icons before adding
  new primitives.

## Implementation checklist

1. Identify the primary user task and the component or route that owns it.
2. Read the local component patterns before editing.
3. Patch the narrowest surface that solves the issue.
4. Add responsive constraints for fixed-format controls, toolbars, grids, and
   counters so text and hover states cannot resize the layout unexpectedly.
5. Keep data loading, state derivation, and rendering responsibilities clear.
6. Add tests when logic, persistence, routing, permissions, or shared helpers
   change.
7. Verify the main happy path and the most relevant edge case.

## Visual quality gates

- Text must fit inside its container on mobile and desktop.
- Toolbars may wrap, but controls must remain reachable.
- Buttons should use familiar icons when the icon is clearer than text.
- Cards should be used for repeated items, modals, and framed tools, not for
  every page section.
- Avoid one-note color palettes and decorative backgrounds that compete with
  operational content.
- Dense product surfaces should optimize for scanning, comparison, and repeated
  use.

## Handoff format

Report:

- What changed.
- What user behavior changed.
- Required validation that passed.
- Any validation skipped and the concrete reason.
- Optional follow-up work, clearly separated from required fixes.