كيفاش تستضيف Whirl بوحدك، تطبيق دردشة بالذكاء الاصطناعي فل ستاك

شنو هو Whirl؟

Whirl هو تطبيق مفتوح المصدر للدردشة مع الذكاء الاصطناعي، مبني بتقنيات Next.js وConvex وكيخدم من الواجهة حتى للخلفية. هو الكود اللي ورا whirl.chat، ومتوفر برخصة MIT، يعني تقدر تطّلع عليه، تشغّل النسخة ديالك، ولا تساهم بتحسينات.

المشروع كيجمع نماذج متعددة ديال الذكاء الاصطناعي، وذاكرة دائمة، ونتائج قابلة للتعديل، وبحث فالويب، وأدوات مخصّصة، ومحادثات مركّزة على الخصوصية فواجهة وحدة. النماذج كيدوزو عبر OpenRouter، بينما Convex كيوفّر قاعدة البيانات، ودوال الخلفية، والبث، والمهام المجدولة.

الميزات الرئيسية

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

التقنيات المستعملة

تطبيق الويب فالإنتاج كيستعمل Next.js 16، وReact 19، وTailwind CSS v4، وMotion. Convex كيوفّر الخلفية، وClerk كيتكلف بالمصادقة، وOpenRouter كيوفّر الولوج للنماذج عبر AI SDK. المستودع منظّم كورشات عمل ديال Bun ومكتوب بـTypeScript.

غير Convex وClerk وOpenRouter ضروريين للإعداد الأساسي. الخدمات الأخرى اختيارية:

• Autumn للفوترة
• Exa للبحث فالويب
• Supermemory للذاكرة
• PostHog وAxiom للتحليلات
• Braintrust للتتبّع
• Resend للبريد الإلكتروني
• Median لوكيل الدعم

إلى ما تهيّأتش شي خدمة اختيارية، Whirl كيخبي الميزة اللي كتستعملها بلا ما يفرض عليك إعدادها باش يشغّل التطبيق.

المتطلبات الأساسية

قبل ما تثبّت Whirl، وجّد هاد الحوايج:

• Bun مثبّت فالحاسوب ديالك
• حساب مجاني فـConvex
• تطبيق فـClerk
• مفتاح API ديال OpenRouter
• Git باش تنسخ المستودع

الخطوة 1: نسخ Whirl وتثبيتو

نسخ المستودع، دخل للمجلد ديالو، وثبّت جميع اعتماديات الورشات باستعمال Bun:

git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install

الخطوة 2: إنشاء خلفية Convex

دخل لحزمة الخلفية وبدا عملية التطوير ديال Convex:

cd packages/backend
bunx convex dev

فأول تشغيل، Convex غادي يرافقك فعملية إنشاء المشروع وبيئة النشر ديال التطوير. خلّي هاد العملية خدامة باش تتزامن تغييرات الخلفية أثناء التطوير.

الخطوة 3: إعداد أسرار الخلفية

حلّ طرفية أخرى داخل packages/backend. زِد نطاق مُصدِر JWT ديال Clerk ومفتاح API ديال OpenRouter لبيئة Convex:

bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...

عوّض القيم النموذجية ببيانات الدخول ديال حسابات Clerk وOpenRouter ديالك. وثائق الاستضافة الذاتية المفصّلة كتشرح قالب Clerk JWT اللي كيحتاجو Convex.

ما تديرش مفاتيح API ولا أسرار المصادقة فالمستودع. خزّن أسرار الخلفية باستعمال أوامر بيئة Convex، وإعدادات الويب المحلية فملف البيئة المناسب.

الخطوة 4: إعداد تطبيق الويب

دخل لتطبيق الويب ديال الإنتاج وأنشئ ملف بيئة محلي انطلاقاً من المثال المرفق:

cd ../../apps/v2
cp .env.example .env.local

حلّ .env.local وعمّر القيم الأربعة المطلوبة ديال Convex وClerk. استعمل الملف النموذجي باش تعرف أسماء المتغيرات بالضبط، وما تنشئش أسماء جديدة.

الخطوة 5: تشغيل بيئة التطوير

رجع لجذر المستودع وبدا أمر التطوير:

cd ../..
bun run dev

منين تبدا الخدمات خدامة، حلّ localhost:3000. سجّل الدخول عبر تطبيق Clerk المهيّأ وبدا محادثة.

الاستعمال الأساسي

بدا محادثة

دخل طلب فمحرّر الدردشة وصيفطو للنموذج المهيّأ. هاد أول طلب بسيط يقدر يتأكد بلي تطبيق الويب، والمصادقة، وخلفية Convex، والاتصال بـOpenRouter خدامين مجموعين:

شرح المكوّنات الرئيسية ديال هاد التطبيق فخمسة نقط مختصرة.

خدم مع النماذج

Whirl مصمّم باش يوفّر الولوج لعدة نماذج رائدة عبر OpenRouter داخل محادثة وحدة. وتقدر حتى تستعمل مستويات تفكير قابلة للتعديل فالحالات اللي كيدعمها التطبيق والنموذج المختار.

صايب ونقّح المصنوعات

طلب من Whirl يصايب ليك وثيقة، رسم بياني، ولا صفحة تفاعلية. هاد المصنوعات كيبقاو قابلين للتعديل فلوحة جانبية، وتقدر تشاركهم بالرابط، وهادشي كيخليهم مناسبين للنتائج اللي خاصها تنقيح مستمر، ماشي غير جواب واحد فالدردشة.

استعمل الملفات، الصوت، والتنظيم

Whirl كيدعم إرفاق الملفات والإدخال الصوتي زيادة على الرسائل المكتوبة. تقدر تنظم المحادثات فمجلدات، وميزات المشاركة كتخلي الخدمة المختارة متاحة للآخرين.

فهم المستودع

المستودع الموحد فيه بزاف ديال التطبيقات وخلفية مشتركة:

• apps/v2: تطبيق الويب الإنتاجي المبني بـ Next.js واللي كيستعملو Whirl.
• apps/console: لوحة إدارة مبنية بـ Vite لتدبير النماذج، التكاملات، والمهارات.
• apps/mobile: تطبيق أصلي مبني بـ Expo.
• apps/waitlist: صفحة مستقلة ديال لائحة الانتظار.
• apps/remotion: تركيبات ديال الفيديوهات الترويجية.
• apps/legacy: تطبيق الويب السابق، مخلي غير للرجوع ليه وما بقاش كيتصان.
• packages/backend: مخطط Convex، الدوال، وخط أنابيب الذكاء الاصطناعي.
• docs: دلائل الاستضافة الذاتية، الإعداد، والهندسة المعمارية.
• brand: الشعارات، الألوان، اللافتات، وأيقونات التطبيق.

فالتطوير الحالي ديال الويب، ركّز على apps/v2 وpackages/backend. بعد على بناء خدمة جديدة فوق apps/legacy، حيث ما بقاش كيتصان.

نصائح متقدمة

زيد الخدمات الاختيارية بالتدريج

بدا بالإعدادات الضرورية ديال Convex وClerk وOpenRouter. من بعد ما يخدم مسار الدردشة الأساسي، زيد المزوّدين الاختياريين واحد بواحد. Whirl كيخبي أوتوماتيكياً الوظائف اللي المفاتيح الضرورية ديالها ناقصة، وهادشي كيخلي تشغيل تثبيت صغير أسهل.

راجع دليل الإعداد ديال المستودع باش تعرف متغيرات البيئة المرتابطة بالفوترة، البحث، الذاكرة، التحليلات، التتبع، البريد الإلكتروني، والدعم.

اختار وضع الخصوصية المناسب

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

تفقّد مسار الرسائل

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

وجّد للإنتاج بعناية

البداية السريعة كتنشئ بيئة تطوير. قبل النشر للعموم، تبع دليل الاستضافة الذاتية الكامل، بما فيه التعليمات الخاصة بقالب Clerk JWT والنشر فالإنتاج.

ساهم بأمان

قبل ما تفتح طلب دمج، راجع دليل المساهمة ديال المشروع باش تعرف القواعد والاختبارات المطلوبة. تبع مدونة السلوك، وبلّغ على المشاكل الأمنية باستعمال المسار الموضح فـ SECURITY.md، وماشي عبر issue علنية.

الخلاصة

Whirl كيعطيك نقطة انطلاق غنية بالميزات لمساحة عمل دردشة بالذكاء الاصطناعي مستضافة ذاتياً، وكيجمع بين واجهة Next.js وخلفية Convex، والمصادقة عبر Clerk، والولوج لنماذج OpenRouter. بدا بالخدمات الثلاثة الضرورية، تأكد من الدردشة المحلية فـ localhost:3000، ومن بعد فعّل البحث، الذاكرة، التحليلات، الفوترة، والتكاملات الأخرى الاختيارية حسب احتياجات النشر ديالك.