البدء السريع

التثبيت بمساعدة الذكاء الاصطناعي: أخبر ذكاءك الاصطناعي المبرمج (Claude Code، Cursor، Windsurf، إلخ) بجلب واتباع https://stavrobot.stavros.io/INSTALL.md — سيرشدك خلال الإعداد بالكامل بشكل تفاعلي.

التثبيت اليدوي:

1. راسل @BotFather على تليجرام لإنشاء بوت وانسخ الرمز المميز (Token). راسل @userinfobot للحصول على معرف المستخدم الخاص بك على تليجرام (يُستخدم كمعرف الدردشة).

2. انسخ env.example إلى .env وقم بتغيير POSTGRES_PASSWORD إلى شيء آمن و TZ إلى منطقتك الزمنية.

3. انسخ config.example.toml إلى data/main/config.toml واملأ الحقول المطلوبة: apiKey، password، publicHostname، [owner].name، [owner].telegram (معرف الدردشة الخاص بك)، و [telegram].botToken. كل شيء آخر في الملف اختياري.

4. docker compose up --build

هذا كل شيء. راسل بوتك على تليجرام وسيستجيب. راجع أقسام الإعداد التفصيلية أدناه لخيارات Signal وWhatsApp والبريد الإلكتروني وغيرها.

الإعداد

الإعدادات

1. انسخ config.example.toml إلى data/main/config.toml.
2. املأ مفاتيح API والإعدادات. يحتوي ملف المثال على تعليقات تشرح كل قسم.
3. على الأقل، قم بتعيين authFile (أو apiKey) و publicHostname. كل شيء آخر اختياري.
4. انسخ env.example إلى .env واضبط منطقتك الزمنية (TZ). يمكن أيضًا تجاوز بيانات اعتماد Postgres والإعدادات البيئية الأخرى هناك. قم دائمًا بتعيين POSTGRES_PASSWORD إلى شيء آمن — الإعداد الافتراضي هو عنصر نائب ضعيف ولا ينبغي استخدامه في الإنتاج.

نقاط النهاية المخصصة والمتوافقة مع OpenAI

يمكن توجيه ستافروبوت إلى أي نقطة نهاية متوافقة مع OpenAI (Ollama، LiteLLM، vLLM، إلخ) أو وكيل مخصص متوافق مع Anthropic عن طريق تعيين baseUrl في config.toml. راجع config.example.toml للحقول المطلوبة وتكوينات المثال.

المصادقة

يدعم التطبيق وضعي مصادقة: مفتاح API أو OAuth.

• مفتاح API: قم بتعيين apiKey في config.toml. لا حاجة لتسجيل الدخول أو الخروج.
• OAuth: قم بتعيين authFile في config.toml (مسار حيث سيتم تخزين بيانات الاعتماد). تعمل صفحة تسجيل الدخول مع أي موفر OAuth يدعمه Pi.
  • تسجيل الدخول: زر <your-hostname>/login في متصفح. اتبع التعليمات على الصفحة، ويتم حفظ بيانات الاعتماد في ملف المصادقة. إذا انتهت صلاحية المصادقة أثناء تشغيل البوت، فإنه يرسل لك رسالة تحتوي على رابط تسجيل الدخول عبر منصة المراسلة الخاصة بك.
  • تسجيل الخروج: احذف الملف الموجود في مسار authFile. سيكتشف البوت عدم وجود بيانات الاعتماد في الرسالة التالية وسيطلب منك تسجيل الدخول مرة أخرى.

إعداد Claude Code

حاوية coder اختيارية (مطلوبة فقط لميزة البرمجة الذاتية). تستخدم Claude Code مع مصادقة الاشتراك (OAuth)، منفصلة عن مفتاح API الخاص بالتطبيق الرئيسي.

ملفات تعريف Docker Compose مفصولة بفواصل، لذا يمكنك دمجها (على سبيل المثال COMPOSE_PROFILES=signal,coder).

1. قم بتعيين COMPOSE_PROFILES في ملف .env الخاص بك ليشمل coder (على سبيل المثال COMPOSE_PROFILES=coder، أو COMPOSE_PROFILES=signal,coder إذا كنت تستخدم Signal أيضًا).
2. ابدأ الحاويات: docker compose --profile coder up --build
3. سجل الدخول: docker compose exec -u coder coder claude (سيطلب منك تسجيل الدخول إذا لم تكن قد قمت بذلك).
4. اتبع تدفق OAuth المستند إلى المتصفح.
5. قم بتعيين [coder].model في إعداداتك إلى اسم مستعار لنموذج Claude Code (sonnet، opus، أو haiku).

إعداد Signal

يتطلب Signal رقم هاتف منفصل — وليس رقمك الشخصي. تعمل شريحة SIM مدفوعة مسبقًا أو رقم VoIP.

1. قم بإلغاء تعليق COMPOSE_PROFILES=signal في ملف .env الخاص بك لتمكين حاوية signal-bridge.
2. قم ببناء الحاويات: docker compose --profile signal build
3. سجل Signal على الحاوية (اختر واحدًا):
   • الربط بحساب Signal موجود: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' — امسح رمز QR بهاتفك (Signal > الإعدادات > الأجهزة المرتبطة).
   • تسجيل رقم جديد: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +رقمك سجل'، ثم تحقق باستخدام docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +رقمك تحقق CODE'.
4. قم بتعيين [signal].account في إعداداتك.
5. ابدأ الحاويات: docker compose up --build
6. بعد بدء التشغيل الأول، أضف الأرقام المسموح بها عبر واجهة الويب /settings.
7. هام: لا يقوم signal-cli بحل أرقام الهواتف لجهات الاتصال التي لم يراسلها بعد. يجب أن يرسل البوت الرسالة الأولى إلى كل جهة اتصال برقم الهاتف قبل أن يتمكن من استقبال الرسائل الواردة منهم والتعرف عليها. لتشغيل هذا للمالك، قم بتشغيل:
   root@kitploit:~

   docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Send the message \"Hello from Stavrobot\" to my Signal number.'})}).then(r=>r.text()).then(console.log)"
   

8. راجع البدء السريع لـ signal-cli للحصول على التفاصيل.

إعداد تليجرام

1. راسل @BotFather على تليجرام، وأنشئ بوتًا جديدًا، وانسخ الرمز المميز.
2. راسل @userinfobot على تليجرام للحصول على معرف المستخدم الخاص بك (يُستخدم كمعرف الدردشة).
3. قم بتعيين [telegram].botToken في إعداداتك.
4. قم بتعيين معرف الدردشة (وليس رقم هاتفك المحمول) في [owner].telegram في إعداداتك.
5. بعد بدء التشغيل الأول، أضف معرفات الدردشة المسموح بها عبر واجهة الويب /settings.
6. يتم تسجيل الويب هوك (Webhook) تلقائيًا عند بدء تشغيل التطبيق.

إعداد واتساب

يتطلب واتساب رقم هاتف منفصل، وإلا فسترسل لنفسك رسائل، وهو ما لا يعمل حقًا.

يستخدم واتساب Baileys، وهي مكتبة واتساب ويب غير رسمية تربط كجهاز مصاحب (مثل واتساب ويب). لا حاجة لرقم هاتف منفصل — فهو يرتبط بحساب واتساب الحالي الخاص بك.

خطر: يستخدم Baileys واجهة برمجة تطبيقات غير رسمية. قد يقوم واتساب بحظر الحسابات التي تستخدمها. استخدم على مسؤوليتك الخاصة.

1. أضف قسم [whatsapp] إلى ملف config.toml الخاص بك (راجع config.example.toml للصيغة).
2. ابدأ الحاويات: docker compose up --build
3. سيظهر رمز QR في سجلات التطبيق (docker compose logs -f app).
4. افتح واتساب على هاتفك، وانتقل إلى الأجهزة المرتبطة، وامسح رمز QR.
5. تستمر الجلسة عبر عمليات إعادة التشغيل في ./data/whatsapp.
6. أضف أرقام الهواتف المسموح بها عبر واجهة الويب /settings.

إعداد البريد الإلكتروني

يستخدم البريد الإلكتروني Cloudflare Email Worker للتسليم الوارد و SMTP للصادر. راجع config.example.toml للحصول على كود العامل الكامل وتعليمات الإعداد التفصيلية.

1. أضف قسم [email] إلى ملف config.toml الخاص بك مع بيانات اعتماد SMTP و webhookSecret عشوائي.
2. انشر Cloudflare Email Worker (الكود في config.example.toml) وقم بتعيين متغيرات البيئة WEBHOOK_URL و WEBHOOK_SECRET على العامل.
3. في توجيه البريد الإلكتروني لـ Cloudflare، أضف قاعدة لإعادة توجيه البريد الوارد إلى العامل.
4. أضف عناوين المرسلين المسموح بها عبر واجهة الويب /settings.

التشغيل

واجهة API متاحة على http://localhost:10567/chat.

ملاحظة: يعرض Docker Compose التطبيق فقط على localhost:10567. لجعله متاحًا خارجيًا (مطلوب لـ webhooks تليجرام/Signal وإعداد publicHostname)، قم بإعداد وكيل عكسي (Reverse Proxy) (مثل Nginx، Caddy) يشير إلى localhost:10567. يمكنك أيضًا كشف المنفذ مباشرة، لكن هذا غير موصى به لأن حركة المرور ستكون غير مشفرة.

بدون Docker

يتطلب Node.js >= 20 ومثيل PostgreSQL قيد التشغيل.

ملاحظة: تنفيذ بايثون وتكامل Signal يعملان فقط داخل حاويات Docker.

نظام المعرفة

لدى ستافروبوت نظام معرفة ثلاثي المستويات: الذكريات (Memories)، المسودة (Scratchpad)، وقاعدة البيانات (Database). سيديرها بشكل جيد بمفرده، لكن من المهم أن تعرفها لأنك سترغب في مساعدة البوت على استخدامها بشكل صحيح.

الذكريات (Memories) يتم حقنها دائمًا في مطالبة النظام (System Prompt) بالكامل. يجب أن تكون مقتصدًا مع هذه، حيث يتم تضمينها في السياق في كل مرة، ووجود الكثير منها قد يزيد من السياق. مثال على الذاكرة الجيدة سيكون "المستخدم يفضل الدردشة بأسلوب غير رسمي."، شيء يجب أن يعرفه البوت في كل مرة، حتى لو كان ذلك بتكلفة في طول السياق الإضافي.

المسودة (Scratchpad) هي المكان الذي يحتفظ فيه البوت بالمعرفة التي يتم الوصول إليها بشكل أقل تكرارًا، ولكنها معرفة تتعلق بموضوع معين. إدخالات المسودة لها عنوان ومحتوى، ويتم حقن العنوان في السياق تلقائيًا. استخدم هذا للأشياء المهمة، ولكن الأقل حاجة، والأشياء التي تتعلق عادة بموضوع معين.

على سبيل المثال، إدخال مسودة جيد سيكون "تفضيلات الطعام"، مع تفاصيل حول ما تحب أكله، ومتى، إلخ. سيرى البوت أن هناك موضوعًا "تفضيلات الطعام"، لكنه لن يقوم بتحميل النص الفعلي في السياق تلقائيًا، فقط الوصول إليه عند الطلب.

عندما تتحدث مع البوت عن الطعام، سيعرف أن هناك إدخال مسودة "تفضيلات الطعام" يمكنه النظر إليه، وعادة ما يفعل ذلك بمفرده.

قاعدة البيانات (Database) هي المستوى الثالث، للبيانات المنظمة أو الضخمة التي لا تنتمي إلى الذكريات أو المسودة. يتمتع البوت بوصول كامل للقراءة/الكتابة إلى PostgreSQL عبر SQL غير مقيد، لذا يمكنه إنشاء الجداول وتشغيل الاستعلامات وتخزين أي شيء. استخدم هذا للأشياء مثل القوائم والسجلات والسجلات المنظمة، أو أي بيانات من الأفضل الاستعلام عنها بدلاً من قراءتها كنثر.

سيعرف البوت عادةً ما يكفي عن ماذا يستخدم، لكن في بعض الأحيان سترغب في إخباره صراحةً بالمعلومات التي يجب وضعها في أي مكان.

التحدث مع أشخاص آخرين

يمكن لستافروبوت مراسلة الأشخاص نيابة عنك عبر Signal أو Telegram أو WhatsApp أو البريد الإلكتروني. هل تحتاج إلى تحديد موعد عشاء مع صديق؟ أخبر البوت بالعثور على وقت يناسبكما، وسيراسله ويتفاوض على التاريخ ويضعه في تقويمك. هل تريد ترتيب موعد، أو تنسيق نزهة جماعية، أو سؤال شخص ما عن شيء أثناء انشغالك؟ فقط أخبر البوت بما تحتاج إليه ومن تتحدث معه.

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

للحفاظ على الأمور آمنة، تتطلب المراسلة أمرين قبل أن يتمكن البوت من التحدث مع شخص ما:

1. قم بإضافته إلى القائمة المسموح بها. اذهب إلى /settings وأضف رقم هاتفه (Signal أو WhatsApp) أو معرف الدردشة (Telegram). هذه خطوة لمرة واحدة لكل شخص. لا يمكن للبوت تعديل هذه القائمة أو مراسلة أي شخص غير موجود فيها، مهما كان الأمر.
2. يقوم البوت بإنشاء سجل جهة اتصال. عندما تطلب من البوت مراسلة شخص ما في القائمة المسموح بها، فإنه ينشئ سجل جهة اتصال ويقوم بتشغيل وكيل فرعي مخصص للمحادثة. عند اكتمال المهمة، يقوم بتعطيل جهة الاتصال، مما يمنع المراسلة في كلا الاتجاهين حتى تطلب من البوت إعادة تمكينها.

التدفق النموذجي: تقوم بإضافة رقم هاتف صديقك إلى القائمة المسموح بها عبر /settings مرة واحدة، ثم تخبر البوت "ابحث عن وقت لتناول العشاء مع Alex الأسبوع المقبل". يقوم البوت بإنشاء سجل جهة اتصال لـ Alex، ويشغل وكيلًا فرعيًا، ويراسل Alex على Signal، ويتفاوض ذهابًا وإيابًا للعثور على تاريخ، ويبلغك بالنتيجة.

المهارات (Skills)

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

لتثبيت نظام المهارات، أخبر البوت بجلب https://stavrobot.stavros.io/skills/bootstrap.md واتباع تعليماته.

قائمة كاملة بالمهارات المتاحة موجودة على https://stavrobot.stavros.io/skills/index.md. لتثبيت مهارة، فقط أخبر البوت بجلبها وتثبيتها من هذا الرابط. سيوضح لك البوت ما تفعله المهارة ويطلب التأكيد قبل المتابعة.

توجد ملفات المهارات في فرع pages من هذا المستودع (يتم تقديمها عبر Cloudflare Pages). للمساهمة بمهارة، أضف ملف Markdown إلى skills/ على ذلك الفرع. يحتوي كل ملف مهارة على YAML front matter مع title و description و version و author اختياري، متبوعًا بالتعليمات باللغة العادية في النص. راجع SKILL-AUTHORING.md لدليل التأليف الكامل. قدم PR ضد فرع pages.

كيفية إنشاء الإضافة الخاصة بك

راجع PLUGIN.md لكل ما تحتاج إلى معرفته لإنشاء إضافة ستافروبوت. يعمل نفس المستند كمرجع لكل من البشر ونماذج LLM.

الإضافات الموصى بها

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

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

يمكنك العثور على بعض الإضافات من الطرف الأول هنا:

https://github.com/orgs/stavrobot/repositories

البنية التحتية

ثلاث حاويات Docker أساسية: app (خادم TypeScript، يعرض POST /chat، يتعامل مع webhooks تليجرام في POST /telegram/webhook، يتعامل مع webhooks البريد الإلكتروني الواردة في POST /email/webhook، ويشغل واتساب داخل العملية عبر Baileys)، و postgres (PostgreSQL 17 للحالة المستمرة)، و plugin-runner (خادم Node.js — يسرد ويفحص وينفذ الإضافات، سواء المنشأة محليًا أو المثبتة عبر git). حاوية اختيارية coder (وكيل Claude Code الرأسي لإنشاء وتعديل الإضافات القابلة للتحرير) يتم تمكينها عبر ملف تعريف coder في Docker Compose. يمكن للوكيل الرئيسي إنشاء وكلاء فرعيين، لكل منهم تاريخ المحادثة الخاص، ومطالبة النظام، والقائمة البيضاء للأدوات. المحاورون هم سجلات جهات اتصال مخصصة للوكلاء لتوجيه الرسائل الواردة.

الترخيص

AGPL-3.0