Forem: Yusuf Khalidd

كلود للوكلاء المدارة ضد حزمة تطوير الوكيل (2026): أيهما تختار؟

Yusuf Khalidd — Tue, 19 May 2026 10:28:58 +0000

لقد قررت إطلاق وكيل ذكاء اصطناعي إنتاجي على Claude. القرار المعماري الأول ليس اختيار النموذج فقط، بل اختيار مكان تشغيل حلقة الوكيل: هل تستخدم وكلاء Claude المُدارين (Claude Managed Agents) لتدير Anthropic الحلقة وبيئة الاختبار وحالة الجلسة، أم تستخدم حزمة تطوير وكيل Claude (Claude Agent SDK) لتشغيل الحلقة داخل خدمتك وبنيتك التحتية؟ هذا الدليل يحوّل المقارنة إلى خطوات قرار عملية باستخدام أمثلة مثل وكيل استرداد مدفوعات ووكيل فرز تذاكر دعم.

جرّب Apidog اليوم

خلاصة القرار

اختر وكلاء Claude المُدارين عندما تريد تقليل عبء التشغيل: Anthropic تستضيف حلقة الوكيل، بيئة الاختبار، وسجل الجلسة، وهذا مناسب للأعمال الطويلة أو غير المتزامنة.

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

كلا الخيارين يدعمان نماذج Claude وMCP، لكنهما يختلفان جذريًا في الملكية التشغيلية.

قبل الاختيار: حدّد أين ستفشل المنظومة

معظم وكلاء الإنتاج لا “يفكرون” فقط؛ هم يستدعون APIs:

إصدار استرداد مدفوعات.
إنشاء تذكرة Zendesk.
قراءة مخزون.
استدعاء خدمة تسعير داخلية.
تشغيل أداة عبر MCP.

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

للمقدمة الخاصة بالخيار المستضاف، راجع دليل وكلاء Claude المُدارين.

ما هو وكلاء Claude المُدارون؟

وكلاء Claude المُدارون هو وقت تشغيل مستضاف للوكيل. بدل أن تبني حلقة الوكيل، بيئة الاختبار، وتنفيذ الجلسات بنفسك، تصف الوكيل وترسل له الأحداث عبر API.

تم إطلاقه في نسخة تجريبية عامة في أبريل 2026 ويتطلب حاليًا الرأس التجريبي:

anthropic-beta: managed-agents-2026-04-01

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

Agent: النموذج، موجه النظام، الأدوات، خوادم MCP، والمهارات.
Environment: قالب حاوية يحتوي على حزم مثبتة مسبقًا وقواعد شبكة.
Session: تشغيل فعلي لوكيل داخل بيئة لتنفيذ مهمة واحدة.
Events: الرسائل، نتائج الأدوات، وتحديثات الحالة المتدفقة بين تطبيقك والوكيل عبر SSE.

التدفق العملي يكون كالتالي:

أنشئ Agent.
اربطه ببيئة Environment.
ابدأ Session.
أرسل رسالة المستخدم كحدث.
استقبل النتائج والأحداث المتدفقة.
استعد سجل الأحداث عند التصحيح أو التدقيق.

يدعم الخيار أدوات مدمجة مثل Bash، عمليات الملفات، البحث عبر الويب، والاسترجاع، إضافة إلى خوادم MCP. وهو مناسب عندما تحتاج إلى:

تنفيذ طويل من دقائق إلى ساعات.
جلسات ذات حالة دائمة.
تشغيل غير متزامن.
تقليل عبء البنية التحتية.
سجل أحداث مستضاف.

لكن انتبه إلى نقطتين:

الأدوات المخصصة لا تُنفَّذ داخل Anthropic تلقائيًا. Claude يطلب استدعاء الأداة، وتطبيقك ينفذها ويرجع النتيجة عبر تدفق الأحداث.
بعض الميزات مثل النتائج والوكلاء المتعددين قد تكون مقيدة بطلب وصول منفصل كمعاينة بحثية.

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

ما هي حزمة تطوير وكيل Claude؟

حزمة تطوير وكيل Claude هي مكتبة بايثون أو تايب سكريبت تشغّل حلقة الوكيل داخل عمليتك. كانت تُعرف سابقًا باسم Claude Code SDK، ثم أُعيدت تسميتها لتعكس استخدامات أوسع من مهام البرمجة.

التثبيت:

pip install claude-agent-sdk

أو:

npm install @anthropic-ai/claude-agent-sdk

الفكرة الأساسية: بدل أن تكتب حلقة أدوات يدويًا مثل:

while response.stop_reason == "tool_use":
    # نفّذ الأداة
    # أرسل النتيجة
    # أكمل الحلقة

تستخدم SDK التي توفر الحلقة، إدارة السياق، الأدوات، الجلسات، والخطافات.

مثال مبسط بالفكرة العامة:

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"]
)

async for message in query(
    prompt="افحص المشروع واقترح إصلاحًا للاختبارات الفاشلة",
    options=options
):
    print(message)

توفر SDK آليات مهمة للإنتاج:

أدوات مدمجة: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch.
Hooks: مثل PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd.
Subagents: وكلاء فرعيون لمهام مركزة.
MCP: ربط قواعد بيانات، متصفحات، وخدمات خارجية.
Permissions: السماح أو الحظر أو طلب موافقة بشرية.
Sessions: حفظ واستئناف الجلسات، عادة بصيغة JSONL على نظام ملفاتك.

مثال عملي على استخدام Hook لمنع أمر خطير:

def pre_tool_use_hook(event):
    if event.tool_name == "Bash" and "rm -rf" in event.input.get("command", ""):
        return {
            "allow": False,
            "reason": "الأمر محظور لأنه قد يحذف ملفات حرجة"
        }

    return {"allow": True}

هذه النقطة مهمة: مع SDK أنت تملك الحلقة. هذا يعني أنك تملك أيضًا مسؤولية التشغيل، السجلات، التوسع، العزل، والحوكمة.

للبداية العملية، راجع إعداد حزمة تطوير وكيل Claude بخطة Claude وبناء Claude Code الخاص بك.

ملاحظة فوترة: بدءًا من 15 يونيو 2026، سيتم سحب استخدام Agent SDK وclaude -p في خطط الاشتراك من رصيد شهري منفصل لـ Agent SDK، مختلف عن حدود الاستخدام التفاعلي. تحقق دائمًا من شروط Anthropic الحالية قبل بناء توقعات التكلفة.

مقارنة مباشرة

راجع الأسعار والحالة الرسمية من صفحة أسعار Anthropic ووثائق الوكلاء المُدارين قبل اعتماد قرار ميزانية.

المعيار	وكلاء Claude المُدارون	حزمة تطوير وكيل Claude
مكان تشغيل الحلقة	بنية Anthropic التحتية	عمليتك وبنيتك التحتية
الواجهة	REST API + SSE	مكتبة Python أو TypeScript
التحكم في الحلقة	تكوين وتوجيه عبر الأحداث	تحكم كامل داخل العملية
التكلفة	رموز Claude + رسوم تشغيل لكل ساعة جلسة نشطة	رموز Claude + تكلفة البنية التي تشغلها
عبء التشغيل	منخفض	أعلى
قابلية المراقبة	سجل أحداث مستضاف وقابل للاستعادة	Hooks وسجلات ومراقبة تبنيها أنت
زمن الوصول	قفزة إلى وقت تشغيل مستضاف	قرب أعلى من خدماتك الداخلية
محلية البيانات	الجلسة والبيئة لدى Anthropic أو AWS حسب الخيار	الحالة والأدوات داخل بنيتك
تنفيذ الأدوات المخصصة	تطبيقك ينفذ ويرجع النتيجة عبر الأحداث	دوال داخل العملية
أفضل استخدام	أعمال طويلة وغير متزامنة	بيانات حساسة، VPC، تحكم دقيق

كيف تقرأ المقارنة عمليًا؟

1. التكلفة ليست رقمًا واحدًا

وكلاء Claude المُدارون يضيفون تكلفة تشغيل لكل ساعة جلسة نشطة. إذا كان الوكيل يعمل طويلًا أو ينتظر بين أدوات كثيرة، فهذا يؤثر على التكلفة.

مع SDK لا توجد رسوم تشغيل مستضافة من Anthropic لكل ساعة، لكنك تدفع مقابل:

الخوادم.
العزل.
التخزين.
المراقبة.
التوسع.
وقت فريق التشغيل.

لذلك اسأل:

هل أريد دفع تكلفة تشغيل مُدارة، أم أريد امتلاك البنية وتشغيلها؟

2. محلية البيانات قد تحسم القرار

إذا كان الوكيل يتعامل مع بيانات منظمة، مالية، صحية، أو محصورة داخل VPC، فغالبًا ستحتاج SDK.

مع SDK:

تنفيذ الأدوات داخل بنيتك.
حالة الجلسة على نظامك.
يمكنك ربط سياسات تدقيق داخلية.
فقط الاستنتاج يذهب إلى Claude.

مع الوكلاء المُدارين:

بيئة الاختبار وسجل الأحداث مستضافان لدى Anthropic أو AWS حسب التوفر والقيود.

3. قابلية المراقبة تختلف في مكانها

الوكلاء المُدارون يعطونك سجل أحداث مستضافًا.

SDK تعطيك Hooks، لكن عليك ربطها بـ:

OpenTelemetry.
Datadog.
Grafana.
سجلات داخلية.
نظام تدقيق.

مثال Hook لتسجيل كل استخدام أداة:

def post_tool_use_hook(event):
    audit_log.write({
        "tool": event.tool_name,
        "input": event.input,
        "result_status": event.result.status,
        "session_id": event.session_id
    })

اختبر APIs التي يستدعيها الوكيل

بغض النظر عن نموذج الاستضافة، فشل الوكيل غالبًا لا يأتي من Claude نفسه، بل من API غير مستقرة أو أداة MCP تعيد شكلًا غير متوقع.

اختبر ثلاث طبقات قبل الإطلاق.

1. عقود API

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

باستخدام Apidog، يمكنك:

تعريف مخطط endpoint.
إنشاء mock service.
تشغيل اختبارات عقود.
إعادة تشغيل سيناريوهات وكيل حقيقية ضد المحاكاة.

مثال عقد مبسط لاسترداد مدفوعات:

{
  "endpoint": "/refunds",
  "method": "POST",
  "request": {
    "transaction_id": "string",
    "amount": "number",
    "reason": "string"
  },
  "response": {
    "refund_id": "string",
    "status": "approved|pending|rejected"
  }
}

إذا بدأت الخدمة الحقيقية بإرجاع state بدل status، يجب أن يفشل اختبار العقد قبل أن يفشل وكيلك في الإنتاج.

راجع كيفية اختبار وكلاء الذكاء الاصطناعي الذين يستدعون واجهات برمجة التطبيقات.

2. خوادم MCP

كلا الخيارين يدعمان MCP. لكن خادم MCP نفسه قد يفشل بطرق شائعة:

أداة ترجع JSON غير مطابق.
مهلة لا تُعالج.
خطأ يرجع نصًا حرًا بدل كائن منظم.
اختلاف أسماء الحقول.
غياب pagination أو rate limits واضحة.

اختبر كل أداة MCP مباشرة قبل ربطها بوكيل. راجع اختبار خادم MCP باستخدام Apidog.

3. نمط طلبات الوكيل

الوكلاء لا يتصرفون مثل المستخدمين البشر. قد يفعلون الآتي:

يعيدون المحاولة بسرعة.
يستدعون نفس endpoint عدة مرات.
يقرؤون بيانات جزئية.
يكررون استدعاء أداة بعد خطأ غامض.
يخلطون بين أخطاء مؤقتة ونجاح جزئي.

لذلك أعد تشغيل حركة مرور الوكيل ضد mocks. استخدم مصححًا يلتقط الطلبات والاستجابات الفعلية بدل الاعتماد على التوقعات.

يمكنك تنزيل Apidog لاختبار هذه التبعيات قبل ربط الوكيل بعميل حقيقي.

إطار قرار سريع

ابدأ بهذه الأسئلة. أول “نعم” قوية غالبًا تحدد الخيار.

اختر وكلاء Claude المُدارين إذا:

الوكيل يعمل دقائق أو ساعات.
العمل غير متزامن.
لا تريد تشغيل workers أو sandbox أو session store.
فريقك صغير وعبء العمليات هو القيد الأساسي.
تحتاج سجل أحداث مستضاف وقابل للاستعادة.
بياناتك تسمح بوجود الجلسة في بيئة Anthropic أو AWS.
أنت مرتاح للتعامل مع منتج في مرحلة بيتا وبعض الميزات المقيدة.

اختر حزمة تطوير وكيل Claude إذا:

الوكيل يجب أن يعمل داخل VPC.
يحتاج الوصول إلى قواعد بيانات أو خدمات داخلية.
لا يمكن تخزين حالة الجلسة لدى طرف ثالث.
تحتاج Hooks للتدقيق والسياسات.
تحتاج أذونات دقيقة وموافقات بشرية.
تريد تنفيذ الأدوات داخل العملية.
تريد الاستفادة من عقود Bedrock أو Vertex أو Azure القائمة مع إبقاء الحلقة داخليًا.
تعمل على نموذج أولي محلي سريع.

مسار شائع

مسار عملي للفرق:

ابدأ بـ Agent SDK محليًا لتسريع التجربة.
اختبر APIs وMCP بعقود ومحاكاة.
قيّم عبء التشغيل.
انقل الإنتاج إلى الوكلاء المُدارين إذا كانت وفورات التشغيل أكبر من خسارة التحكم.

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

إذا كنت تقارن أيضًا بين النماذج أو وكلاء البرمجة، راجع مقارنة Claude و Codex لعام 2026.

حالات استخدام عملية

1. وكيل استرداد مدفوعات

المهمة:

قراءة تذكرة دعم.
البحث عن المعاملة.
التحقق من سياسة الاسترداد.
استدعاء API المدفوعات.
كتابة ملخص إلى التذكرة.

هذا الوكيل يتعامل مع المال، لذلك تحتاج:

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

الخيار الأنسب غالبًا: Agent SDK.

سبب الاختيار:

يعمل داخل VPC.
حالة الجلسة تبقى داخل الشركة.
يمكن استخدام PreToolUse لفرض الموافقات.
يمكن تسجيل كل استدعاء API.

مثال سياسة:

def pre_tool_use_hook(event):
    if event.tool_name == "issue_refund":
        amount = event.input["amount"]

        if amount > 500:
            return {
                "allow": False,
                "requires_human_approval": True,
                "reason": "استرداد يتجاوز الحد المسموح آليًا"
            }

    return {"allow": True}

قبل الإطلاق، يحاكي الفريق نقاط نهاية المدفوعات في Apidog، يشغل اختبارات عقود، ثم يعيد تشغيل تذاكر تاريخية ضد المحاكاة. إذا اكتشف أن الوكيل يعيد طلب الاسترداد بعد 504 رغم نجاح العملية في الخلفية، فهذا فشل يجب اكتشافه قبل الإنتاج.

2. وكيل فرز تذاكر دعم غير متزامن

المهمة:

استقبال آلاف التذاكر يوميًا.
تصنيف كل تذكرة.
سحب سجلات مرتبطة.
صياغة رد.
حل التذكرة أو تصعيدها.

الخصائص:

كل مهمة تستغرق عدة دقائق.
العمل غير متزامن.
البيانات منخفضة الحساسية.
الفريق لا يريد تشغيل أسطول workers.

الخيار الأنسب غالبًا: وكلاء Claude المُدارون.

سبب الاختيار:

Anthropic تدير الجلسات.
مناسب للأعمال الطويلة.
سجل الأحداث المستضاف يساعد في تتبع كل تذكرة.
عبء التشغيل أقل.

لكن ما زال يجب اختبار:

API السجلات.
MCP الخاص بنظام التذاكر.
مخططات الطلبات والاستجابات.
حالات المهلة وإعادة المحاولة.

3. وكيل عمليات بيانات داخلي خلف جدار الحماية

المهمة:

“أعد تشغيل أقسام ETL الفاشلة بالأمس، ثم أرسل تقرير الحالة.”

يتطلب ذلك:

الوصول إلى API مهام داخلية.
تشغيل سكريبت إصلاح.
قراءة سجلات داخلية.
التعامل مع بيانات حساسة.

الخيار الأنسب: Agent SDK.

سبب الاختيار:

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

في هذه الحالة، خاصية “يعمل داخل عمليتك” ليست ميزة إضافية؛ إنها شرط معماري.

للمزيد عن سبب اعتبار الوكلاء مستهلكين أساسيين لـ APIs، راجع وكلاء الذكاء الاصطناعي كمستهلكين جدد لواجهة برمجة التطبيقات.

خلاصة تنفيذية

قرار Claude Managed Agents مقابل Claude Agent SDK هو قرار تشغيل وحوكمة بيانات أكثر من كونه اختيار مكتبة.

تذكّر:

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

قبل ربط الوكيل بأي نظام حقيقي، ضع كل API وخادم MCP تحت الاختبار. قم بتنزيل Apidog لمحاكاة endpoints، تشغيل اختبارات العقود، وتصحيح حركة مرور الوكيل الفعلية.

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

ما الفرق الجوهري بين وكلاء Claude المُدارين وAgent SDK؟

وكلاء Claude المُدارون هو REST API مستضاف تدير فيه Anthropic حلقة الوكيل وبيئة الاختبار وحالة الجلسة. Agent SDK هي مكتبة Python أو TypeScript تشغل الحلقة داخل عمليتك وبنيتك التحتية.

هل Agent SDK هي نفسها Claude Code SDK القديمة؟

نعم. تم تغيير اسم Claude Code SDK إلى Claude Agent SDK ليعكس نطاقًا أوسع من مهام البرمجة. الآلية الأساسية ما زالت حلقة وكيل وأدوات مدمجة وإدارة سياق.

أي الخيارين أرخص؟

يعتمد على عبء العمل. الوكلاء المُدارون يضيفون رسوم تشغيل لوقت الجلسة النشط. SDK لا تضيف رسوم تشغيل مستضافة من Anthropic لكل ساعة، لكنك تدفع تكلفة الخوادم والتشغيل والمراقبة. تحقق من الأسعار الرسمية قبل الميزانية.

هل يمكن استخدام MCP مع كلا الخيارين؟

نعم. كلاهما يدعم MCP. لذلك يجب اختبار خوادم MCP قبل ربطها بأي وكيل. راجع اختبار خادم MCP باستخدام Apidog.

كيف أحافظ على بيانات العملاء خارج بنية Anthropic؟

استخدم Agent SDK وشغّل الحلقة داخل بيئتك. بذلك يبقى تنفيذ الأدوات وحالة الجلسة على بنيتك، بينما يذهب استنتاج النموذج فقط إلى Claude. مع الوكلاء المُدارين، تعيش بيئة الاختبار وسجل الأحداث في بيئة Anthropic أو AWS حسب الخيار.

هل وكلاء Claude المُدارون جاهزون للإنتاج؟

تم إطلاقهم في نسخة تجريبية عامة في أبريل 2026 ويتطلبون الرأس التجريبي managed-agents-2026-04-01. بعض الميزات قد تكون مقيدة بطلب معاينة بحثية. تحقق من الوثائق الرسمية قبل الاعتماد الإنتاجي.

كيف أختبر وكيلًا قبل أن يستخدم APIs حقيقية؟

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

هل يمكن البدء بخيار ثم الانتقال للآخر؟

نعم. المسار الشائع هو النموذج الأولي باستخدام Agent SDK ثم الانتقال إلى الوكلاء المُدارين للإنتاج إذا كان تقليل التشغيل أهم من التحكم. لكنه ليس تغيير إعدادات فقط: الواجهة، تنفيذ الأدوات، وإدارة الجلسات تختلف.

Cursor Composer 2.5 ضد Opus 4.7 ضد GPT-5.5: أي نموذج برمجة يجب أن تستخدم؟

Yusuf Khalidd — Tue, 19 May 2026 02:27:56 +0000

ادعاء Cursor حول Composer 2.5 واضح: جودة برمجة قريبة من النماذج المتقدمة بتكلفة تقارب عُشر السعر. عمليًا، السؤال ليس "من يتصدر لوحة المعايير؟" بل: أي نموذج تختاره كافتراضي عند العمل على قاعدة كود حقيقية وميزانية محدودة؟ في هذا الدليل نقارن Composer 2.5 مع Claude Opus 4.7 و GPT-5.5 من زاوية الأداء، السرعة، التكلفة، وكيف تختبرها على مشروعك.

جرّب Apidog اليوم

إذا كنت تريد خلفية كاملة عن النموذج نفسه، ابدأ بدليلنا حول Cursor Composer 2.5. هنا نركز على قرار عملي واحد: عند وجود قاعدة كود حقيقية ومهام يومية، أي نموذج يجب أن تستخدم؟

الإجابة المختصرة

Composer 2.5 ليس الأفضل في كل معيار، لكنه يقدم أفضل توازن لمعظم فرق التطوير: قريب جدًا من Opus 4.7 في مهام البرمجة الواقعية، ويتفوق على GPT-5.5 في بعض معايير الكود، مع تكلفة أقل بكثير لكل مهمة. لا يزال Opus 4.7 خيارًا قويًا عندما تريد أعلى سقف تفكير ممكن، بينما يظل GPT-5.5 مميزًا في الأعمال الثقيلة داخل الطرفية.

استخدم القاعدة التالية كبداية:

اجعل Composer 2.5 النموذج الافتراضي لمهام التطوير اليومية.
استخدم Opus 4.7 للمهام الصعبة جدًا أو الغامضة.
استخدم GPT-5.5 عندما يكون العمل قائمًا على أوامر shell وسلاسل terminal طويلة.

مقارنة المعايير

يعرض Cursor ثلاث مجموعات رئيسية من الاختبارات. الجدول التالي يضع النماذج جنبًا إلى جنب، مع أرقام Composer 2 القديمة للسياق:

المعيار	Composer 2.5	Opus 4.7	GPT-5.5	Composer 2
SWE-bench متعدد اللغات	79.8%	80.5%	77.8%	73.7%
Terminal-bench 2.0	69.3%	69.4%	82.7%	غير متوفر
CursorBench v3.1	63.2%	64.8% حد أقصى / 61.6% افتراضي	59.2% افتراضي	غير متوفر

كيف تقرأ هذه الأرقام؟

1. في SWE-bench متعدد اللغات، الفارق صغير جدًا

هذا المعيار يختبر إصلاح مشكلات GitHub حقيقية عبر لغات مختلفة. Composer 2.5 يحقق 79.8%، أي أقل من Opus 4.7 بنقطة تقريبًا، ويتقدم على GPT-5.5. القفزة الأهم هي من Composer 2 عند 73.7% إلى Composer 2.5. إذا كنت تستخدم Composer 2 سابقًا، فهذه ترقية واضحة. يمكنك الرجوع إلى دليل Composer 2 لمعرفة نقطة البداية.

2. في CursorBench، Composer 2.5 قوي كإعداد افتراضي

في مهام Cursor الخاصة، يسجل Composer 2.5 نسبة 63.2%. هذا أعلى من Opus 4.7 في الإعداد الافتراضي 61.6%، وأعلى من GPT-5.5 في الإعداد الافتراضي 59.2%. يتقدم Opus 4.7 فقط عند دفعه إلى أقصى إعداداته، وهذا يعني عادةً تكلفة وزمن استجابة أعلى.

3. في Terminal-bench، GPT-5.5 يتفوق بوضوح

إذا كانت مهامك تتضمن سلاسل أوامر طويلة، إعداد بيئات، تشغيل سكربتات، أو إدارة حالات معقدة عبر الطرفية، فانتبه إلى رقم GPT-5.5: 82.7% مقابل 69.3% لـ Composer 2.5. هذا ليس فرقًا صغيرًا.

للتأكيد المستقل لهذه الأرقام، راجع تغطية The Decoder والإعلان الرسمي لـ Cursor Composer 2.5.

التكلفة: هنا يظهر الفرق الحقيقي

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

النموذج	الإدخال / مليون رمز	الإخراج / مليون رمز	التكلفة التقريبية لكل مهمة
Composer 2.5 قياسي	0.50 دولار	2.50 دولار	أقل من 1 دولار
Composer 2.5 سريع	3.00 دولارات	15.00 دولارًا	أرقام فردية منخفضة
Opus 4.7 / GPT-5.5	مستوى متقدم	مستوى متقدم	عدة دولارات، وقد تصل إلى 11 دولارًا تقريبًا

يفيد Cursor بأن Composer 2.5 يحقق حوالي 63% على CursorBench بتكلفة متوسطة أقل من دولار واحد لكل مهمة. في المقابل، قد تكلف النماذج المتقدمة عدة دولارات لكل مهمة للحصول على نتائج مشابهة أو أفضل قليلًا.

مثال عملي:

عدد مهام الوكيل شهريًا	تكلفة 1 دولار / مهمة	تكلفة 5 دولارات / مهمة	تكلفة 11 دولارًا / مهمة
500	500 دولار	2,500 دولار	5,500 دولار
2,000	2,000 دولار	10,000 دولار	22,000 دولار
10,000	10,000 دولار	50,000 دولار	110,000 دولار

إذا كنت تدير 2,000 مهمة وكيل شهريًا، فالفارق بين Composer 2.5 ونموذج متقدم قد يكون آلاف الدولارات شهريًا. لذلك، اختيار النموذج الافتراضي أهم من مطاردة أعلى رقم في معيار واحد.

لتحليل أعمق لطريقة حساب التكلفة، راجع دليل تسعير Cursor Composer. وللمقارنة مع النماذج المتقدمة، اقرأ منشور GPT-5.5 pricing post ودليل Claude Opus 4.7.

السرعة وسلوك كل نموذج أثناء التطوير

الأداء والتكلفة لا يكفيان. عند استخدام النموذج يوميًا داخل IDE، يهمك أيضًا كيف يتصرف أثناء تنفيذ مهمة متعددة الخطوات.

Composer 2.5

استخدمه عندما تريد:

تعديل عدة ملفات داخل Cursor.
تنفيذ مهمة agentic طويلة نسبيًا.
الحفاظ على سياق المشروع عبر خطوات متتابعة.
توازن بين جودة جيدة وتكلفة منخفضة.

Composer 2.5 مبني على نقطة تفتيش Moonshot Kimi K2.5 مفتوحة المصدر، وتم تدريبه وتخصيصه بواسطة Cursor لسير عمل الوكيل داخل المحرر. لذلك يظهر قوته في حلقة: قراءة الكود، اقتراح تعديل، تطبيقه، ثم الاستمرار بناءً على النتائج.

Opus 4.7

استخدمه عندما تكون المهمة:

غامضة أو تحتاج تفكيرًا معماريًا عميقًا.
عالية المخاطر.
تتطلب تحليلًا طويلًا قبل كتابة الكود.
لا تكون التكلفة فيها العامل الأهم.

Opus 4.7 يتفوق عندما تحتاج أعلى سقف تفكير، لكنك تدفع مقابل ذلك في السعر وزمن الاستجابة.

GPT-5.5

استخدمه عندما تكون المهمة:

مبنية حول terminal.
تتطلب سلاسل أوامر طويلة.
تشمل إعداد بيئة، تشغيل اختبارات، تحليل مخرجات shell، أو إصلاح أخطاء build.
تحتاج نموذجًا عامًا قويًا إلى جانب قدرته البرمجية.

رقم Terminal-bench يوضح لماذا قد يكون GPT-5.5 الخيار الأفضل لهذا النوع من العمل.

كيف تختار النموذج المناسب؟

لا تتعامل مع النماذج الثلاثة كبدائل مطلقة. تعامل معها كأدوات مختلفة.

اختر Composer 2.5 إذا:

تكتب كودًا يوميًا داخل Cursor.
لديك عدد كبير من مهام الوكيل.
التكلفة لكل مهمة تؤثر على ميزانية الفريق.
تحتاج جودة قريبة من النماذج المتقدمة بسعر أقل.
معظم مهامك هي إصلاحات، ميزات صغيرة، refactors، واختبارات.

اختر Opus 4.7 إذا:

المهمة معقدة جدًا أو غير محددة جيدًا.
تريد أقصى جودة تفكير بغض النظر عن السعر.
تستخدم بالفعل سير عمل متمركزًا حول Claude. تغطي مقارنة Claude Code vs Cursor هذا المسار.

اختر GPT-5.5 إذا:

تعتمد كثيرًا على terminal automation.
تريد نموذجًا عامًا تستخدمه أيضًا للبرمجة.
مهامك تتضمن أوامر shell طويلة، إعداد أنظمة، أو تتبع مخرجات تنفيذ معقدة.

الاستراتيجية العملية: نظام هجين

كثير من الفرق ستحصل على أفضل نتيجة بهذا النمط:

المهمة اليومية المعتادة        -> Composer 2.5
مشكلة صعبة أو معمارية          -> Opus 4.7
سير عمل terminal طويل          -> GPT-5.5

بهذه الطريقة لا تدفع سعر النموذج المتقدم لكل مهمة، ولا تحرم نفسك منه عندما يكون مفيدًا فعلًا. إذا كنت لا تزال تقارن أدوات البرمجة نفسها، راجع ملخص Codex vs Claude Code vs Cursor vs Copilot.

اختبر النماذج على كودك خلال 20 دقيقة

المعايير العامة مفيدة، لكنها لا تمثل مشروعك بالكامل. نفّذ اختبارًا صغيرًا داخل مستودعك قبل اعتماد نموذج افتراضي.

1. اختر مهمة حقيقية

اختر مهمة كنت ستعطيها عادةً لوكيل داخل Cursor، مثل:

إصلاح bug مع خطوات إعادة إنتاج.
إضافة endpoint صغير.
refactor لدالة أو module.
تحديث اختبارات موجودة.
تعديل منطق يتعامل مع API خارجي.

لا تستخدم مهمة مصطنعة. الهدف هو قياس النموذج على عملك الحقيقي.

2. اكتب prompt واحدًا وثابتًا

مثال:

أصلح الخطأ التالي في وحدة الدفع.

السلوك الحالي:
- عند إرسال طلب refund لقيمة جزئية، يرجع النظام status=success
- لكن لا يتم تحديث refunded_amount في قاعدة البيانات

المطلوب:
- تتبع سبب الخطأ
- عدّل أقل عدد ممكن من الملفات
- أضف أو حدّث الاختبارات المناسبة
- لا تغيّر واجهة API الحالية

استخدم نفس النص مع كل نموذج.

3. شغّل المهمة ثلاث مرات

داخل Cursor، بدّل محدد النموذج بين:

composer-2.5
Opus 4.7
GPT-5.5

حافظ على نفس الشروط:

نفس الفرع.
نفس prompt.
نفس الاختبارات.
نفس القيود.
بدون تدخل يدوي أثناء التشغيل قدر الإمكان.

4. قيّم النتائج

استخدم جدولًا بسيطًا:

النموذج	هل اجتازت الاختبارات؟	هل التعديل صغير ومفهوم؟	الزمن	التكلفة	ملاحظات
Composer 2.5
Opus 4.7
GPT-5.5

لا تقيّم فقط "هل كتب كودًا؟". قيّم:

هل حل المشكلة فعلًا؟
هل كسر سلوكًا آخر؟
هل اخترع API غير موجود؟
هل أضاف تعقيدًا غير ضروري؟
هل احتجت إلى تدخل بشري كثير؟

5. إذا كانت المهمة تتعامل مع API، اختبر الطلبات فعليًا

إذا ولّد النموذج كودًا يستدعي endpoint، لا تعتمد فقط على unit tests. أرسل الطلبات عبر Apidog وتحقق من:

status codes.
response body.
authentication.
headers.
edge cases.
تطابق schema مع المتوقع.

بهذا يصبح معنى "نجح" هو أن نقطة النهاية تعمل فعلًا، وليس فقط أن الاختبارات المحلية أصبحت خضراء.

المعيار الذي لا تقيسه لوحات النتائج

هناك فشل شائع في كل النماذج: كتابة كود API يبدو صحيحًا لكنه مبني على endpoints أو payloads يفترضها النموذج بدلًا من مواصفاتك الحقيقية.

مثال:

// النموذج افترض أن endpoint موجود بهذا الشكل
await fetch("/api/users/update-profile", {
  method: "POST",
  body: JSON.stringify({
    userId,
    displayName,
    avatarUrl
  })
});

لكن API الحقيقي قد يكون:

PATCH /v1/users/{id}
Content-Type: application/json

مع payload مختلف:

{
  "profile": {
    "name": "string",
    "avatar_url": "string"
  }
}

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

الحل لا يعتمد على النموذج الذي تختاره:

اربط النموذج بمواصفات API الحقيقية.
اجعل Cursor يرى schema الفعلية.
شغّل الطلبات الناتجة ضد API حية أو بيئة اختبار.
ثبّت الطلبات الناجحة في اختبارات تلقائية.

يمكنك تمرير مواصفات API إلى Cursor عبر MCP Server حتى يكتب النموذج وفق مخططك الفعلي، ثم تشغيل الطلبات في Apidog للتحقق من status codes والحمولات والمصادقة قبل وصول الكود إلى مراجعة الفريق. يشرح دليل ربط مواصفات API في Cursor طريقة الإعداد.

النموذج الذي تختاره يغيّر السرعة والتكلفة. أما حلقة التحقق فهي التي تمنع السرعة من التحول إلى ديون تصحيح أخطاء.

أسئلة شائعة

هل Composer 2.5 أفضل من Opus 4.7؟

ليس دائمًا. في SWE-bench Multilingual، Composer 2.5 قريب جدًا: 79.8% مقابل 80.5%. وفي CursorBench بالإعدادات الافتراضية، يتقدم Composer 2.5 على Opus 4.7 الافتراضي. لكن Opus 4.7 يتصدر عند أقصى إعداداته. من ناحية القيمة مقابل التكلفة، Composer 2.5 هو الخيار الأفضل لمعظم المهام اليومية.

هل Composer 2.5 أفضل من GPT-5.5؟

يعتمد على نوع العمل. Composer 2.5 يتفوق في SWE-bench Multilingual و CursorBench. أما GPT-5.5 فيتقدم بوضوح في Terminal-bench 2.0. إذا كان عملك داخل المحرر وعلى ملفات المشروع، ابدأ بـ Composer 2.5. إذا كان عملك قائمًا على terminal، جرّب GPT-5.5.

لماذا Composer 2.5 أرخص بكثير؟

لأنه مبني على قاعدة Kimi K2.5 مفتوحة المصدر وتم ضبطه خصيصًا لحلقة وكيل Cursor. هذا يعطي Cursor تحكمًا أكبر في الجدوى الاقتصادية مقارنة بالنماذج العامة المتقدمة ذات التسعير الأعلى.

هل يمكنني استخدام النماذج الثلاثة داخل Cursor؟

نعم. يمكنك التبديل من محدد النماذج لكل مهمة. وهذا ما يجعل الاستراتيجية الهجينة عملية: Composer 2.5 كافتراضي، مع Opus 4.7 و GPT-5.5 للحالات التي تستفيد منهما. راجع دليل Cursor Composer 2.5 للإعداد.

الخلاصة

إذا قارنت أعلى أرقام المعايير فقط، فلكل من Opus 4.7 و GPT-5.5 نقاط قوة واضحة. لكن إذا قارنت الجودة مقابل الدولار في مهام تطوير يومية، فإن Composer 2.5 هو النموذج الذي يجب أن تبدأ به معظم الفرق كخيار افتراضي.

النهج العملي:

ابدأ بـ Composer 2.5
ارفع إلى Opus 4.7 عند الحاجة لتفكير أعمق
استخدم GPT-5.5 عندما تهيمن terminal على المهمة
تحقق من أي كود API باستخدام مواصفاتك الحقيقية وطلبات فعلية

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

كيفية بناء واجهات برمجة التطبيقات باستخدام Cursor Composer 2.5

Yusuf Khalidd — Tue, 19 May 2026 02:26:56 +0000

Cursor Composer 2.5 سريع ورخيص بما يكفي ليكتب وكيل AI عملاء API ومعالجات مسارات كاملة. لكن المشكلة تبدأ عند لمس خدمة حقيقية: قد يولّد النموذج طلبًا نظيفًا إلى /v2/orders بينما خدمتك تستخدم فعليًا /orders وتتوقع حمولة مختلفة. الكود يتجمّع، لكنه يفشل وقت التشغيل.

جرّب Apidog اليوم

في هذا الدليل ستبني سير عمل عمليًا يقلل هذه الأخطاء: اربط Composer 2.5 بمواصفات API الحقيقية عبر MCP، اجعله يولّد الكود بناءً على العقد الفعلي، ثم اختبر النتيجة في Apidog قبل أن تصل إلى زميل في الفريق. إذا كنت جديدًا على النموذج، فراجع دليل Cursor Composer 2.5.

لماذا تخمّن النماذج الوكيلة أشكال API؟

Composer 2.5 مصمم لمهام الوكيل الطويلة متعددة الخطوات. يمكنك أن تطلب منه:

أضف عميلًا لخدمة الفوترة واربطه بسير عمل الدفع.

سيخطط، يعدّل عدة ملفات، ويشغّل الاختبارات حتى تنجح. هذه ترقية مفيدة عن Composer 2.

لكن المشكلة بنيوية: إذا لم يمتلك النموذج عقد API داخل السياق، فسيملأ الفراغ بما يراه “الأكثر احتمالًا”:

أسماء حقول شائعة.
اتفاقيات REST عامة.
بادئات إصدار مثل /v1 أو /v2.
أنماط مصادقة افتراضية.

النتيجة تبدو صحيحة في مراجعة الكود، لكنها تفشل أمام خادمك لأن خادمك لا يمثل “متوسط” واجهات API على الإنترنت.

أعراض شائعة:

نقطة نهاية قريبة لكن خاطئة: /api/users/{id} بدلًا من /users/{userId}.
حقول مخترعة داخل body.
مصادقة عامة بدل المخطط الفعلي لخدمتك.

يمكنك لصق OpenAPI كاملًا في الدردشة، لكن هذا هش ويستهلك السياق بسرعة. الحل الأفضل هو إعطاء النموذج وصولًا منظمًا للمواصفات.

الحل: اربط Composer 2.5 بمواصفات API عبر MCP

بروتوكول سياق النموذج MCP هو معيار مفتوح لإتاحة الأدوات والبيانات لنماذج AI. يدعم Cursor خوادم MCP، ويعرض خادم Apidog MCP مواصفات API الموجودة في Apidog للنموذج كمصدر منظم يمكنه الاستعلام عنه أثناء كتابة الكود.

بدل أن يخمّن Composer 2.5 نقاط النهاية والمخططات والمعاملات، يمكنه قراءتها من العقد الحقيقي ثم كتابة الكود بناءً عليها. هذا هو نفس مبدأ الترميز السلس باستخدام خادم Apidog MCP، لكن مطبق على نموذج قادر على تنفيذ المهمة عبر عدة ملفات.

الخطوة 1: جهّز مواصفات API في Apidog

ابدأ من مصدر حقيقة واضح:

صمّم API في Apidog، أو استورد مواصفات موجودة.
تأكد من تحديث:
- المسارات.
- معاملات query/path/header.
- مخططات request/response.
- أمثلة الاستجابات.
- حالات الخطأ مثل 400 و401 و422.

إذا كان لديك OpenAPI أو Postman Collection، يمكنك استيرادها إلى Apidog. المهم أن تكون المواصفات دقيقة، لأن Composer 2.5 سيبني الكود بناءً عليها.

الخطوة 2: اربط خادم Apidog MCP بـ Cursor

يقرأ Cursor خوادم MCP من ملف إعداد داخل المشروع، غالبًا:

.cursor/mcp.json

مثال تكوين نموذجي:

{
  "mcpServers": {
    "apidog-api-spec": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--project=<your-project-id>"
      ],
      "env": {
        "APIDOG_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

استبدل:

<your-project-id> بمعرّف مشروعك.
<your-access-token> برمز الوصول الخاص بك.

استخدم الأمر والقيم الدقيقة من دليل إعداد Apidog MCP، لأن الإعدادات قد تختلف حسب حسابك وإصدار الخادم.

بعد حفظ الملف، أعد تشغيل Cursor حتى يحمّل خادم MCP الجديد.

الخطوة 3: تأكد أن Composer 2.5 يرى المواصفات

قبل أن تطلب منه كتابة كود، اختبر الاتصال بسؤال قراءة فقط.

افتح جلسة Agent في Cursor، اختر composer-2.5، ثم اكتب:

باستخدام خادم apidog-api-spec MCP، اذكر نقاط النهاية ضمن مورد الطلبات والحقول المطلوبة لإنشاء طلب.

إذا أعاد نقاط النهاية والحقول الفعلية من مشروعك، فالاتصال يعمل.

إذا أجاب بإجابة عامة أو اخترع مسارات، تحقق من:

اسم الخادم داخل mcp.json.
رمز الوصول.
معرّف المشروع.
أنك أعدت تشغيل Cursor.
أن المواصفات موجودة ومحدّثة في Apidog.

الخطوة 4: اجعله يولّد الكود وفقًا للعقد

الآن أعطه المهمة الحقيقية، واذكر مصدر MCP صراحةً:

باستخدام خادم apidog-api-spec كمصدر للحقيقة، اكتب عميل TypeScript مكتوبًا لواجهة orders API.

المطلوب:
- دالة createOrder.
- دالة getOrder.
- مطابقة مخططات الطلب والاستجابة بدقة.
- معالجة خطأ التحقق 422 كما تحدده المواصفات.
- عدم افتراض أي مسار أو حقل غير موجود في المواصفات.

صياغة مثل “كمصدر للحقيقة” مهمة لأنها تقلل انجراف النموذج إلى الأنماط العامة.

مثال هيكل ناتج متوقع:

export async function createOrder(input: CreateOrderRequest): Promise<OrderResponse> {
  const response = await fetch("/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(input)
  });

  if (response.status === 422) {
    const error = await response.json();
    throw new ValidationError(error);
  }

  if (!response.ok) {
    throw new Error(`Create order failed: ${response.status}`);
  }

  return response.json();
}

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

تحقق قبل أن تثق: حلقة اختبار Apidog

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

استخدم هذه الحلقة:

شغّل الطلبات المولّدة كطلبات حقيقية

خذ نقاط النهاية التي كتبها Composer 2.5 وشغّلها في Apidog مقابل بيئة حقيقية أو mock. تحقق من:
- status code.
- response body.
- headers.
- المصادقة.
- حالات الخطأ.
حوّل الطلبات الصحيحة إلى اختبارات

احفظ الطلبات التي تم التحقق منها كسيناريوهات اختبار تلقائية. بهذه الطريقة، يلتقط CI الانحدار بدلًا من المستخدم.
استخدم mock لما لم يُبنَ بعد

إذا كتب النموذج عميلًا لنقطة نهاية لم تُشحن بعد من الخلفية، يمكن لخادم Apidog الوهمي إرجاع استجابات واقعية حتى يستمر عمل الواجهة الأمامية. هذا يتوافق مع الأنماط المذكورة في عملاء الذكاء الاصطناعي واختبار API.

القاعدة العملية:

النموذج يكتب المسودة الأولى وفقًا للعقد، وأنت تتحقق من أنها تعمل أمام خادم حقيقي.

مثال عملي: إضافة ميزة استرداد أموال

لنفترض أنك تضيف ميزة refund إلى خدمة المدفوعات.

1. جهّز العقد

تأكد أن مشروع Apidog يحتوي على:

نقطة نهاية إنشاء استرداد.
مخطط request.
مخطط response.
رأس idempotency-key إذا كان مطلوبًا.
حالات الخطأ، مثل 409 عند التكرار.

2. اطلب من Composer 2.5 التنفيذ

استخدم مطالبة صريحة:

باستخدام apidog-api-spec، أنشئ refund client وخطاف React يستدعيه.

التزم بالتالي:
- اتبع مخطط create-refund بدقة.
- أرسل رأس idempotency-key كما تتطلب المواصفات.
- عالج 409 عند تكرار الطلب.
- أضف أنواع TypeScript من العقد.
- لا تضف حقولًا غير موجودة في المواصفات.

3. راجع الملفات الناتجة

توقع أن يعدّل ملفات مثل:

src/api/refunds.ts
src/hooks/useCreateRefund.ts
src/types/refunds.ts

راجع تحديدًا:

هل المسار صحيح؟
هل body مطابق للمخطط؟
هل idempotency-key موجود؟
هل معالجة 409 مطابقة للمواصفات؟

4. اختبر في Apidog

افتح Apidog وشغّل:

طلب create-refund صالح.
نفس الطلب مرة ثانية بنفس idempotency-key.
تحقق من سلوك 409 عند التكرار.
احفظ السيناريوهات كاختبارات.

ما تجنبته هنا: عميل ينسى رأس المثابرة، فيسمح باسترداد مكرر في بيئة اختبار أو إنتاج.

قائمة تحقق سريعة

قبل دمج الكود الذي كتبه Composer 2.5، تحقق من الآتي:

[ ] خادم MCP يعمل داخل Cursor.
[ ] النموذج قرأ نقاط النهاية من Apidog، لا من المعرفة العامة.
[ ] المسارات مطابقة للمواصفات.
[ ] request body لا يحتوي حقولًا مخترعة.
[ ] المصادقة مطابقة للعقد.
[ ] حالات الخطأ المهمة معالجة.
[ ] الطلبات شُغّلت في Apidog.
[ ] الطلبات الصحيحة حُفظت كاختبارات.

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

هل يدعم Composer 2.5 بروتوكول MCP؟

نعم. لديه وصول إلى أدوات الوكيل في Cursor، بما في ذلك خوادم MCP. حدده من منتقي النموذج، ثم عرّف خادم MCP داخل مشروعك. راجع دليل Composer 2.5 لمعرفة كيفية اختيار النموذج.

هل أحتاج إلى Apidog لاستخدام MCP مع Composer 2.5؟

تحتاج إلى مصدر مواصفات منظم. خادم Apidog MCP هو المسار المستخدم هنا لأنه يجمع المواصفات، الاختبار، والمحاكاة في مكان واحد. توجد خيارات أخرى ضمن أفضل خوادم MCP لـ Cursor.

هل يمنع هذا كل هلوسات النموذج؟

لا. لكنه يزيل فئة كبيرة من الأخطاء: المسارات والمخططات والحقول الخاطئة. لا يزال الاختبار ضروريًا لأن المواصفات قد تنحرف عن الخدمة الفعلية.

هل يستحق الإعداد لمشروع صغير؟

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

الخلاصة

Composer 2.5 مفيد عندما يكتب كود API وفقًا لعقدك الفعلي، لا وفق أنماط عامة. اربط مواصفاتك عبر خادم Apidog MCP حتى يقرأ النموذج الحقيقة، ثم استخدم Apidog لإرسال الطلبات، تأكيد الاستجابات، وتحويل السيناريوهات الصحيحة إلى اختبارات ومحاكاة. هذا هو سير العمل العملي: توليد قائم على المواصفات، ثم تحقق قبل الدمج.

مؤلف المؤشر 2.5: ما هو، كيفية استخدامه، وكيفية الوصول إليه

Yusuf Khalidd — Tue, 19 May 2026 02:25:56 +0000

أطلقت Cursor نموذج Composer 2.5 في 18 مايو 2026. الفكرة العملية للمطورين واضحة: نموذج برمجة يقترب من Opus 4.7 وGPT-5.5 في معايير برمجية حقيقية، مع تكلفة أقل من دولار واحد لكل مهمة في نتائج Cursor المعلنة. إذا كنت تستخدم وكلاء البرمجة يوميًا، فهذا يغيّر طريقة توزيع المهام بينك وبين النموذج.

جرّب Apidog اليوم

في هذا الدليل ستتعرف على: ما هو Composer 2.5، كيف تفعّله داخل Cursor، وكيف تستخدمه في مهام إنتاجية حقيقية، خصوصًا عند توليد كود يتعامل مع API باستخدام مواصفات فعلية بدل التخمين.

ما هو Cursor Composer 2.5؟

Composer 2.5 هو نموذج برمجة عامل داخل Cursor. وظيفته ليست فقط اقتراح أسطر كود، بل تنفيذ مهام متعددة الخطوات: قراءة الملفات، تعديلها، تشغيل أوامر الطرفية، والتحقق من النتيجة داخل المحرر.

إنه خليفة Composer 2، والفرق الأساسي أنه أقرب إلى وكيل قادر على إكمال مهمة طويلة بدل أن يكون مجرد مساعد إكمال سريع.

أهم النقاط التقنية:

بُني على نقطة التحقق مفتوحة المصدر Moonshot Kimi K2.5، وهي قاعدة بحوالي تريليون معلمة.
خصصت Cursor نحو 85% من حوسبة التدريب للتدريب اللاحق والتعلم المعزز.
تم تدريبه على 25 ضعفًا من المهام التركيبية مقارنة بـ Composer 2، بما في ذلك مهام حذف ميزة وإعادة بنائها حتى تنجح الاختبارات.

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

إذا أردت خلفية أعمق عن الأساس الذي يبني عليه هذا الإصدار، راجع دليل Composer 2.

ماذا تغير تحت الغطاء؟

ثلاثة تغييرات تفسر التحسن:

تعلم معزز موجه بتغذية راجعة نصية

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

زيادة المهام التركيبية 25 ضعفًا تعني تدريبًا أكثر على سيناريوهات قريبة من المستودعات الحقيقية، مع التحقق عبر الاختبارات.
بنية تدريب أسرع باستخدام Muon وHSDP

هذه ليست ميزة تستخدمها مباشرة، لكنها تسمح بتكرارات تدريب أسرع على نموذج كبير، ما ينعكس على جودة سلوك الوكيل.

كمستخدم، لا تحتاج إلى حفظ التفاصيل. ما يهمك هو أن النموذج صار أنسب لمهام مثل:

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

معايير Composer 2.5: ما مدى جودته؟

تعرض Cursor نتائج تقارن Composer 2.5 مع Opus 4.7 وGPT-5.5:

المعيار	Composer 2.5	Opus 4.7	GPT-5.5
SWE-bench متعدد اللغات	79.8%	80.5%	77.8%
Terminal-Bench 2.0	69.3%	69.4%	82.7%
CursorBench v3.1	63.2%	64.8% حد أقصى / 61.6% افتراضي	59.2% افتراضي

كيف تقرأ هذه الأرقام عمليًا؟

في SWE-bench متعدد اللغات، يحقق Composer 2.5 نتيجة 79.8%، قريبًا جدًا من Opus 4.7 ومتقدمًا على GPT-5.5.
في CursorBench، يتفوق على إعداد Opus 4.7 الافتراضي.
في Terminal-Bench 2.0، يتأخر بوضوح عن GPT-5.5، لذلك انتبه إذا كان عملك يعتمد بكثافة على سلاسل أوامر طرفية طويلة.

النقطة الأهم ليست أنه يفوز في كل معيار، بل أنه يقدّم جودة قريبة من النماذج الرائدة بتكلفة أقل بكثير لكل مهمة. توصلت تغطية مستقلة من The Decoder إلى النتيجة نفسها: جودة قريبة من المستوى الرائد بجزء من التكلفة.

كم يكلف Composer 2.5؟

تقدم Cursor نوعين من Composer 2.5:

النوع	الإدخال	الإخراج	متى تستخدمه؟
القياسي	$0.50 / مليون رمز	$2.50 / مليون رمز	للمهام الطويلة والحساسة للتكلفة
السريع	$3.00 / مليون رمز	$15.00 / مليون رمز	للتكرار المباشر عندما يهمك زمن الاستجابة

النوع السريع يقدّم نفس الذكاء مع زمن استجابة أقل، وهو عادة الإعداد الافتراضي في المنتج.

طريقة الفوترة تعتمد على خطتك:

الخطط الفردية مثل Pro تتضمن مجمع استخدام Composer مستقلًا.
خطط الفرق والمؤسسات تُحاسب بسعر API مباشرة.
عرض الإطلاق: ضاعفت Cursor استخدام Composer 2.5 للأسبوع الأول بعد الإصدار.

للتفاصيل، راجع دليل تسعير Cursor Composer. وإذا أردت تجربة الاستخدام المضمن قبل الدفع، اقرأ شرح استخدام Composer مجانًا.

كيفية الوصول إلى Cursor Composer 2.5

اتبع هذه الخطوات داخل Cursor:

حدّث Cursor

افتح Cursor وتحقق من التحديثات. على macOS من قائمة Cursor، وعلى الأنظمة الأخرى من قائمة Help. أعد التشغيل بعد التحديث.
سجّل الدخول إلى حساب مناسب

خطط Pro وBusiness تتضمن استخدام Composer. الحساب المجاني قد يسمح بالتجربة عبر البدلات المضمنة، لكن الاستخدام الكثيف يحتاج خطة مدفوعة.
افتح منتقي النموذج

ابدأ جلسة Chat أو Agent، ثم افتح قائمة النماذج.
اختر النموذج

اختر:

composer-2.5

استخدم وضع Agent لا تستخدمه كدردشة عادية إذا كنت تريد تعديلات ملفات وتشغيل اختبارات. Composer 2.5 مصمم للعمل كوكيل.

بعد ذلك يستطيع النموذج استخدام أدوات Cursor المتاحة: قراءة الملفات، تعديلها، تشغيل الطرفية، واستدعاء الأدوات. راجع وثائق Composer 2.5 الرسمية لمعرفة الإعدادات الحالية إذا تغيرت.

إذا كنت جديدًا على واجهة الوكيل في Cursor، ابدأ من نظرة Cursor 2.0.

كيفية استخدام Composer 2.5 بفعالية

الوصول إلى النموذج سهل. جودة النتائج تعتمد على طريقة صياغة المهمة.

1. أعطه مهمة كاملة لا تعليمات صغيرة

بدلًا من:

عدّل هذا الملف.

اكتب:

أضف ترقيم صفحات إلى endpoint الطلبات.
حدّث service وcontroller والاختبارات.
يجب أن تقبل الصفحة page وlimit.
تأكد أن جميع الاختبارات الحالية تستمر بالنجاح.

النموذج أفضل عندما تعطيه حالة نهائية واضحة.

2. اكتب شرط النجاح

مثال جيد:

اعتبر المهمة مكتملة فقط إذا:
- نجحت جميع الاختبارات الحالية.
- أُضيفت اختبارات للحالة الجديدة.
- تعيد نقطة النهاية 422 عند تمرير limit غير صالح.
- لا يتغير شكل الاستجابة الحالي إلا بإضافة pagination metadata.

هذا يدفع النموذج للتحقق بدل الاكتفاء بتعديل الكود.

3. اختر النوع حسب سير العمل

استخدم:

Standard عندما تطلب مهام طويلة أو دفعات عمل.
Fast عندما تنتظر الرد أثناء التطوير المباشر.

الجودة نفسها، لكنك توازن بين الزمن والتكلفة.

4. لا تجعله يخمن شكل API

أكبر خطأ في مهام API هو أن النموذج قد يخترع endpoint أو حقلًا أو طريقة مصادقة تبدو منطقية لكنها غير موجودة.

إذا كتبت:

اكتب client لخدمة المدفوعات.

قد ينتج كودًا نظيفًا لكنه مبني على افتراضات.

الأفضل:

استخدم مواصفات OpenAPI المرفقة لخدمة المدفوعات.
أنشئ TypeScript client للعمليات التالية فقط:
- إنشاء دفعة
- جلب حالة دفعة
- إلغاء دفعة
ثم أضف اختبارات تغطي 200 و400 و401.

Composer 2.5 مع سير عمل API

معظم مهام البرمجة الإنتاجية تلمس API بشكل مباشر. لذلك تحتاج إلى حلقة عمل تمنع التخمين:

أعطِ النموذج مواصفات API الحقيقية.
اجعله يولّد الكود والاختبارات بناءً على المواصفات.
اختبر الطلبات فعليًا.
ثبّت السلوك الناجح في اختبارات أو mock server.

يمكنك ربط مواصفات API في Apidog مع Cursor عبر خادم Apidog MCP، بحيث يكتب Composer 2.5 الكود اعتمادًا على المخطط الحقيقي لا على التخمين. وإذا كنت تستخدم وكلاء أخرى، راجع أفضل خوادم MCP لـ Cursor.

بعد توليد الكود، افتح الطلبات في Apidog، وأرسل طلبات حقيقية، وتحقق من:

رموز الحالة.
شكل الاستجابة.
المصادقة.
رسائل الخطأ.
الحالات الحدية.

الفكرة ليست أن النموذج لا يخطئ، بل أن تجعل الخطأ يُكتشف قبل أن يصل إلى فرع زميلك.

مثال عملي لمطالبة جيدة

استخدم قالبًا مثل هذا عند العمل على API:

أنت تعمل داخل مستودع Node.js/TypeScript.

المطلوب:
أضف دعم endpoint جديد لجلب طلبات المستخدم مع pagination.

المصدر الحقيقي:
استخدم مواصفات API المتاحة عبر MCP ولا تخترع حقولًا غير موجودة.

الخطوات:
1. افحص بنية المشروع الحالية.
2. حدّد الملفات التي تحتاج تعديلًا.
3. أضف types بناءً على schema الحقيقي.
4. أضف client method للطلب الجديد.
5. أضف اختبارات تغطي:
   - استجابة ناجحة 200
   - page غير صالح
   - limit غير صالح
   - حالة 401
6. شغّل الاختبارات.
7. أصلح أي فشل قبل إنهاء المهمة.

شرط النجاح:
لا تعتبر المهمة منتهية حتى تنجح الاختبارات ويطابق شكل الاستجابة مواصفات API.

هذا النوع من التعليمات يعطي Composer 2.5 مساحة للعمل، لكنه يضع حدودًا واضحة للتحقق.

Composer 2.5 مقابل المنافسة

إذا كنت تختار أداة يومية، استخدم هذا التوجيه السريع:

مقابل Opus 4.7: قريب جدًا في SWE-bench متعدد اللغات وCursorBench، وأرخص بكثير لكل مهمة. ما زال Opus يتفوق في بعض الإعدادات القصوى.
مقابل GPT-5.5: يتقدم Composer 2.5 في SWE-bench متعدد اللغات وCursorBench، بينما يتفوق GPT-5.5 في Terminal-Bench 2.0.
مقابل Claude Code: Composer 2.5 يعمل داخل محرر Cursor، بينما Claude Code وكيل طرفية. راجع مقارنة Claude Code مقابل Cursor.
مقابل GitHub Copilot: Copilot قوي في الإكمال المدمج، بينما Composer 2.5 أفضل كوكيل لمهام متعددة الملفات. اقرأ دليل Cursor مقابل GitHub Copilot.

ذكرت Cursor أيضًا أنها تدرب نموذجًا أكبر بالتعاون مع xAI باستخدام نحو عشرة أضعاف قوة الحوسبة، لذلك يبدو Composer 2.5 أقرب إلى مرحلة في مسار تطور أكبر، لا نقطة النهاية.

الأسئلة المتكررة

هل Composer 2.5 مجاني؟

لا توجد طبقة مجانية بالكامل، لكن الخطط الفردية تتضمن استخدامًا مدمجًا يغطي كثيرًا من العمل اليومي. راجع دليل استخدام Composer مجانًا.

هل Composer 2.5 أفضل من Composer 2؟

نعم. ارتفع SWE-bench متعدد اللغات من 73.7% إلى 79.8%، وتحسن احتفاظ النموذج بالسياق في المهام الطويلة. راجع دليل Composer 2 لفهم الأساس.

على أي نموذج يعتمد Composer 2.5؟

يعتمد على نقطة التحقق Kimi K2.5 مفتوحة المصدر من Moonshot، ثم دربته Cursor بشكل مكثف باستخدام التعلم المعزز والمهام التركيبية.

أي نوع أختار: القياسي أم السريع؟

اختر القياسي للمهام الطويلة أو المتكررة بتكلفة أقل. اختر السريع عندما تعمل تفاعليًا وتحتاج زمن استجابة أقل. الذكاء نفسه.

هل يعمل Composer 2.5 مع مواصفات API وMCP؟

نعم. يدعم أدوات وكيل Cursor، بما في ذلك MCP. يمكنك ربط مواصفات API عبر خادم Apidog MCP حتى يكتب النموذج الكود بناءً على schema حقيقي.

الخلاصة

Composer 2.5 يجعل استخدام وكيل برمجة قوي داخل Cursor أكثر قابلية للتطبيق اليومي: جودة قريبة من النماذج الرائدة، تكلفة أقل لكل مهمة، وسلوك أفضل في المهام متعددة الخطوات.

للاستخدام العملي:

حدّث Cursor.
اختر composer-2.5.
استخدم وضع Agent.
أعطه مهمة كاملة مع شرط نجاح واضح.
لا تجعله يخمن API.
تحقق من الطلبات والاستجابات قبل الدمج.

عند العمل على APIs، اربطه بمواصفاتك الحقيقية ثم قم بتنزيل Apidog لاختبار الطلبات، تأكيد الاستجابات، وتحويل السلوك الصحيح إلى اختبارات آلية أو mock servers. الكود السريع مفيد فقط عندما يكون قابلًا للتحقق.

Bitwarden Agent Access: كيفية مشاركة بيانات اعتماد الخزنة بشكل آمن مع وكلاء ترميز الذكاء الاصطناعي

Yusuf Khalidd — Fri, 15 May 2026 08:12:21 +0000

إذا كنت تستخدم Claude Code أو Codex أو Cursor مع أي شيء يتصل بواجهة برمجة تطبيقات حقيقية، فالمشكلة العملية هي بيانات الاعتماد: الوكيل يحتاجها، ومدير كلمات المرور لا يريد تسريبها. لصق مفتاح API داخل المحادثة يضعه في سياق النموذج. وضعه في ملف .env يجعله قابلًا للقراءة من أي أمر يشغله الوكيل. الحل الأفضل هو إعطاء الوكيل أقل قدر ممكن من الأسرار، وفي وقت التشغيل فقط.

جرّب Apidog اليوم

مشروع Bitwarden مفتوح المصدر، Agent Access، يحاول حل هذه الفجوة عمليًا. يوفر بروتوكولًا لمشاركة بيانات الاعتماد، وواجهة سطر أوامر باسم aac، وحزم SDK بلغة Rust وPython لبناء نفق مشفر بين مدير كلمات المرور وعملية بعيدة مثل وكيل AI، أو مهمة CI، أو سكريبت محلي.

في هذا الدليل ستتعلم كيف تثبت Agent Access، تستخدم aac connect لجلب بيانات اعتماد محددة النطاق، وتستخدم aac run لحقن الأسرار في بيئة عملية فرعية بدون كشفها للوكيل. هذا يكمل أنماط النظافة الأمنية الموضحة في كيفية تأمين بيانات اعتماد واجهة برمجة تطبيقات وكيل الذكاء الاصطناعي.

ما هو Agent Access؟

Agent Access هو بروتوكول مفتوح وتطبيق مرجعي من Bitwarden، لكنه مصمم بحيث يمكن لأي مدير كلمات مرور تبنيه. يعمل عبر طرفين:

Provider: الجهاز أو الخدمة التي تمتلك الوصول إلى القبو.
Consumer: الوكيل، السكريبت، أو مهمة CI التي تحتاج إلى بيانات اعتماد محددة.

تستخدم أداة aac نفقًا مشفرًا من طرف إلى طرف عبر Noise Protocol. يطلب المستهلك بيانات اعتماد حسب النطاق أو معرف عنصر القبو، ويقرر المزود ما الذي يُرجع. المستهلك لا يرى القبو بالكامل، والمزود لا يحتاج لمعرفة ما الذي ستفعله العملية بالسر بعد استلامه.

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

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

لماذا هذا مهم؟

وكلاء البرمجة لم يعودوا يكتبون كودًا فقط. Claude Code وCodex وCursor يمكنهم قراءة المستودع، تشغيل الاختبارات، استدعاء APIs، وبدء عمليات نشر. كل خطوة قد تحتاج إلى بيانات اعتماد.

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

القاعدة العملية:

لا تثق بالوكيل أكثر. أعطه أقل.

Agent Access يطبق ذلك عبر:

بيانات اعتماد محددة النطاق.
تشفير أثناء النقل.
جلب في وقت التشغيل.
عدم حفظ الأسرار على القرص افتراضيًا.
عزل السر داخل عملية فرعية عند استخدام aac run.

للمقارنة مع أدوات إدارة المفاتيح الأخرى، راجع أدوات إدارة مفاتيح API.

التثبيت

اختر الحزمة المناسبة لنظامك.

macOS Apple Silicon

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-aarch64.tar.gz | tar xz
sudo mv aac /usr/local/bin/

macOS Intel

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/

Linux x86_64

curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-linux-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/

Windows x86_64

نزّل aac-windows-x86_64.zip من صفحة الإصدارات، ثم استخرجه إلى مجلد موجود في متغير PATH.

تحقق من التثبيت:

aac --help

إذا كان Bitwarden CLI (bw) موجودًا في PATH، فسيستخدمه aac كمزود افتراضي. للتجربة بدون Bitwarden، استخدم المزود التجريبي:

aac --provider example --help

بدء سريع: الإقران وجلب بيانات الاعتماد

شغّل المستمع على الجهاز الذي لديه الوصول إلى القبو، غالبًا جهازك المحلي:

aac listen

سيطبع الأمر رمز إقران. من جهة المستهلك، نفّذ:

aac connect --token <pairing-token> --domain github.com --output json

الناتج سيكون مشابهًا:

{
  "credential": {
    "notes": null,
    "password": "alligator5",
    "totp": null,
    "uri": "https://github.com",
    "username": "example"
  },
  "domain": "github.com",
  "success": true
}

يمكنك أيضًا الجلب حسب معرف عنصر القبو بدل النطاق:

aac connect --id <vault-item-id> --output json

ملاحظات مهمة:

--id و--domain لا يُستخدمان معًا.
إذا كان عنصر القبو يحتوي على TOTP، فسيظهر ضمن الحمولة.
--output json مناسب للسكريبتات التي تريد تحليل الناتج مباشرة.

مثال بسيط باستخدام jq:

PASSWORD=$(aac connect --domain github.com --output json | jq -r '.credential.password')

لكن انتبه: هذا النمط قد يضع السر في متغير داخل shell. في معظم حالات الوكلاء، استخدم aac run بدلًا من ذلك.

استخدام `aac run` لحقن الأسرار في البيئة

aac run هو النمط الأكثر أمانًا مع وكلاء AI. بدل طباعة السر، يشغل عملية فرعية ويحقن القيم المطلوبة كمتغيرات بيئة.

حقن حقول محددة

aac run --domain example.com \
  --env DB_PASSWORD=password \
  --env DB_USER=username \
  -- psql

في هذا المثال:

قيمة حقل password تصبح DB_PASSWORD.
قيمة حقل username تصبح DB_USER.
العملية الفرعية psql فقط هي التي تستقبل المتغيرات.

حقن كل الحقول

aac run --domain example.com --env-all -- ./deploy.sh

سيتم حقن الحقول المتاحة ببادئة افتراضية مثل AAC_.

دمج `--env-all` مع أسماء مخصصة

aac run --domain example.com \
  --env-all \
  --env CUSTOM_PW=password \
  -- ./deploy.sh

الحقول المتاحة:

username
password
totp
uri
notes
domain
credential_id

نمط عملي مع سكريبت نشر

بدل أن تجعل Claude Code أو Codex يعرف المفتاح، اجعل الوكيل يستدعي سكريبتًا مغلفًا بـ aac run.

# deploy.sh
#!/usr/bin/env bash
set -euo pipefail

aac run --domain api.example.com \
  --env API_TOKEN=password \
  -- ./run-deploy.sh

ثم داخل run-deploy.sh:

#!/usr/bin/env bash
set -euo pipefail

curl -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/deploy

بهذا الشكل:

الوكيل يرى الأمر ./deploy.sh.
السر لا يظهر في المحادثة.
السر لا يُكتب إلى ملف.
السر موجود فقط داخل بيئة العملية الفرعية.

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

استخدام SDKs بلغة Python وRust

إذا كنت تريد تضمين Agent Access داخل تطبيقك بدل استدعاء CLI، يمكنك استخدام SDK.

Python

from agent_access import RemoteClient

client = RemoteClient("python-remote")
client.connect(token="ABC-DEF-GHI")

cred = client.request_credential("example.com")
print(cred.username, cred.password)

client.close()

وحدة Python مبنية فوق PyO3، لذلك يبقى تنفيذ البروتوكول الأساسي في Rust مع توفير واجهة Python.

Rust

توفر حزمة Rust واجهة RemoteClient كمكتبة مباشرة. التطبيقات المرجعية موجودة في المستودع تحت:

examples/rust-remote/

استخدم Rust SDK عندما تبني:

CLI مخصصًا.
build runner.
خدمة داخلية توزعها كثنائي compiled.
أداة تحتاج إلى دمج Agent Access بدون shell wrapper.

إذا كان فريقك يستخدم أدوات مثل HashiCorp Vault أو Azure Key Vault، فاعتبر Agent Access طبقة مناسبة أكثر لحالات أجهزة المطورين ومشغلات CI، وليس بديلًا كاملًا لخزائن الأسرار المؤسسية.

التكامل مع وكلاء برمجة الذكاء الاصطناعي

Claude Code

اجعل Claude Code يستدعي سكريبتًا بدل التعامل مع السر مباشرة:

# deploy.sh
#!/usr/bin/env bash
set -euo pipefail

aac run --domain prod.example.com --env-all -- ./run-deploy.sh

أضف السكريبت إلى مشروعك، ثم وجّه سير العمل إليه. الوكيل ينفذ:

./deploy.sh

ولا يرى بيانات الاعتماد.

يمتد نفس النمط إلى CI مع Claude Code GitHub Actions: ثبّت aac في runner، اربطه بمزود القبو، واجعل خطوات النشر أو الاختبار تعمل عبر aac run.

OpenAI Codex

في Codex CLI، يرى النموذج الأوامر التي سيستدعيها. لذلك لا تمرر المفتاح داخل الأمر. استخدم wrapper:

# test-api.sh
#!/usr/bin/env bash
set -euo pipefail

aac run --domain staging.example.com \
  --env API_KEY=password \
  -- npm run test:api

بهذا يبقى المفتاح خارج سياق النموذج. للمزيد حول استخدام Codex في سيناريوهات أوسع، راجع Codex من هاتفك.

Cursor

مع أوامر الطرفية وComposer في Cursor، استخدم نفس السكريبتات المغلفة بـ aac run. غالبًا سيكون المستمع والمستهلك على نفس الجهاز لأن Cursor يركز على التحرير المحلي.

مثال:

aac run --domain dev.example.com \
  --env DATABASE_URL=uri \
  -- npm run dev

OpenClaw

يوفر Agent Access مهارة OpenClaw رسمية جاهزة للاستخدام، وملف SKILL.md موجود في المستودع. إذا كنت تستخدم مهارات على نمط OpenClaw، فهذا هو التكامل الأكثر مباشرة: المهارة تعرف البروتوكول، تجلب بيانات الاعتماد، ثم تمررها للأداة التابعة.

راجع أيضًا دليل مفاتيح API لـ OpenClaw.

نموذج الأمان

ثلاث نقاط يجب فهمها قبل الاعتماد على Agent Access:

تشفير من طرف إلى طرف عبر Noise

الاتصال بين المستهلك والمزود مشفر باستخدام Noise Protocol Framework، وهي نفس عائلة المصافحة التي تستخدمها أنظمة مثل WireGuard وSignal.
بيانات اعتماد محددة النطاق

المستهلك يطلب نطاقًا واحدًا أو عنصر قبو واحدًا. لا يحصل على إمكانية تعداد القبو بالكامل.
لا أسرار على قرص المستهلك افتراضيًا

مع aac run، تُمرر الأسرار كمتغيرات بيئة إلى عملية فرعية. لا تُكتب إلى ملف، ولا تظهر في stdout، ولا تُسجل في shell history إذا لم تطبعها أنت.

ما لا يحميك منه Agent Access:

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

نمط CI عملي: الوكيل يكتب، Apidog يختبر

نمط العمل المفيد لمعظم الفرق:

الوكيل يكتب الكود

Claude Code أو Codex أو Cursor يفتح PR يضيف استدعاء API أو يغير عقدًا.
CI يشغل الاختبارات

runner يستخدم aac run لجلب مفتاح API محدد النطاق وتشغيل اختبارات التكامل.
Apidog يتحقق من العقد

Apidog يشغل اختبارات OpenAPI أو اختبارات العقد كخطوة منفصلة في CI، أيضًا عبر aac run.

مثال مبسط:

aac run --domain staging-api.example.com \
  --env API_TOKEN=password \
  -- npm run test:contract

النتيجة:

الوكيل يشحن الكود.
اختبارات API تتحقق من العقد.
السر لا يظهر في سياق النموذج.
المفتاح لا يُحفظ في المستودع.

للتوسع في هذا النمط، راجع كيفية اختبار وكلاء الذكاء الاصطناعي الذين يستدعون واجهات برمجة التطبيقات الخاصة بك.

القيود والتحذيرات

المشروع في معاينة مبكرة

واجهات API والبروتوكول قابلة للتغيير. لا تبنِ سير عمل إنتاجيًا حساسًا بدون توقع تغييرات لاحقة.
يعتمد افتراضيًا على Bitwarden CLI

ثبّت Bitwarden CLI إذا أردت استخدام قبو Bitwarden. للتجارب، استخدم --provider example.
لا يوجد ملف إعداد ثابت حتى الآن

يتم التحكم في السلوك عبر flags، لذلك يفضل تغليف الاستدعاءات المتكررة داخل سكريبتات.
لا تطبع الأسرار

حتى مع aac run، يمكن لسكريبتك أن يطبع المتغيرات بالخطأ. تجنب set -x في سكريبتات تحتوي على أسرار.
لا تلصق الأسرار في Prompts

إذا وضعت المفتاح يدويًا في محادثة LLM، فلن ينقذك أي بروتوكول.

أسئلة شائعة

هل Agent Access مجاني؟

نعم. CLI وSDKs والبروتوكول مفتوحة المصدر ضمن منظمة Bitwarden على GitHub. إذا استخدمت Bitwarden كقبو، فتنطبق عليك شروط وتسعير Bitwarden نفسه.

هل يعمل مع مديري كلمات مرور غير Bitwarden؟

البروتوكول مصمم ليكون محايدًا للموردين. التطبيق المرجعي يدعم Bitwarden ومزودًا تجريبيًا. يمكن لموردين آخرين إضافة مزوداتهم لاحقًا.

هل يمكن استخدامه بدون مدير كلمات مرور؟

للاختبار نعم:

aac connect --provider example --domain test.com --output json

للإنتاج، تحتاج إلى مزود حقيقي مثل Bitwarden.

هل يحتاج المستهلك إلى الشبكة؟

نعم. المستهلك يحتاج إلى الوصول إلى مستمع المزود. إذا كان الاثنان على نفس الجهاز، يمكن استخدام إعداد محلي.

كيف يختلف عن ملف `.env`؟

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

هل يحل محل HashiCorp Vault أو AWS Secrets Manager؟

لا. الخزائن المؤسسية ما زالت مناسبة للأسرار بين الخدمات وعلى نطاق واسع. Agent Access يعالج فجوة مختلفة: أجهزة المطورين، وكلاء AI، ومشغلات CI التي تحتاج إلى سر محدد في وقت التشغيل.

هل ستدمجه Anthropic أو OpenAI مباشرة؟

لم يُعلن عن دعم مباشر. نموذج التكامل الحالي هو تغليف أوامرك وسكريبتاتك باستخدام aac run.

أين أبلغ عن الأخطاء أو أساهم؟

استخدم مستودع GitHub. المشكلات، طلبات السحب، ومناقشات البروتوكول تتم هناك.

جرّبه الآن

ابدأ بأصغر حلقة ممكنة:

aac listen

ثم من طرفية أخرى:

aac connect --provider example --domain test.com --output json

بعد التأكد من عودة JSON، انتقل إلى Bitwarden CLI، ثم غلّف سكريبتًا حقيقيًا:

aac run --domain api.example.com \
  --env API_KEY=password \
  -- ./run-tests.sh

استخدم Agent Access لحماية الأسرار، وApidog لاختبار واجهات API والعقود. بهذه البنية: القبو يحتفظ بالسر، Apidog يتحقق من API، والوكيل يكتب الكود بدون أن يرى بيانات الاعتماد.

أفضل 7 أدوات لإدارة واجهات برمجة التطبيقات API في 2026، مصنفة حسب G2

Yusuf Khalidd — Fri, 15 May 2026 07:39:45 +0000

لقد صدرت شبكة G2 للربيع 2026 لإدارة واجهات برمجة التطبيقات (API Management). تضم قائدين: Apidog و viaSocket، وثلاثة أصحاب أداء عالٍ: Traefik Labs و Rasayel و Backendless، واثنين من اللاعبين المتخصصين: Moesif/WSO2 و Thunder Client. لكن التصنيف وحده لا يكفي؛ الأهم هو معرفة أي أداة تناسب جزءًا محددًا من دورة حياة الـ API في مكدسك التقني.

جرّب Apidog اليوم

الخلاصة (TL;DR)

تتصدر Apidog و viaSocket شبكة G2 لإدارة واجهات برمجة التطبيقات للربيع 2026.

استخدم هذا التقسيم السريع قبل الاختيار:

تحتاج إلى تصميم، اختبار، محاكاة، وتوثيق API في مساحة واحدة؟ اختر Apidog.
تحتاج إلى ربط أدوات SaaS بدون كود؟ اختر viaSocket.
تحتاج إلى بوابة API سحابية أصلية مع Kubernetes/GitOps؟ انظر إلى Traefik Labs.
تحتاج إلى API حول واتساب للأعمال؟ Rasayel مناسبة.
تريد بناء Backend كامل منخفض الكود؟ Backendless.
لديك API منشورة وتحتاج إلى تحليلات وتحقيق دخل؟ Moesif.
تريد اختبار REST داخل VS Code كمطور منفرد؟ Thunder Client.

ما تشير إليه شبكة G2 للربيع 2026

أصدرت تقارير G2 للربيع 2026 27,019 تقريرًا في 17 مارس 2026، بزيادة ربع سنوية قدرها 1.72%. وفقًا لـ G2، تحصل نسبة صغيرة فقط من المنتجات على شارة "القائد"، لذلك يمكن اعتبارها إشارة مفيدة، لكنها ليست بديلًا عن تقييم المتطلبات التقنية.

تعتمد الشبكة على محورين:

رضا العملاء: مستند إلى المراجعات.
وجود السوق: الحجم، الانتشار، وحجم المراجعات.

في فئة إدارة واجهات برمجة التطبيقات للربيع 2026، تظهر Apidog و viaSocket كـ "قادة". وتظهر Traefik Labs و Rasayel و Backendless كـ "أصحاب أداء عالٍ". أما Moesif، وهي الآن شركة تابعة لـ WSO2، و Thunder Client فتقعان في فئة "متخصصة".

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

الأدوات السبع في لمحة

الأداة	ربع G2	أفضل استخدام	مفتوح المصدر؟	نموذج التسعير
Apidog	قائد	تصميم واجهات برمجة التطبيقات، اختبارها، محاكاتها، وتوثيقها في مساحة واحدة	طبقة مجانية + مدفوعة	SaaS لكل مستخدم
viaSocket	قائد	أتمتة سير العمل بدون كود مع ربط واجهات برمجة التطبيقات	لا	خطة دخول 50 دولار/شهر
Traefik Labs	عالي الأداء	بوابة واجهات برمجة التطبيقات السحابية الأصلية + حوكمة GitOps	نعم، Proxy OSS	مفتوح المصدر مجاني، Hub مدفوع
Rasayel	عالي الأداء	رسائل واتساب للأعمال + REST API	لا	SaaS لكل مقعد
Backendless	عالي الأداء	BaaS مع REST و GraphQL تلقائية التوليد	لا	طبقة مجانية + مدفوعة
Moesif (WSO2)	متخصص	تحليلات واجهات برمجة التطبيقات، المراقبة، وتحقيق الدخل	لا	حسب الاستخدام
Thunder Client	متخصص	عميل REST داخل VS Code	لا	مجاني + ميزات مدفوعة

المشكلة أن فئة G2 تجمع أدوات مختلفة جدًا: منصات دورة حياة API، أدوات iPaaS، بوابات، تحليلات، وامتدادات IDE. لذلك لا تقارن الأدوات كأنها بدائل مباشرة دائمًا؛ قارنها حسب المرحلة التي تريد إدارتها.

Apidog: الرائد لسير عمل واجهات برمجة التطبيقات الشامل

استحقت Apidog مكانها لأنها تجمع أربع مراحل شائعة في مساحة عمل واحدة:

تصميم API.
اختبار API.
محاكاة API.
توثيق API.

بدلًا من كتابة المواصفات في أداة، والاختبارات في أداة أخرى، والتوثيق في مكان ثالث، يمكنك جعل مواصفة OpenAPI هي مصدر الحقيقة المشترك بين الفريق.

ما الذي تحصل عليه عمليًا؟

تصميم مرئي للـ API: محرر OpenAPI 3.0/3.1 يعتمد على المخطط أولًا.
اختبار آلي: بناء سيناريوهات اختبار بصريًا مع إمكانية دمجها في CI/CD.
محاكاة ذكية: استجابات mock يتم توليدها من المخطط.
توثيق تلقائي: نشر وثائق عامة أو خاصة من نفس المصدر.
تعاون الفريق: مزامنة، إصدارات، وأدوار وصول.

مثال سير عمل عملي

ابدأ من مواصفة OpenAPI بسيطة:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                    format: email

ثم نفّذ الخطوات التالية:

استورد ملف OpenAPI إلى Apidog.
راجع المسارات والـ schemas مع الفريق.
أنشئ mock server ليبدأ فريق الواجهة الأمامية قبل اكتمال التنفيذ.
أضف اختبارات تحقق من status code و body schema.
انشر التوثيق من نفس المواصفة.
اربط الاختبارات مع CI/CD عند الحاجة.

يناسب Apidog فرق التطوير التي تريد مصدرًا واحدًا للحقيقة لمواصفات API، خصوصًا عندما يعمل مطورو الخلفية، الواجهة الأمامية، وضمان الجودة على نفس الواجهات. يمكنك تنزيل Apidog واستيراد مجموعة Postman للبدء بسرعة.

viaSocket: الرائد لفرق التكامل بدون كود

viaSocket هو القائد الآخر، لكنه لا يحل نفس مشكلة Apidog. إنه أقرب إلى Zapier أو Make من كونه بوابة API تقليدية. الفكرة هي ربط تطبيقات SaaS عبر webhooks، منطق شرطي، واستدعاءات API مخصصة دون بناء تكامل كامل من الصفر.

منصة أتمتة سير عمل تعتمد على الذكاء الاصطناعي مناسبة عندما تكون المشكلة في ربط الأدوات لا في تصميم API نفسها.

استخدم viaSocket عندما:

تريد ربط CRM بأداة بريد أو نظام دعم.
تحتاج إلى webhook يعالج حدثًا ويرسله إلى تطبيق آخر.
يعمل الفريق غير الهندسي على أتمتة العمليات.
لا تريد بناء خدمة وسيطة لكل تكامل بسيط.

لا تستخدمه كبديل عن:

بوابة API.
اختبار العقود.
إدارة دورة حياة OpenAPI.
تحديد المعدلات أو سياسات OAuth/JWT.
إدارة خدمات مصغرة داخلية.

إذا كانت مشكلتك هي أتمتة SaaS، viaSocket مناسب. إذا كانت مشكلتك هي بناء API ونشرها واختبارها وتوثيقها، فابحث في أدوات دورة الحياة أو البوابات.

Traefik Labs: بوابة مفتوحة المصدر مع إدارة واجهات برمجة التطبيقات

Traefik Proxy معروف كوكيل سحابي مفتوح المصدر. أما Traefik Hub فهو الطبقة التجارية التي تضيف قدرات إدارة API مثل بوابات المطورين، عناصر التحكم في دورة الحياة، وحوكمة GitOps.

أين يلمع Traefik؟

Kubernetes Ingress.
اكتشاف الخدمات.
التكوين الديناميكي.
شهادات Let's Encrypt التلقائية.
إدارة المسارات والسياسات عبر GitOps.
تشغيله عند حافة النظام كبوابة أو reverse proxy.

مثال ذهني للبنية

Client
  |
  v
Traefik Gateway
  |
  +--> users-service
  +--> billing-service
  +--> notifications-service

في هذا السيناريو، Traefik يقرر التوجيه والسياسات، بينما تحتاج أداة أخرى لتصميم العقود واختبارها. لذلك قد تستخدم Traefik كبوابة، وApidog أعلى منه للتصميم والاختبار والتوثيق.

Rasayel: منصة واتساب للأعمال API مع نطاق واضح

Rasayel في جوهرها منصة واتساب للأعمال مع صندوق بريد للفريق، روبوتات دردشة، ورسائل جماعية. وجودها في فئة API Management يعود إلى واجهات REST و GraphQL، وإدارة مفاتيح API، والـ webhooks.

اختر Rasayel إذا كنت:

تدير دعم العملاء أو المبيعات على واتساب.
تحتاج إلى صندوق بريد مشترك للفريق.
تريد ربط واتساب بـ HubSpot أو Pipedrive.
تحتاج إلى webhooks وأتمتة حول محادثات واتساب.

تخطَّ Rasayel إذا كنت:

تدير خدمات مصغرة داخلية.
تحتاج إلى API Gateway عامة.
لا تستخدم واتساب في سير عملك.
تبحث عن منصة تصميم واختبار API عامة.

Rasayel ليست منصة API عامة لكل فريق، لكنها مناسبة جدًا إذا كان واتساب هو قناة التشغيل الأساسية.

Backendless: BaaS مع واجهات REST و GraphQL تلقائية التوليد

Backendless هي منصة Backend-as-a-Service تولد نقاط نهاية REST و GraphQL من نموذج البيانات والخدمات التي تعرفها داخل المنصة.

الفكرة العملية:

تعرّف جدولًا أو نموذج بيانات.
تحصل على API تلقائية.
تضبط الأدوار والصلاحيات.
تستخدم SDKs أو REST/GraphQL من تطبيقك.

نقاط القوة

بناء Backend منخفض الكود.
SDKs لأنظمة Android و iOS و JavaScript و .NET.
صلاحيات على مستوى العمليات.
تتبع استدعاءات الخدمات.
مناسب للنماذج الأولية والتطبيقات الصغيرة والمتوسطة.

متى لا يكون الخيار المناسب؟

لديك Backend قائم بالفعل وتحتاج فقط إلى بوابة أمامه.
تريد تصميم API بالعقد أولًا قبل نموذج البيانات.
تريد تجنب الارتباط بمنصة BaaS.
تحتاج إلى بنية داخلية مخصصة جدًا.

استخدم Backendless عندما تريد تقليل بناء الواجهة الخلفية نفسها، لا عندما تريد إدارة واجهات قائمة بالفعل.

Moesif (شركة تابعة لـ WSO2): تحليلات واجهات برمجة التطبيقات وتحقيق الدخل

Moesif أداة متخصصة في تحليلات API، المراقبة، وتحقيق الدخل. استحوذت WSO2 على Moesif في مايو 2025 وتقوم بدمجها كطبقة تحليلية لمنصة Choreo، مع استمرار Moesif ككيان مستقل.

ما الذي تفعله Moesif؟

تحليل استخدام API حسب المستخدم.
تحليل الاستدعاءات حسب endpoint.
كشف أنماط الاستخدام غير الطبيعية.
دعم نماذج تسعير مبنية على الاستخدام.
لوحات تحكم للعملاء والمطورين.
تحليلات الاحتفاظ والمسارات لمستهلكي API.

مثال قرار

استخدم Moesif إذا كان لديك سؤال مثل:

أي عميل يستهلك أكثر endpoints؟
ما هي أكثر الأخطاء شيوعًا لكل خطة؟
هل يمكننا فوترة العملاء حسب عدد الاستدعاءات؟

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

Thunder Client: إضافة عميل REST لـ VS Code

Thunder Client هو امتداد لـ VS Code لإرسال طلبات HTTP من داخل المحرر. يشبه Postman أو Insomnia، لكنه أخف ومباشر للمطور الفردي.

جيد في:

اختبار REST دون مغادرة VS Code.
حفظ المجموعات كـ JSON داخل المستودع.
استخدام متغيرات بيئة.
كتابة اختبارات وتأكيدات بسيطة.
تشغيل طلبات سريعة أثناء التطوير.

ليس مناسبًا لـ:

تعاون فرق كبير.
تصميم API بالعقد أولًا.
توليد وثائق.
تشغيل mock server شامل.
إدارة دورة حياة API كاملة.

راجع أيضًا: Thunder Client للفرق: قيود التعاون.

إذا كانت "إدارة API" لديك تعني اختبار endpoint أثناء كتابة الكود، Thunder Client كافٍ. إذا احتجت إلى تصميم، محاكاة، توثيق، وتعاون، فستحتاج إلى منصة أوسع مثل Apidog.

كيف تختار الأداة المناسبة لفريقك؟

ابدأ بالسؤال الصحيح: ما الجزء الذي تريد إدارته من دورة حياة API؟

1. حدّد المشكلة الأساسية

المشكلة	الأداة الأقرب
تصميم، اختبار، محاكاة، وتوثيق	Apidog
ربط SaaS و webhooks بدون كود	viaSocket
بوابة API، routing، policies	Traefik
واتساب للأعمال مع API	Rasayel
بناء Backend منخفض الكود	Backendless
تحليلات واستخدام وفوترة	Moesif
اختبار REST داخل VS Code	Thunder Client

2. قيّم حجم الفريق

مطور منفرد: Thunder Client أو الطبقة المجانية من Apidog.
فريق 5–50 شخصًا: Apidog للتصميم والاختبار، أو Backendless إذا كنت تبني Backend كاملًا.
فريق يستخدم Kubernetes: Traefik كبوابة، مع أداة تصميم واختبار منفصلة.
شركة لديها API عامة: بوابة + Moesif للتحليلات + Apidog للعقود والاختبارات.

3. حدّد القيد الرئيسي

المال: الطبقة المجانية من Apidog، Traefik Proxy OSS، وخطط مجانية/دخولية عند الحاجة.
الوقت: Apidog لتقليل تبديل الأدوات، و viaSocket لتكاملات SaaS السريعة.
الحوكمة: Traefik Hub للـ GitOps، Apidog لمراجعة التصميم، Moesif لتحليلات الاستخدام.

للمزيد، اقرأ أداة اختبار واجهات برمجة التطبيقات لفريق من 50 مهندسًا ومنصة واجهة برمجة التطبيقات التي تعتمد على التصميم أولًا.

ماذا تعلمك شبكة G2 للربيع 2026؟

الأدوات السبع في شبكة G2 لإدارة واجهات برمجة التطبيقات للربيع 2026 ليست بدائل مباشرة لبعضها دائمًا. كل أداة تحل طبقة مختلفة من المشكلة.

النقاط الرئيسية:

Apidog و viaSocket قائدان، لكنهما يحلان مشكلتين مختلفتين.
Traefik مناسب للبوابات، وليس للتصميم والاختبار.
Rasayel ممتاز إذا كان واتساب جزءًا أساسيًا من سير العمل.
Backendless مناسب عندما تريد إنشاء Backend بدلًا من إدارته فقط.
Moesif طبقة تحليلات وتحقيق دخل، لا بوابة.
Thunder Client أداة اختبار فردية داخل VS Code، لا منصة دورة حياة API كاملة.

إذا كان فريقك يتعامل يوميًا مع التصميم، الاختبار، المحاكاة، والتوثيق، فابدأ بـ Apidog. وإذا كنت تحتاج إلى جانب البوابة في المكدس، راجع أفضل 10 بوابات واجهات برمجة تطبيقات للمطورين في عام 2026.

كيفية استخدام واجهة برمجة تطبيقات ERNIE 5.1؟

Yusuf Khalidd — Thu, 14 May 2026 08:38:47 +0000

تم إطلاق ERNIE 5.1 في 9 مايو 2026، وبعد أسبوع أصبح متاحًا عبر Qianfan API. إذا كنت تريد استدعاء النموذج من الكود، أو تشغيل tool calling، أو بناء agent loop واختبارها عبر Apidog، فهذا الدليل يركز على التنفيذ: إنشاء المفتاح، إرسال الطلبات، التدفّق، الأدوات، ومعالجة الأخطاء.

جرّب Apidog اليوم

بنهاية المقال سيكون لديك أمثلة جاهزة لـ curl وPython وNode.js، بالإضافة إلى طريقة تنظيم الطلبات داخل Apidog لاختبار ERNIE 5.1 مقابل مزودين آخرين.

إذا لم تقرأ بعد شرح إطلاق ERNIE 5.1، فابدأ به سريعًا؛ فهو يغطي المعايير والمقارنات مع DeepSeek V4 وKimi K2.6. هذا المقال هو جزء التنفيذ العملي.

الخطوة 1: الحصول على مفتاح API لـ Qianfan

يتم تقديم ERNIE 5.1 عبر منصة Qianfan من Baidu Intelligent Cloud. لا يوجد API منفصل خاص بـ ERNIE؛ كل الاستدعاءات تمر عبر Qianfan.

نفّذ الخطوات التالية:

انتقل إلى cloud.baidu.com وأنشئ حسابًا في Baidu Intelligent Cloud أو سجّل الدخول.
- يمكن للمطورين الدوليين التسجيل بالبريد الإلكتروني.
- بعض ميزات المؤسسات قد تتطلب رقم هاتف صيني.
افتح لوحة Qianfan من console.bce.baidu.com/qianfan.
من إدارة مفاتيح API (API Key 管理) اختر إنشاء مفتاح API.
اختر مساحة العمل، وامنح المفتاح صلاحية الوصول إلى خدمة chat completions.
انسخ المفتاح وخزّنه في متغير بيئة، وليس داخل الكود.

export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"

نقطتان مهمتان قبل أول طلب:

نقطة النهاية v2 تستخدم Bearer token واحدًا. لا تبنِ تطبيقًا جديدًا على تدفق OAuth القديم access_token الخاص بـ v1.
ERNIE 5.1 نموذج مدفوع منذ البداية. أضف رصيدًا بسيطًا، مثل 10 ¥، قبل الاختبار.

الخطوة 2: استدعاء نقطة النهاية المتوافقة مع OpenAI باستخدام curl

يوفر Qianfan نقطة نهاية chat completions متوافقة مع تنسيق OpenAI. إذا كان تطبيقك يستخدم OpenAI SDK أو نفس شكل الطلبات، فغالبًا ستحتاج فقط إلى تغيير:

base_url
model
api_key

الإعدادات الأساسية:

Base URL: https://qianfan.baidubce.com/v2
Model: ernie-5.1

يمكنك أيضًا استخدام:

ernie-5.1-preview

للمزايا ذات الوصول المبكر.

مثال curl بسيط:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-5.1",
    "messages": [
      {"role": "system", "content": "You are a senior API designer."},
      {"role": "user", "content": "Sketch a REST schema for a GitHub-style PR review API. Be concise."}
    ],
    "temperature": 0.3
  }'

شكل الاستجابة سيكون قريبًا من OpenAI:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1746780000,
  "model": "ernie-5.1",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 318,
    "total_tokens": 360
  }
}

أخطاء شائعة في هذه المرحلة:

401 Unauthorized: المفتاح غير صحيح أو منتهي الصلاحية.
403: المفتاح صحيح، لكن النموذج غير مفعّل في مساحة العمل. فعّل ERNIE 5.1 من لوحة Qianfan.

الخطوة 3: استدعاء ERNIE 5.1 من Python

بما أن نقطة النهاية متوافقة مع OpenAI، يمكنك استخدام حزمة openai الرسمية في Python مع تغيير base_url.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QIANFAN_API_KEY"],
    base_url="https://qianfan.baidubce.com/v2",
)

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=[
        {"role": "system", "content": "You explain APIs in plain English."},
        {"role": "user", "content": "Why would I use server-sent events over WebSockets for a chat UI?"},
    ],
    temperature=0.4,
)

print(response.choices[0].message.content)
print(f"\nTokens used: {response.usage.total_tokens}")

إذا كان لديك wrapper داخلي حول OpenAI SDK، فاختبار ERNIE 5.1 غالبًا يكون تغييرًا في سطر الإعداد فقط. نفس النمط يعمل مع API الخاص بـ DeepSeek ومعظم مزودي النماذج الذين يدعمون تنسيق OpenAI.

الخطوة 4: تفعيل تدفق الرموز لواجهات الدردشة

لواجهات الدردشة، لا تنتظر الاستجابة كاملة. استخدم streaming حتى تعرض الرموز تدريجيًا للمستخدم.

في Python:

stream = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "Write a haiku about API versioning."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

ولتصحيح الأخطاء باستخدام curl:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-5.1",
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a 3-sentence joke."}]
  }' \
  --no-buffer

شكل التدفق مطابق تقريبًا لتنسيق OpenAI:

data: {...}
data: {...}
data: [DONE]

الخطوة 5: استخدام ERNIE 5.1 مع الأدوات

يدعم ERNIE 5.1 نمط tool calling باستخدام نفس شكل function calling المتوافق مع OpenAI. الفكرة العملية:

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

مثال تعريف أداة:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. Singapore"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "What's the weather in Tokyo right now?"}],
    tools=tools,
    tool_choice="auto",
)

tool_calls = response.choices[0].message.tool_calls
if tool_calls:
    call = tool_calls[0]
    print(f"Model wants to call: {call.function.name}({call.function.arguments})")

بعد تنفيذ الأداة في تطبيقك، أضف النتيجة كرسالة بدور tool، ثم استدعِ النموذج مرة أخرى. تنتهي الحلقة عندما:

finish_reason == "stop"

ولا توجد:

tool_calls

ملاحظة تنفيذية: قد يعيد ERNIE 5.1 أحيانًا arguments الخاصة بالأداة كسلسلة JSON داخل code fence بدل JSON نظيف. تعامل معها دفاعيًا:

import json
import re

def parse_tool_args(raw):
    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        cleaned = re.sub(r"^```

json|

```$", "", raw.strip(), flags=re.MULTILINE).strip()
        return json.loads(cleaned)

الخطوة 6: استدعاء ERNIE 5.1 من Node.js

إذا كنت تستخدم حزمة openai في Node.js، غيّر baseURL فقط:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QIANFAN_API_KEY,
  baseURL: "https://qianfan.baidubce.com/v2",
});

const completion = await client.chat.completions.create({
  model: "ernie-5.1",
  messages: [
    { role: "user", content: "Return a JSON object with 3 API design tips." },
  ],
  response_format: { type: "json_object" },
});

console.log(completion.choices[0].message.content);

response_format: { type: "json_object" } يعمل للاستخدامات العملية. أما json_schema الصارم فما زال قيد الطرح في Qianfan؛ لذلك تحقّق من شكل الاستجابة في الكود بدل الاعتماد الكامل على القيود.

مثال تحقق بسيط:

const raw = completion.choices[0].message.content;

try {
  const parsed = JSON.parse(raw);

  if (!Array.isArray(parsed.tips)) {
    throw new Error("Expected tips to be an array");
  }

  console.log(parsed);
} catch (error) {
  console.error("Invalid JSON response:", error);
}

الخطوة 7: الاختبار والمقارنة باستخدام Apidog

إذا كنت تقارن ERNIE 5.1 مع DeepSeek V4 أو Kimi K2.6، لا تجعل المقارنة تعتمد على أوامر متفرقة في الطرفية. استخدم Apidog لإنشاء مشروع واحد، وبيئات منفصلة، وطلبات متطابقة لكل مزود.

إعداد سريع:

افتح Apidog.
أنشئ مشروعًا جديدًا باسم LLM bake-off.

أضف بيئة تحتوي على المتغيرات التالية:

QIANFAN_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY

أنشئ طلبًا لكل مزود.
استخدم نفس مصفوفة messages في كل الطلبات.
غيّر فقط base_url وmodel.

مثال للنماذج:

{
  "model": "ernie-5.1",
  "messages": [
    {
      "role": "user",
      "content": "Design a REST API for pull request reviews. Return endpoints and payload examples."
    }
  ],
  "temperature": 0.3
}

استخدم ميزة Run في Apidog لتشغيل الطلبات بالتوازي ومقارنة النتائج. يحتفظ Apidog بسجل الطلبات حسب البيئة، ما يجعل إعادة نفس التقييم لاحقًا أسهل من تشغيل عدة أوامر curl.

لمزيد من الاختبارات متعددة المزودين، راجع اختبار نماذج LLM المحلية كواجهات برمجة تطبيقات ودليل GLM 5.1 API.

التسعير، حدود المعدل، والحصص

لم يكن تسعير Qianfan العام لـ ERNIE 5.1 مذكورًا في منشور الإصدار. تحقق من بطاقة الأسعار داخل لوحة Qianfan قبل مشاركة أرقام داخلية مع فريقك.

نصائح عملية:

حدود المعدل مرتبطة بمساحة العمل. الحسابات الجديدة تبدأ غالبًا بحد QPS منخفض. ارفع الحد من لوحة التحكم بعد الاختبار.
استخدم حقل usage. كل استجابة تحتوي على:
- prompt_tokens
- completion_tokens
- total_tokens
سجّل الاستخدام لكل طلب. لا تعتمد فقط على لوحة التحكم لتقدير التكلفة.
لا يوجد prompt caching تلقائي. إذا كان لديك system prompt طويل، فسيتم احتسابه في كل استدعاء. اختصره أو خزّن النتائج في طبقة التطبيق عند الإمكان.

مثال تسجيل بسيط:

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=messages,
)

usage = response.usage

print({
    "prompt_tokens": usage.prompt_tokens,
    "completion_tokens": usage.completion_tokens,
    "total_tokens": usage.total_tokens,
})

معالجة الأخطاء التي ستواجهها غالبًا

الأخطاء العملية الأكثر شيوعًا:

الحالة	المعنى	الإصلاح
401	رمز Bearer خاطئ أو منتهي الصلاحية	أعد توليد المفتاح من لوحة التحكم
403	النموذج غير مفعّل في مساحة العمل	فعّل ERNIE 5.1 من لوحة Qianfan
429	تم تجاوز حد المعدل	استخدم backoff مع jitter ثم أعد المحاولة
400 (`invalid messages`)	ترتيب أدوار الرسائل غير صحيح	راجع تسلسل user/assistant/tool
500/502	مشكلة من جهة Qianfan	أعد المحاولة مرة، ثم تحقق من حالة الخدمة

للاستخدام الإنتاجي، غلّف كل استدعاء بإعادة محاولة مع exponential backoff، وسجّل request_id من رؤوس الاستجابة إذا كان متاحًا؛ ستحتاجه عند التواصل مع دعم Baidu.

غلاف Python بسيط مناسب كبداية إنتاجية

هذا wrapper يغطي السيناريوهات الأساسية: استدعاء chat completions مع إعادة محاولة عند حدود المعدل أو أخطاء الخادم.

import os
import time
import random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(
    api_key=os.environ["QIANFAN_API_KEY"],
    base_url="https://qianfan.baidubce.com/v2",
)

def chat(messages, *, model="ernie-5.1", temperature=0.3, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                temperature=temperature,
            )

        except RateLimitError:
            sleep_for = (2 ** attempt) + random.random()
            time.sleep(sleep_for)

        except APIError as e:
            if e.status_code and e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(1 + attempt)
                continue
            raise

    raise RuntimeError("ERNIE 5.1 retries exhausted")

استخدامه:

messages = [
    {"role": "system", "content": "You are a concise API reviewer."},
    {"role": "user", "content": "Review this endpoint design: POST /users/search"}
]

response = chat(messages)

print(response.choices[0].message.content)

للتدفق وtool calling، ابنِ فوق هذا الغلاف بدل تكرار منطق retry في كل مكان.

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

هل ERNIE 5.1 API مجاني؟

لا. Qianfan يعمل بنظام الدفع حسب الاستخدام. لا توجد طبقة مجانية دائمة، لكن الحسابات الجديدة قد تحصل أحيانًا على أرصدة تجريبية. للتجربة المجانية عبر واجهة دردشة، استخدم ernie.baidu.com أو راجع خيارات LLM المجانية.

هل يمكن تشغيل ERNIE 5.1 محليًا؟

لا. لا توجد أوزان عامة متاحة. إذا كان التشغيل المحلي أو on-prem مطلبًا أساسيًا، راجع كيفية تشغيل DeepSeek V4 محليًا أو أفضل نماذج LLM المحلية في عام 2026.

هل يعمل OpenAI SDK بدون تغييرات كبيرة؟

نعم. اضبط:

base_url="https://qianfan.baidubce.com/v2"

واستخدم مفتاح Qianfan في api_key. حقل model يجب أن يحتوي على معرف نموذج Qianfan مثل:

ernie-5.1

وليس معرفًا من OpenAI.

هل يدعم ERNIE 5.1 streaming وtool calling؟

نعم. يعمل streaming عبر stream: true، وتعمل الأدوات باستخدام مخطط function calling المتوافق مع OpenAI. أما response_format: json_object فهو مدعوم، بينما json_schema الصارم ما زال قيد الطرح.

كيف يتعامل ERNIE 5.1 مع العربية أو الإنجليزية أو الصينية؟

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

ما الحد الأقصى لطول المخرجات؟

لم يُنشر رسميًا. عمليًا، قد تصل استجابات الدور الواحد إلى حوالي 8 آلاف رمز قبل أن ينهي النموذج. للتوليد الطويل، قسّم المهمة إلى أجزاء واستخدم رسائل متابعة.

إذا كنت تبني agent أو طبقة API فوق ERNIE 5.1، يمكنك تحميل Apidog واستخدام طلبات متوافقة مع OpenAI لاختبار وتوثيق نقطة نهاية Qianfan بجانب بقية خدماتك.

ما هو ERNIE 5.1؟ نموذج MoE الجديد من بايدو

Yusuf Khalidd — Thu, 14 May 2026 07:14:41 +0000

أطلقت بايدو ERNIE 5.1 في 9 مايو 2026. الرقم الأهم للمطورين: نموذج Mixture-of-Experts بحوالي ثلث إجمالي معلمات ERNIE 5.0، حقق المركز الرابع عالميًا في Arena Search والأول بين النماذج الصينية بنتيجة 1,223.

جرّب Apidog اليوم

هذا الإصدار مهم لأن بايدو تضع ERNIE 5.1 كنموذج عملي لاستخدام الأدوات ذاتيًا، والكتابة الطويلة، والاستدلال، وليس كنموذج محادثة صيني فقط. إذا كنت تبني وكلاء AI أو تختبر موفري نماذج متعددة باستخدام Apidog، فـ ERNIE 5.1 يستحق التقييم خصوصًا إذا كنت تريد نموذجًا صينيًا مستضافًا دون بصمة نموذج 70B.

في هذا الدليل ستجد ما تحتاجه عمليًا: ما هو ERNIE 5.1، ما الذي تغير في البنية، كيف تقرأ المعايير، ومتى تختاره بدلًا من DeepSeek V4 أو Kimi K2.6.

TL;DR: ERNIE 5.1 في فقرة واحدة

ERNIE 5.1 هو نموذج MoE نصي فقط. تقول بايدو إن تدريبه المسبق كلف حوالي 6% من تكلفة النماذج الرائدة المشابهة. يستخدم إجمالي معلمات يقارب ثلث ERNIE 5.0، ومعلمات نشطة لكل تمريرة أمامية تقارب النصف. حقق 1,223 في Arena Search، وتفوق على DeepSeek-V4-Pro في τ³-bench و SpreadsheetBench-Verified، وحقق 99.6 في AIME26 مع استخدام الأدوات. الوصول متاح عبر واجهة دردشة ERNIE، وساحة لعب Baidu AI Studio، وواجهة Qianfan API.

لماذا يهم ERNIE 5.1 للمطورين؟

بدل التعامل معه كـ “نموذج جديد من بايدو”، قيّمه من ثلاث زوايا عملية:

1. تكلفة أقل قد تعني API أرخص

تدعي بايدو أن تكلفة التدريب المسبق تقارب 6% من تكلفة النماذج المشابهة. هذا لا يعني تلقائيًا أن أسعار Qianfan ستكون منخفضة، لكنه مؤشر يجب مراقبته. إذا انعكس ذلك على التسعير، فقد يصبح ERNIE 5.1 خيارًا اقتصاديًا لسير عمل الوكلاء.

2. MoE أكثر مرونة

ERNIE 5.1 يستخدم توجيهًا عبر ثلاثة محاور:

العمق
العرض
الندرة

الفكرة العملية: النموذج لا يحتاج إلى تفعيل كل مكوناته لكل طلب. هذا قد يساعد في تقليل التكلفة وزمن الاستجابة مع الحفاظ على جودة جيدة في مهام استخدام الأدوات.

3. التركيز على الاستخدام الذاتي للأدوات

الفرق المهم عن إصدارات ERNIE السابقة هو أن ERNIE 5.1 يستهدف صراحةً سيناريوهات agentic tool use. هذا يجعله مرشحًا للاختبار في:

وكلاء البحث
وكلاء تحليل الجداول
سير عمل استدعاء API
مساعدات كتابة طويلة مع أدوات خارجية
تطبيقات RAG ثنائية اللغة

المعايير: كيف تقرأ النتائج؟

هذه أهم الأرقام التي نشرتها بايدو مع معناها العملي:

المعيار	ERNIE 5.1	ما يختبره	أقرب منافس
Arena Search	1,223، الرابع عالميًا، الأول في الصين	أسئلة وأجوبة مرتبطة بالبحث بتقييم بشري	Gemini 3.1 Pro, GPT-5.x
τ³-bench	يتفوق على DeepSeek-V4-Pro	استخدام الأدوات ذاتيًا عبر عدة أدوار	DeepSeek-V4-Pro
SpreadsheetBench-Verified	يتفوق على DeepSeek-V4-Pro	مهام جداول بيانات واقعية	DeepSeek-V4-Pro
AIME26 مع الأدوات	99.6	رياضيات مسابقات مع مفسر أكواد	GPT-5.x, Gemini 3.1 Pro
GPQA	يقارب النماذج الرائدة مغلقة المصدر	أسئلة علمية بمستوى الدراسات العليا	Claude Sonnet 4.6
MMLU-Pro	يقارب النماذج الرائدة مغلقة المصدر	معرفة عامة متقدمة	النماذج الرائدة

تعامل مع هذه النتائج كإشارات أولية، لا كقرار إنتاج مباشر. درجات Arena تعتمد على نوعية المطالبات والمصوتين. درجة AIME26 معززة بالأدوات، وليست بالضرورة انعكاسًا للاستدلال الخالص. لكن τ³-bench و SpreadsheetBench-Verified يستحقان الانتباه لأنهما أقرب إلى سيناريوهات الوكلاء التي يستخدمها المطورون فعليًا.

ما نعرفه عن البنية

كشفت بايدو عن معلومات محدودة، لكن المؤكد حتى الآن:

إجمالي المعلمات: حوالي ثلث ERNIE 5.0
المعلمات النشطة لكل رمز: حوالي نصف ERNIE 5.0
التوجيه: عبر العمق والعرض والندرة
تكلفة التدريب المسبق: حوالي 6% من النماذج المشابهة
النمطية: نص فقط عند الإطلاق
اللغات: نسخ صينية وإنجليزية

لم تُنشر بعد تفاصيل مهمة مثل:

طول السياق
عدد المعلمات الدقيق
حجم بيانات التدريب
سياسات الاستدعاء للأدوات
حدود المعدل وأسعار Qianfan النهائية

إذا سبق أن اختبرت نماذج MoE صينية مثل GLM 5.1، فتوقع تجربة تكامل مشابهة: نموذج مستضاف، API، وتقييمات عملية قبل الإنتاج.

ما لا يمكنك فعله مع ERNIE 5.1 بعد

قبل أن تبني عليه، انتبه لهذه القيود:

لا يدعم الصور. ERNIE 5.1 نصي فقط. لمهام الرؤية استخدم ERNIE-VL أو نموذج رؤية خارجي.
لا يدعم الصوت. لا يوجد إدخال أو إخراج صوتي أصلي.
لا يوجد طول سياق معلن. قسّم المستندات الطويلة ولا تفترض نافذة سياق كبيرة.
لا توجد أوزان عامة. النموذج مستضاف فقط. إذا كنت تحتاج نشرًا محليًا، انظر إلى تشغيل DeepSeek V4 محليًا أو نماذج اللغة الكبيرة المحلية.

متى تختار ERNIE 5.1 بدل DeepSeek أو Kimi أو GLM؟

استخدم هذا النموذج الذهني السريع:

اختر ERNIE 5.1 عندما تحتاج إلى agentic tool-use قوي مع إجابات بحثية بالصينية والإنجليزية، وتريد اختبار نموذج مستضاف داخل منظومة بايدو.
اختر DeepSeek V4 عندما تحتاج إلى أوزان مفتوحة، نشر محلي، أو استدلال رياضي قوي بدون أدوات.
اختر Kimi K2.6 عندما تكون نافذة السياق الطويلة أهم من كل شيء، خصوصًا في تطبيقات المستندات.
اختر GLM 5.1 عندما تريد نموذجًا عامًا متوازنًا ولديك بالفعل Z.ai أو Zhipu في المكدس.

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

أين يمكنك تجربة ERNIE 5.1؟

لديك ثلاثة مسارات:

ernie.baidu.com: واجهة دردشة للمستخدمين. مناسبة للتجربة السريعة للكتابة والاستدلال.
Baidu AI Studio Playground: ساحة لعب مستضافة تتضمن عروضًا لاستخدام الأدوات. مناسبة قبل كتابة تكامل API.
Qianfan API: نقطة نهاية المطورين. تستخدم مصادقة Bearer token وشكل طلب متوافقًا مع OpenAI. راجع الدليل العملي: كيفية استخدام واجهة ERNIE 5.1 API.

إذا كنت تختبر عدة موفرين في الوقت نفسه، يمكنك استخدام Apidog لحفظ الطلبات، إدارة المفاتيح، ومقارنة استجابات النماذج جنبًا إلى جنب.

مثال عملي: كيف تقيّم ERNIE 5.1 قبل الإنتاج؟

ابدأ بتقييم صغير بدل الاعتماد على المعايير العامة.

1. جهّز مجموعة مطالبات حقيقية

مثال JSON بسيط:

[
  {
    "id": "tool_call_001",
    "prompt": "ابحث عن آخر حالة للطلب رقم 12345 باستخدام أداة orders_api ثم لخّص النتيجة للمستخدم.",
    "expected_tools": ["orders_api"],
    "success_criteria": [
      "يستدعي الأداة الصحيحة",
      "لا يخترع حالة الطلب",
      "يعطي ملخصًا واضحًا"
    ]
  },
  {
    "id": "spreadsheet_001",
    "prompt": "حلل جدول المبيعات وأخرج أعلى 3 منتجات حسب الإيراد.",
    "expected_tools": ["spreadsheet_parser"],
    "success_criteria": [
      "يستخدم بيانات الجدول فقط",
      "يرتب النتائج بشكل صحيح",
      "يعرض الحسابات بوضوح"
    ]
  }
]

2. اختبر نفس المطالبات على نموذجك الحالي وERNIE 5.1

سجّل لكل حالة:

هل استدعى الأداة الصحيحة؟
هل اتبع تنسيق الإخراج؟
هل هلوس؟
كم كان زمن الاستجابة؟
كم كانت التكلفة التقريبية؟
هل احتجت إلى إعادة المحاولة؟

3. استخدم نتيجة قابلة للمقارنة

مثال بسيط:

النتيجة = 
  40% صحة استدعاء الأدوات +
  30% جودة الإجابة +
  20% الالتزام بالتنسيق +
  10% زمن الاستجابة

هذا النوع من التقييم أكثر فائدة من قراءة لوحة صدارة عامة، لأنه يعكس عبء العمل الحقيقي لديك.

التسعير والإطلاق

أعلنت بايدو أن ERNIE 5.1 سيصل إلى أكثر من 10 منصات إنتاج إبداعي بعد الإطلاق. لم تنشر بايدو في منشور الإصدار تسعيرًا عامًا لكل رمز على Qianfan.

عمليًا، لا تبنِ حسابات التكلفة على افتراضات. عند التقييم:

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

كيف تفكر في ERNIE 5.1 كمطور؟

اتبع هذه الخطوات قبل دمجه:

1. اختبره على agentic eval الخاص بك

لا يكفي أن يتفوق في τ³-bench. ابنِ تقييمًا يعكس أدواتك الفعلية: API داخلية، قواعد بيانات، جداول، مستندات، أو وظائف بحث. يمكنك الاستفادة من منهجية اختبار نماذج اللغة الكبيرة كواجهات API.

2. تحقق من متطلبات إقامة البيانات

Qianfan مستضاف ضمن منظومة بايدو. إذا كانت متطلباتك تمنع استخدام بنية تحتية في الصين، فلن يحل الأداء العالي هذه المشكلة.

3. راقب التسعير وحدود الاستخدام

أهم وعد في ERNIE 5.1 هو الكفاءة. لكن القرار الإنتاجي يعتمد على:

سعر الرموز
حدود المعدل
زمن الاستجابة من منطقتك
سياسات الحسابات والمؤسسات
استقرار API
دعم الأدوات في الطلبات الفعلية

الأسئلة المتكررة

هل ERNIE 5.1 مفتوح المصدر؟

لا. ERNIE 5.1 نموذج مستضاف فقط عبر دردشة بايدو، Baidu AI Studio، وQianfan API. لا توجد أوزان عامة على HuggingFace وقت كتابة هذا المقال.

هل يدعم ERNIE 5.1 الصور؟

لا. ERNIE 5.1 نصي فقط. لمهام الرؤية استخدم ERNIE-VL أو نموذجًا متعدد الوسائط مثل Qwen 3.5 Omni.

ما طول السياق؟

لم تنشر بايدو رقمًا رسميًا لطول السياق. حتى يحدث ذلك، قسّم المستندات الطويلة وصمم نظامك بشكل دفاعي.

هل يمكن استخدام ERNIE 5.1 من خارج الصين؟

يمكن الوصول إلى واجهة الدردشة وQianfan API من عدة مناطق، لكن زمن الاستجابة والتحقق من الحساب قد يختلفان. بعض ميزات المؤسسات قد تتطلب رقم هاتف صينيًا أو ترخيص عمل. راجع دليل استخدام ERNIE 5.1 API للتفاصيل.

هل ERNIE 5.1 أفضل من DeepSeek-V4-Pro؟

حسب أرقام بايدو، نعم في τ³-bench و SpreadsheetBench-Verified. لكنه ليس بديلًا مباشرًا إذا كنت تحتاج أوزانًا مفتوحة أو نشرًا محليًا. القرار يعتمد على نموذج النشر وسيناريو الاستخدام.

الخلاصة

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

ابدأ بمجموعة صغيرة من الحالات، اختبرها عبر Qianfan API، وقارن النتائج مع نموذجك الحالي في مساحة عمل واحدة باستخدام Apidog.

قضيت صباحًا مع وضع Spec-First في Apidog: المصمم المرئي لم يعد البالغ الوحيد في الغرفة

Yusuf Khalidd — Thu, 14 May 2026 07:05:27 +0000

يوجد نمطان شائعان داخل فرق تطوير واجهات برمجة التطبيقات: فريق يكتب مواصفات OpenAPI يدويًا داخل Git ويتعامل معها كمصدر الحقيقة، وفريق يستخدم مصممًا مرئيًا ثم يصدّر المواصفات عند الحاجة.

جرّب Apidog اليوم

جرّبت النمطين. الكتابة اليدوية أبطأ في البداية، لكنها أوضح وأكثر قابلية للمراجعة بعد أسابيع من التطوير. أما المصمم المرئي فهو أسرع في اليوم الأول، لكنه قد يخلق فجوة بين ما هو موجود في الأداة وما هو موجود في المستودع.

حتى وقت قريب، كان Apidog مناسبًا أكثر للنمط الثاني: تصميم مرئي ممتاز، مع إمكانية تصدير YAML عند الحاجة. لكن مع ظهور وضع Spec-First التجريبي، أصبح بالإمكان جعل ملف OpenAPI نفسه هو مركز العمل، مع مزامنة مباشرة مع Git.

في هذا المقال أشرح كيف يعمل الوضع الجديد عمليًا، وكيف تُعدّه، ومتى يكون مناسبًا لفريقك.

ما الذي يغيّره وضع Spec-First فعليًا؟

في Apidog يوجد الآن نمطان مختلفان لإنشاء المشاريع:

الوضع العام
- تبني الـ API عبر واجهة مرئية.
- تضيف المسارات، الطلبات، الاستجابات، والمخططات من خلال نماذج.
- يتم إنشاء مواصفات OpenAPI خلف الكواليس.
وضع Spec-First
- تعمل مباشرة على ملفات .yaml أو .json.
- ملف OpenAPI في المستودع هو مصدر الحقيقة.
- تحصل على محرر كود، إكمال تلقائي حسب مخطط OpenAPI، ومخطط جانبي يتحدث أثناء الكتابة.
- توجد مزامنة ثنائية الاتجاه مع Git.

الفكرة الأساسية: أنت لا “تصدّر” المواصفات من الأداة، بل تعدّل الملف نفسه الذي يعيش في المستودع.

openapi: 3.0.3
info:
  title: Store API
  version: 1.0.0

paths:
  /store/token:
    post:
      summary: Create store token
      responses:
        "200":
          description: Token created

عند إضافة مسار مثل /store/token، يظهر في المخطط الجانبي داخل Apidog دون الحاجة إلى الانتقال بين ملفات أو البحث يدويًا.

الميزة المهمة هنا ليست فقط تحرير YAML. يمكنك فعل ذلك في VS Code. القيمة الحقيقية هي أن Apidog يعرض بنية الـ API كتنقل حي فوق ملف المواصفات نفسه.

إعداد مشروع Spec-First خطوة بخطوة

هذا هو المسار العملي لإنشاء مشروع يعتمد على المواصفات أولًا.

1. أنشئ مشروعًا جديدًا بالوضع الصحيح

من شاشة المشاريع:

+ مشروع جديد → عام → وضع المواصفات أولاً

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

2. اربط المشروع بمستودع Git

بعد اختيار وضع Spec-First:

افتح خيار الاتصال بمستودع Git.
فوّض مزود Git الذي تستخدمه.
اختر:
- المنظمة
- المستودع
- الفرع الرئيسي

استخدمت GitHub في التجربة، لكن الفكرة نفسها تنطبق على مزودي Git المدعومين.

3. هيّئ المشروع

أدخل:

اسم المشروع
إعدادات الفريق
صلاحيات الوصول

ثم انقر إنشاء.

في أول مزامنة، يسحب Apidog ملفات .yaml و .json الموجودة في المستودع إلى مساحة العمل.

4. حرّر ملف OpenAPI مباشرة

افتح ملف YAML أو JSON من داخل المشروع. ستحصل على:

تمييز نحوي
إكمال تلقائي حسب OpenAPI Schema
مخطط جانبي للمسارات
تنقل مباشر إلى تعريف كل endpoint

مثال عملي لإضافة endpoint:

paths:
  /admin/auth:
    post:
      summary: Admin login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        "200":
          description: Login successful
        "401":
          description: Invalid credentials

بعد الكتابة، يظهر المسار /admin/auth في الشريط الجانبي، ويمكنك النقر عليه للعودة إلى موضعه في الملف.

5. نفّذ Commit and Push

عند الانتهاء من التعديل:

انقر Commit & Push في أعلى اليمين.
راجع الملفات المعدلة في قسم التغييرات.
اكتب رسالة commit واضحة.
انقر Push.

مثال لرسالة commit مناسبة:

Add admin authentication endpoint to OpenAPI spec

لا توجد خطوة staging منفصلة. أي ملف ظاهر في قائمة التغييرات يدخل في commit.

6. راقب حالة المزامنة

في أسفل اليسار سترى مؤشر المزامنة، مثل:

تمت المزامنة الآن

هذا المؤشر يخبرك هل:

التغييرات المحلية دُفعت إلى Git
هناك تغييرات بعيدة تحتاج إلى سحب
المشروع غير متزامن

عمليًا، هذا المؤشر مهم جدًا إذا كان أكثر من شخص يعدّل المواصفات.

ملاحظات عملية من التجربة

المخطط الجانبي يتحدث بسرعة

في بعض محررات OpenAPI، لا يظهر المسار الجديد إلا بعد الحفظ أو إعادة التحليل. في Apidog، المخطط الجانبي تحدّث أثناء الكتابة تقريبًا.

هذا يجعل المخطط أداة تنقل فعلية، وليس مجرد تقرير حالة بعد انتهاء العمل.

تكامل Git ثنائي الاتجاه

جرّبت تعديل الملف من الطرفية ثم دفع التغييرات إلى Git بينما كان Apidog مفتوحًا.

ما حدث:

اكتشف Apidog أن الفرع المحلي داخل الأداة متأخر.
تغيّر مؤشر المزامنة.
أمكن سحب التغييرات إلى المحرر.

هذا مهم إذا كان بعض أعضاء الفريق يفضلون Vim أو VS Code أو أي محرر آخر. طالما أن الجميع يعدّل الملف نفسه في Git، يمكن لكل شخص استخدام الأداة التي تناسبه.

لا يمكنك التحويل إلى المصمم المرئي داخل نفس المشروع

إذا أنشأت المشروع بوضع Spec-First، فهو يبقى مشروعًا قائمًا على المواصفات.

لا يوجد تبديل مباشر إلى الوضع المرئي داخل المشروع نفسه، لأن نموذج البيانات مختلف.

إذا احتجت إلى دعم النمطين، فالخيار العملي هو:

اجعل مستودع Git هو مصدر الحقيقة.
استخدم مشروع Spec-First للعمل على المواصفات.
استخدم مشروعًا منفصلًا يستورد من المصدر نفسه عند الحاجة إلى الواجهة المرئية.

هذا ليس مثاليًا، لكنه واضح وقابل للإدارة.

متى تستخدم Spec-First؟

استخدم هذا الوضع إذا كان فريقك:

يكتب OpenAPI يدويًا بالفعل
يراجع تغييرات الـ API عبر Pull Requests
يشغّل أدوات مثل:

spectral lint openapi.yaml

يولّد SDKs أو clients من ملف المواصفات
يريد أن تكون المواصفات داخل Git بدل الاعتماد على export يدوي
يحتاج إلى تقليل الفجوة بين “المواصفات في الأداة” و“المواصفات في المستودع”

مثال لسير عمل مناسب:

git checkout -b add-admin-auth
# تعديل openapi.yaml داخل Apidog
# Commit & Push من Apidog
# فتح Pull Request
# تشغيل CI للتحقق من المواصفات

متى لا تستخدمه؟

لا أنصح به إذا كان فريقك:

لا يلمس OpenAPI مباشرة
يعتمد بالكامل على الواجهة المرئية لفهم الـ API
يضم مساهمين غير معتادين على YAML أو JSON
يحتاج إلى مزج الوضع المرئي ووضع Spec-First داخل المشروع نفسه

في هذه الحالات، الوضع العام في Apidog ما زال مناسبًا أكثر.

خلاصة

وضع Spec-First في Apidog يجعل ملف OpenAPI داخل Git هو مصدر الحقيقة، بدل أن يكون ناتجًا يتم تصديره من أداة تصميم.

النتيجة العملية:

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

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

كيفية استخدام Claude Agent SDK مع خطة Claude الخاصة بك؟

Yusuf Khalidd — Thu, 14 May 2026 03:57:51 +0000

تسمح لك Anthropic بتشغيل Claude Agent SDK على اشتراكك الحالي في Claude اعتبارًا من 15 يونيو 2026. سابقًا، كان بناء أي عميل باستخدام Agent SDK يتطلب مفتاح API منفصلًا وفوترة دفع حسب الاستخدام، حتى لو كنت تدفع بالفعل مقابل Claude Pro أو Max. الآن تتضمن خطة Claude الشهرية رصيدًا مخصصًا لاستخدام Agent SDK، ولا تحتاج إلى مفتاح API للتجربة.

جرّب Apidog اليوم

إذا كنت تريد بناء عميل مخصص مثل بوت نشر، مساعد بحث، أو أداة فرز مشكلات، فهذا التغيير يقلل العائق الأول: لم تعد بحاجة إلى إعداد فوترة API منفصلة فقط لتجربة SDK. تحصل خطة Pro على رصيد شهري بقيمة 20 دولارًا، وخطة Max 20x على 200 دولار، ومقاعد Team Premium على 100 دولار.

ما الذي تغير في 15 يونيو 2026؟

أصبح استخدام Claude Agent SDK يُخصم من رصيد شهري مرتبط بخطة Claude الخاصة بك. سابقًا، كان الاستخدام يُفوتر عبر Anthropic API ورصيد منفصل في لوحة التحكم.

الرصيد حسب الخطة:

الخطة	رصيد Agent SDK الشهري
Pro	$20
Max 5x	$100
Max 20x	$200
Team Standard لكل مقعد	$20
Team Premium لكل مقعد	$100
Enterprise حسب الاستخدام	$20
مقعد Enterprise Premium	$200

قواعد مهمة قبل البدء:

مقاعد Enterprise Standard لا تحصل على رصيد. تحتاج إلى مفتاح API أو ترقية المقعد إلى Premium.
الأرصدة لكل مستخدم وغير قابلة للتحويل. لا يمكن دمج رصيدك مع رصيد زميلك.
الأرصدة غير المستخدمة لا تُرحّل. يتم تصفير المتبقي في نهاية دورة الفوترة.
يجب الاشتراك مرة واحدة. لن يتم تفعيل الرصيد حتى تطالب به يدويًا مرة واحدة، ثم يتجدد شهريًا.
مستخدمو ANTHROPIC_API_KEY لا يحصلون على هذا الرصيد تلقائيًا. إذا كنت تصادق عبر مفتاح API، فأنت تستخدم نموذج فوترة API القديم.

ما الذي يغطيه الرصيد؟

يغطي رصيد Agent SDK أحمال العمل البرمجية وغير التفاعلية، مثل:

استدعاءات Claude Agent SDK من Python أو TypeScript.
أمر claude -p في Claude Code، أي الوضع غير التفاعلي.
تكامل Claude Code مع GitHub Actions.
تطبيقات الطرف الثالث التي تصادق باستخدام Agent SDK.

ولا يغطي:

جلسات Claude Code التفاعلية.
محادثات Claude عبر الويب أو تطبيق الهاتف.
جلسات Claude Cowork.

بمعنى آخر: استخدم الرصيد للمهام المؤتمتة، وليس للمحادثات اليومية. استخدام Claude Code التفاعلي يبقى ضمن حدود الخطة العادية، والتي زادتها Anthropic مؤخرًا بنسبة 50% حتى 13 يوليو.

ماذا يحدث عند نفاد الرصيد؟

يعتمد السلوك على إعداد الاستخدام الإضافي:

الاستخدام الإضافي مفعّل: يتم فوترة ما بعد الرصيد بأسعار API القياسية.
الاستخدام الإضافي معطّل: تتوقف الطلبات عند سقف الرصيد حتى دورة الفوترة التالية.

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

يتم دائمًا استهلاك الرصيد أولًا، ثم تبدأ فوترة الاستخدام الزائد إن كانت مفعلة.

كيفية الاشتراك في رصيد Agent SDK

الرصيد لا يعمل تلقائيًا. اتبع الخطوات التالية مرة واحدة:

سجّل الدخول إلى حساب Claude الذي يملك الاشتراك.
افتح إعدادات Claude Agent SDK من مقالة الدعم الرسمية لـ Anthropic.
طالب بالرصيد.
بعد التفعيل، سيتجدد الرصيد تلقائيًا كل شهر.

إذا كنت ضمن خطة Team أو Enterprise، يجب على كل مستخدم المطالبة برصيده بنفسه. لا يمكن للمسؤول تفعيل الرصيد نيابة عن الجميع.

إعداد Claude Agent SDK في Python

ثبّت الحزمة:

pip install claude-agent-sdk

سجّل الدخول عبر Claude Code:

claude login

هذا يخزن بيانات الاعتماد المرتبطة بخطتك محليًا. لا تضبط ANTHROPIC_API_KEY إذا كنت تريد استخدام الرصيد المرتبط بالخطة.

مثال عميل بسيط:

from claude_agent_sdk import Agent

agent = Agent(
    system_prompt="You are a code review assistant.",
)

response = agent.run(
    "Review the diff in /tmp/patch.diff and flag concerns."
)

print(response.text)

نقطة الاختبار المهمة: شغّل المثال بدون ANTHROPIC_API_KEY وتأكد أن الاستخدام يظهر ضمن رصيد Agent SDK في إعدادات حسابك.

إعداد Claude Agent SDK في TypeScript

ثبّت الحزمة:

npm install @anthropic-ai/claude-agent-sdk

سجّل الدخول:

claude login

مثال عميل بسيط:

import { Agent } from "@anthropic-ai/claude-agent-sdk";

const agent = new Agent({
  systemPrompt: "You are a code review assistant.",
});

const response = await agent.run(
  "Review the diff in /tmp/patch.diff and flag concerns."
);

console.log(response.text);

في بيئات CI أو Docker أو بيئات التطوير البعيدة، قد لا يجد SDK بيانات اعتماد Claude Code تلقائيًا. في هذه الحالة، استخدم متغيرات البيئة التي تنشرها Anthropic في وثائق Agent SDK.

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

استخدام `claude -p` للمهام المؤتمتة

لا تحتاج دائمًا إلى كتابة كود لاستخدام رصيد Agent SDK. يمكنك استخدام:

claude -p "Your prompt here"

الخيار -p يشغّل Claude Code في وضع غير تفاعلي: يعطي نتيجة ثم يخرج. هذا مناسب لـ:

مهام CI.
مهام cron.
Git hooks.
مراجعات diff تلقائية.
إنشاء تقارير قصيرة من المستودع.

مثال hook قبل الالتزام:

#!/usr/bin/env bash
# .git/hooks/pre-commit

DIFF=$(git diff --cached)

claude -p "Review this diff for security issues, secret leaks, and breaking changes. Return PASS or FAIL with reasoning:

$DIFF"

بعد 15 يونيو، يتم خصم هذا النوع من التشغيلات من رصيد Agent SDK، وليس من ميزانية Claude Code التفاعلية.

يمكن دمج هذا النمط مع أمر /goal للحلقات المستقلة، ومع ملفات AGENTS.md لتوفير سياق ثابت للعميل.

استخدام GitHub Actions

تكامل Claude Code مع GitHub Actions يقع أيضًا ضمن رصيد Agent SDK.

ينطبق ذلك على تشغيلات مثل:

مراجعة Pull Requests.
فرز issues.
إنشاء ملاحظات إصدار.
تشغيل مهام صيانة على المستودع.

إذا كان التكامل مثبتًا عبر حساب مستخدم طالب برصيد Agent SDK، يتم خصم التشغيلات من رصيد ذلك المستخدم.

هذا مفيد لمشاريع مثل Clawsweeper، بوت فرز GitHub المبني على Claude Code، حيث تعمل الأتمتة باستمرار وكانت سابقًا تعتمد على مفتاح API وفوترة منفصلة.

بناء عميل حقيقي باستخدام Agent SDK و Apidog

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

يمكن استخدام Apidog كطبقة عقد API في هذا التدفق:

عرّف عقد API في Apidog. أضف endpoints، مخططات الطلب والاستجابة، وأمثلة payload.
صدّر OpenAPI. استخدمه كسياق للعميل أو كمرجع لتوليد الأدوات.
اربط Agent SDK بنقاط النهاية الفعلية. اجعل العميل يستدعي API بناءً على المخططات المحددة.
تحقق من السلوك عبر Apidog CLI. اجعل كل تشغيل عميل يتحقق أن API ما زال يطابق العقد.

إذا كان عميلك ينظم أدوات عبر MCP servers، استخدم سير عمل اختبار خادم MCP مع Apidog لاختبار الأدوات التي يستدعيها العميل.

الفكرة الأوسع موضحة في دليل سير عمل API الذي يركز على التصميم أولًا: عندما يمتلك العميل عقدًا واضحًا، تقل أخطاء JSON schema ويصبح وقتك موجهًا لتحسين القيود والسلوك بدل تصحيح payloads عشوائية.

يمكنك تنزيل Apidog مجانًا إذا كنت تريد طبقة عقود API لمشاريع Agent SDK.

متى تحتاج إلى مفتاح API منفصل؟

الرصيد المرتبط بالخطة مناسب لمعظم التجارب والعمل الشخصي. لكن مفتاح API مستقل يبقى أفضل في حالات معينة:

عملاء إنتاج يحتاجون إلى ميزانية وفوترة واضحة. رصيد الخطة محدود بقيمة شهرية ثابتة.
وصول مشترك بين عدة مستخدمين أو فرق. مفاتيح API ليست مرتبطة بمستخدم واحد بنفس طريقة رصيد الخطة.
مقاعد Enterprise Standard. هذه المقاعد لا تحصل على رصيد Agent SDK.

إذا كنت تبحث عن مسارات استخدام مختلفة، راجع دليل الوصول المجاني إلى Claude API.

قائمة تحقق قبل التشغيل

[ ] تأكد أن خطتك مؤهلة: Pro أو Max 5x أو Max 20x أو Team Standard أو Team Premium أو Enterprise usage-based أو Enterprise Premium seat.
[ ] طالب برصيد Agent SDK من إعدادات Claude.
[ ] قرر هل تريد تفعيل الاستخدام الإضافي أم لا.
[ ] شغّل claude login.
[ ] ثبّت حزمة Python أو TypeScript.
[ ] شغّل عميلًا بسيطًا بدون ANTHROPIC_API_KEY.
[ ] راقب الرصيد بعد أول عدة تشغيلات.
[ ] إذا كنت تستخدم CI، تأكد من إعداد بيانات الاعتماد حسب وثائق Anthropic.

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

هل أحتاج إلى إزالة ANTHROPIC_API_KEY القديم؟

لا بالضرورة. عند توفر بيانات اعتماد Claude Code المحلية بعد claude login، يمكن لـ SDK استخدام مصادقة الخطة. إذا كان ANTHROPIC_API_KEY مستخدمًا لأدوات أخرى، اتركه، لكن اختبر أن تشغيلات SDK تُخصم من رصيد الخطة.

هل الرصيد يُحسب بعدد الطلبات؟

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

هل يمكنني مشاركة الرصيد مع زميل؟

لا. الرصيد لكل مستخدم وغير قابل للتحويل.

ماذا يحدث لرصيد Anthropic API القديم؟

يبقى منفصلًا. رصيد الخطة يستخدم Agent SDK والأسطح المدعومة، بينما رصيد API القديم يستمر لأحمال العمل التي تستخدم مفاتيح API.

هل Agent SDK هو Claude Code؟

لا. Claude Code هو واجهة سطر أوامر وإضافات IDE. Agent SDK مكتبة برمجية لبناء عملاء مخصصين في Python أو TypeScript. الرصيد يغطي SDK وclaude -p غير التفاعلي، بينما يبقى Claude Code التفاعلي ضمن حدود الخطة العادية.

هل تتغير فوترة GitHub Actions؟

إذا كنت تستخدم تكامل Claude Code GitHub Actions الرسمي وكان حساب المستخدم المثبت قد طالب بالرصيد، تُخصم التشغيلات من رصيد Agent SDK.

هل يعمل الرصيد خارج SDK وclaude -p وGitHub Actions؟

لا. ينطبق الرصيد على الأسطح المدعومة فقط: Python/TypeScript SDK، أمر claude -p، GitHub Actions، وتطبيقات Agent SDK التابعة لجهات خارجية. أي استخدام آخر يرجع إلى حدود خطة Claude العادية أو مفتاح API حسب طريقة المصادقة.

زيادة كود كلود الأسبوعية 50% حتى 13 يوليو: دليل المستخدمين المحترفين، ماكس، والفرق للاستفادة من الحصة الإضافية

Yusuf Khalidd — Thu, 14 May 2026 02:58:17 +0000

قامت Anthropic بزيادة حدود الاستخدام الأسبوعي لـ Claude Code بنسبة 50% حتى 13 يوليو الساعة 6 مساءً بتوقيت المحيط الهادئ الصيفي (1 صباحًا بتوقيت جرينتش، 14 يوليو). ينطبق ذلك على جميع الخطط المدفوعة: Pro وMax وTeam والخطط المؤسسية القائمة على المقاعد، ويعمل في كل واجهات Claude Code: CLI، إضافات IDE، تطبيق سطح المكتب، والويب. لا تحتاج إلى تفعيل أي خيار؛ السقف الجديد موجود بالفعل في حسابك.

جرّب Apidog اليوم

الأهم عمليًا: هذه الزيادة تأتي بعد مضاعفة حدود نافذة الخمس ساعات في الأسبوع السابق. النتيجة هي سعة أكبر على مستويين في الوقت نفسه: 2x للنافذة القصيرة، و1.5x للسقف الأسبوعي، دون تغيير في السعر. خلال هذه الفترة يمكنك تشغيل جلسات Claude Code أطول، وتجربة وكلاء أكثر استهلاكًا للتوكنات، وتنفيذ مهام API كاملة بدل تقسيمها يدويًا على عدة جلسات.

تشرح هذه المقالة ما تغيّر، كيف تقيس استخدامك، وما workflows التي تستحق استغلال السعة الإضافية فيها، خصوصًا عند بناء واجهات API باستخدام Apidog.

ما هي الحدود الأسبوعية، وماذا تعني زيادة 50%

يستخدم Claude Code في الخطط المدفوعة نموذج حدود من مستويين:

حدود الخمس ساعات: سقف متجدد للتوكنات داخل أي نافذة مدتها 5 ساعات. يظهر أثره في الجلسات الطويلة مثل إعادة الهيكلة، إصلاح الأخطاء، أو بناء ميزة كاملة.
الحدود الأسبوعية: سقف إجمالي للتوكنات على مدار الأسبوع. هذا هو الحد الذي يصطدم به المستخدمون المتقدمون بعد عدة أيام من العمل المكثف.

لا تنشر Anthropic أرقام التوكنات الثابتة لكل خطة، وقد تعدّلها حسب السعة. لكن عمليًا:

مستخدمو Pro يحصلون على مساحة أكبر قبل ظهور قيود الإخراج قرب نهاية الأسبوع.
مستخدمو Max يمكنهم تشغيل جلسات عمل عميقة لعدة أيام على قاعدة أكواد كبيرة.
مستخدمو Team والخطط المؤسسية القائمة على المقاعد يحصلون على زيادة 50% لكل مقعد. في فريق من 10 مقاعد، هذا يعني زيادة كبيرة في السعة الأسبوعية الإجمالية.

للتحقق من السقف الحالي، استخدم:

/usage

داخل Claude Code CLI، أو راقب شريط الحالة في إضافة IDE، أو صفحة إعدادات الحساب على الويب.

لماذا تقوم Anthropic بذلك الآن

هناك سببان مهمان:

السعة: أضافت Anthropic قدرات حوسبة جديدة خلال الربعين الأول والثاني من عام 2026. عندما تتوفر سعة إضافية، يكون رفع حدود المستخدمين الحاليين طريقة مباشرة لاختبار الطلب وزيادة اعتمادهم على المنصة.
المنافسة: أطلقت Codex حلقة الوكيل المستقل /goal قبل أسابيع، كما بدأت OpenAI بزيادة حدود بعض خطط المطورين. لذلك تبدو زيادة Claude Code خطوة للحفاظ على فرق الهندسة التي بدأت تقسم مهامها بين أكثر من مزود.

المهم: هذه الزيادة مؤقتة. تنتهي في 13 يوليو الساعة 6 مساءً بتوقيت المحيط الهادئ الصيفي. لم تعلن Anthropic إن كانت ستجعل السقف الجديد دائمًا أو تعيده إلى الوضع السابق.

ما الذي تفتحه الزيادة بنسبة 50% فعليًا

بدل التفكير فيها كـ "استخدام أكثر"، تعامل معها كفرصة لتجربة workflows كانت سابقًا مكلفة جدًا من ناحية التوكنات.

1. تشغيل الوكلاء لفترة أطول

بعد مضاعفة حد الخمس ساعات وزيادة السقف الأسبوعي، يمكن لحلقة الوكيل المستقل /goal العمل لفترة أطول قبل الوصول إلى الحد.

مثال هدف عملي:

/goal
Refactor the authentication module to remove duplicated session logic.
Success criteria:
- All existing tests pass.
- No public API behavior changes.
- Add integration tests for login, refresh, and logout.
- Update docs where behavior is clarified.

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

2. تحميل سياق أكبر من قاعدة الأكواد

قيمة Claude Code ترتفع عندما يفهم مساحة أكبر من المشروع. مع السعة الجديدة يمكنك:

تحميل مجلدات أعمق داخل monorepo.
السماح للوكيل بقراءة ملفات اختبار، docs، وconfig بدل الاكتفاء بالملف الحالي.
تقليل التحديد اليدوي للنطاق فقط لتوفير التوكنات.

مثال workflow مناسب:

claude

ثم داخل الجلسة:

اقرأ بنية packages/api وpackages/shared.
حدد نقاط التكرار بين validators وDTOs.
اقترح خطة refactor قبل تعديل أي ملف.

بعد مراجعة الخطة:

نفّذ الخطة على مراحل صغيرة.
بعد كل مرحلة شغّل الاختبارات ذات الصلة واصلح الفشل.

3. تشغيل سير عمل متعدد الوكلاء

أدوات مثل Ruflo، منسق الوكلاء المتعددين فوق Claude Code، تشغّل عدة نسخ من Claude على نفس المهمة ثم تدمج النتائج. هذا يستهلك الحصة بسرعة لأنك لا تشغّل وكيلًا واحدًا، بل 3 إلى 5 وكلاء بالتوازي.

مع السقف الجديد، تصبح هذه التجارب أكثر قابلية للاستخدام اليومي، مثل:

وكيل يكتب التنفيذ.
وكيل يراجع الأمان.
وكيل يكتب الاختبارات.
وكيل يتحقق من التوافق مع التصميم أو مواصفة API.

4. استخدام أثقل لخوادم MCP

يستدعي Claude Code أدوات خارجية عبر بروتوكول سياق النموذج MCP، وتُحسب هذه الاستدعاءات ضمن الحصة. إذا كنت تؤجل ربط خوادم MCP بسبب الاستهلاك، فالوقت مناسب لتجربتها.

أمثلة على خوادم MCP مفيدة:

الوصول إلى قاعدة بيانات محلية للقراءة.
تشغيل اختبارات API.
أتمتة المتصفح.
فرز GitHub issues.
قراءة logs أو traces.

مثال طلب عملي:

استخدم خادم MCP الخاص بالاختبارات لتشغيل اختبارات endpoint /users.
إذا فشل اختبار، اقرأ الاستجابة، حدّد سبب عدم تطابق العقد، وعدّل الكود أو المواصفة حسب الحاجة.

إذا واجهت مشكلة إعداد في Claude Code، راجع إصلاح تكوين المؤسسة custom3p غير الصالح.

الخطة العملية للأسابيع الثمانية القادمة

لديك حتى 13 يوليو. لا تستخدم الزيادة بشكل عشوائي؛ استخدمها لاختبار workflows ذات قيمة حقيقية.

1. شغّل workflow الوكيل الذي كنت تؤجله

إذا كان لديك workflow قائم على /goal أو متعدد الوكلاء وكان قريبًا من أن يصبح عمليًا ضمن الحدود القديمة، ابنِه الآن.

ابدأ بمهمة واحدة واضحة:

/goal
Migrate the billing module from callbacks to async/await.
Success criteria:
- No behavior changes.
- Unit tests pass.
- Add regression tests for failed payments.
- Keep public function signatures unchanged unless necessary.

بعد انتهاء المهمة، سجّل:

كم استهلكت من الحصة؟
كم مرة احتجت للتدخل؟
هل النتيجة أفضل من تنفيذها يدويًا؟
هل تحتاج خطة أعلى إذا انتهت الزيادة؟

2. انقل المهام الجانبية إلى Claude Code

مهام كانت تُنفّذ يدويًا يمكن الآن نقلها إلى Claude Code دون استنزاف السقف بسرعة، مثل:

كتابة ملفات AGENTS.md.
مراجعة pull requests.
إنشاء مواصفات OpenAPI.
إعداد خوادم MCP.
تلخيص بنية مشروع قديم.
كتابة اختبارات تكامل.

للبدء السريع، راجع دليل كتابة ملفات AGENTS.md.

مثال prompt لإنشاء ملف AGENTS.md:

أنشئ ملف AGENTS.md لهذا المستودع.
يجب أن يتضمن:
- أوامر التثبيت والتشغيل والاختبار.
- قواعد تنسيق الكود.
- حدود ما يجب على الوكيل تعديله.
- خطوات التحقق قبل فتح pull request.

3. اختبر السقف الجديد بصدق

استخدم Claude Code كما لو أن الحدود الجديدة دائمة. الهدف ليس فقط الاستفادة المؤقتة، بل جمع بيانات قرار:

هل تكفيك خطة Pro بعد الزيادة؟
هل تحتاج Max؟
هل من الأفضل تقسيم العمل بين أكثر من مزود؟
ما المهام التي تستهلك الحصة دون عائد واضح؟

استخدم /usage عدة مرات خلال الأسبوع وسجّل النتائج في ملف بسيط:

# Claude Code usage log

## Week 1
- Main tasks:
- Agents used:
- API work:
- Reached warning? yes/no
- Notes:

## Week 2
- Main tasks:
- Agents used:
- API work:
- Reached warning? yes/no
- Notes:

أين يدخل عمل واجهات API

بالنسبة لمهندسي backend والمنصات، أفضل استخدام للسعة الإضافية هو عمل API. السبب أن مهام API تستهلك توكنات كثيرة لأنها تحتاج إلى:

قراءة handlers.
فهم models وDTOs.
مقارنة التنفيذ مع OpenAPI.
تشغيل اختبارات تكامل.
إصلاح اختلافات العقد.
تكرار cycle التنفيذ والاختبار.

Workflow عملي باستخدام Apidog وClaude Code

صمّم عقد API في Apidog.

عرّف endpoints، مخططات الطلب والاستجابة، وأمثلة payload. اجعل Apidog مصدر الحقيقة.
صدّر مواصفة OpenAPI.

أعطِ الملف لـ Claude Code كسياق داخل المشروع.
اطلب من Claude Code التنفيذ مقابل المواصفة.

مثال:

/goal
Implement the API described in openapi.yaml.
Success criteria:
- Every endpoint in the spec has a handler.
- Request validation matches the schema.
- Response shape matches the examples.
- Existing tests pass.
- Add integration tests for all 2xx and 4xx cases.

شغّل اختبارات Apidog CLI كمدقق.

استخدم اختبارات Apidog CLI للتأكد أن التنفيذ يطابق العقد الحقيقي، لا افتراضات الوكيل.
اجعل Claude Code يصلح الفشل بناءً على نتائج الاختبار.

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

بهذا الشكل يصبح Claude Code جزءًا من loop تصميم وتنفيذ واختبار API، وليس مجرد مساعد يكتب snippets منفصلة.

لشرح أعمق لفلسفة contract-first مع وكلاء الذكاء الاصطناعي، راجع دليل سير عمل واجهة برمجة التطبيقات بالاعتماد على التصميم أولاً.

إذا لم تستخدم Apidog من قبل، يمكنك تنزيل Apidog وتجربة workflow التصميم أولاً مع حصة Claude Code الإضافية.

ماذا عن الوصول المجاني إلى واجهة برمجة تطبيقات Claude؟

إذا كنت لا تريد الدفع مقابل خطة Claude Code، فهناك مسارات منفصلة للوصول إلى Claude API. يشرح دليل الوصول المجاني إلى واجهة برمجة تطبيقات Claude الخيارات التي تقدمها Anthropic وشركاؤها.

لكن هذه المسارات منفصلة عن حصة Claude Code المدفوعة. زيادة 50% تنطبق فقط على:

Pro
Max
Team
الخطط المؤسسية القائمة على المقاعد

ولا تغيّر حدود Claude API المباشرة.

ما الذي لا يغيّره هذا التحديث

هذا التحديث لا يقوم بـ:

تغيير حدود معدل Claude API للمستخدمين الذين يستدعون API مباشرة.
تغيير الأسعار في أي مستوى.
إضافة ميزات جديدة إلى Claude Code نفسه.
تغيير آلية الفوترة في الخطط المؤسسية القائمة على المقاعد.

إنها زيادة في سقف الاستخدام فقط. القيمة الحقيقية تعتمد على كيفية استغلالك للمساحة الإضافية.

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

متى تنتهي الزيادة بنسبة 50%؟

تنتهي في 13 يوليو 2026 الساعة 6 مساءً بتوقيت المحيط الهادئ الصيفي، أي 1 صباحًا بتوقيت جرينتش في 14 يوليو. بعد ذلك لم تعلن Anthropic ما إذا كان السقف سيعود إلى الأساس أو سيستمر.

هل أحتاج إلى تفعيلها يدويًا؟

لا. الحدود مرفوعة بالفعل في حسابك. استخدم الأمر التالي داخل Claude Code CLI:

/usage

هل تنطبق زيادة 50% على حد الخمس ساعات؟

لا. زيادة 50% تخص الحد الأسبوعي. أما حد الخمس ساعات فقد تمت مضاعفته بشكل منفصل في الأسبوع السابق. كلاهما سارٍ حتى 13 يوليو.

ماذا يحدث إذا قمت بالترقية أثناء الفترة؟

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

هل يؤثر هذا على Claude API؟

لا. التغيير خاص بخطط Claude Code فقط. إذا كنت تستدعي Claude عبر Anthropic API مباشرة، فحدود المعدل الخاصة بك تُدار بشكل منفصل.

هل ستصبح الزيادة دائمة؟

غير معروف. تعامل مع الأسابيع القادمة كتجربة إنتاجية: اختبر workflows حقيقية، سجّل الاستهلاك، ثم قرر هل تحتاج سقفًا أعلى بعد انتهاء الفترة أم لا.

كيفية اختبار واجهات برمجة تطبيقات راست (Rust API)؟

Yusuf Khalidd — Wed, 13 May 2026 08:49:06 +0000

لغة Rust تمنحك خادم HTTP سريعًا وآمنًا من حيث الأنواع بسرعة، لكنها لا تمنحك دائمًا حلقة تغذية راجعة سريعة لاختبار عقد الـ API. cargo test مهم، لكنه يدور حول الكود لا حول HTTP الفعلي. لاختبار أكواد الحالة، شكل JSON، الرؤوس، JWT، وطلبات الواجهة الأمامية قبل اكتمال المعالج، تحتاج أداة تعمل خارج سلسلة أدوات Rust وتتحدث مع الخادم قيد التشغيل.

جرّب Apidog اليوم

هذا الدليل يوضح سير عمل عملي لاختبار واجهة برمجة تطبيقات Rust داخل Apidog: توصيل Apidog بخادم Axum أو Actix، إنشاء طلبات، التحقق من JSON المُسلسل بواسطة Serde، التعامل مع JWT، إنشاء mocks للواجهة الأمامية، ثم تشغيل كل ذلك في CI. إذا كنت تستخدم Postman أو curl، فستحصل أيضًا على مواصفات OpenAPI، عناوين mock قابلة للمشاركة، وبيئات عمل جماعية. يمكنك قراءة قصة ترحيل Postman لاحقًا؛ هنا نركز على Rust.

ملخص سريع

شغّل خادم Rust محليًا باستخدام cargo run.
أضف http://localhost:3000 كـ baseUrl في بيئة Apidog.
أنشئ طلب GET /healthz كاختبار دخان.
اختبر JSON القادم من Serde باستخدام assertions بعد كل طلب.
خزّن JWT في متغير {{token}} وطبّق Bearer Auth على مستوى المجلد.
استخدم Mock endpoints حتى تعمل الواجهة الأمامية قبل اكتمال المعالج.
احفظ الطلبات كسيناريو اختبار وشغّلها في CI باستخدام apidog-cli.

لماذا تختبر Rust API خارج `cargo test`؟

cargo test ممتاز لاختبارات الوحدة والتكامل داخل Rust، لكنه ليس دائمًا أفضل طبقة لاختبار عقد HTTP العام.

إذا أردت التأكد من أن المعالج يعيد:

Status code صحيحًا
JSON بالشكل المتوقع
Headers صحيحة
رسالة خطأ واضحة عند الإدخال غير الصحيح
سلوكًا ثابتًا أمام الواجهة الأمامية

فستحتاج عادة إلى كتابة اختبارات HTTP داخل Rust أو استخدام curl يدويًا. هذا يعمل، لكنه يصبح مكلفًا مع تغيّر المعالجات.

Apidog يضيف طبقة عقد فوق الخادم قيد التشغيل:

الطلبات محفوظة وقابلة لإعادة التشغيل.
التأكيدات موجودة بجانب الطلب.
الفريق كله يرى نفس العقود.
يمكن تشغيل نفس السيناريو في CI.
يمكن توليد OpenAPI من الطلبات المحفوظة.

الفكرة: اترك cargo test لاختبار كود Rust، واستخدم Apidog لاختبار واجهة HTTP كما يراها العملاء.

الخطوة 1: أضف خادم Rust كبيئة في Apidog

ابدأ بخادم Axum بسيط:

use axum::{routing::get, Router};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() {
    let app = Router::new().route("/healthz", get(|| async { "ok" }));

    let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap();

    axum::serve(listener, app).await.unwrap();
}

شغّله:

cargo run

في Apidog:

أنشئ مشروعًا جديدًا.
افتح إدارة البيئات.
أضف بيئة باسم Rust Local.

المتغير	القيمة
`baseUrl`	`http://localhost:3000`
`token`	اتركها فارغة الآن
`apiVersion`	`v1`

أضف بيئة ثانية باسم Rust Staging واستخدم عنوان URL التجريبي. بهذه الطريقة يمكنك التبديل بين المحلي والتجريبي بدون تعديل كل طلب يدويًا.

الخطوة 2: أنشئ أول طلب

داخل المشروع، أنشئ مجلدًا باسم Rust API، ثم أضف طلبًا جديدًا:

Method: GET
URL: {{baseUrl}}/healthz

اضغط Send.

النتيجة المتوقعة:

200 OK
ok

احفظ الطلب باسم:

health-check

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

إذا ظهر خطأ connection refused، تحقق من:

أن الخادم يعمل.
أن المنفذ صحيح.
أن الخادم مربوط بـ 0.0.0.0:3000 وليس فقط 127.0.0.1:3000، خصوصًا إذا كنت تستخدم Docker أو بيئة محلية مختلفة.

الخطوة 3: اختبر طلب واستجابة JSON باستخدام Serde

أضف مسارًا لإنشاء مستخدم:

use axum::{extract::Json, routing::post, Router};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

#[derive(Serialize)]
struct User {
    id: u64,
    name: String,
    email: String,
}

async fn create_user(Json(payload): Json<CreateUser>) -> Json<User> {
    Json(User {
        id: 1,
        name: payload.name,
        email: payload.email,
    })
}

let app = Router::new().route("/users", post(create_user));

في Apidog، أنشئ طلبًا جديدًا:

Method: POST
URL: {{baseUrl}}/users
Body: JSON

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

أرسل الطلب واحفظه باسم:

create-user

أضف assertions في تبويب Tests:

pm.test("Status is 200", () => {
  pm.expect(pm.response.code).to.eql(200);
});

pm.test("Body has id, name, email", () => {
  const body = pm.response.json();

  pm.expect(body).to.have.property("id");
  pm.expect(body.name).to.eql("Ada Lovelace");
  pm.expect(body.email).to.match(/^[^@]+@[^@]+$/);
});

الآن إذا تغيّر شكل الاستجابة لاحقًا بسبب serde، مثل إضافة:

#[serde(rename_all = "camelCase")]

فسيفشل اختبار العقد قبل أن يصل التغيير إلى الإنتاج.

الخطوة 4: غطِّ حالات رفض Serde

لا تختبر المسار السعيد فقط. اختبر المدخلات الخاطئة أيضًا.

أنشئ الطلبات التالية في Apidog:

الطلب	Body	المتوقع
`create-user-missing-email`	`{ "name": "Ada" }`	`422`، مع رسالة عن الحقل المفقود
`create-user-extra-field`	`{ "name": "Ada", "email": "a@b.c", "admin": true }`	`200` إذا لم تستخدم `deny_unknown_fields`، أو `422` إذا استخدمته
`create-user-wrong-type`	`{ "name": 1, "email": "a@b.c" }`	`422`، مع رسالة عن النوع غير الصحيح

مثال assertion:

pm.test("Status is 422", () => {
  pm.expect(pm.response.code).to.eql(422);
});

هذه الاختبارات توثق سياسة التحقق الفعلية. إذا قررت لاحقًا إضافة:

#[serde(deny_unknown_fields)]

فسيتغير سلوك extra-field، وسيظهر ذلك فورًا في Apidog وCI.

الخطوة 5: اختبر المسارات المحمية بواسطة JWT

غالبًا ما تكون واجهات Rust الإنتاجية محمية بطبقة مصادقة. مثال مبسط باستخدام JWT:

use axum::{Json, http::StatusCode};
use axum_extra::extract::cookie::PrivateCookieJar;
use jsonwebtoken::{decode, DecodingKey, Validation};

async fn me(jar: PrivateCookieJar) -> Result<Json<User>, StatusCode> {
    let token = jar
        .get("token")
        .ok_or(StatusCode::UNAUTHORIZED)?;

    let claims = decode::<Claims>(
        token.value(),
        &DecodingKey::from_secret(b"secret"),
        &Validation::default(),
    )
    .map_err(|_| StatusCode::UNAUTHORIZED)?;

    Ok(Json(User {
        id: claims.claims.sub,
        name: "Ada".into(),
        email: "ada@example.com".into(),
    }))
}

بدل إنشاء JWT يدويًا لكل طلب، أضف Pre-Request Script على مستوى المجلد في Apidog:

const jwt = require("jsonwebtoken");

const token = jwt.sign(
  {
    sub: 1,
    exp: Math.floor(Date.now() / 1000) + 3600
  },
  "secret"
);

pm.environment.set("token", token);

ثم من إعدادات المجلد:

Auth Type: Bearer Token
Token: {{token}}

الآن ترث كل الطلبات داخل المجلد نفس إعداد المصادقة، ويتم توليد JWT جديد قبل التشغيل.

للمزيد حول اختبار JWT، راجع كيفية اختبار مصادقة JWT في واجهات برمجة التطبيقات.

الخطوة 6: اختبر Streaming و Server-Sent Events

يدعم Axum وActix التدفق كجزء أساسي من HTTP. في Axum، يمكن أن يعيد المعالج Sse مبنيًا على futures::Stream.

تنسيق SSE عادة يكون:

data: { ... }

data: { ... }

event: done
data: {}

في Apidog:

أنشئ طلب GET لنقطة SSE.
أرسله.
إذا كان Content-Type هو text/event-stream، ستظهر الاستجابة في وضع streaming.
راقب كل frame مع زمن وصوله.

ما يجب اختباره:

أول event يصل ضمن الزمن المتوقع.
event معين مثل event: done يصل قبل إغلاق الاتصال.
الاتصال لا يبقى مفتوحًا للأبد.
يمكن ضبط timeout للطلب حتى يفشل الاختبار عند التدفق غير المنتهي.

إذا كنت تستخدم WebSocket بدل SSE، استخدم نوع طلب WebSocket في Apidog واحفظ تسلسل الرسائل والاستجابات بنفس الفكرة.

الخطوة 7: أنشئ Mock API لتطوير الواجهة الأمامية بالتوازي

الواجهة الأمامية لا تحتاج انتظار اكتمال كل معالج Rust. يمكنها العمل ضد mock ثابت طالما أن العقد واضح.

في Apidog:

افتح طلب create-user.
اختر Smart Mock.
فعّله.

سيُنشئ Apidog endpoint مثل:

https://mock.apidog.com/m1/<projectId>/users

ويمكن للواجهة الأمامية إرسال POST إليه بنفس شكل الطلب الحقيقي.

لـ mock ديناميكي، استخدم Advanced Mock:

return {
  id: Math.floor(Math.random() * 10000),
  name: body.name,
  email: body.email,
  createdAt: new Date().toISOString()
};

النتيجة: الواجهة الأمامية تحصل على id وcreatedAt واقعيين بدون انتظار معالج Rust.

عندما يصبح المعالج جاهزًا، تغيّر الواجهة الأمامية baseUrl من mock إلى:

http://localhost:3000

ولا تحتاج لتغيير شكل الطلب.

لنفس النمط في بيئات أخرى، راجع بناء واختبار واجهة برمجة تطبيقات Spring Boot وسير عمل اختبار واجهة برمجة التطبيقات العام.

الخطوة 8: احفظ الطلبات كسيناريو CI

حوّل الطلبات إلى سيناريو اختبار قابل للتشغيل بدون واجهة رسومية.

مثال تسلسل:

health-check

تأكيد 200.
create-user

تأكيد 200، ثم خزّن body.id في متغير.
create-user-missing-email

تأكيد 422.
me

يستخدم JWT من Pre-Request Script، ثم يؤكد 200.
طلب SSE

يؤكد أن التدفق يكتمل خلال 5 ثوانٍ.

مثال لتخزين id بعد إنشاء المستخدم:

const body = pm.response.json();

pm.environment.set("userId", body.id);

ثم يمكن استخدامه لاحقًا:

pm.test("Returned id matches created user", () => {
  const body = pm.response.json();

  pm.expect(String(body.id)).to.eql(String(pm.environment.get("userId")));
});

صدّر السيناريو كملف JSON وضعه في المستودع:

tests/apidog/contract.json

مثال GitHub Actions:

- name: Run API contract tests
  run: |
    cargo build --release
    ./target/release/myserver &
    sleep 2
    apidog-cli run tests/apidog/contract.json --env "Rust Local"

الآن كل Pull Request يلمس معالجًا يحصل على اختبار عقد فعلي ضد binary قيد التشغيل.

الخطوة 9: أنشئ OpenAPI من الطلبات المحفوظة

بعد استقرار الطلبات:

افتح قائمة Export في Apidog.
اختر OpenAPI 3.1.
صدّر المواصفة.

ستحصل على ملف مواصفات مبني من الطلبات والأمثلة التي اختبرتها فعليًا.

يمكنك أيضًا تشغيل التصدير من CI:

apidog-cli export --format openapi --output openapi.json

ثم أضف openapi.json إلى المستودع حتى يستخدمه من يحتاج إلى توليد عملاء TypeScript أو Swift أو Kotlin أو Python.

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

هل يعمل Apidog مع Axum وActix-web؟

نعم. Apidog يتعامل مع HTTP، لذلك يعمل مع Axum وActix-web وRocket وWarp وPoem وLoco. النقطة المهمة في التطوير المحلي هي ربط الخادم بـ 0.0.0.0 عند الحاجة.

كيف أختبر المعالجات التي تتعطل؟

يمكنك وضع CatchPanicLayer من tower-http أمام الـ router لتحويل panic إلى 500. بعدها أنشئ طلبًا في Apidog يؤدي إلى هذا المسار وتأكد من status code.

إذا لم تغلف حالات panic، قد يسقط الاتصال ويظهر خطأ شبكة. هذا أيضًا سلوك عقد يمكن توثيقه.

هل يمكن تشغيل Apidog ضد binary داخل Docker؟

نعم. اجعل baseUrl يشير إلى المنفذ المكشوف للحاوية. إذا كنت تستخدم Docker Compose، تأكد أن مشغل Apidog يستطيع الوصول إلى نفس الشبكة أو استخدم المنفذ المربوط بالمضيف.

ماذا عن gRPC؟

Apidog يدعم نوع طلب gRPC. استورد ملفات .proto، اختر service وmethod، املأ request body، ثم أرسل. نفس مفاهيم البيئات والمصادقة وسيناريوهات الاختبار تنطبق أيضًا.

هل يغني ذلك عن `cargo test`؟

لا. استخدم cargo test لاختبارات منطق Rust الداخلي. استخدم Apidog لاختبار العقد التشغيلي عبر HTTP.

الطبقتان تكملان بعضهما:

cargo test يكتشف دالة مكسورة.
Apidog يكتشف JSON خاطئًا، status code مختلفًا، header مفقودًا، أو سلوك مصادقة غير متوقع.

هل Apidog مجاني لمشاريع Rust مفتوحة المصدر؟

نعم. عميل Apidog مجاني للأفراد والفرق الصغيرة، وتتضمن الطبقة المجانية سيناريوهات الاختبار، المحاكاة، وتصدير OpenAPI.

الخلاصة

واجهات Rust تحتاج اختبارًا لا ينتظر المترجم في كل مرة. باستخدام Apidog يمكنك بناء مجموعة طلبات تتحقق من HTTP الحقيقي، JSON الحقيقي، JWT، mocks للواجهة الأمامية، وسيناريو CI يعمل ضد binary فعلي.

ابدأ بـ GET /healthz، أضف طلبات JSON، غطِّ حالات Serde الفاشلة، ثم شغّل السيناريو في CI. بعد ذلك يصبح كل تغيير في Axum أو Actix اختبار عقد واضحًا بدل مفاجأة في وقت التشغيل.

قم بتنزيل Apidog ووجهه إلى خادم Rust الخاص بك. الإعداد يستغرق دقائق، والنتيجة عقد API مستقل عن cargo وقابل للمشاركة مع الفريق.