تطبيق عملي لـ IvyClaw: بناء نظام تطوير متعدد الوكلاء قادر على التخطيط والبرمجة والاختبار والمراجعة

١. آش هو IvyClaw

IvyClaw هو نظام هندسي ديال AI Agent متعدد الوكلاء، موجه لمهام تطوير البرمجيات، ومبني على DeepAgents وLangGraph. ماشي غير كينفذ استدعاء واحد للنموذج، ولكن كينظم فهم المتطلبات، وتخطيط المهام، والبحث على المعلومات، وتنفيذ الكود، والاختبارات الآلية، ومراجعة الكود، وإرجاع النتائج فـ Agent Workflow كيخدم باستمرار.

المشروع كيستعمل تقنيات بحال Python وFastAPI وPostgreSQL وRedis وARQ وDocker وPrometheus وGrafana، وكيصلح للتعلم والتطبيق العملي ديال الهندسة ديال AI Agent.

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

رابط المشروع: مستودع IvyClaw على GitHub.

٢. سير العمل الأساسي وبنية النظام

IvyClaw كيفرق طلب التطوير الواحد على مجموعة ديال Agents، وكل واحد عندو مسؤوليات واضحة. السير النموذجي هو:

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（حسب الحاجة）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner مسؤول على فهم المتطلبات، وتخطيط المهام، واتخاذ القرارات؛ وResearcher كيقلب على المعلومات وكينظمها ملي كتكون الحاجة؛ وCoder مسؤول على تنفيذ الكود وتعديلو؛ وTester كينفذ الاختبارات وكيحدد المشاكل؛ وReviewer كيراجع الكود فالنتيجة النهائية.

الطلب كيدخل غالباً للـ API Gateway، ومن بعد كيتحول عبر محولات القنوات وDispatcher لـ Agent Runtime. PostgreSQL كيتكلف بتخزين حالة الجلسات وبيانات LangGraph Checkpointer وStore، وRedis كيتستعمل للكاش، وتحديد معدل الطلبات، وحالة التشغيل، وطابور المهام. أما المهام اللي كتحتاج وقت طويل فكيتم تنفيذها بشكل غير متزامن بواسطة ARQ Worker.

٣. تحضير بيئة التشغيل

قبل ما تبدا، وجد بيئة تشغيل مشروع Python، وخدمات PostgreSQL وRedis خدامة، وواجهة API ديال النموذج مطابقة لمتطلبات إعدادات المشروع. المشروع كيستعمل uv لتدبير اعتمادات Python.

أولاً، كلون المستودع ودخل لمجلد المشروع:

git clone https://github.com/ivyfan-toowell/IvyClaw.git
cd IvyClaw

من بعد، أنشئ إعدادات البيئة المحلية انطلاقاً من ملف المثال. فـ Linux أو macOS أو أي بيئة شبيهة بـ Unix، تقدر تنفذ:

cp .env.example .env

فـ Windows PowerShell تقدر تنفذ:

Copy-Item .env.example .env

فـ .env عمر الإعدادات الضرورية حسب البيئة المحلية، مثلاً:

IVC_API_KEY=your_api_key_here
IVC_POSTGRES_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_DATABASE_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_REDIS_URL=redis://localhost:6379/0

ماترفعش ملف .env الحقيقي لـ GitHub. مفاتيح LLM API وLangSmith API وFeishu App Secret وكلمات سر قاعدة البيانات ومفاتيح API الحقيقية ديال البوابة خاصها تبقى محلياً أو فبيئة نشر آمنة.

٤. تثبيت الاعتمادات وتشغيل الخدمات

تثبيت اعتمادات Python

من جذر المشروع نفذ:

uv sync

هاد الأمر كيساوي بيئة Python والاعتمادات مع إعدادات المشروع.

تشغيل FastAPI API

استعمل الأمر التالي لتشغيل خادم التطوير:

uv run uvicorn api.app:app --reload --port 8000

من بعد التشغيل، حل http://localhost:8000/docs باش تشوف وثائق Swagger ديال API اللي كينشئها FastAPI أوتوماتيكياً.

تشغيل ARQ Worker

إلا كنت محتاج تعالج مهام Agent اللي كتحتاج وقت طويل، خاصك حتى تشغل ARQ Worker فطرفية أخرى:

uv run arq tasks.worker.WorkerSettings

يمكن إرسال الطلبات لـ Worker عبر طابور Redis، ومن بعد كيستعمل Worker الـ Agent Runtime وكيخزن نتيجة المهمة. سير المهام غير المتزامنة كيتضمن غالباً Job ID، والاستعلام على حالة المهمة، والتنفيذ فالخلفية، والإرسال بطريقة idempotent، والحصول على النتيجة.

تشغيل الاتصال الدائم مع Feishu

إلا كنت محتاج تستعمل اتصال Feishu عبر WebSocket، تقدر تنفذ:

uv run python -m channels.feishu_ws

IvyClaw كيدعم حتى Feishu Webhook وGeneric Webhook وCLI كمداخل. القنوات المختلفة كيتحولو كاملين بشكل موحد لـ InboundMessage، ومن بعد كيعيدو استعمال نفس منطق handle_message() ومعالجة Agent.

٥. فهم استدعاء الأدوات من طرف Agent

IvyClaw كيعطي لكل Agent مجموعة أدوات صغيرة ومناسبة للمسؤوليات ديالو، باش ينقص الاستدعاءات اللي ماعندهاش ضرورة ومخاطر الأخطاء. أنواع الأدوات اللي كيدعمها المشروع هي:

• Git: عرض والتعامل مع إصدارات الكود.
• pytest: تنفيذ الاختبارات الآلية.
• Python وShell: تشغيل أوامر التطوير.
• Web Search: البحث على المعلومات عبر Tavily أو Exa.
• MCP: الربط مع الأدوات والخدمات الخارجية.
• File Tools: قراءة وتعديل ملفات مساحة العمل.
• Sandbox: تنفيذ الكود اللي كيولدو Agent فبيئة معزولة.

المشروع كيجمع حتى مسارات تطوير قابلة لإعادة الاستعمال فـ skills/، بحال توضيح المتطلبات، وتصحيح الأخطاء بطريقة منهجية، والتطوير المبني على الاختبارات، واختبارات الوحدات، والتحقق قبل الإكمال. ومن المجلدات النموذجية:

skills/
├── fastapi-endpoint/
├── requirements-clarification/
├── systematic-debugging/
├── test-driven-development/
├── unit-test/
└── verification-before-completion/

٦. Sandbox ديال الكود والتنفيذ الآمن

الكود اللي كيولدو Agent ماكيتنفذش مباشرة فعملية الخدمة الرئيسية، ولكن يقدر يتحط فبيئة معزولة ويتنفذ تما. IvyClaw كيدعم Docker Sandbox وDaytona Sandbox، وكيقدر ينفذ أوامر Python وpytest وGit وغيرها.

قدرات الـ Sandbox كتشمل مجلد عمل مستقل، وإعادة استعمال الـ Sandbox وتدبير دورة حياتو، وزيد عليها تحديد موارد CPU وMemory وPID. فبيئة الإنتاج كيتستعمل Docker Sandbox بشكل افتراضي، مع ترك مجال للتوسع نحو بيئات تشغيل بعزل أقوى بحال gVisor أو Kata.

ملي كتضبط الـ Sandbox، خاصك تقيم مخاطر صلاحيات الشبكة، ونطاق الوصول للملفات، والحدود القصوى للموارد، وحجم التنفيذ المتزامن حسب الاستعمال الفعلي. الـ README كيوضح بلي بيئة الإنتاج مازال خاصها تعزيز العزل الأمني، وماخاصش تعتبر إعدادات العرض الحالية حلاً أمنياً كاملاً.

٧. تخزين الحالة والمهام غير المتزامنة

مكونات التخزين الدائم

PostgreSQL كيتكلف بالأساس بتخزين LangGraph Checkpointer وStore وحالة الجلسات وباقي البيانات الدائمة؛ أما Redis فكيتحمل الكاش، وتحديد معدل الطلبات، وطابور المهام، وحالة التشغيل. بفضل Checkpointer وStore، سياق تنفيذ Agent يقدر يستمر بين الطلبات.

سير المهام غير المتزامنة

بالنسبة لمهام التطوير اللي كتحتاج وقت طويل، من الأفضل يخلي FastAPI ينشئ المهمة، ومن بعد يعالجها Redis وARQ Worker بشكل غير متزامن:

Client
  ↓
FastAPI
  ↓
Create Job
  ↓
Redis Queue
  ↓
ARQ Worker
  ↓
Agent Runtime
  ↓
Persist Result
  ↓
Query Job Status

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

٨. Human-in-the-Loop: إضافة المصادقة للعمليات عالية المخاطر

حذف الملفات أو تنفيذ تعديلات مدمرة ماشي مناسب يكون مؤتمت بشكل كامل. IvyClaw كيدعم Human-in-the-Loop، وملي كيطلب Agent استدعاء أداة عالية المخاطر، يقدر يوقف التنفيذ وينتظر قرار الإنسان.

Agent requests risky action
          ↓
       Interrupt
          ↓
    Human Approval
       ↓       ↓
    Approve   Reject
       ↓
 Command(resume)
       ↓
Agent continues

من بعد الموافقة البشرية، كيتواصل التنفيذ بواسطة أمر الاستئناف؛ وإذا ترفض الطلب، كيتوقف المسار الحالي أو كيتبدل. هاد الآلية كتخلق نقطة تحكم بين فعالية الأتمتة وسلامة العمليات.

٩. البوابة، وتعدد المستأجرين، وتدبير الاستقرار

قبل ما يوصل الطلب لـ Agent Runtime، كيدوز من طبقة البوابة اللي كتتكلف بالتعرف على الهوية والتدبير الأساسي. القدرات اللي كيوفرها المستودع حالياً كتشمل:

• المصادقة بواسطة API Key.
• التعرف على Tenant وعزلو.
• Rate Limit لتحديد معدل الطلبات.
• Idempotency للتحكم فالإرسال المتكرر.
• Request Context لسياق الطلب.
• Audit Log لتدقيق العمليات.

الـ README كيوضح بالخصوص بلي Key وTenant حالياً مجرد إعدادات للعرض. فبيئة الإنتاج خاص الربط مع قاعدة بيانات أو نظام مخصص للمصادقة على الهوية، وزيد تحسين صلاحيات المستأجرين وعزل البيانات.

طبقة البنية التحتية كتقدم حتى آليات Retry وTimeout وFallback وConcurrency Control وPostgreSQL Connection Pool وRedis Connection Pool وSandbox Pool، باش تتعامل مع الضغط العالي، وأعطاب النموذج، وعدم استقرار البنية التحتية.

١٠. قابلية المراقبة والاختبارات والتقييم

IvyClaw مدمج مع مجموعة من مكونات قابلية المراقبة. LangSmith كيتستعمل لتتبع سلسلة استدعاءات Agent وLLM، وPrometheus مسؤول على جمع المقاييس، وGrafana كيتستعمل للمراقبة البصرية، وكاينين حتى السجلات المهيكلة وسجلات التدقيق.

فوقت التشغيل، من المهم التركيز على المقاييس التالية:

• مدة الاستجابة ومعدل الأخطاء.
• حجم التنفيذ المتزامن.
• عدد استدعاءات LLM.
• حجم استعمال Token والتكلفة.
• حالة ARQ Worker.
• حالة Sandbox.

المشروع كيتضمن حتى مجلدات tests/ وeval/ وloadtest/، وكتغطي الاختبارات الآلية بـ pytest، واختبارات Agent Runtime، وCode Cases، وExecution Scorer، وLLM Judge، وBaseline Evaluation، وReviewer Flow Test، واختبارات الضغط بـ Locust.

من الأفضل تبني حلقة تحقق بالترتيب التالي: «التطوير، الاختبارات الآلية، تقييم Agent، اختبارات الضغط، مراقبة المقاييس، تحسين المشاكل»، بلا ما تعتمد غير على حوار يدوي واحد باش تحكم واش Agent موثوق.

١١. نشر الإنتاج باستعمال Docker

إلا كنت محتاج تشغل حزمة الخدمات كاملة، تقدر تستعمل إعدادات Compose ديال الإنتاج اللي كيوفرها المستودع:

docker compose -f docker-compose.prod.yml up -d --build

النشر فالإنتاج كيشمل خدمة الويب FastAPI، وARQ Worker، وخدمة فيسبوك، وPostgreSQL، وRedis، وPrometheus وGrafana. الـ API والـ Worker يقدرو يوصلو بجوج لـ Agent Runtime، وAgent Runtime كينفّذ الكود اللي تولّد باستعمال Docker Sandbox.

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

12. تحديد مكان الكود انطلاقا من بنية المشروع

معرفة بنية المجلدات كتعاون على توسيع الوظائف بسرعة:

IvyClaw/
├── agent/          # الـ Agent الرئيسي وجدولة المهام
├── api/            # FastAPI API
├── channels/       # الولوج عبر CLI / Feishu / Webhook
├── gateway/        # المصادقة ديال API، وTenant، وتحديد المعدل
├── infra/          # PostgreSQL، وRedis، وLLM Router
├── middleware/     # سياق الطلب، والتوازي، والتدقيق، وإحصائيات التكلفة
├── obs/            # Metrics وقابلية المراقبة
├── profiles/       # ملفات تعريف النماذج والـ Agent
├── sandbox/        # صناديق Docker / Daytona المعزولة
├── skills/         # مهارات الـ Agent
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # المهام غير المتزامنة ديال ARQ
├── tools/          # أدوات Git / pytest / Search / MCP
├── eval/           # تقييم الـ Agent
├── loadtest/       # اختبار الضغط بـ Locust
├── tests/          # الاختبارات الآلية
├── scripts/        # سكريبتات التطوير والاختبار والعروض التوضيحية
├── web/            # واجهة الويب
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

13. نصائح للاستعمال العملي

1. بدا بتكوين .env وPostgreSQL وRedis، وتأكد باللي API كتقدر توصل ليها عبر توثيق Swagger.
2. تحقق أولا من Agent Workflow الأساسي باستعمال API متزامنة أو CLI، ومن بعد شغّل ARQ Worker لمعالجة المهام الطويلة.
3. راجع صلاحيات الأدوات ديال Coder وTester وReviewer كل واحد بوحدو، باش ما تعطيش لـ Agent واحد قدرات عالية الخطورة ما محتاجهاش.
4. فعّل تنفيذ الكود المولّد داخل صندوق معزول، وحدد قيود مناسبة على CPU والذاكرة وعدد العمليات ومجلد العمل.
5. إلى كان الأمر متعلق بالحذف أو بتعديل تخريبي، فعّل Human-in-the-Loop، وما توافقش عليه آليا بشكل افتراضي.
6. استعمل LangSmith وPrometheus وGrafana والسجلات المهيكلة لمراقبة مسار الطلبات والتكلفة ومدة الاستجابة والأخطاء.
7. قبل الإطلاق، شغّل pytest وAgent Evaluation واختبار الضغط بـ Locust، وعدّل توجيه النماذج والتوازي وسياسة إعادة المحاولة حسب النتائج.

الخلاصة

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

من بعد ما تكمل التشغيل المحلي، تقدر تبدا من subagents/ وtools/ وskills/ الموجودين، وتفهم بالتدريج طريقة التعاون بين Planner وResearcher وCoder وTester وReviewer، ومن بعد توسّع القنوات أو الأدوات أو مسار التقييم حسب متطلبات العمل.