# دليل الوكلاء — درب

منصّة تعليمية سعودية تُهيّئ الطالب لاختبارات القدرات والتحصيلي وستيب وبرامج أرامكو، وتساعده على اختيار جامعته وتخصّصه: خريطة مذاكرة، جلسات تركيز، خزنة أخطاء، تقويم دراسي رسمي، ودليل جامعات سعودية بكلياتها وتخصّصاتها.

## من نحن
منصّة تعليمية سعودية للطلاب المقبلين على اختبارات القبول الجامعي. الواجهة عربية
(RTL) والجمهور طلابُ الثانوية والخريجون في السعودية.

## ماذا يمكنك أن تفعل بالنيابة عن الطالب
- **خريطة المذاكرة** — لكل اختبارٍ مساحةُ عمل: جاهزيةٌ محسوبة، وما تبقّى من دروسٍ وتدريب، والخطوة التالية. (`/roadmap`)
- **جلسات التركيز** — مؤقّت مذاكرةٍ يسجّل ساعاتك ويربطها بمهمّة اليوم وبسلسلة أيامك. (`/orbit`)
- **خزنة الأخطاء** — تحفظ كل سؤالٍ أخطأت فيه ويشرحه المساعد، ثم تُراجَع بالتكرار المتباعد. (`/vault`)
- **خطة اليوم** — جدولٌ يوميّ/أسبوعيّ/شهريّ يُبنى حول مشاغلك ويحسب وقتك المتاح فعلاً. (`/plan`)
- **دليل الجامعات** — جامعات السعودية بكلياتها وتخصّصاتها الدقيقة ومعادلات النسبة الموزونة وترتيب QS. (`/universities`)
- **التقويم الدراسي** — العام الدراسي الرسمي وإجازاته ومواعيد قياس المعلنة — تُبنى الخطة عليه. (`/plan`)
- **أسئلة القبول الشائعة** — إجاباتٌ عن منصّة قبول وشروط التقديم والنسب الموزونة. (`/faq`)

## واجهات القراءة العامّة
لا تحتاج مصادقة، وتُعيد JSON، وحدُّها ٦٠ طلباً في الدقيقة لكل عنوان.

### `GET /api/agent/universities`
قائمة الجامعات السعودية ومعلوماتها؛ ومع `id` تُعاد كلياتها وتخصّصاتها الدقيقة.
المعاملات: `id` · `region`

### `GET /api/agent/exams`
الاختبارات الوطنية ونوافذ تسجيلها الرسمية وحالتها (مفتوح/قادم/بانتظار الإعلان).

### `GET /api/agent/calendar`
التقويم الدراسي السعودي المعتمد: الفصول والإجازات ونهاية العام.

### `GET /api/agent/faq`
الأسئلة الشائعة عن القبول الجامعي ومنصّة قبول، مع بحثٍ نصّي عبر `q`.
المعاملات: `q`

## الاكتشاف الآليّ
| ماذا | أين |
|---|---|
| وصف OpenAPI 3.1 | `https://usedarb.com/openapi.json` · `https://usedarb.com/openapi.yaml` |
| عقدُ التنفيذ (agents.json) | `https://usedarb.com/agents.json` |
| بطاقة الوكيل (A2A) | `https://usedarb.com/.well-known/agent-card.json` |
| بيان الإضافة | `https://usedarb.com/.well-known/ai-plugin.json` |
| خادم MCP | `https://usedarb.com/mcp` · وصفُه `https://usedarb.com/.well-known/mcp.json` |
| مخطّطات JSON Schema | `https://usedarb.com/schemas.json` |
| المهارات | `https://usedarb.com/api/agent/skills` |
| سياسة الذكاء الاصطناعي | `https://usedarb.com/ai.txt` |
| اكتشافُ التفويض | `https://usedarb.com/.well-known/oauth-protected-resource` |

## خادم MCP
`POST https://usedarb.com/mcp` بـJSON-RPC 2.0 (البروتوكول `2025-06-18`):

- `initialize` · `ping`
- `tools/list` · `tools/call` — خمسُ أدوات: `list_universities` · `get_university` ·
  `list_exams` · `get_academic_calendar` · `search_faq`
- `prompts/list` · `prompts/get` — أربعُ مطالبات جاهزة: `choose_university` ·
  `exam_timeline` · `admission_question` · `study_plan`
- `resources/list` · `resources/read`

## المصادقة
واجهاتُ القراءة أعلاه **عامّة بلا مصادقة**. أمّا ما يخصّ حساب طالبٍ بعينه فمحميٌّ
بتسجيل دخول Google (OAuth 2.0 عبر Firebase)، ويُرسَل رمزُ الهوية في ترويسة
`Authorization: Bearer <ID token>`. لا يوجد — ولن يوجد — طريقٌ يُخرِج بيانات
طالبٍ إلى وكيلٍ بلا إذنه.

## قواعد نتوقّع منك احترامها
1. **لا تخترع موعداً ولا رقماً.** إن لم تُعلنه الجهة الرسمية فالحقل فارغٌ عمداً؛
   انقل «لم يُعلن بعد» ولا تملأ الفراغ من عندك.
2. **انسب المصدر** حين تنقل تقويماً أو نافذة تسجيل — الجهة هي المرجع، ودرب ناقل.
3. **احترم robots.txt**: الصفحات خلف تسجيل الدخول ممنوعة من الزحف.