Mattermost Hermes Agent — استضافة ذاتية للفريق

Mattermost Hermes Agent — استضافة ذاتية للفريق

إذا كان فريقك يستخدم Mattermost، فأنت تعرف جاذبيته بالفعل: يبدو ويُحسّ مثل Slack، لكن الخادم — والبيانات — يبقيان على بنيتك التحتية الخاصة. يتصل Hermes Agent بذلك كروبوت، عبر واجهة Mattermost REST API (الإصدار 4) بالإضافة إلى WebSocket للأحداث الفورية، حتى يتمكن مساعدك من الرد في الرسائل المباشرة وقنوات الفريق دون أن يغادر أي شيء شبكتك.

لا توجد مكتبة إضافية لتثبيتها: يستخدم المحوّل aiohttp، المضمّن أصلاً مع Hermes. وهو يعمل مع كل من Mattermost Team Edition (المجاني) وEnterprise Edition.

كيف يتصرف Hermes في Mattermost

أين تتحدث إليه	ما الذي يحدث
الرسائل المباشرة	يرد Hermes على كل رسالة — دون الحاجة إلى @mention. كل رسالة مباشرة لها جلستها الخاصة.
القنوات	يرد Hermes عندما تشير إليه بـ @mention. بدون إشارة، يتجاهل الرسالة.
المواضيع (Threads)	مع MATTERMOST_REPLY_MODE=thread، تتداخل الردود تحت رسالتك وتبقى معزولة عن القناة الأم.
القنوات المشتركة	سجل الجلسة معزول لكل مستخدم افتراضياً، فلا يتشارك شخصان في قناة واحدة نفس النص.

يُتحكم في السلوك الأخير عبر group_sessions_per_user في config.yaml:

group_sessions_per_user: true   # each person keeps their own context

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

---

الخطوة 1: تفعيل حسابات الروبوتات (جانب المسؤول)

يجب تشغيل حسابات الروبوتات على الخادم قبل أن تتمكن من إنشاء واحد:

1. سجّل الدخول إلى Mattermost كـ System Admin.
2. اذهب إلى System Console → Integrations → Bot Accounts.
3. اضبط Enable Bot Account Creation على true، ثم انقر Save.

ليس لديك صلاحية مسؤول؟ اطلب من مسؤول Mattermost تفعيل حسابات الروبوتات وإنشاء واحد لك.

الخطوة 2: إنشاء حساب الروبوت

1. انقر على قائمة ☰ (أعلى اليسار) → Integrations → Bot Accounts → Add Bot Account.
2. املأ التفاصيل: Username مثل hermes، وDisplay Name مثل Hermes Agent، وRole — يكفي Member.
3. انقر Create Bot Account، ثم انسخ الرمز فوراً — يُعرض مرة واحدة فقط. إذا فقدته، سيتعين عليك إعادة إنشائه من إعدادات حساب الروبوت.

⚠️ لا تشارك الرمز أبداً ولا ترفعه إلى Git. من يحمله يتحكم بالروبوت بالكامل.

تفضّل أن ينشر الوكيل باسم مستخدمك الخاص بدلاً من روبوت منفصل؟ أنشئ personal access token تحت Profile → Security → Personal Access Tokens → Create Token.

الخطوة 3: دعوة الروبوت إلى القنوات

لا يستجيب الروبوت إلا في القنوات التي ينتمي إليها:

1. افتح القناة → انقر على اسم القناة → Add Members.
2. ابحث عن اسم مستخدم الروبوت (مثلاً hermes) وأضفه.

بالنسبة للرسائل المباشرة، ما عليك سوى فتح رسالة مباشرة مع الروبوت — لا حاجة لدعوة.

الخطوة 4: العثور على معرّف مستخدم Mattermost الخاص بك

يستخدم Hermes User ID الخاص بك — وليس اسم المستخدم — لتحديد من يُسمح له بالتحدث إلى الروبوت:

1. انقر على avatar الخاص بك (الزاوية العلوية اليسرى) → Profile.
2. يعرض الحوار معرّف المستخدم الخاص بك: سلسلة أبجدية رقمية من 26 حرفاً مثل 3uo8dkh1p7g1mfk49ear5fzs5c. انقر عليها لنسخها.

يمكنك أيضاً قراءته من واجهة API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost-server/api/v4/users/me | jq .id

معرّف المستخدم الخاص بك ليس هو @username الذي تراه في الرسائل. لصق اسم المستخدم هو السبب الأكثر شيوعاً لبقاء الروبوت صامتاً.

الخطوة 5: إعداد Hermes

شغّل الإعداد الموجّه واختر Mattermost عند المطالبة — يسألك عن عنوان URL للخادم ورمز الروبوت ومعرّف المستخدم الخاص بك:

hermes gateway setup

أو قم بتوصيله يدوياً في ~/.hermes/.env:

# Required
MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c

# Multiple allowed users (comma-separated)
# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e

# Optional: reply in a thread instead of flat messages (default: off)
# MATTERMOST_REPLY_MODE=thread

# Optional: respond without an @mention (default: true = mention required)
# MATTERMOST_REQUIRE_MENTION=false

# Optional: channels where no @mention is needed (comma-separated channel IDs)
# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2

ثم شغّل البوابة:

hermes gateway

يتصل الروبوت بخادم Mattermost الخاص بك خلال ثوانٍ. أرسل له رسالة مباشرة، أو أشِر إليه بـ @mention في قناة تمت إضافته إليها، للاختبار.

الخطوة 6: مفاتيح السلوك الاختيارية

الإعداد	ما الذي يفعله
MATTERMOST_REPLY_MODE	off (افتراضي) ينشر رسائل مسطحة؛ thread يُدخل الردود تحت رسالتك ويحافظ على ترتيب القنوات المزدحمة.
MATTERMOST_REQUIRE_MENTION	true افتراضياً. اضبطه على false للرد على جميع رسائل القناة (الرسائل المباشرة تعمل دائماً).
MATTERMOST_FREE_RESPONSE_CHANNELS	معرّفات القنوات التي تتجاوز شرط الإشارة حتى عند اشتراط الإشارات.
MATTERMOST_HOME_CHANNEL	حيث تذهب الرسائل الاستباقية — مخرجات cron، والتذكيرات، والإشعارات. أو اكتب /sethome في قناة.
mattermost.allowed_channels	تقييد الروبوت بقائمة معرّفات قنوات؛ تُسقط الرسائل من أي مكان آخر. الرسائل المباشرة مستثناة.
mattermost.channel_prompts	حقن موجّه نظام مؤقت لكل قناة — يُطبَّق في كل دور، ولا يُحفظ أبداً في سجل النص.

عندما يُشار إلى الروبوت بـ @mentioned، تُزال الإشارة من الرسالة قبل المعالجة، لذا تصل @hermes summarize this thread كتعليمة نظيفة.

استكشاف الأخطاء وإصلاحها

العَرَض	السبب المحتمل	الحل
يتجاهلك الروبوت في القنوات	ليس في القناة، أو معرّف المستخدم الخاص بك ليس في MATTERMOST_ALLOWED_USERS	أضف الروبوت إلى القناة، وتحقق من معرّف المستخدم المكوّن من 26 حرفاً، وأعد تشغيل البوابة
لا يستطيع الروبوت النشر	رمز غير صالح، أو الروبوت يفتقر إلى الصلاحية في تلك القناة	تحقق من MATTERMOST_TOKEN، وتأكد من أن الحساب نشط وعضو في القناة
انقطاعات مستمرة	انقطاع WebSocket، أو إعادة تشغيل الخادم، أو مشكلات الوكيل/الجدار الناري	يعيد المحوّل الاتصال بتراجع أُسّي (2s → 60s)؛ بالنسبة لـ nginx، تأكد من تكوين رؤوس ترقية WebSocket
لا شيء يحدث على الإطلاق	البوابة لا تعمل، أو عنوان URL/الرمز خاطئ	تحقق من مخرجات hermes gateway، ومن أن MATTERMOST_URL يتضمن https:// بدون شرطة مائلة زائدة

اختبر الرمز مباشرة بـ:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/api/v4/users/me

تأمين الروبوت

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

---

ما التالي؟

بمجرد تشغيل البوابة، يتصرف Mattermost مثل أي قناة Hermes أخرى: أوامر الشرطة المائلة، ورفع الملفات، والملاحظات الصوتية، ومخرجات cron المُسلَّمة إلى قناتك الرئيسية — كل ذلك على بنية تحتية تتحكم بها. إذا كنت تفضّل استخدام الخيار المستضاف، يغطي تكامل Slack مسار Socket Mode؛ وإذا كنت تشغّل بوابات على عدة أجهزة، يربطها Hermes Relay.