# الوصول إلى SSH عبر وسيط

يحتاج الوكلاء إلى تنفيذ أوامر على أجهزة بعيدة — نشر حاوية، قراءة سجل، إصلاح إعداد. تسليم مفاتيح SSH الخاصة الخام إلى LLM فكرة سيئة: المفاتيح تنتهي في نوافذ السياق والسجلات والمحفوظات النصية. وسيط SSH يحل هذا: هو من يمتلك بيانات الاعتماد، والوكيل يتحدث HTTP فقط.

## النموذج

```
LLM ──HTTPS──► وسيط SSH ──SSH──► الأجهزة الهدف
                (يملك المفاتيح،
                 سجل التدقيق،
                 حدود المعدل)
```

يعرض الوسيط جلسات دائمة عبر سطح REST بسيط:

| نقطة النهاية | الغرض |
|---|---|
| `POST /connect?target=vps1` | فتح جلسة → `session_id` |
| `POST /<sid>/exec` `{command, timeout}` | تنفيذ أمر (غير متزامن) → `exec_id` |
| `GET /<sid>/exec/<exec_id>` | استطلاع المخرجات |
| نقاط SFTP | رفع/تنزيل الملفات، `ls`، `mkdir`، `rm` |

المصادقة برمز Bearer — النمط نفسه لكل واجهة برمجية أخرى تستخدمها.

## نمط التنفيذ

```bash
# 1. اتصل مرة واحدة، وأعد استخدام الجلسة للمهمة كلها
SID=$(curl -s -H "Authorization: Bearer $KEY" \
  "https://ssh-proxy.example/connect?target=vps1" | jq -r .session_id)

# 2. نفّذ أمرًا
EID=$(curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -X POST "https://ssh-proxy.example/$SID/exec" \
  -d '{"command": "docker ps --format \"{{.Names}}\"", "timeout": 120}' | jq -r .exec_id)

# 3. استطلع النتيجة
curl -s -H "Authorization: Bearer $KEY" "https://ssh-proxy.example/$SID/exec/$EID"
```

## قواعد التعامل

1. **أعد استخدام الجلسات.** الاتصال لكل أمر يبدد الموارد ويلمس حدود المعدل. احفظ `session_id` (مثل `/tmp/vps1_sid`) وأجرِ نبضة له قبل إعادة الاستخدام.
2. **سمِّ الأهداف ولا تكتشفها.** الأهداف مسجّلة مسبقًا (`vps1`، `pi`، …). الوسيط هو مصدر الحقيقة الوحيد — لا تضمّن عناوين IP في كود الوكيل أبدًا.
3. **فضّل SFTP على cat/heredoc في الصدفة للملفات.** تهريب البيانات الثنائية عبر `exec` يفسد الحمولات. استخدم نقاط الرفع/التنزيل المخصصة.
4. **ضع أوامرك بين علامات اقتباس.** تُحلَّل حامل JSON مرتين (HTTP + الصدفة). لُف الأوامر البعيدة بعلامات اقتباس مفردة وأبقها سطرًا واحدًا.
5. **افترض التدقيق.** كل تنفيذ يدخل سجل تدقيق الوسيط — تصرّف كأن الإنسان يقرأ كل شيء (بوسعه ذلك).

## متى لا تستخدم exec

- قراءة حالة مُهيكلة لها واجهة برمجية (Docker، قواعد بيانات، Mind API في Synapse) — فضّل الواجهة البرمجية دائمًا على تحليل مخرجات سطر الأوامر.
- العمليات التفاعلية طويلة الأمد. `exec` نمط «أطلق وانسَ» بمهلة؛ استخدم بدلًا منه `nohup` + ملف حالة على الجهاز الهدف.
- أي شيء مدمّر بلا تعليمات صريحة. الوسيط يمنحك القدرة — والإنسان يمنحك الإذن.

## استعادة الأخطاء

| العَرَض | الحل |
|---|---|
| 401 عند الاتصال | انتهى الرمز — اقرأه من memory/settings من جديد، لا من محفوظات أبدًا |
| الجلسة 404 | انتهت صلاحية الجلسة (حد 24 ساعة) — أعد الاتصال |
| انتهاء مهلة التنفيذ | ارفع `timeout` أو قسّم الأمر؛ تحقق من حمل الجهاز الهدف |
| محتوى ملف فاسد | استخدمت `exec` بدلًا من SFTP — انتقل إلى نقاط SFTP |