DEV Community

Cover image for كيفية استخدام Apidog CLI في وكيل هيرميس
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام Apidog CLI في وكيل هيرميس

يعمل وكيل Hermes من الطرفية، ويتذكر ما يتعلمه عبر الجلسات، ويشغّل أوامر Shell حقيقية. لذلك إذا كان بإمكانه تشغيل أمر، فيمكنه تشغيل اختبارات واجهة برمجة التطبيقات عبر Apidog CLI.

جرّب Apidog اليوم

الأداة التي تربط Hermes باختباراتك هي Apidog CLI، وهي حزمة npm باسم apidog-cli. يشغّل الأمر apidog run سيناريوهات الاختبار التي أنشأتها بصريًا في Apidog مباشرة من الطرفية، ثم يرجع رمز خروج يستطيع Hermes الاعتماد عليه لاتخاذ قرار: نجاح أو فشل.

في هذا الدليل ستضبط Hermes عمليًا لكي:

  1. يعرف أمر apidog run من ملف سياق داخل المستودع.
  2. يشغّل الاختبار عبر أداة terminal.
  3. يقرأ رمز الخروج بدل الاعتماد على ملخص نصي.
  4. يستخدم خادم Apidog MCP اختياريًا لقراءة مواصفات API أثناء كتابة الكود.

إذا لم يكن CLI مثبتًا بعد، ابدأ من كيفية تثبيت Apidog CLI باستخدام وكيل ترميز يعمل بالذكاء الاصطناعي. عد عندما يطبع الأمر التالي رقم إصدار:

apidog --version
Enter fullscreen mode Exit fullscreen mode

ستحتاج أيضًا إلى حساب Apidog وسيناريو اختبار واحد محفوظ على الأقل.

ماذا يعني استخدام Apidog CLI داخل Hermes؟

Hermes، من Nous Research، يعمل داخل الطرفية ويتصرف عبر أدوات مدمجة. الأداة المهمة هنا هي terminal: يستخدمها Hermes لتشغيل أوامر Shell داخل دليل العمل، ثم يقرأ الإخراج ويستنتج الخطوة التالية.

لا تحتاج إلى مكون إضافي خاص بـ Apidog. الإعداد العملي يتكون من ثلاث قطع:

  1. ملف سياق مثل AGENTS.md يشرح لـ Hermes أمر الاختبار وقاعدة النجاح/الفشل.
  2. تشغيل apidog run عبر أداة terminal.
  3. خادم Apidog MCP اختياري حتى يستطيع Hermes قراءة مواصفات API أثناء تعديل الكود.

الفكرة ليست أن تطلب من Hermes كل مرة: "شغّل هذا الأمر". الأفضل أن تضع التعليمات في المستودع مرة واحدة، فيقرأها Hermes تلقائيًا في كل جلسة.

الآلية: استخدم ملف سياق بدل تذكير داخل المحادثة

عند بدء الجلسة، يبحث Hermes في دليل العمل عن ملفات تعليمات مثل:

  • AGENTS.md
  • CLAUDE.md

ثم يحقن محتواها في سياق النظام. لذلك ضع تعليمات الاختبار في ملف داخل المستودع بدل كتابتها يدويًا في المحادثة.

استخدم AGENTS.md لتعليمات المشروع. قد يقرأ Hermes أيضًا SOUL.md، لكن هذا مخصص لشخصية الوكيل وليس لسير عمل الاختبار.

الخطوة 1: أضف تعليمات Apidog إلى AGENTS.md

أنشئ ملف AGENTS.md في جذر المستودع، أو افتحه إذا كان موجودًا، ثم أضف كتلة واضحة تحتوي على الأمر الحقيقي ومعرفات Apidog الفعلية.

مثال:

## API testing with the Apidog CLI

This repo uses the Apidog CLI (`apidog-cli`, the `apidog` command) to run API
test scenarios. The scenarios live in our Apidog project, not in this repo.

When you change an API handler, route, or response shape, run the relevant
Apidog scenario through the terminal tool before considering the change done:

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` is the checkout-flow test scenario.
- `-e 1629989` is the staging environment.
- The machine is already authenticated via `apidog login`, so do NOT pass
  an access token and do NOT print one.

Treat the exit code as the source of truth: `0` means every assertion passed,
non-zero means a failure. If it exits non-zero, read the failing assertion in
the report and fix the code, then re-run. Do not report a pass on a non-zero
exit.
Enter fullscreen mode Exit fullscreen mode

استبدل:

  • 605067 بمعرف سيناريو الاختبار لديك.
  • 1629989 بمعرف البيئة التي تريد الاختبار عليها، مثل staging أو بيئة التطوير المحلية.
  • لا تستخدم الإنتاج كبيئة افتراضية لتشغيل الوكيل.

هذه الكتلة مهمة لسببين:

  1. تمنع Hermes من تخمين flags غير صحيحة.
  2. تجبره على اعتبار رمز الخروج هو مصدر الحقيقة.

قاعدة العمل بسيطة:

exit code 0     => كل التأكيدات نجحت
exit code != 0  => يوجد فشل ويجب إصلاحه
Enter fullscreen mode Exit fullscreen mode

الخطوة 2: انسخ أمر التشغيل الصحيح من Apidog

قبل أن تطلب من Hermes تشغيل أي شيء، احصل على أمر صحيح من Apidog.

داخل Apidog:

  1. افتح سيناريو الاختبار.
  2. انتقل إلى تبويب CI/CD.
  3. اختر خيار سطر الأوامر.
  4. انسخ أمر apidog run.

سيكون شبيهًا بهذا:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

إذا كنت قد سجلت الدخول محليًا عبر CLI، احذف --access-token من الأمر قبل وضعه في AGENTS.md:

apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

لا تضع رمز الوصول داخل ملف ملتزم به في Git.

الخطوة 3: اطلب من Hermes تشغيل الاختبار

ابدأ Hermes من جذر المستودع، ثم اطلب منه تشغيل السيناريو بناءً على ملف السياق.

مثال موجه:

شغّل سيناريو اختبار واجهة برمجة التطبيقات في Apidog كما يصف AGENTS.md. أنا مصادق بالفعل، لذلك لا تمرر رمز وصول. استخدم apidog run -t 605067 -e 1629989 -n 1 -r cli. أعرض الإخراج الكامل وأخبرني برمز الخروج.

سيشغّل Hermes الأمر عبر أداة terminal:

apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

يستخدم الخيار -r cli إخراجًا مناسبًا للطرفية، بحيث يستطيع Hermes قراءة خطوات الاختبار والنتائج.

إذا كان Hermes يعمل بطبقة موافقات، قد يظهر طلب موافقة قبل تشغيل الأمر. بالنسبة لاختبار قراءة فقط ضد staging، يكون هذا عادة أمرًا آمنًا داخل مساحة العمل.

كيف تتحقق من النتيجة؟

لا تعتمد على جملة مثل "الاختبارات نجحت". تحقق من رمز الخروج.

echo $?
Enter fullscreen mode Exit fullscreen mode

أو اطلب من Hermes أن يذكر رمز الخروج صراحة.

المعيار:

  • 0: كل التأكيدات نجحت.
  • غير 0: يوجد فشل.

إذا قال Hermes إن الاختبارات نجحت بينما رمز الخروج غير صفري، فاعتبر التشغيل فاشلًا. رمز الخروج هو مصدر الحقيقة.

للاطلاع على flags المتاحة في إصدار CLI لديك، شغّل:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

للتفاصيل الكاملة حول التقارير مثل html وjson وjunit، راجع الدليل الكامل لـ Apidog CLI.

الخطوة 4: أدخل الاختبار في دورة عمل Hermes

بعد إضافة كتلة AGENTS.md، يصبح السلوك المتوقع كالتالي:

  1. يعدّل Hermes كود API، مثل handler أو route أو response schema.
  2. يلاحظ أن التغيير يمس واجهة API.
  3. يشغّل سيناريو Apidog عبر terminal.
  4. يقرأ رمز الخروج.
  5. إذا فشل الاختبار، يقرأ التأكيد الفاشل ويصلح الكود.
  6. يعيد التشغيل حتى يصبح رمز الخروج 0.

مثال دورة عملية:

تعديل handler
→ تشغيل apidog run
→ فشل assertion بسبب حقل مفقود
→ تعديل response body
→ إعادة تشغيل apidog run
→ exit code 0
Enter fullscreen mode Exit fullscreen mode

بهذا يصبح اختبار API جزءًا من حلقة التعديل والاختبار والإصلاح، مثل اختبارات الوحدة.

للتشغيلات الطويلة، يمكن لـ Hermes تشغيل الأمر في الخلفية إذا كان تكوين أداة terminal يدعم background=true، ثم يعود لاحقًا لقراءة الإخراج ورمز الخروج.

للنمط الأوسع لاستخدام الوكلاء في اختبار API، راجع:

اختياري: وصّل خادم Apidog MCP

يشغّل CLI الاختبارات، بينما يسمح خادم Apidog MCP لـ Hermes بقراءة مواصفات API أثناء كتابة الكود.

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

  • MCP يعطي Hermes العقد والمخطط.
  • CLI يتحقق من السلوك الفعلي عبر السيناريوهات.

أضف إعداد MCP في:

~/.hermes/config.yaml
Enter fullscreen mode Exit fullscreen mode

مثال:

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"
Enter fullscreen mode Exit fullscreen mode

بعد الحفظ:

/reload-mcp
Enter fullscreen mode Exit fullscreen mode

أو أعد تشغيل Hermes.

يسجل Hermes أدوات MCP تحت مساحة أسماء مثل:

mcp_apidog_<tool>
Enter fullscreen mode Exit fullscreen mode

لإعداد معرف المشروع والرمز، راجع دليل خادم Apidog MCP.

ولنسخة مشابهة من هذه الحلقة مع Claude، راجع دليل Apidog CLI مع مهارات Claude.

من التشغيل المحلي إلى CI

بعد أن يعمل الأمر محليًا داخل Hermes، استخدم الأمر نفسه في CI.

الفرق الأساسي:

  • محليًا: تعتمد على apidog login.
  • في CI: تمرر رمز الوصول كسِرّ مخفي.

اطلب من Hermes كتابة خطوة GitHub Actions مثلًا:

اكتب خطوة لـ GitHub Actions تقوم بتثبيت apidog-cli وتشغّل apidog run -t 605067 -e 1629989 -r junit، مع قراءة رمز الوصول من سر مستودع باسم APIDOG_ACCESS_TOKEN.

مثال عام:

- name: Install Apidog CLI
  run: npm install -g apidog-cli

- name: Run Apidog API tests
  run: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

آليات الأسرار والتقارير وبوابة رمز الخروج مشروحة في Apidog CLI في GitHub Actions.

بهذا تستخدم الأمر نفسه في:

  1. طرفيتك.
  2. دورة Hermes.
  3. GitHub Actions أو أي CI آخر.

المشكلات الشائعة

Hermes يتجاهل AGENTS.md

تحقق من الآتي:

  • اسم الملف هو AGENTS.md أو CLAUDE.md بالضبط.
  • الملف موجود في الدليل الذي بدأت منه Hermes.
  • أعد تشغيل الجلسة بعد تعديل الملف.

Hermes يقترح الأمر بدل تشغيله

Hermes يشغّل الأوامر عبر أداة terminal وخلف طبقة موافقات. وافق على التشغيل إذا ظهر طلب موافقة.

إذا كان تكوينك يمنع أوامر الطرفية، اسمح بأمر:

apidog run
Enter fullscreen mode Exit fullscreen mode

apidog whoami يظهر أنك غير مصادق

تسجيل الدخول محفوظ على جهازك، وليس داخل Hermes.

شغّل بنفسك:

apidog login --with-token
Enter fullscreen mode Exit fullscreen mode

ثم اطلب من Hermes التأكد:

apidog whoami
Enter fullscreen mode Exit fullscreen mode

لا تلصق رمز الوصول داخل المحادثة.

Hermes يخترع flag غير موجودة

إذا ظهر خطأ مثل:

unknown option
Enter fullscreen mode Exit fullscreen mode

اجعله يشغّل:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

ثم استخدم flags الموجودة في إصدار CLI المثبت لديك.

Hermes يعلن نجاح تشغيل فاشل

هذه أهم مشكلة يجب منعها.

القاعدة:

عند اختلاف الملخص النصي ورمز الخروج، ثق برمز الخروج.
Enter fullscreen mode Exit fullscreen mode

لذلك ضع قاعدة exit code داخل AGENTS.md واطلب من Hermes دائمًا عرض الرمز بعد التشغيل.

الخلاصة

إعداد Hermes لتشغيل اختبارات Apidog يحتاج إلى ملف واحد وعادة واحدة:

  1. أضف كتلة واضحة في AGENTS.md تحتوي على أمر apidog run والمعرفات وقاعدة رمز الخروج.
  2. اسمح لـ Hermes بتشغيل الأمر عبر terminal.
  3. تحقق من رمز الخروج بدل الملخص.
  4. أضف Apidog MCP اختياريًا إذا أردت أن يقرأ Hermes مواصفات API أثناء كتابة الكود.

تستمر أنت في بناء السيناريوهات بصريًا داخل Apidog، بينما يتولى Hermes تشغيلها محليًا أثناء تطوير الكود.

بعد ذلك، انقل الأمر نفسه إلى CI عبر Apidog CLI في GitHub Actions، أو راجع الدليل الكامل لكل خيارات CLI.

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

هل أحتاج إلى مكون إضافي لـ Hermes لاستخدام Apidog CLI؟

لا. Hermes يشغّل أوامر Shell عبر أداة terminal، لذلك يستطيع استدعاء apidog run مباشرة. الإعداد الخاص بـ Hermes هو ملف AGENTS.md، مع خادم MCP اختياري.

أين أضع تعليمات سير العمل؟

ضعها في AGENTS.md داخل جذر المستودع. يقرأ Hermes ملفات السياق مثل AGENTS.md وCLAUDE.md عند بدء الجلسة ويستخدمها أثناء العمل.

كيف أتأكد من أن Hermes لا يزيف نتيجة اختبار ناجحة؟

اطلب منه عرض رمز الخروج. يخرج apidog run بـ 0 فقط عندما تنجح كل التأكيدات. إذا كان الرمز غير صفري، فالتشغيل فاشل حتى لو قال الملخص غير ذلك.

كيف أوصل خادم Apidog MCP بـ Hermes؟

أضف إدخال mcp_servers إلى ~/.hermes/config.yaml باستخدام apidog-mcp-server ومعرف مشروعك، ثم شغّل /reload-mcp أو أعد تشغيل Hermes. راجع دليل خادم Apidog MCP للتفاصيل.

هل يعمل هذا مع وكلاء ترميز آخرين؟

نعم، CLI نفسه يعمل في أي بيئة تستطيع تشغيل أوامر Shell. الاختلاف فقط في طريقة تعليم الوكيل. Hermes يستخدم AGENTS.md وأداة terminal، بينما قد تستخدم وكلاء أخرى ملفات تعليمات مختلفة. التثبيت والمصادقة موضحان في دليل التثبيت.

Top comments (0)