fast-mailer: كيف أدى إخراج النموذج من خطوة الإرسال إلى اختصار البريد إلى ثوانٍ

قصة بناء · أدوات للوكلاء

وكيل يحتاج من دقيقة إلى أربع دقائق ليرسل بريدًا واحدًا لا يفكر بجهد. إنه ينتظر: تحميل المتصفح، وظهور الزر، وحلول دوره التالي. يقول مؤلف fast-mailer، وهو مستودع صغير مفتوح المصدر نُشر في 24 سبتمبر 2026، إن صديقًا واجه المشكلة نفسها. لم يكن الحل نموذجًا أذكى، بل إخراج النموذج من الجزء الوحيد من العمل الذي لم يحتج إليه قط.

إجابة سريعة

لماذا هو سريع

يكتب الوكيل الرسالة ويسلّمها. سكربت عادي يبني الرسالة ويرسلها مباشرة إلى Gmail API. لا متصفح، ولا تشغيل لخادم أدوات إضافي، ولا استدعاء للنموذج بين «أرسِل» و«أُرسِلت».

المشكلة: وكيل يؤدي عمل سكربت

كثير من إعدادات الوكلاء ترسل البريد كما يفعل الإنسان: فتح Gmail في المتصفح، النقر على «إنشاء»، الكتابة، النقر على «إرسال». كل خطوة رحلة ذهاب وإياب عبر النموذج، الذي ينظر إلى الصفحة ويقرر ما يفعله بعدها. ملف المهارة في المستودع نفسه يضع طريق المتصفح في المرتبة الأخيرة ويصفه بـ«minutes - last resort only» (دقائق، الملاذ الأخير فقط). لم ينشر المؤلف كيف كان وكيل صديقه يرسل من قبل، لذا فالمتصفح هو المشتبه الأرجح، لا سببًا مؤكدًا.

ما يحتويه المستودع

الجزء	ما يفعله
send.py	مكتبة Python القياسية فقط. يبني رسالة MIME، ويجدد رمز OAuth في الذاكرة، ويرسل إلى نقطة الإرسال في Gmail، ويطبع JSON بمعرّف الرسالة والوقت المستغرق.
مجلد triggers/	ضع ملف .txt أو .json لكل رسالة، ثم شغّل python send.py watch --once. تنتقل الملفات المرسلة إلى triggers/sent/، والفاشلة تحصل على اللاحقة .failed.
cli/gmaild.mjs	خدمة Node 18+ اختيارية على 127.0.0.1 تُبقي اتصال TLS دافئًا مع Gmail وتجدد الرمز كل 5 دقائق.
cli/auth-server.js	تسجيل دخول لمرة واحدة عبر Google يخزن رمز التحديث في secrets/.
skills/fast-mailer/SKILL.md، AGENTS.md	تعليمات تخبر Claude Code وCursor وZCode والأدوات المشابهة بالأمر الذي يجب تشغيله، مع إضافة لـZCode.

من أين تأتي الثواني الـ14

قبل: الوكيل يقود واجهة البريد، دور نموذج لكل نقرة←بعد: الوكيل يكتب to وsubject وbody←أمر طرفية واحد←السكربت يرسل إلى Gmail API←JSON: message_id + ms

استدعاء الإرسال قصير. قلب send.py طلب HTTPS POST واحد لرسالة مرمّزة بـbase64 إلى gmail.googleapis.com/gmail/v1/users/me/messages/send، وهي النقطة التي توثقها Google لهذا الغرض. يقدّرها README بـ0.6-1 ثانية من البداية الباردة ونحو 0.5 ثانية مع الخدمة الدائمة.

فأين تذهب الثواني الـ13~ الأخرى؟ هذه قراءتي لا قياسًا: على الوكيل أن يقرأ الطلب ويكتب الأمر وينتظر النتيجة ويرد. هذه دورة نموذج واحدة بدل عشرات. بل إن ملف المهارة يطلب من الوكيل أن يجيب بـ«message_id + ms فقط. بلا سرد»، وهذا يختصر الخطوة الأخيرة أيضًا.

التسريع ليس من إرسال أسرع، بل من أدوار نموذج أقل بين الطلب والإنجاز.

ما الذي فحصته في الشيفرة

شغّلت send.py دون اتصال في بيئة معزولة ببيانات اعتماد وهمية واستُبدل استدعاء الشبكة، فلم يُرسل شيء. استغرق بناء الرسالة نحو 1.4 مللي ثانية. صمدت ادعاءات الأمان في README في المسارات التي اختبرتها:

• مسموح بمضيفين اثنين فقط: oauth2.googleapis.com وgmail.googleapis.com. أي عنوان آخر يُرفض.
• يجب أن تطابق أسماء ملفات triggers نمطًا صارمًا. رُفضت ../x.txt والأسماء التي فيها مسافات والملفات المخفية.
• قبل كل طلب يُحلّ اسم المضيف ويُحظر إن أشار إلى عنوان خاص أو محلي. وإعادات التوجيه محدودة باثنتين.
• لا يكتب مُرسِل Python أبدًا في ملف الرمز. أما الخدمة فتحفظ الرموز المجددة بصلاحية الملف 0600.

ثغرة واحدة: حقلا الموضوع والمستلم لا يُفحصان بحثًا عن فواصل الأسطر. في اختباري دون اتصال، أنتج موضوع Hello + سطر جديد + Bcc: attacker@example.net ترويسة Bcc إضافية حقيقية. إن كان الوكيل يرسل فقط ما كتبته أنت، فلا أهمية لذلك. أما إن كان يستطيع وضع نص من صفحة ويب أو من بريد وارد في سطر الموضوع، فالأمر مهم. إصلاح قصير:

# add at the top of send_email() in send.py
for field in [to, subject, sender or ""] + list(cc or []):
    if "\r" in field or "\n" in field:
        raise ValueError("line break in a header field")

جرّب: قِس مسارك أنت

لتعرف أين يذهب وقت وكيلك، قِس السكربت وحده وقارنه بدور الوكيل كاملًا. يعيد السكربت حقل ms الخاص به؛ وهذا الغلاف يضيف الوقت الفعلي حوله:

start=$(date +%s.%N)
python send.py you@example.com "timing test" "hello" | tee /tmp/send.json
end=$(date +%s.%N)
echo "script wall time: $(echo "$end - $start" | bc) s"
# the gap between this and the agent's full reply time is model time

تحليل (Jack Gross)

الدرس العام: أبعِد النموذج عن المسار الحرج

النمط بسيط ويستحق النسخ إلى ما هو أبعد من البريد. حين يكون للمهمة شكل ثابت (إلى، الموضوع، النص) دع النموذج يملأ الحقول ودع الشيفرة العادية تتولى الباقي. كل خطوة يضطر النموذج إلى مراقبتها واعتمادها تكلف ثواني وتزيد فرصة الخطأ. الانتقال من 1-4 دقائق إلى 14 ثانية يعني خفضًا يقارب 4x إلى 17x، وجلّه ناتج عن إزالة دورات النموذج لا عن شبكة أسرع.

مجلد triggers هو الفكرة الأكثر إثارة. إنه يفصل «تقرير ما يُرسل» عن «إرساله». يستطيع وكيل أو مهمة cron أو إنسان وضع الرسائل في طابور كملفات، ومسح واحد يرسلها كلها. كما يصبح صندوق الصادر سهل الفحص قبل أن يخرج أي شيء.

حدود يجب إبقاؤها في الحسبان

• جديد تمامًا. نُشر يوم كتابة المقال، الإصدار 1.0.0، بلا اختبارات في المستودع، ولا مستخدمين خارجيين بعد. رقم الـ14 ثانية تقرير شخص واحد عن إعداد واحد.
• صلاحيات واسعة. يطلب تسجيل الدخول gmail.modify وgmail.readonly. وتذكر وثائق Google أن النطاق الأضيق gmail.send يكفي للإرسال. الرمز المسروق من هذا الإعداد يسمح بقراءة بريدك وتعديله، لا بالإرسال فقط.
• فحص الترويسات. أضف فحص فواصل الأسطر أعلاه قبل تمرير نص غير موثوق.
• حدود Gmail لا تزال قائمة. تحدد Google الإرسال اليومي (مثلًا 2,000 رسالة لكل مستخدم في Google Workspace و500 للحسابات التجريبية) و500 مستلم لكل رسالة عبر API. لا يحتوي السكربت على تحديد للمعدل ولا إعادة محاولة سوى تجديد واحد للرمز، لذا ستصطدم عمليات الإرسال الجماعي بهذه الحدود.
• السرعة سلاح ذو حدين. بلا خطوة المتصفح لا توجد شاشة يلقي فيها إنسان نظرة على المسودة. إن كان على وكيلك أن يسأل قبل الإرسال، فيجب أن يعيش هذا الفحص الآن في تعليماته.
• عناء الإعداد. تحتاج مشروع Google Cloud وعميل OAuth خاصين بك، ومساعد تسجيل الدخول يستخدم المنفذ 80 افتراضيًا.
• Gmail فقط. لا Outlook ولا SMTP عام، ولا مرفقات في الشيفرة الحالية.

الحكم

fast-mailer حل صغير مقروء لمشكلة حقيقية شائعة، ونموذج الأمان فيه أدق من معظم أدوات اليوم الأول. اعتبره نقطة انطلاق جيدة: ضيّق النطاق إلى gmail.send وأضف فحص الترويسات وأبقِ موافقة بشرية حيث تهم. والدرس يتجاوز البريد بكثير: عدد أقل من دورات النموذج يتفوق على نموذج أسرع.

الأسئلة الشائعة

هل يستخدم fast-mailer نموذج ذكاء اصطناعي لإرسال البريد؟

لا. يكتب الوكيل المحتوى، ثم يرسله سكربت عبر Gmail API دون استدعاء للنموذج بينهما.

هل الـ14 ثانية هي وقت إرسال رسالة واحدة؟

إنها وقت دور الوكيل كاملًا بحسب المؤلف. أما استدعاء الإرسال نفسه فيستغرق نحو 0.6-1 ثانية وفق README.

مع أي وكلاء يعمل؟

مع أي وكيل يستطيع تشغيل أوامر الطرفية. يتضمن المستودع تعليمات لـClaude Code وCursor وZCode.

المصادر: fast-mailer على GitHub (الشيفرة وREADME وSKILL.md وسجل الإيداعات، قُرئت في 24 سبتمبر 2026) · Gmail API: users.messages.send · حدود إرسال Gmail في Google Workspace. مدة 1-4 دقائق و14 ثانية من رواية مؤلف المستودع.