# AskUserQuestion

يعرض على المستخدم سؤالاً أو أكثر من الأسئلة المنظمة متعددة الخيارات داخل واجهة المحادثة، ويجمع اختياراته ثم يُعيدها إلى المساعد — مفيد لإزالة الغموض عن النية دون تبادل نصي مفتوح.

## متى يُستخدم

- عندما يحتمل الطلب عدة تفسيرات معقولة ويحتاج المساعد إلى أن يختار المستخدم أحدها قبل المتابعة.
- عندما يجب على المستخدم الاختيار بين خيارات محددة (إطار عمل، مكتبة، مسار ملف، استراتيجية) حيث تكون الردود الحرة عرضة للخطأ.
- عندما تريد المقارنة بين البدائل جنباً إلى جنب باستخدام جزء المعاينة.
- عندما يمكن تجميع عدة قرارات مترابطة في موجه واحد لتقليل التبادل.
- عندما تعتمد خطة أو استدعاء أداة على إعدادات لم يحددها المستخدم بعد.

## المعاملات

- `questions` (مصفوفة، مطلوب): من سؤال واحد إلى أربعة أسئلة تُعرض معاً في موجه واحد. يحتوي كل كائن سؤال على:
  - `question` (سلسلة، مطلوب): نص السؤال الكامل، منتهياً بعلامة استفهام.
  - `header` (سلسلة، مطلوب): تسمية قصيرة (12 حرفاً كحد أقصى) تُعرض كشارة فوق السؤال.
  - `options` (مصفوفة، مطلوب): من خيارين إلى أربعة كائنات خيار. يحتوي كل خيار على `label` (1-5 كلمات) و`description` ومعاينة `markdown` اختيارية.
  - `multiSelect` (قيمة منطقية، مطلوب): عندما تكون `true`، يمكن للمستخدم اختيار أكثر من خيار.

## أمثلة

### مثال 1: اختيار إطار عمل واحد

```
AskUserQuestion(questions=[{
  "header": "Test runner",
  "question": "Which test runner should I configure?",
  "multiSelect": false,
  "options": [
    {"label": "Vitest (Recommended)", "description": "Fast, Vite-native, Jest-compatible API"},
    {"label": "Jest",                  "description": "Mature, broadest plugin ecosystem"},
    {"label": "Node --test",           "description": "Zero dependencies, built in"}
  ]
}])
```

### مثال 2: معاينة جنباً إلى جنب لتخطيطين

```
AskUserQuestion(questions=[{
  "header": "Layout",
  "question": "Which dashboard layout do you prefer?",
  "multiSelect": false,
  "options": [
    {"label": "Sidebar",  "description": "Nav on the left", "markdown": "```\n+------+---------+\n| NAV  | CONTENT |\n+------+---------+\n```"},
    {"label": "Top bar",  "description": "Nav across top",  "markdown": "```\n+-----------------+\n|       NAV       |\n+-----------------+\n|     CONTENT     |\n+-----------------+\n```"}
  ]
}])
```

## ملاحظات

- تُضيف الواجهة تلقائياً خيار نص حر «أخرى» لكل سؤال. لا تُضف خانتك الخاصة من نوع «أخرى» أو «لا شيء» أو «مخصص» — فسيُكرر ذلك المخرج المدمج.
- اقصر كل استدعاء على ما بين سؤال وأربعة أسئلة، وكل سؤال على ما بين خيارين وأربعة خيارات. يرفض الإطار أي تجاوز لهذه الحدود.
- إذا أوصيت بخيار محدد، ضعه أولاً وأضف "(Recommended)" إلى تسميته حتى تبرز الواجهة المسار المفضل.
- تُدعم المعاينات عبر حقل `markdown` في أسئلة الاختيار الفردي فقط. استخدمها للعناصر المرئية مثل تخطيطات ASCII أو مقتطفات الشفرة أو فروقات الإعدادات — لا لأسئلة التفضيل البسيطة حيث تكفي التسمية مع الوصف.
- عندما يحمل أي خيار في السؤال قيمة `markdown`، تتحول الواجهة إلى تخطيط جنباً إلى جنب مع قائمة الخيارات على اليسار والمعاينة على اليمين.
- لا تستخدم `AskUserQuestion` لسؤال «هل تبدو هذه الخطة جيدة؟» — استدعِ `ExitPlanMode` بدلاً منها، فهي موجودة تحديداً لاعتماد الخطة. وفي وضع التخطيط، تجنَّب كذلك ذكر «الخطة» في نص السؤال لأنها لا تكون مرئية للمستخدم قبل تشغيل `ExitPlanMode`.
- لا تستخدم هذه الأداة لطلب مدخلات حساسة أو نصية حرة مثل مفاتيح API أو كلمات المرور. اطلبها في المحادثة بدلاً من ذلك.
