من الفكرة إلى MVP — بناء وكيل ذكي

From Idea to MVP — Building an AI Agent

تطبيق Next.js يُعرض في ورشة حيّة: نصفه تطبيق حقيقي، ونصفه نافذة على ما يجري داخله. يعمل بالعربية والإنجليزية، ويُبدَّل بينهما بزرّ واحد.

• التطبيق الحيّ. محادثة عادية. لا يعرف المستخدم شيئاً عن ReAct.
• لوحة الشرح. ثلاث لوحات تتحرّك مع كل طلب: بناء الـ Context، ثم تفكير الوكيل، ثم مسار n8n كرسم تخطيطي.

اللغتان

زر التبديل أعلى الصفحة يقلب كل شيء، لا الواجهة وحدها:

	عربي	إنجليزي
الاتجاه	RTL	LTR
موضع التطبيق	يميناً	يساراً
موضع لوحة الشرح	يساراً	يميناً
System Prompt	عربي	إنجليزي
خطوات ReAct وجواب الوكيل	عربي	إنجليزي
الأمثلة الجاهزة	عربية	إنجليزية

القاعدة واحدة في اللغتين: التطبيق يقع حيث تبدأ القراءة، ولوحة الشرح بعده. لا يوجد order صريح في الكود — الترتيب المنطقي وحده يحقّق ذلك، وأدوات Tailwind المنطقية (ms/me, ps/pe, start/end) تنقلب من dir على <html>. أضِف ml-4 أو text-left مرة واحدة، وتكسر إحدى اللغتين بصمت.

ما يبقى إنجليزياً في اللغتين عن قصد: أسماء عقد n8n (Webhook, Set Context, AI Agent) وأسماء الأدوات ومخرجات JSON. هذه أسماء حقيقية داخل n8n، ومن يفتحه بعد الورشة سيبحث عنها بهذه الحروف — وترجمتها تقطع الصلة بينه وبين ما رآه.

إضافة لغة ثالثة: مفتاح جديد في lib/i18n.ts وآخر في القواميس الثنائية داخل lib/agent-sim.ts. لا يُلمس أي مكوّن.

التشغيل

npm install
npm run dev      # http://localhost:3000
npm run build    # بناء الإنتاج

يحتاج Node 20.9+ أو 22+.

النشر على Vercel

ادفع المشروع إلى GitHub، ثم من Vercel اختر New Project وأشِر إلى المستودع. لا توجد متغيّرات بيئة ولا مفاتيح — يبني وينشر كما هو.

بنية المشروع

app/
  layout.tsx            الجذر — لغة البداية قبل تشغيل الحزمة
  page.tsx              الشاشة المقسومة، وهي الوحيدة التي تملك الحالة
  globals.css           رموز التصميم (@theme) وقواعد الأساس
  api/agent/route.ts    نقطة النهاية — تبثّ NDJSON
components/
  AgentChat.tsx         التطبيق الحيّ
  WorkshopDashboard.tsx لوحة الشرح — اللوحات الثلاث
  WorkflowGraph.tsx     رسم مسار n8n — عقد تضيء بالتتابع
lib/
  agent-sim.ts          محرّك المحاكاة — كل المنطق هنا
  i18n.ts               كل نصوص الواجهة في اللغتين

لماذا كل شيء محاكاة

لا يوجد استدعاء لنموذج حقيقي، ولا مفتاح API، ولا اتصال بالشبكة. نفس المدخل يعطي نفس المخرج في كل مرة.

هذا قرار مقصود لا اختصار: التطبيق يُعرض أمام قاعة. استدعاء نموذج حقيقي يجعل العرض رهينة الشبكة والحصة وزمن الاستجابة — وفشل واحد أمام الحضور يكلّف أكثر بكثير من الواقعية التي كسبتها.

للانتقال إلى وكيل حقيقي: استبدل runAgent في lib/agent-sim.ts باستدعاء فعلي، مع الإبقاء على نفس شكل الأحداث (AgentEvent). الواجهة لن تتغيّر إطلاقاً.

لماذا البثّ (NDJSON) لا استجابة واحدة

الدرس هو الترتيب: كيف يُركَّب الـ context، ثم كيف يفكّر الوكيل، ثم متى يستدعي الأداة. لو أرسلنا كل شيء دفعة واحدة لظهرت اللوحة مكتملة في لحظة وضاع التسلسل الذي جاء الحضور ليروه.

STEP_DELAY_MS في lib/agent-sim.ts يتحكّم بالإيقاع. ارفعه لو كانت القاعة كبيرة، واخفضه في التجربة.

أثناء العرض

• الأمثلة الجاهزة تحت حقل الإدخال تغطّي أربعة مسارات، بينها واحد بلا أدوات («شنو الفرق بين الوكيل والـ chatbot؟» / "What is the difference…"). اعرضه: يُثبت للحضور أن الوكيل يقرّر، ولا ينفّذ أداة دائماً.
• افتح تبويب Network وأرِهم أسطر NDJSON تصل واحداً بعد آخر. هذه أوضح لحظة في الشرح كله.
• الملف الذي تستعرضه أمامهم هو lib/agent-sim.ts — كل المنطق فيه، مُعلَّق بالعربية.

على الجوال

الحضور سيمسحون QR ويفتحونه على هواتفهم أثناء الورشة، فالجوال ليس حالة استثنائية:

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

ما جرى التحقّق منه

• npm run build نظيف، بلا أخطاء TypeScript.
• التطبيق قُيد فعلياً في Chromium في اللغتين × ثلاثة مقاسات (1920×1080، 1280×720، 390×844) — ست حالات: صفر أخطاء كونسول، صفر تجاوز أفقي، <h1> واحد، ولا زر بلا اسم وصول.
• في كل حالة: وصلت العقد الخمس كاملة وظهر جواب الوكيل باللغة الصحيحة.
• تأكّد انقلاب الجانبين بقياس موضع اللوحين فعلياً: التطبيق يميناً في العربي ويساراً في الإنجليزي.
• الكود يبقى LTR داخل الواجهة العربية (direction: ltr على pre و code).
• بُثّت الأحداث بالترتيب الصحيح عبر /api/agent وتأكّد ذلك من الاستجابة الخام.

أخطاء وُجدت أثناء التحقّق وأُصلحت

1. لوحة الـ Context كانت تطغى على اللوحة تحتها — نمت مع محتواها بدل أن تمرّر داخلياً. أُصلح بـ h-full على إطار اللوح.
2. الجانبان كانا معكوسين عن المواصفة — order-first على لوحة الشرح جعلها يميناً في العربية بدل التطبيق. حُذف الـ order كلّه، فصار الترتيب المنطقي يتكفّل بالاتجاهين.
3. أسهم الرسم كانت تشير يساراً في الإنجليزية أيضاً — المثلث كان موضوعاً قبل الخط، فبقي عند بداية الوصلة في الاتجاهين. نُقل بعد الخط وصار حدّه الملوَّن على جهة البداية، فأصبح يشير نحو النهاية في اللغتين.
4. تسميات عقد n8n لم تكن موسّطة — قاعدة text-align: start على .font-mono في globals.css كانت تغلب text-center لأنها خارج طبقات Tailwind. حُصرت القاعدة في code و pre و kbd. الصنف كان يظهر سليماً في الـ HTML، فلم يكن يُكتشف إلا بقراءة الأنماط المحسوبة.