مكتمل
SmartShop RAG Product Advisor
مساعد تسوّق محلي: استرجاع هجين وإعادة ترتيب بمرمِّز متقاطع فوق كتالوج المتجر نفسه.
نموذج أولي
SocialAgent
مشروع شخصي متكامل: تطبيق بـ FastAPI وReact يتعلّم أسلوب الكتابة من منشورات مستورَدة، ويصوغ منه منشورات وردودًا جاهزة لكل منصة، ويمرّر كل مسوّدة على بطارية ضوابط، ولا ينقل شيئًا إلى الطابور دون اعتماد صريح. ويُجدوَل المحتوى المعتمد ويُنشر مرة واحدة تمامًا عبر عمّال Celery من خلال واجهات OAuth الرسمية للمنصات؛ وتُستوعَب التعليقات الواردة وتُخيَّط وتُفرَز إلى طابور المراجعة نفسه. حلقة الإنشاء ← الاعتماد ← النشر ← التفاعل مكتملة ومختبَرة من طرفها إلى طرفها على محوِّل منصة صوري — ولم يُربط بعد أي حساب حقيقي.
الانتقال إلى قسم
نظرة عامة
يصوغ SocialAgent منشورات التواصل بصوت صاحبها، ويجدولها، ويصوغ ردودًا على التعليقات العائدة — ويضع قرارًا بشريًا أمام كل واحدة منها.
وخطوة الاعتماد ليست إعدادًا. تنتقل المسوّدة `draft ← approved ← queued ← published`، والانتقال إلى الطابور هو الطريق الوحيد إلى النشر، مفروضًا في نموذج البيانات ومؤكَّدًا بالاختبارات. ولا مفتاح يوقفه.
وهو مكتمل برمجيًا في نطاق النسخة الأولى: ملفات الصوت، والصياغة، والضوابط، والاعتماد، والجدولة، والنشر، واستيعاب التعليقات، وصياغة الردود، وتقويم المحتوى، ومقاييس التقييم، وواجهة React لكل ذلك. وما لم يحدث هو الاتصال بمنصة حقيقية — فكل تكامل مُتحقَّق منه على محوِّل صوري ريثما تُنجَز مراجعات تطبيقات المنصات، ولهذا يقف المشروع نموذجًا أوليًا لا شيئًا منشورًا.
السياق
الأدوات التي تنشر تلقائيًا نيابةً عن أحد تميل إلى إنتاج محتوى يُقرأ وكأن أحدًا لم يكتبه، لأن أحدًا لم يكتبه فعلًا. وليس هذا خللًا عارضًا — فالمنشور خارج الصوت هو المخرج المعتاد، ويكتشفه صاحبه وقد صار علنيًا.
ولذلك لم يكن سؤال التصميم يومًا «كم يمكن أتمتته؟» بل «أين يقع القرار البشري، وما الذي يمنع تخطّيه؟». ووضع تلك البوابة في مخطط البيانات لا في سياسة مكتوبة هو القرار الذي بُني حوله سائر النظام.
المشكلة
العمل على المحتوى متكرر بما يكفي لتتمنى معه عونًا، وشخصي بما يكفي لأن تُفقِد أتمتتُه الكاملة الغرضَ منه — والأنظمة التي تؤدّيه تمسّ هوية صاحبها العلنية وحساباته على المنصات وبيانات اعتماده.
- أن تبدو المسوّدات بصوت صاحبها، ما يعني تعلّم أسلوب كتابته لا تطبيق صوت عام.
- ألا يبلغ شيء جمهورًا دون اعتماد بشري صريح، وأن يكون ذلك بنيويًا لا إعدادًا.
- أن المسوّدة المولَّدة قد تخرج عن الهوية أو تكون غير آمنة أو تحمل تعليمة مهرَّبة عبر تعليق — فيجب فحص كل مسوّدة قبل عرضها على إنسان ليعتمدها.
- ألا تُبلَغ المنصات إلا عبر واجهات OAuth والنشر الموثّقة لديها، ضمن ما تسمح به كل منصة فعلًا من أتمتة.
- أن رموز المنصات بيانات اعتماد: مشفَّرة في السكون، لا تُسجَّل في السجلات، ولا تعيدها الواجهة أبدًا.
- أن يُنشر المنشور المجدوَل مرة واحدة — لا صفرًا لأن عاملًا سقط، ولا مرتين لأنه أعاد المحاولة.
- أن التعليقات الواردة تحتاج فرزًا قبل أن تحتاج ردودًا.
دوري في المشروع
دوري في المشروع
هذا مشروعي الخاص، بنيتُه من طرفه إلى طرفه: مجموعة التخطيط التي سبقت الكود، ونموذج البيانات وترحيلاته، والمصادقة وخزنة الرموز المشفَّرة، وتكاملات OAuth، واستخراج الصوت وتوليد المسوّدات خلف تجريد للمزوّد، وبطارية الضوابط، وبوابة الاعتماد، وعمّال الجدولة والنشر، واستيعاب التعليقات وصياغة الردود، وأداة التقييم والمقاييس، وواجهة React، وخط التكامل المستمر وبواباته.
المسؤوليات
الصوت والتوليد
- ملفات الصوت: التقاط منشورات عيّنة واستخراج دليل أسلوب منها.
- توليد المسوّدات مشكَّلًا بذلك الدليل وبقواعد كل منصة.
- صياغة الردود بالصوت نفسه، من التعليق وسياق خيطه.
- تجريد للمزوّد يجعل نموذجًا محليًا في التطوير وآخر مستضافًا في الإنتاج تغييرَ إعداد.
السلامة والاعتماد
- بطارية ضوابط فوق كل مسوّدة: فحوص حتمية، وفحوص بالنموذج، ومسح لحقن الأوامر في النص الوارد من الغرباء.
- بوابة الاعتماد، مفروضةً في نموذج البيانات طريقًا وحيدًا من المسوّدة إلى الطابور.
- صندوق اعتماد للمنشورات والردود، وأثر تدقيق وراء كل قرار.
النشر والتفاعل
- الجدولة وناشرٌ على Celery beat ينشر المنشور المعتمد مرة واحدة تمامًا.
- إعادات محاولة ومطابقة ولحاق، فتُستدرَك الخانة الفائتة أو يُنبَّه عليها بدل ضياعها.
- منظِّم معدّل لكل منصة.
- استيعاب التعليقات — استطلاعًا وعبر Webhook — منزوعَ التكرار، مخيَّطًا، ومفروزًا.
- تقويم محتوى فوق العناصر المسوَّدة والمجدوَلة والمنشورة.
المنصة والجودة
- مخطط PostgreSQL وترحيلات Alembic؛ وDocker Compose للواجهة والعامل وقاعدة البيانات والطابور.
- واجهة React وTypeScript: المحرِّر، وصندوق الاعتماد، والتقويم، والإعدادات، بوحدات تصميمها الخاصة ووضعها الداكن.
- مجموعة ذهبية خارج التشغيل ببوابة انحدار، ومقاييس إنتاجية — معدّل التحرير لكل ملف صوت، ومعدّل اجتياز السلامة، ومحاولات الحقن.
- بوابات تكامل مستمر: Ruff، وmypy الصارم، وdetect-secrets، وpytest، واختبارات ثوابت أمنية تؤكّد أن كل مسار محمي بالمصادقة.
المنهج التقني
بناء الحلقة بترتيب جريانها، وجعل البوابة البشرية خاصيةً في نموذج البيانات لا خطوةً يُؤتمَن الكود على استدعائها.
- تعلّم الصوت: استيراد منشورات عيّنة واستخراج دليل أسلوب تُحاسَب عليه مرحلة الصياغة.
- الصياغة من موجز أو خانة تقويم، مشكَّلةً بذلك الدليل وبما تسمح به المنصة الهدف.
- الفحص قبل سؤال الإنسان: تشغيل بطارية الضوابط — قواعد حتمية، وفحوص بالنموذج، ومسح حقن على كل ما جاء من غريب.
- البوابة: الاعتماد هو الانتقال الوحيد الذي يضع عنصرًا في طابور.
- نشر العناصر المعتمدة في موعدها، مرة واحدة تمامًا، عبر واجهة المنصة نفسها، تحت منظِّم معدّل.
- استيعاب التعليقات ونزع تكرارها وخياطتها وفرزها، وصياغة ردود تعود إلى طابور الاعتماد نفسه.
- قياس الشقّين: إشارة إنتاجية من قرارات الاعتماد والتحرير الحقيقية، ومجموعة ذهبية خارج التشغيل تمنع تغيير Prompt يُنكِص الصوت أو السلامة.
البنية التقنية
يُصاغ الموجز أو خانة التقويم على ملف صوت مستخرَج من منشورات مستورَدة. وتمرّ كل مسوّدة — منشورًا كانت أو ردًّا مكتوبًا من تعليق مستوعَب — على بطارية الضوابط، ثم تنتظر في بوابة الاعتماد، وهي الانتقال الوحيد القادر على وضعها في الطابور. ويُجدوَل المعتمد ويُنشر مرة واحدة تمامًا بعمّال Celery عبر واجهة OAuth للمنصة، برموز محفوظة في خزنة مشفَّرة بـ Fernet. وتغذّي قرارات الاعتماد مقاييسَ التقييم.
- الموجز: تدخل فكرة محتوى أو خانة تقويم إلى المحرِّر.
- ملف الصوت: دليل أسلوب مستخرَج من منشورات صاحبه المستورَدة.
- الصياغة: تُولَّد مسوّدة جاهزة للمنصة على ذلك الدليل.
- التعليقات: تُستوعَب التعليقات الواردة وتُنزَع تكراراتها وتُخيَّط وتُفرَز.
- صياغة الرد: يُكتب الرد من التعليق، بالصوت نفسه.
- الضوابط: تعمل الفحوص الحتمية والنموذجية وفحص حقن الأوامر على كل مسوّدة ورد.
- بوابة الاعتماد: القرار البشري هو الانتقال الوحيد إلى الطابور.
- النشر: ينشر عمّال Celery العناصر المعتمدة في موعدها، مرة واحدة تمامًا، عبر واجهة المنصة.
- خزنة الرموز: لا تُفكّ شيفرة بيانات اعتماد OAuth إلا لحظة الاستعمال.
- التقييم: تغذّي قرارات الاعتماد والتحرير مقاييسَ الصوت والسلامة.
الميزات
ملفات الصوت
دليل أسلوب مستخرَج من منشورات كتبها صاحبها فعلًا، وقابل للتحرير بعدها.
صياغة تراعي المنصة
مسوّدات مكتوبة وفق حدود المنصة الهدف وأعرافها، لا منشورًا عامًا واحدًا.
بطارية الضوابط
قواعد حتمية وفحوص بالنموذج ومسح لحقن الأوامر تعمل قبل أن يُسأل إنسان الاعتماد.
بوابة لا إعداد
الاعتماد هو الانتقال الوحيد الذي يضع عنصرًا في الطابور، مفروضًا في المخطط ومؤكَّدًا بالاختبارات.
ينشر مرة واحدة تمامًا
يصمد العمل المجدوَل أمام إعادة تشغيل العامل: مواعيد الاستحقاق في قاعدة البيانات، والخانة الفائتة يُلحَق بها أو يُنبَّه عليها.
فرز التعليقات والردود
تُنزع تكرارات التعليقات وتُخيَّط وتُصنَّف؛ وتعود الردود المقترحة عبر البوابة نفسها.
خزنة رموز مشفَّرة
بيانات اعتماد OAuth مشفَّرة في السكون، لا تُسجَّل ولا تعيدها الواجهة أبدًا.
مقيس لا مفترَض
معدّل التحرير لكل ملف صوت ومعدّل اجتياز السلامة في الإنتاج، ومجموعة ذهبية خارج التشغيل تحكم تغييرات الـ Prompt.
الأمان والموثوقية
ضوابط الأمان
- بوابة الاعتماد انتقالُ حالة في نموذج البيانات لا رايةَ صلاحية: لا يبلغ شيء طابورَ نشر دونها.
- رموز OAuth للمنصات في خزنة مشفَّرة بـ Fernet، لا تُفكّ شيفرتها إلا لحظة الاستعمال، ولا تُسجَّل ولا تعيدها الواجهة أبدًا.
- تجزئة كلمات المرور بـ bcrypt ورموز جلسات JWT؛ وكل إجراء يخصّ صاحب الحساب يُكتب في سجل تدقيق.
- مسح لحقن الأوامر على النص الوارد من الغرباء — فالتعليق مدخل غير موثوق، وقد أثبتت حالة عدائية ذلك حين أطاعها نموذج محلي بينما ظل الضابط مانعًا للرد.
- واجهات المنصات الرسمية وحدها، ضمن قواعد الأتمتة الموثّقة لكل منصة — بلا كشط ولا جلسات متصفح صامت.
- detect-secrets في التكامل المستمر، واختبارات ثوابت أمنية تؤكّد أن كل مسار يشترط المصادقة بدل الاتّكال على المراجعة — وقد كشفت مسارَين بلا مصادقة ومسحًا للمسارات كان ينجح فارغًا.
الموثوقية والرصد
- مواعيد الاستحقاق في قاعدة البيانات، فيصمد المسار أمام انقطاعه: يُلحَق بالخانة الفائتة أو يُنبَّه عليها بدل ضياعها صامتة.
- النشر مُتماثل الأثر — لا تحوّل إعاداتُ المحاولة والمطابقة منشورًا معتمدًا واحدًا إلى اثنين.
- منظِّم معدّل لكل منصة يُبقي الناشر داخل حدودها.
- نبضات حياة ومراقبُ ركود يجعلان الطابور المتوقّف مسموعًا، مع تنبيه لصاحب العمل الذي توقّف.
- معايير قبول النسخة الأولى تعمل مجموعةَ اختبارات قابلة للتنفيذ، وتُجرَّب الحلقة كاملة في جلسة واحدة — على محوِّل منصة صوري، وهذا هو الحد الأمين لتلك البيّنة.
التحديات
محاكاة الأسلوب هي الجزء الأرجح فشلًا على نحو أسوأ من عدم المحاولة — فالاقتراب غير المصيب من صوت أحدهم يُقرأ زائفًا.
تُبقي البوابة المسوّدة الرديئة خاصة، ويحوّل معدّل التحرير لكل ملف صوت سؤالَ «هل يشبهني هذا؟» إلى شيء مرئي لا إلى شعور.
أوقف أولُ تشغيل لأداة التقييم الإصدارَ: على نموذج التطوير المحلي، سقطت بوابة السلامة في الحالات العدائية، وأُطيع حقنُ أوامر مصوغ بلباقة إطاعةً كاملة.
أمسكت الضوابط بكل تلك الإخفاقات، وهو ما يتنبأ به التصميم المتعدد الطبقات — لكن التشغيل حسم أيضًا مسألة النموذج: النموذج المحلي الصغير صالح للبناء عليه ولا يصلح لصياغة شيء علني. ولم يُحفَظ خطُّ أساس، لأن تشغيلًا فاشلًا لا يصحّ أن يصير المعيار.
كل قرار يواجه المنصات — أشكال المسارات والحمولات وتثبيت إصدارات الواجهات وما تسمح به كل منصة للأتمتة — غير قابل للتحقق حتى تُنجَز مراجعة التطبيق.
تقف التكاملات خلف واجهة محوِّل واحدة بتنفيذ صوري، فأمكن بناء الحلقة كاملة واختبارها دون انتظار — مع الإقرار بأن هذه أكبر مساحة غير مختبَرة في المشروع.
القرارات والمفاضلات
| القرار | البديل المطروح | المبرر |
|---|---|---|
| جعل الاعتماد انتقالَ حالة في نموذج البيانات. | وضع نشر تلقائي قابل للإعداد، أو اعتماد مفروض في طبقة الخدمات. | يحدّ الاعتماد من قدر الوقت الذي توفّره الأداة، وهذا كل مغزى المقايضة: أن يبقى المحتوى محتوى صاحبه. ووضعه في المخطط يعني أن ميزة لاحقة لا تستطيع الالتفاف حوله بهدوء — والثمن أن تصير ميزات الراحة كقواعد الاعتماد التلقائي عملًا مقصودًا لا راية إعداد. |
| بناء الحلقة كاملة على محوِّل منصة صوري. | انتظار مراجعة تطبيق المنصة قبل بناء النصف المعتمد على التكامل. | لم ينتظر شيء في الجدول طابورَ مراجعة خارج سيطرة المشروع، وبقي التكامل المستمر بلا اتصال وسريعًا. وفي المقابل، يبقى كل تفصيل خاص بالمنصات غير متحقَّق منه حتى تصل بيانات الاعتماد، وعلى مجموعة القبول أن تُعاد على حساب اختباري حقيقي قبل أن يُحسَب أي من ذلك عاملًا. |
| تشغيل نموذج محلي صغير في التطوير خلف تجريد للمزوّد. | التطوير مباشرةً على النموذج المستضاف المقصود للإنتاج. | الاستدلال المحلي لا يكلّف شيئًا، ويُبقي منشورات العيّنة على الجهاز، ويتيح لمجموعة الاختبارات تزييف المزوّد بالكامل. وهو أيضًا لا يجامل: النموذج الأضعف هو ما كشف حجم ما كانت الضوابط تحمله فعلًا. والمأخذ أن قراءات الجودة المأخوذة في التطوير لا تنتقل، فيلزم إعادة التقييم على نموذج الإنتاج قبل أن تعني درجاته شيئًا. |
النتيجة
الحلقة كاملة تعمل من طرفها إلى طرفها: استيراد عيّنات كتابة، واستخراج صوت، وصياغة منشور أو رد، واجتياز الضوابط، والاعتماد يدويًا، ثم مشاهدته يُنشر في موعده — مع تعليقات تعود وتُفرز ويُردّ عليها عبر البوابة نفسها. وتغطي واجهة React ذلك كله: المحرِّر وصندوق الاعتماد وتقويم المحتوى والإعدادات.
وهو بصدق نموذج أولي لا شيء منشور. فكل تفاعل مع المنصات متحقَّق منه على محوِّل صوري لأن مراجعات التطبيقات معلّقة، وأداة التقييم شُغِّلت مرة فأوقفت الإصدار على نموذج التطوير المحلي، ولا استضافة إنتاجية بعد. وما يتبقى نظام مكتمل ومختبَر بحافة واحدة غير متحقَّق منها — وسجل مكتوب يحدد أين تقع تلك الحافة بالضبط.
الدروس المستفادة
- تحديد موضع خطوة الاعتماد البشري قرارٌ منتَجي يقيّد البنية كلها من حوله — ووضعه في المخطط هو ما يمنع تآكله لاحقًا.
- أداة التقييم تستحق كلفتها أول مرة تقول «لا». فأول تشغيل لها أوقف إصدارًا وأجاب عن سؤال اختيار النموذج في آن.
- ينبغي أن تُصمَّم الضوابط لتصمد حين يفشل النموذج، لأنه سيفشل: أهمّ الحالات كانت تلك التي أطاع فيها النموذج حقنَ أوامر وأمسك بها الفحص الحتمي رغم ذلك.
- المحوِّل الصوري يمنحك نظامًا كاملًا سريعًا ويترك شيئًا واحدًا بلا اختبار. وهي مقايضة جيدة فقط ما دمتَ تصرّح دائمًا بما هو ذلك الشيء.
حزمة التقنيات
اللغة
Backend
البيانات
الواجهة الأمامية
الذكاء الاصطناعي والاسترجاع
المنصة
الممارسات
لقطات الشاشة
ستُضاف لقطات الشاشة لاحقًا
لنتحدث عن مشروعك
هل لديك مشروع برمجي أو ذكاء اصطناعي أو RAG أو تطبيق ويب؟ لنتحدث عمّا تحتاجه ونحدد المنهج التقني المناسب.