# Mind Key مقابل JWT — ماذا ومتى؟

يمتلك Synapse رمزي مصادقة. اختيار الخاطئ يؤدي إلى أخطاء 401.
يمنحك هذا الدليل إطار قرار واضح.

## جدول القرار السريع

| تريد... | استخدم |
|----------------|-----|
| تخزين / استدعاء الذكريات | Mind Key |
| إرسال / استطلاع رسائل الدردشة | Mind Key |
| إدارة المهام | Mind Key |
| تخزين السكربتات | Mind Key |
| تسجيل الـ webhooks | Mind Key |
| التحكم بالأجهزة | Mind Key (جانب المستخدم) / Computer Token (جانب الوكيل) |
| تسجيل حساب مستخدم | لا شيء (عام) |
| تسجيل الدخول | لا شيء (عام) |
| إنشاء / سرد / حذف العقول | JWT |
| مشاركة عقل مع مستخدم آخر | JWT |
| الاشتراك في إشعارات web push | JWT |
| عرض سجل التدقيق | Mind Key |

## القاعدة البسيطة

> [!TIP]
> **إذا كان يلامس بيانات عقل واحد → Mind Key.**
> **إذا كان يدير الحساب أو بيانات العقل الوصفية → JWT.**

## Mind Key — رمز وصول البيانات

يمنح Mind Key الوصول إلى **بيانات عقل واحد**. إنه رمز طويل الأمد
لا ينتهي (حتى يُحذف العقل). مثالي لـ:

- وكلاء LLM الذين يحفظون الذكريات عبر الجلسات
- مهام cron الخلفية
- إعداد خادم MCP
- تكاملات الـ webhooks
- تطبيقات الموبايل التي تقرأ الذاكرة

### ما يستطيع Mind Key فعله

- `GET /memory/recall` — قراءة جميع الذكريات في هذا العقل
- `POST /memory` — تخزين/تحديث الذكريات
- `GET /chat/poll` — قراءة رسائل الدردشة
- `POST /chat/reply` — إرسال رسائل الدردشة
- `GET /mind/tasks` — سرد المهام
- `POST /mind/task` — إنشاء المهام
- `POST /script` — تخزين السكربتات
- `POST /webhooks` — تسجيل الـ webhooks
- `POST /computers/:id/commands` — إدراج أوامر الأجهزة في الطابور

### ما لا يستطيع Mind Key فعله

- إنشاء / سرد / حذف العقول (يحتاج JWT)
- مشاركة عقل مع مستخدم آخر (يحتاج JWT)
- عرض معلومات حساب المستخدم (يحتاج JWT)
- الاشتراك في web push (يحتاج JWT)

## JWT — رمز إدارة الحساب

تُصادق JWT **حساب المستخدم**. تنتهي بعد 7 أيام وتُستخدم
لعمليات مستوى الحساب التي تمتد عبر عقول متعددة أو تتضمن مستخدمين آخرين.

### ما تستطيع JWT فعله

- `POST /minds` — إنشاء عقل جديد (يُرجع Mind Key جديد)
- `GET /minds` — سرد جميع العقول لهذا المستخدم
- `DELETE /minds/:id` — حذف عقل
- `POST /sharing` — مشاركة عقل مع مستخدم آخر
- `POST /push/subscribe` — الاشتراك في إشعارات web push
- `GET /sharing` — سرد مشاركات العقل

### ما لا تستطيع JWT فعله

- قراءة / كتابة الذكريات (تحتاج Mind Key)
- إرسال رسائل الدردشة (تحتاج Mind Key)
- إدارة المهام (تحتاج Mind Key)
- تسجيل الـ webhooks (تحتاج Mind Key)

## حالة خاصة: Computer Token

نقاط النهاية `/computers/me/*` (الخاصة بالوكيل، لـ screen-remote-agent)
تستخدم نوع رمز ثالث: **Computer Token**. يُرجع هذا الرمز بواسطة
`POST /computers/register` عند استرداد رمز تثبيت، وهو خاص بـ
جهاز مسجّل واحد.

| نقطة النهاية | المصادقة |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key أو JWT |
| `POST /computers/:id/commands` | Mind Key أو JWT |

## الأنماط الشائعة

### النمط 1: وكيل LLM واحد

1. سجّل مرة واحدة → احصل على JWT
2. أنشئ عقلًا واحدًا → احصل على Mind Key
3. يستخدم LLM Mind Key لكل شيء

### النمط 2: وكيل متعدد المشاريع

1. سجّل مرة واحدة → احصل على JWT
2. أنشئ عقولًا متعددة (work، personal، project-x) → احصل على Mind Keys متعددة
3. يحمل LLM Mind Key مختلفًا حسب السياق

### النمط 3: مشاركة الفريق

1. المستخدم A ينشئ عقلًا → يحصل على Mind Key A
2. المستخدم A يشارك مع المستخدم B عبر JWT (`POST /sharing`)
3. المستخدم B يستطيع الآن الوصول عبر JWT الخاص به
4. لوصول LLM، يحتاج المستخدم B لإنشاء Mind Key خاص به (أو استخدام A's)

### النمط 4: خادم MCP

خوادم MCP تستخدم دائمًا Mind Key (عيينها عبر متغير البيئة `SYNAPSE_MIND_KEY`). نسخة خادم MCP
واحدة = عقل واحد. لوصول عقول متعددة، شغّل نسخ MCP متعددة
أو نفّذ تبديل العقل من جانب العميل.

## ورقة غش تنسيق الرموز

| الرمز | التنسيق | مثال |
|-------|--------|---------|
| Mind Key | `mk_` + 36 حرفًا | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 حرفًا | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## الخطوات التالية

- [المصادقة](/docs/getting-started/authentication) — دليل المصادقة الكامل
- [User & Minds API](/docs/api/user) — نقاط نهاية محمية بـ JWT
- [Memory API](/docs/api/memory) — نقاط نهاية محمية بـ Mind Key