الدرس 26: المعالجة الدفعية

هذا جزء من سلسلة دروس هيرميس الرسمية. عرض كل الدروس

تخيّل هذا كقائمة مهام صباحية تشغّلها قبل بدء العمل — لا تريد أن تتذكّر كل مهمة بنفسك، لذا تكتبها مرة واحدة، ويساعدك مساعدك في التحقق منها تلقائيًا كل يوم. هذا بالضبط ما يتيح لك هيرميس فعله عبر خطافات البوابة وملف بسيط اسمه BOOT.md.

في هذا الدرس، ستتعلم كيف تجعل هيرميس ينفّذ “دفعة” مخصصة من المهام في كل مرة تبدأ فيها بوابتك — مثل فحص السجلات، أو نشر تذكيرات، أو حتى تشغيل وكيل مصغّر يفكّر ويُرسل تقريرًا.

---

الخطوة 1: إنشاء مجلد الخطاف

أولًا، أنشئ مجلدًا داخل مجلد الخطافات لديك. كل خطاف يعيش في مجلد فرعي خاص به مع ملفين: HOOK.yaml (الإعدادات) وhandler.py (المنطق).

mkdir -p ~/.hermes/hooks/boot-md
cd ~/.hermes/hooks/boot-md

الآن أنشئ HOOK.yaml:

name: "boot-md"
event: "gateway_startup"

هذا كل شيء — الحدث يخبر هيرميس بتشغيل هذا الخطاف عند إقلاع البوابة.

---

الخطوة 2: كتابة المعالج

الآن أنشئ handler.py. هنا يحدث السحر. يقرأ المعالج ملفًا اسمه BOOT.md من مجلدك الرئيسي، ثم يبدأ خيطًا في الخلفية يشغّل وكيلًا بهذه التعليمات.

إليك الفكرة الأساسية (مبسّطة):

import os, threading
from pathlib import Path
from hermes.agent import AIAgent

def run_boot_md():
    content = Path.home().joinpath(".hermes", "BOOT.md").read_text()
    print(f"Running BOOT.md ({len(content)} chars)")

    agent = AIAgent(
        instructions=content,
        model=_resolve_gateway_model(),          # uses your gateway’s model
        **_resolve_runtime_agent_kwargs()       # uses your provider credentials
    )
    result = agent.run()
    print(f"boot-md completed: {result.summary()}")

def handler(event):
    thread = threading.Thread(target=run_boot_md, daemon=True)
    thread.start()

السطران الأساسيان:

• _resolve_gateway_model() يقرأ النموذج المُعدّ حاليًا في البوابة.
• _resolve_runtime_agent_kwargs() يحلّ بيانات اعتماد المزود بنفس الطريقة التي تعمل بها دورة بوابة عادية — بما في ذلك مفاتيح API، وعناوين URL الأساسية، ورموز OAuth، ومجموعات بيانات الاعتماد.

بدون هذين السطرين، سيعود AIAgent() المجرّد إلى الإعدادات الافتراضية المدمجة وسيفشل بمصادقة 401 مع أي نقطة نهاية غير افتراضية.

---

الخطوة 3: اختباره

أعد تشغيل البوابة:

hermes gateway restart

راقب السجلات:

hermes logs --follow --level INFO | grep boot-md

يجب أن ترى Running BOOT.md (N chars) متبوعًا إما بـ boot-md completed: ... (ملخص ما فعله الوكيل) أو boot-md completed (nothing to report) عندما يردّ الوكيل برمز صمت تام مثل [SILENT].

احذف ~/.hermes/BOOT.md لتعطيل القائمة — يبقى الخطاف محمّلًا لكنه يتخطى بصمت عندما لا يكون الملف موجودًا.

---

توسيع النمط

• قوائم مهام مدركة للجدول: اعتمد على datetime.now().weekday() داخل تعليمات BOOT.md (“إذا كان اليوم الاثنين، تحقق أيضًا من سجل النشر الأسبوعي”). التعليمات نص حر، لذا أي شيء يمكن للوكيل التفكير فيه هو خيار متاح.
• قوائم متعددة: وجّه الخطاف إلى ملف مختلف (STARTUP.md، MORNING.md، إلخ) وسجّل مجلدات خطاف منفصلة لكل منها.
• نسخة بدون وكيل: إذا لم تكن بحاجة إلى دورة وكيل كاملة، فتخطَّ AIAgent تمامًا واجعل المعالج يرسل إشعارًا ثابتًا مباشرة عبر httpx. أرخص وأسرع ولا يعتمد على أي مزود.

---

لماذا هذا ليس مدمجًا؟

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

---

كيف يعمل

1. عند إقلاع البوابة، يفحص HookRegistry.discover_and_load() مجلد ~/.hermes/hooks/
2. كل مجلد فرعي يحتوي على HOOK.yaml + handler.py يُحمَّل ديناميكيًا
3. تُسجَّل المعالجات للأحداث المعلنة
4. عند كل نقطة دورة حياة، يُطلق hooks.emit() جميع المعالجات المطابقة
5. أي خطأ في أي معالج يُلتقط ويُسجَّل — الخطاف المعطوب لا يُسقط الوكيل أبدًا

:::info خطافات البوابة تعمل فقط في البوابة (تيليجرام، ديسكورد، سلاك، واتساب، تيمز). سطر الأوامر لا يحمّل خطافات البوابة. للخطافات التي تعمل في كل مكان، استخدم خطافات الإضافات. :::

---

الخلاصة

أنت الآن تعرف كيف تحوّل ملفًا نصيًا بسيطًا إلى قائمة مهام إقلاع قوية تعمل تلقائيًا. سواء كانت دورة وكيل كاملة أو استدعاء HTTP سريع، النمط واحد: اكتب خطافًا، وجّهه إلى ملف، ودع هيرميس يتكفل بالباقي.

التالي: الدرس 27 — الوضع الصوتي: التحدث إلى هيرميس دون استخدام اليدين.

---