Microsoft Teams — محادثة المؤسسات

فكّر في ربط Hermes Agent بخدمة Microsoft Teams وكأنك تمنح مساعدك الذكي شارة موظف — بمجرد انضمامه إلى الفريق، يمكنه حضور الاجتماعات، والإجابة على الأسئلة في القنوات، وتقديم المساعدة في الرسائل الخاصة، كل ذلك دون مغادرة التطبيق الذي يستخدمه زملاؤك يوميًا.

لماذا يختلف Teams عن Slack

إذا كنت قد استخدمت وضع Socket في Slack من قبل، فاعلم أن Teams يعمل بشكل مختلف قليلًا. فبدلًا من الحفاظ على اتصال مفتوح، يقوم Teams باستدعاء webhook العام لبوتك كلما أرسل شخص ما رسالة. هذا يعني أن نسختك من Hermes تحتاج إلى رابط HTTPS عام — وليس localhost. للاختبار، يمكنك استخدام نفق (tunnel)؛ أما للإنتاج، فستوجّهه إلى نطاق خادمك الفعلي.

كيف يتصرف البوت

إليك القاعدة البسيطة:

أين تتحدث معه	ماذا يحدث
محادثة خاصة (رسالة مباشرة)	يرد البوت على كل رسالة — دون حاجة إلى منشن
محادثة جماعية	يرد البوت فقط عندما تضع منشن له
قناة	يرد البوت فقط عندما تضع منشن له

يرسل Teams المنشن بصيغة <at>BotName</at>، لكن Hermes يزيلها تلقائيًا قبل المعالجة — فلا داعي للقلق بشأن ذلك.

الخطوة 1: تثبيت واجهة أوامر Teams

أولًا، ثبّت أداة سطر الأوامر من مايكروسوفت التي تؤتمت تسجيل البوت — دون الحاجة إلى بوابة Azure:

npm install -g @microsoft/teams.cli@preview
teams login

للتحقق من تسجيل الدخول والعثور على معرّف كائن AAD الخاص بك (ستحتاجه لاحقًا لتقييد الوصول)، شغّل:

teams status --verbose

الخطوة 2: كشف منفذ الـ Webhook

لا يمكن لـ Teams تسليم الرسائل إلى localhost. للتطوير المحلي، استخدم نفقًا للحصول على رابط HTTPS عام. المنفذ الافتراضي هو 3978 (غيّره عبر TEAMS_PORT إذا لزم الأمر).

إليك ثلاثة خيارات سهلة:

# devtunnel (مايكروسوفت)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https
devtunnel host hermes-bot

# ngrok
ngrok http 3978

# cloudflared
cloudflared tunnel --url http://localhost:3978

انسخ رابط https:// من المخرجات — ستحتاجه في الخطوة التالية. أبقِ النفق يعمل أثناء التطوير.

الخطوة 3: إنشاء البوت

الآن سجّل بوتك مع Teams:

teams app create \
  --name "Hermes" \
  --endpoint "https://<your-tunnel-url>/api/messages"

سيُخرج لك سطر الأوامر CLIENT_ID وCLIENT_SECRET وTENANT_ID، بالإضافة إلى رابط التثبيت. احفظ السر (client secret) فورًا — لن يظهر مرة أخرى.

الخطوة 4: ضبط متغيرات البيئة

أضف هذه الأسطر إلى ملف ~/.hermes/.env:

# مطلوب
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>

# تقييد الوصول لمستخدمين محددين (موصى به)
# استخدم معرّفات كائن AAD من `teams status --verbose`
TEAMS_ALLOWED_USERS=<your-aad-object-id>

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

إذا كنت تستخدم Docker، شغّل من المجلد الذي يحتوي على docker-compose.yml (عادةً مجلد hermes-agent المستنسخ، وليس ~):

cd /path/to/hermes-agent
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up

للتثبيت من المصدر، تأكد من تضمين إضافة Teams أولًا:

uv sync --extra teams
# أو، للتثبيت القابل للتحرير:
uv pip install -e ".[teams]"

الخلاصة

ربط Hermes بـ Teams هو رقصة من أربع خطوات: ثبّت سطر الأوامر، اكشف رابطًا عامًا، أنشئ البوت، واضبط متغيرات البيئة. بمجرد تشغيله، يصبح مساعدك الذكي عضوًا كاملًا في الفريق — يرد على الرسائل الخاصة تلقائيًا وينضم إلى المحادثات الجماعية عند استدعائه.

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

---