استكشاف الأخطاء وإصلاحها

ابدأ من العَرَض في الجدول. يذكر كل صف السبب الأرجح والحل. البندان اللذان لهما عنوان خاص هما سلوكان تغيّرا في 0.1.2، لذلك يحتاجان إلى انتباه أكبر.

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

العَرَض	الحل
لا يظهر الوكيل getman بحالة متصل	تأكد أن getman موجود في PATH، وأن Node.js 20 أو أحدث مثبت. شغّل claude من جذر المستودع. لمعرفة الخطأ، شغّل getman mcp --workspace getman يدويًا.
401 مع رسالة “Token request returned 401”	السر فارغ. اضبطه في Environments، أو صدّره لسطر الأوامر والوكلاء: export GETMAN_VAR_<KEY>=….
بيئة غير معروفة (الرمز 3)	استخدم اسمًا من قائمة Environments.
تم تخطي طلبات في الإنتاج (الرمز 4)	هذا مقصود. في CLI، استخدم --allow-mutations فقط عندما تقصد ذلك. بالنسبة للوكلاء، وافق على الطلب عندما يطلب ذلك عميل الوكيل.
رُفض Pull	احفظ تغييراتك المحلية بـ commit أو تخلّص منها أولًا. الفرع المتباعد يحتاج إلى دمج عادي في Git أو إلى rebase.
Push معطّل	ليس للفرع أي upstream. شغّل git push -u origin <branch> مرة واحدة.
علامات تعارض أو YAML غير صالح	يرفض Getman تحميل الملف. أصلحه في Git، ثم شغّل getman change validate --workspace getman.
أنشأ شخصان معرّف التغيير نفسه، مثل GT-…-007	في ملف واحد، غيّر id: إلى الرقم الحر التالي، وأعد تسمية الملف ليطابقه، ثم نفّذ commit.
فشل تأكيد	تُظهر تبويبة Tests في الاستجابة القيمة المتوقعة والفعلية. في CLI، يخرج التشغيل بالرمز 1 ويطبع الفحص الفاشل.
“Couldn’t open that folder”	اختر مجلد getman نفسه، وهو المجلد الذي يحتوي على getman.yaml، وليس جذر المستودع.
يقول macOS إنه لا يمكن فتح Getman	البناء غير موقّع بعد. انقر بزر الفأرة الأيمن على Getman، واختر Open، وأكّد مرة واحدة.

الأسرار المحفوظة مقفلة (الرمز 5)

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

1. افتح Project settings → Command line & agents.
2. فعّل Allow the command-line tool and agents to use saved secrets.
3. شغّل الأمر مرة أخرى.

إذا لم ترغب في السماح بالوصول، فاستخدم --no-secrets، ومرّر القيم بطريقة أخرى، مثل GETMAN_VAR_<KEY>.

يفشل طلب برسالة “Status is not an HTTP error”

أعادت الواجهة استجابة بالحالة 4xx أو 5xx. يعامل Getman ذلك الآن كفشل في كل مكان: في التطبيق، والمشغّل، وCLI، وأدوات الوكيل. إذا كانت الحالة متوقعة، فأضف لها تأكيد حالة، مثل Status equals 401 على طلب يختبر حالة عدم التفويض. ولا يستطيع إلا تأكيد حالة مفعّل أن يجعل حالة خطأ تنجح.

القيود المعروفة

• تعتمد موافقة الإنتاج للوكلاء على دعم العميل لنموذج التأكيد في MCP. اختُبر النموذج مع عميل MCP SDK، ولم يُختبر مع واجهة Claude Code التفاعلية.
• لم يُختبر استخدام سطر الأوامر في CI بعد.

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