تنسيقات مخرجات Cursor CLI وتكامل CI

المنشور السابق 10-headless-scripts استخدم -p --force لتغيير الملفات من السكربتات. هذا عن تنسيق المخرجات: لنفس تشغيل الـ Agent يمكنك اختيار "نص نهائي فقط" أو "JSON منظم كامل" أو "JSON متدفق أثناء التشغيل" — في CI تحلّل النتائج أو تقيس الزمن أو تعرض التقدّم بهذه التنسيقات الثلاثة.

ثلاثة تنسيقات مخرجات

text: إجابة نهائية نظيفة

cursor agent -p "What is the entry point of this repo?"

بدون --output-format تحصل على نص: المخرجات فقط الرد النهائي، لا استدعاءات أدوات ولا خطوات وسيطة — جيد للصق في الوثائق أو كوصف قصير.

في CI، لكتابة خلاصة الـ Agent إلى ملف:

cursor agent -p "Generate release notes for this version from CHANGELOG" > release_notes.txt

json: للسكربتات وCI

cursor agent -p --output-format json "Analyze src/ dependencies and return JSON: { \"entry\": \"...\", \"deps\": [...] }"

المخرجات JSON منظم، قد يتضمّن result، duration_ms أو حقولاً طلبتها في الـ prompt.
في CI يمكنك:

• استخدام jq لاستخراج حقول أو التحقق من الفراغ أو البحث عن كلمات مفتاحية
• استخدام كود الخروج والمحتوى لقرار نجاح/فشل الـ job

مثال تصوّري:

cursor agent -p --output-format json "Do a short code review; return {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'
# Then use .ok or .summary for next steps or to fail the build

الحقول الدقيقة تعتمد على وثائق Cursor؛ المغزى هنا "json للتحليل البرمجي."

stream-json: تقدّم مباشر وتتبع الأدوات

cursor agent -p --output-format stream-json --stream-partial-output "Analyze project and write analysis.txt"

• كل سطر حدث JSON (مثلاً system، assistant، tool_call، result)
• --stream-partial-output يرسل نص الـ assistant كـ دلتا تدريجية، فيمكنك عرض "عدد الأحرف مباشر" أو "نسبة التقدّم"
• حلّل بداية/انتهاء tool_call لمعرفة أي ملف يقرأ/يكتب الـ Agent وكم استغرق

جيد لـ: تشغيلات طويلة، عرض "معالجة الملف N" في سجلات CI أو واجهة، أو عد استدعاءات الأدوات والمدة.

نصائح تكامل CI

التعامل مع الفشل

• عند فشل تشغيل الـ Agent، تُرجع CLI عادة كود خروج غير صفري
• في السكربتات استخدم if [ $? -ne 0 ]; then exit 1; fi أو set -e ليفشل الـ CI بشكل صحيح
• مع json يمكنك أيضاً التحقق من حقل error أو ok: false المخصّصك للحماية الإضافية

ملخص

• text: افتراضي، قابل للقراءة، حدّ أدنى من المخرجات؛ جيد للكتابة إلى ملف أو كوصف
• json: منظم لـ jq أو السكربتات؛ جيد لقرارات CI والاستخراج
• stream-json + --stream-partial-output: تدفق أحداث مباشر؛ جيد للتقدّم وتتبع الأدوات
• في CI: اضبط CURSOR_API_KEY، احترم كود الخروج، واحلل JSON للنجاح/الفشل عند الحاجة

التالي: 12-sessions-cloud — استئناف الجلسة بـ --resume والتنفيذ السحابي بـ -c.