دليل Agent Autoloop: خلّي Claude Code وCodex ووكلاء السطر الأوامر يخدمو فالخلفية ويستقبلو المهام ويتبعوها بشكل مستمر

شنو هو Agent Autoloop؟

Agents ديال سطر الأوامر بحال Claude Code وCodex كيتطلبو غالباً تفاعل مستمر من المستخدم فالترمينال: كتدخل المهمة، كتسنى التنفيذ، كتجاوب على الأسئلة، ومن بعد كتخليه يكمل. إلا تسدّ الترمينال ولا بعدتي شوية، العملية كتقدر توقف.

Agent Autoloop هو وسيط خفيف للأتمتة موجه لـ Agents ديال سطر الأوامر. كيدير جدولة المهام فـ نواة ما كتحتاج حتى اعتماد على runtime، وكيقسم مصادر الأحداث، والـ Agent، وقنوات الإشعارات، وسلاسل التسليم إلى إضافات قابلة للتبديل. يقدر يخدم محلياً على حاسوب Mac ولا Linux، بلا ما تحتاج تشري سيرفر سحابي ولا تحل بورت للإنترنت العمومي.

طريقة الخدمة الأساسية هي: منين كيدخل الحدث، كيتعطى للـ Agent حسب القواعد؛ الـ Agent كيكمل جولة وكيخرج؛ غير ملي كيكون شي إجراء غير مؤكد بحال مسح البيانات، إعادة تشغيل خدمة، صرف الفلوس ولا إرسال رسالة للبرا، النظام كيسولك عبر بطاقة إشعار باش تقرر. منين كتجاوب، كيكمل الجلسة الأصلية وكيتم المهمة الباقية.

المزايا الأساسية

• خدمة محلية: تقدر تنصبو على حاسوب واحد فيه macOS ولا Linux، بلا backend سحابي مستقل.
• ربط الـ Agent بسهولة: أي أداة فـ سطر الأوامر كتقدر تستقبل prompt وتخرج جواب نهائي، تقدر تربطها عبر إضافة الأوامر العامة.
• ما كاين حتى استهلاك ديال Agent أثناء الانتظار: ملي كيتسنى جواب الإنسان، process ديال الـ Agent كيخرج مباشرة وما كيبقاش كيستهلك Token؛ حالة الانتظار كتبقى محفوظة فقاعدة البيانات.
• مدفوع بالقواعد: عبر rules.json كتحدد شنو الحدث اللي يمشي لأي Agent وفأي مجلد يتنفذ، بلا ما تكتب glue code.
• إشعارات حسب الحاجة: كيدعم إشعارات سطح المكتب، Feishu، وقوالب Webhook ديال DingTalk وWeCom وSlack وDiscord.
• استكمال الجلسة: منين كيجاوب الإنسان، يقدر يكمل من نفس المحادثة بلا ما يعاود المهمة من الأول.
• قابل للتتبع: الحالة كتتحسب من log كيزيد غير بالإضافة، وتقدر تشوف سبب تشغيل كل جولة والنتيجة ديالها.
• إضافات قابلة للتوسيع: مصادر الأحداث، والـ Agents، وقنوات الإشعارات، وسلاسل تسليم CI/CD كاملين قابلين للتوسيع ولا التبديل.

التحضير قبل التثبيت

قبل ما تبدا، تأكد باللي النظام ديالك هو macOS ولا Linux، وأن الأدوات التالية منصبة:

• Node 24
• Git
• curl
• على الأقل Agent واحد ديال سطر الأوامر منصب ومسجل الدخول، بحال Claude Code ولا Codex

التثبيت والتجربة المحلية ما كيحتاجوش حساب GitHub. Agent Autoloop كينادي مباشرة على أدوات سطر الأوامر الموجودة فالحاسوب ديالك، وما كيقراش ولا كينقل بيانات اعتماد هاد الأدوات.

الخطوة الأولى: تثبيت Agent Autoloop

نفذ سكريبت التثبيت الرسمي فالترمينال:

curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh

إلا بغيتي تراجع تفاصيل التثبيت قبل، قرا تعليمات التثبيت ديال المشروع. حتى README كيقترح تعطي هاد التعليمات للـ Agent المحلي باش يعاونك فالتثبيت.

الخطوة الثانية: دير أول تجربة تفاعلية

من بعد ما يكمل التثبيت، نفذ:

agent-autoloop try

هاد الأمر كيستعمل الـ Agent المحلي باش يوريك العملية كاملة: إرسال المهمة، سؤال الـ Agent، الخروج والانتظار، استقبال القرار ديالك، ومن بعد استكمال الجلسة وإنهاء المهمة.

فأثناء التجربة، غادي تشوف نتيجة قريبة من هادي:

الحدث تصيفط، والـ Agent بدا الخدمة……

الـ Agent سالى هاد الجولة وطرح عليك سؤال. دابا ما كيشغل حتى process وما كيستهلك حتى Token.

【كنستناو القرار ديالك】#1 تجربة: اختار لون
هاد غير تجربة، اختار اللي بغيتي.
  1. الأزرق
  2. الأخضر

فالترمينال التفاعلي، تقدر تدخل رقم الاختيار مباشرة وتضغط Enter. فالترمينال غير التفاعلي، تقدر تجاوب بشكل صريح على البطاقة رقم 1 وتختار الاختيار الثاني:

agent-autoloop answer 1 2

ومن بعد شوف الحالة العامة:

agent-autoloop status

إلا دازت العملية مزيان، غادي تشوف الـ Agent كيكمل الجلسة الأصلية وكيأكد نتيجة الاختيار. أمر الحالة حتى هو كيبين عدد جولات التشغيل ديال اليوم وآخر 7 أيام، وعدد الـ Token والإحصائيات ديال المصاريف.

الخطوة الثالثة: فهم كيفاش كتخدم المهام أوتوماتيكياً

1. دخول الحدث: المهام المبرمجة، ولا GitHub Issue، ولا أخطاء نظام العمل كيتحولو لأحداث موحدة.
2. مطابقة القاعدة: النواة كتقرر حسب القواعد المحلية شنو هو الـ Agent المستعمل وفأي مجلد خدمة غادي يتنفذ.
3. تنفيذ جولة: الـ Agent كيعالج المهمة، وكيشرح النتيجة فآخر جواب، ومن بعد كيخرج الـ process.
4. طلب القرار عند الضرورة: إلا كان شي إجراء كيحتاج حكم الإنسان، الوسيط كيرسل بطاقة إشعار وكيحفظ حالة الانتظار.
5. الاستكمال من بعد الجواب: منين كتسيفط الاختيار، النظام كيرجع المحادثة الأصلية وكيكمل المهمة.

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

الخطوة الرابعة: كتب أول قاعدة للأتمتة

الإعدادات اليومية كاينة فـ:

~/.agent-autoloop/rules.json

كل قاعدة خاصها على الأقل توضّح فاش كتطلق، ولمن كتتعطى، وفأي مجلد كتخدم. وto خاصو يشير لاسم موجود من قبل فـ agents.

مثال: إنشاء تقرير الصباح كل نهار مع 9

{
  "name": "تقرير الصباح",
  "when": { "cron": "0 9 * * *" },
  "to": "codex",
  "cwd": "~/notes",
  "prompt": "جمع ملاحظات والتزامات البارح، وكتب تقرير الصباح ديال اليوم."
}

هاد القاعدة كتعطي المهمة كل نهار مع 9 للـ Agent اللي سميتو codex، وكتخليه يرتب الملاحظات والتزامات Git فالمجلد ~/notes.

مثال: معالجة GitHub Issue جديدة

بنية قواعد الأحداث الخارجية مشابهة، ولكن خاصك الأول تسجل مصدر الحدث المناسب فـ sources. القاعدة التالية كتراقب حدث issues.opened ديال GitHub:

{
  "name": "معالجة issue",
  "when": {
    "source": "github",
    "types": ["issues.opened"]
  },
  "to": "codex",
  "cwd": "~/code/app",
  "skill": "handle-issue",
  "parallel": 3
}

skill كيحدد الـ Skill اللازم لمعالجة المهمة، وparallel كيخلي عدد العمليات المتوازية هو 3. تسجيل مصدر الحدث خاصو يتدار حسب دليل إعدادات المشروع.

منين كتسجل القاعدة، كتولي خدامة أوتوماتيكياً فبضع ثواني. من الأحسن تدير التحقق مباشرة:

agent-autoloop check

إلا كان شي خطأ فالقاعدة الجديدة، النظام غادي يبقى خدام بالقواعد القديمة، وغادي يبين المشكل بالتفصيل عبر بطاقة، باش ما يوقفش الأتمتة الحالية بسبب إعداد خاطئ.

الخطوة الخامسة: خَلّي الـ Agent يطلب قرار بشري

الاتفاق الأساسي ديال Agent Autoloop مع الـ Agents هو: شرح النتيجة فآخر جواب. إلا كانت المهمة سالات، خرج الخلاصة بشكل عادي؛ وإلا كان خاص اختيار بشري، زيد فآخر الجواب code block ديال agent-autoloop.

الطلبية تراجعات كاملة، والستوك كافي.

```agent-autoloop
{
  "ask": [{
    "title": "كيفاش نصيفطوها؟",
    "text": "الطريقتين بجوج نقدروا نصيفطوهم اليوم.",
    "options": ["التوصيل", "الاستلام الشخصي"],
    "key": "shipping"
  }]
}
```

هنا ask كينشئ بطاقة قرار فيها جوج اختيارات. بالإضافة للسؤال، الـ callback كيدعم حتى الإجراءات التالية:

• notice: إرسال إشعار.
• resolve: تسد بطاقة تحلات.
• later: برمجة مراجعة فواحد الوقت فالمستقبل.
• events: إطلاق أحداث جديدة.

إلا كان JSON اللي خرج الـ Agent فيه خطأ، الوسيط غادي يطلب منو غير يعاود يكتب آخر جزء ديال الـ callback فالجلسة الأصلية، وما غاديش يعاود ينفذ العمليات التجارية اللي سالات. إلا فشلت إعادة الكتابة حتى هي، النظام غادي يحتافظ بالخلاصة الأصلية وينبهك باللي الـ callback ما تطبقش.

استعمال قوالب جاهزة للسيناريوهات

المشروع كيوفر عدة قوالب فيها القواعد، وSkills ديال المهام، وتعليمات التفعيل، وتقدر تستعملها كنقطة انطلاق للإعداد الفعلي:

• تقرير الصباح اليومي: ترتيب الملاحظات المحلية والتزامات Git، وكتابتها فملف مسمي حسب التاريخ.
• متابعة GitHub Issue: فحص الـ Issues الجديدة بانتظام، وتعديل الكود محلياً وتنبيهك باش تراجع؛ افتراضياً ما كيدير لا commit لا push وما كيردش على الـ Issue.
• التحقيق فتنبيهات الإنتاج: استقبال الأخطاء وتحليل أسبابها بمقارنتها مع الكود، وطلب الموافقة قبل عمليات إعادة التشغيل.
• معالجة ملاحظات المستخدمين: فحص حالة الملاحظة، إصلاح المشكل، التحقق من التسليم وتحضير الجواب، وطرح السؤال عبر Feishu ملي كيكون القرار ضروري.
• مراقبة المواقع: فحص الحالة والمحتوى المهم بانتظام، وتفادي الإشعارات المتكررة بسبب نفس المشكل، وتحديث البطاقة الأصلية من بعد ما ترجع الخدمة.
• التقرير الأسبوعي وملخص الأعمال عبر Feishu: قراءة التقارير والجداول المحددة حسب الصلاحيات، حفظ الملخص الكامل محلياً، وإرسال غير خلاصة قصيرة إلى Feishu.
• التسليم الأوتوماتيكي ديال PR: البداية من مراجعة الكود، وانتظار CI، ودمج PR، وانتظار النشر، ومن بعد التحقق من النسخة الموجودة فالإنترنت.

باش تفعل قالب، خاصك تحط Skill ديال المهمة فمجلد skills ديال الـ Agent المستعمل، وتدمج القواعد النموذجية فـ ~/.agent-autoloop/rules.json، وتبدل المسارات واسم الحاسوب، ومن بعد تنفذ agent-autoloop check.

README كيوضح خصوصاً أن البيانات النموذجية ديال معالجة الملاحظات، ومراقبة المواقع، وملخص Feishu خيالية؛ السكريبتات والـ callbacks المرتبطة بها تراجعات غير عبر HTTP محلي وCLI تجريبي ديال Feishu، ومازال ما تدارتش تجربة كاملة على حسابات حقيقية.

ربط Agents وقنوات إشعار مختلفة

إضافات Agents المدمجة

المشروع فيه إضافات مدمجة ديال Claude Code وCodex وACP والأوامر العامة. Claude Code وCodex ومحول Codex ACP الرسمي دازو من اختبارات متعددة ديال الأسئلة والأجوبة واستكمال الجلسات بين العمليات.

ربط Agents آخرين عبر الأوامر العامة

بالنسبة لAgents آخرين ديال سطر الأوامر، تقدر تحدد use: "command" وتعطي مصفوفة ديال الأوامر. الرمز النائب {prompt} كيتعطى كوسيط مستقل، وما كيتنفذش على أنه كود Shell.

README كيسرد، حسب الوثائق الرسمية ديال الأدوات، أمثلة أوامر ديال DeepSeek Harness وpi وOpenClaw وHermes وCursor وWorkBuddy／CodeBuddy، ولكن كيوضح فالنفس الوقت أن هاد الأوامر ما تجربوش واحد بواحد. لذلك، قبل الاستعمال الرسمي، خاصك تتحقق من المعاملات، وشكل المخرجات، وسلوك الجلسة فمجلد معزول.

تثبيت إضافات خارجية

تقدر تثبت الإضافات الخارجية عبر عنوان Git:

agent-autoloop add <عنوان git>

إلا بغيتي تطور إضافة بنفسك، تقدر تبدا من قوالب الإضافات الدنيا ديال الـ Agent والقناة والحدث اللي كيوفرها المشروع، وترجع لـ دليل تطوير الإضافات.

اختيار قناة الإشعار

إشعارات سطح المكتب مفعّلة افتراضياً. تم اختبار الإرسال، واستدعاءات الأزرار، وتحديث البطاقات في Feishu عملياً. أما DingTalk وWeCom وSlack وDiscord فتستعمل قوالب Webhook، وقد تم التحقق منها حالياً غير عبر خدمة محاكاة محلية.

هاد القنوات النصية كتقدّم القرارات عبر روابط فالجواب، وداكشي علاش خاصك تهيّأ hub.publicUrl بعنوان يقدر الهاتف ولا الحاسوب يوصل ليه. واش خاص الولوج من الإنترنت العمومي كيتعلّق بالقناة اللي اخترتي وببيئة الشبكة، ماشي بالتشغيل المحلي الأساسي بحد ذاتو.

تقنيات متقدمة وتصميم الموثوقية

علاش تنفّذات دورة معيّنة من المهام؟

استعمل الأمر why باش تشوف أحداث التشغيل، ونسخة القواعد، والمكلّف، والنتيجة النهائية ديال دورة محددة:

agent-autoloop why 1

هاد الشي مفيد بزاف فالبحث على القواعد الخاطئة، ولا الأحداث المكررة، ولا توزيع المهام بشكل غير متوقع.

فهم الآليات الأربع ديال النواة

• التعليق بلا استهلاك: ملي كتكون كتسنى جواب بشري، كتخرج عملية Agent وكتبقى الحالة مخزنة فقاعدة البيانات؛ ومن بعد الجواب كتعاود نفس الجلسة تكمل.
• مصدر الأحداث: جميع الحالات كتتحسب من سجل كيتزاد فيه غير، وكيتم تسجيل السجل والفهرس فالقرص داخل نفس المعاملة؛ ومن بعد تغيّر الصيغة يمكن إعادة بناء الحالة من السجل.
• فصل التعليمات على البيانات: المحتوى الخارجي بحال عنوان الـIssue والنص ديالو كيتحفظ كمعطيات، وما كيتلصقش مباشرة فالتلقين. الـAgent، ومجلد العمل، والصلاحيات كيحددهم غير قانون الجهاز المحلي؛ والحقول cwd وagent وaccess فالأحداث كيرفضوها.
• قاطع تتابع الاستدعاءات: الأحداث الجديدة اللي كيطلّقها الـAgent كتزيد طبقة، والأسئلة البشرية والمراجعة الدورية ما كيرجعوش الطبقات للصفر. من بعد أكثر من 8 طبقات، كيتسجل الحدث بلا ما تتوزع مهمة جديدة، وكتتبعت بطاقة للمستخدم.

تشغيل المحاكاة واختبارات الأداء

دخل لمجلد البرنامج:

cd ~/.agent-autoloop/app

ومن بعد تقدر تشغّل أوامر التحقق اللي كيوفرها README:

node sim/random.ts 24301 200000
node sim/crash.ts 1000 12648430
npm run benchmark

الأمر الأول كيحاكي انقطاع الشبكة، وضياع الحزم، والانهيار، وإعادة الإرسال؛ والأمر الثاني كيتحقق، عبر إيقاف العملية بالقوة بشكل متكرر، واش السجلات المؤكدة ما كتضيعش؛ والأمر الثالث كيشغّل معيار الأداء. الحدود المذكورة فـREADME مبنية على Apple M5 Pro وذاكرة 24 GB وNode 24.21.0، وقد تبان النتيجة غير مستوفية للحدود فالأجهزة الأخرى بسبب اختلاف العتاد.

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

حدود استعمال خط أنابيب التسليم

Agent Autoloop كيوفر إضافة delivery. منين كتزيد الوسم deliver لـGitHub PR، تقدر تتابعها باستمرار بهاد الترتيب: «مراجعة الكود، انتظار CI، دمج PR، انتظار النشر، والتأكد من النسخة اللي خدامة فالإنترنت».

إعدادات المراجعة والتسليم كتتقرا غير من الفرع main، وما كيتعملش checkout ولا تشغيل للكود اللي فـPR فالحاسوب اللي قبل المهمة. الاصطفاف، والتوازي، وإعادة المحاولة كيعتمدو نفس آليات النواة. قبل التفعيل الرسمي، خاصك تقرا توضيح حدود الأمان مع مراعاة صلاحيات المستودع ومسار النشر.

نصائح الاستهلاك والامتثال

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

Agent Autoloop مشروع مستقل ومفتوح المصدر، وما عندوش علاقة تبعية ولا تزكية من مزودي النماذج بحال Anthropic وOpenAI.

الخلاصة

النقطة الأساسية فـAgent Autoloop ماشي هي أن الـAgent يبقى خدام ديما، ولكن أن المهام تقدر توقف، وتتسنى، وتكمل بشكل موثوق. تقدر تبدا باستعمال agent-autoloop try باش تتحقق من حلقة التفاعل كاملة، ومن بعد تكتب القواعد انطلاقاً من النشرة اليومية الصباحية ولا قالب GitHub Issue. منين تتأكد أن المسار المحلي مستقر، دخل بالتدريج Feishu وWebhook والأحداث الخارجية وخط أنابيب تسليم PR.

فالإعدادات المتقدمة، راجع دليل القواعد وإعدادات التسليم، وبروتوكول الاتصال الكامل، ووثائق تطوير الإضافات.