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

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

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

إذا لم يكن CLI مثبتًا بعد، فابدأ بـ كيفية تثبيت Apidog CLI باستخدام وكيل ترميز يعمل بالذكاء الاصطناعي، والذي يرشد الوكيل خلال التثبيت والمصادقة. عد عندما يطبع apidog --version رقمًا. تحتاج أيضًا إلى حساب Apidog مع سيناريو اختبار واحد محفوظ على الأقل؛ قم بتنزيل Apidog إذا لم يكن لديك حساب.

ماذا يعني "استخدام CLI في Hermes"

يعمل وكيل Hermes، الذي بنته Nous Research، في طرفيتك، ويتحدث إلى نماذج الذكاء الاصطناعي الخاصة بك، ويتصرف من خلال أدوات مدمجة. الأداة المهمة هنا هي أداة terminal: يشغل Hermes أوامر shell عن طريق استدعائها في دليل عملك، ثم يقرأ الإخراج مرة أخرى في منطقه. لا يوجد مكون إضافي لـ Apidog لتثبيته، ولن تحتاج إلى واحد. استخدام Apidog CLI في Hermes يعني ثلاثة أمور:

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

ملف السياق هو ما يجعل هذا الدليل مصممًا لـ Hermes بدلاً من دليل عام يقول "افتح طرفية واكتب"، ويحول "تشغيل اختباراتي" لمرة واحدة إلى شيء يمكنه استدعاؤه بمفرده.

الآلية: ملف سياق، وليس تذكيرًا بالدردشة

يحمل Hermes سياق المشروع في بداية الجلسة. يقوم محرك السياق الخاص به بمسح دليل عملك بحثًا عن ملفات التعليمات، بما في ذلك CLAUDE.md و AGENTS.md، ويقوم بحقنها في موجه النظام. هذا هو نفس التقليد الذي يستخدمه Claude Code و Codex، لذلك إذا كان مستودعك يحتوي بالفعل على AGENTS.md، فإن Hermes يقرأه أيضًا.

لهذا السبب تكتب CLI في ملف سياق بدلاً من ذكره في الدردشة. معرّف السيناريو الذي يتم كتابته في جلسة يختفي عند انتهائها؛ بينما المعرّف الموجود في AGENTS.md يبقى متاحًا لكل عضو في الفريق ولكل تشغيل لـ Hermes من الآن فصاعدًا. (يقرأ Hermes أيضًا ملف SOUL.md، ولكن هذا خاص بشخصية الوكيل، وليس بمشروعك. احتفظ بتعليمات الاختبار في AGENTS.md.)

الخطوة 1: أضف كتلة Apidog إلى ملف السياق الخاص بك

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

## 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.

استبدل 605067 بمعرف السيناريو الحقيقي الخاص بك و 1629989 بالبيئة التي يجب أن يستهدفها Hermes أثناء العمل العادي، وعادةً ما تكون بيئة التجربة (staging) أو التطوير المحلي، وليس الإنتاج أبدًا. للحصول على المعرفات الصحيحة، انسخ أمر apidog run الذي ينشئه Apidog في علامة تبويب CI/CD الخاصة بالسيناريو (سيتم تناولها لاحقًا)، واحذف رمز الوصول قبل لصقه، نظرًا لأن الجهاز مسجل الدخول بالفعل ولا ينتمي الرمز المميز إلى ملف ملتزم به.

يساعد أمران على عمل هذه الكتلة. الأول، أنه يسمي الأمر بدقة، لذا فإن Hermes لا يخمن العلامات. والثاني، أنه يوضح قاعدة النجاح/الفشل بلغة واضحة، لذا فإن Hermes يعرف أن رمز الخروج يتفوق على ملخصه الخاص، مما ينقذك من أكثر أخطاء الوكيل شيوعًا: "الاختبارات نجحت" بثقة فوق تشغيل أحمر (فاشل).

الخطوة 2: احصل على الأمر من Apidog

احصل على أمر معروف وصحيح قبل أن تطلب من Hermes تشغيل أي شيء. افتح السيناريو الخاص بك في Apidog، وانتقل إلى علامة تبويب CI/CD، واختر خيار سطر الأوامر. يقوم Apidog بإنشاء الأمر الكامل apidog run مع المعرفات ورمز وصول مملوء مسبقًا:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

605067 هو معرّف السيناريو و 1629989 هو معرّف البيئة؛ ستختلف المعرفات الخاصة بك. نظرًا لأنك قمت بمصادقة CLI أثناء التثبيت، احذف جزء --access-token واحتفظ بالمعرفات. هذا هو الأمر الذي أخبر ملف السياق الخاص بك Hermes باستخدامه.

الخطوة 3: اجعل Hermes يشغل الاختبار

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

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

يستدعي Hermes أداة terminal الخاصة به لتنفيذ الأمر في دليل عملك، ويقوم المبلّغ -r cli ببث نتيجة خطوة بخطوة مرة أخرى إلى سياقه، حيث تشاهد كل طلب وتأكيد. نظرًا لأن Hermes يوجه الأوامر عبر طبقة موافقة، قد ترى موجهًا قبل تشغيله، اعتمادًا على تكوينك. سيناريو اختبار للقراءة فقط مقابل بيئة التجربة هو بالضبط نوع الأمر الآمن داخل مساحة العمل الذي يمكن السماح به.

فحصك: انظر إلى رمز الخروج، وليس الملخص. يخرج apidog run بـ 0 عندما تنجح كل التأكيدات و بقيمة غير صفرية عندما يفشل أحدها. هذا السلوك هو السبب الرئيسي لعمل هذا كبوابة، لـ CI ولـ Hermes. إذا قال Hermes "الاختبارات نجحت" ولكن رمز الخروج كان غير صفري، فهو مخطئ؛ ثق بالرمز. هذا هو الفشل الذي تمنعه كتلة الخطوة 1.

للحصول على تنسيق تقرير مختلف أو المزيد من التكرارات، اجعل Hermes يشغل apidog run --help ليقرأ قائمة العلامات الحقيقية. يوثق الدليل الكامل لـ Apidog CLI كل علامة، بما في ذلك المبلّغين html و json و junit.

الخطوة 4: اختبار Hermes داخل دورته الخاصة

الهدف هو ما يحدث عندما تتوقف عن الطلب ويشغل Hermes السيناريو بمفرده لأن AGENTS.md أخبره بذلك. تخيل أنه يقوم بتحرير معالج يقوم بإنشاء استجابة دفع: يقوم بتحرير الكود، ويشغل سيناريو Apidog الخاص بك مقابل بيئة التجربة عبر أداة terminal، ويقرأ رمز الخروج، ويتصرف بناءً عليه. إذا كانت النتيجة خضراء، فإنه ينتقل. إذا كانت حمراء، فإنه يفتح التقرير، ويقرأ التأكيد الذي فشل (رمز الحالة، الحقل المفقود، القيمة الخاطئة)، ويحاول إصلاحًا، ثم يعيد التشغيل. يصبح اختبار واجهة برمجة التطبيقات جزءًا من نفس حلقة التعديل والاختبار والإصلاح التي يشغل من خلالها اختبارات الوحدة الخاصة بك بالفعل. لقد كتبت تعليمًا واحدًا وقام بدمج الأمر في طريقة عمله بالفعل.

هذا هو نموذج التفويض ثم التحقق الذي يجعل أي سير عمل للوكيل آمنًا. يشغل Hermes الأمر ويقرأ النتيجة؛ تستمر أنت في إنشاء السيناريوهات في Apidog وتتحقق بشكل عشوائي من أنه يقرأ رموز الخروج بصدق. بالنسبة للتشغيل البطيء، أو مجلد كبير، أو عدد تكرارات عالٍ، تأخذ أداة terminal علامة background=true، بحيث يمكن لـ Hermes إطلاق المسح، ومواصلة العمل، والاستعلام عن رمز الخروج بدلاً من الحظر. للنمط الأوسع، راجع كيفية استخدام وكلاء الذكاء الاصطناعي لاختبار واجهة برمجة التطبيقات و أداة اختبار Apidog AI.

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

يسمح CLI لـ Hermes بـ تشغيل اختباراتك؛ ويسمح خادم Apidog MCP له بـ قراءة مواصفات واجهة برمجة التطبيقات الخاصة بك أثناء كتابة الكود. تتراكم الوظيفتان: يزود MCP هيرمس بالمخطط الخاص بك لكي يولد كودًا يتطابق مع العقد، ويتحقق CLI من هذا الكود مقابل السيناريوهات الحقيقية.

يدعم Hermes بروتوكول سياق النموذج (Model Context Protocol) بشكل جاهز. قم بتحرير ملف ~/.hermes/config.yaml وأضف إدخالاً تحت قسم mcp_servers. لخادم stdio محلي مثل خادم Apidog، يكون هذا عبارة عن command، ومصفوفة args، وأي قيم env:

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

بعد الحفظ، قم بتشغيل /reload-mcp داخل Hermes، أو أعد تشغيله. يكتشف Hermes خوادم MCP عند بدء التشغيل ويسجل أدواتها في سجله العادي، تحت مساحة أسماء mcp_apidog_<tool>، بحيث يستخدمها الوكيل أثناء التفكير العادي. للإعداد الكامل، بما في ذلك معرف المشروع والرمز، راجع دليل خادم Apidog MCP. للحصول على نسخة مجمعة من هذه الحلقة، راجع دليل Apidog CLI مع مهارات Claude.

من الحلقة المحلية إلى التكامل المستمر (CI)

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

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

توجد آليات هذه الخطوة (الأسرار، المبلّغون، بوابة رمز الخروج) في Apidog CLI في GitHub Actions. ثم يتم تشغيل نفس الأمر في ثلاثة أماكن: طرفيتك، حلقة Hermes، و CI، وكل ذلك بناءً على رمز خروج واحد.

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

يتجاهل Hermes كتلة السياق. إذا قام بتشغيل أمر عام أو لم يشغل أي شيء على الإطلاق، فتأكد من أن اسم الملف هو AGENTS.md (أو CLAUDE.md) بالضبط وأنه موجود في الدليل الذي بدأ فيه Hermes. يؤدي إعادة تشغيل الجلسة إلى قراءة جديدة.

يقترح الأمر فقط بدلاً من تشغيله. يشغل Hermes الأوامر عبر أداة terminal خلف طبقة موافقة. وافق على تشغيل معلق؛ إذا كان تكوينك يرفض أوامر الطرفية، فقم بتخفيف إذن apidog run.

apidog whoami يظهر أنك غير مصادق. يتم تخزين تسجيل الدخول على جهازك، وليس في Hermes. قم بتشغيل apidog login --with-token بنفسك باستخدام رمز جديد، ثم اطلب من Hermes التأكيد باستخدام apidog whoami. احتفظ بالرمز خارج الدردشة.

يخترع علامة. يعني خطأ "خيار غير معروف" أن Hermes خمن علامة غير موجودة في إصدارك. اجعله يشغل apidog run --help وانسخ العلامة الحقيقية.

يبلغ عن نجاح في تشغيل فاشل. هذه هي الأكثر تكلفة، والسبب في أن قاعدة رمز الخروج موجودة في كل من AGENTS.md وفي فحصك اليدوي. عندما يختلف الملخص ورمز الخروج، يفوز الرمز.

خاتمة

إعداد Hermes هو ملف واحد وعادة واحدة: كتلة AGENTS.md التي تحدد الأمر، ومصدر المصادقة، وقاعدة رمز الخروج، بالإضافة إلى عادة السماح لـ Hermes بتشغيل apidog run عبر أداة terminal والتحقق من رمز الخروج بنفسك. أضف خادم Apidog MCP عبر ~/.hermes/config.yaml ويمكنه قراءة مواصفاتك أثناء كتابة الكود أيضًا.

تستمر في إنشاء السيناريوهات بصريًا في Apidog؛ Hermes يقوم بتشغيلها فقط. من هنا، وجه نفس الأمر إلى مسار عملك باستخدام Apidog CLI في GitHub Actions، أو اقرأ مرجع العلامات الكامل في الدليل الكامل.

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

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

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

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

في ملف سياق يقوم Hermes بتحميله عند بدء التشغيل. يقوم محرك السياق الخاص به بمسح دليل العمل بحثًا عن ملفات مثل AGENTS.md و CLAUDE.md ويحقنها في موجه النظام. ضع كتلة Apidog الخاصة بك في AGENTS.md في جذر المستودع وستقرأ كل جلسة في ذلك المستودع هذا الملف.

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

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

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

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

هل يعمل هذا بنفس الطريقة في وكلاء ترميز الذكاء الاصطناعي الآخرين؟

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