# Computer Control API

تتيح لك Computer Control API التحكم عن بُعد بالأجهزة المسجّلة. يعمل وكيل
صغير (`screen-remote-agent`) على الجهاز الهدف، يستطلع للأوامر، ينفّذها،
ويُعيد نشر النتائج. هذا يُمكّن أتمتة الواجهة الرسومية المدفوعة بنماذج LLM.

## البنية

```
┌─────────────┐  queue cmd   ┌──────────┐  poll   ┌─────────────────┐
│ LLM Agent   │ ───────────▶ │ Synapse  │ ◀───── │ screen-remote   │
│ (user-side) │              │  Server  │ ──────▶│ (on target PC)  │
└─────────────┘              └──────────┘ result  └─────────────────┘
                                     ▲
                                     │
                              ┌─────────────┐
                              │  Human UI   │
                              │ (browser)   │
                              └─────────────┘
```

## نقاط نهاية المستخدم (Mind Key أو JWT)

### GET /computers/list

قائمة بجميع الأجهزة المسجّلة.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/list
```

### GET /computers/:id

الحصول على تفاصيل جهاز واحد.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001
```

### POST /computers/install-code

توليد رمز تثبيت لتسجيل جهاز جديد.

```bash
curl -X POST https://synapse.schaefer.zone/computers/install-code \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"computer_name": "office-mac"}'
```

الاستجابة: `{ "install_code": "ic_xyz789", "expires_at": "..." }`

### POST /computers/:id/commands

إدراج أمر في الطابور لينفّذه الوكيل البعيد.

```bash
curl -X POST https://synapse.schaefer.zone/computers/comp_001/commands \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "payload": {}
  }'
```

الاستجابة: `{ "command_id": "cmd_001", "status": "queued" }`

### GET /computers/:id/command (عبر الاستعلام)

إدراج أمر عبر GET (للحالات البسيطة).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/command?type=screenshot"
```

### GET /computers/:id/commands

قائمة الأوامر الأخيرة لجهاز.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/computers/comp_001/commands?limit=50"
```

### GET /computers/:id/commands/:cid

الحصول على الحالة + النتيجة لأمر محدد.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/commands/cmd_001
```

### GET /computers/:id/screenshot

أحادي الخطوة: إدراج أمر لقطة شاشة والانتظار حتى 30 ثانية للنتيجة.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/screenshot > screenshot.png
```

### POST /computers/:id/disable

تعطيل جهاز (يُبطل رمزه، ويُبقي السجل للتدقيق).

```bash
curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001/disable
```

### DELETE /computers/:id

حذف جهاز نهائيًا.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/computers/comp_001
```

## نقاط نهاية الوكيل (Computer Token)

تُستخدم هذه النقاط من قبل `screen-remote-agent` الذي يعمل على الجهاز الهدف.
تستخدم Computer Token (يُرجعها `/computers/register`)، وليس Mind Key.

### POST /computers/register

استرداد رمز تثبيت والحصول على Computer Token.

```bash
curl -X POST https://synapse.schaefer.zone/computers/register \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ic_xyz789",
    "computer_name": "office-mac",
    "platform": "darwin",
    "platform_release": "14.5.0",
    "python": "3.12.4"
  }'
```

الاستجابة: `{ "computer_id": "comp_001", "computer_token": "ct_..." }`

> [!CRITICAL]
> احفظ `computer_token` — يُعرض مرة واحدة فقط ومطلوب لجميع نقاط نهاية
> الوكيل.

### GET /computers/me/poll

استطلاع طويل للأوامر الجديدة. يستدعي الوكيل هذا في حلقة.

```bash
curl -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
     "https://synapse.schaefer.zone/computers/me/poll?wait=30"
```

يُرجع فورًا إذا كانت هناك أوامر معلّقة، أو بعد `wait` ثانية إن لم تكن.

### POST /computers/me/commands/:cid/result

نشر نتيجة تنفيذ أمر.

```bash
curl -X POST https://synapse.schaefer.zone/computers/me/commands/cmd_001/result \
  -H "Authorization: Bearer ct_YOUR_COMPUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "result": { "screenshot_b64": "iVBORw0KG..." }
  }'
```

## أنواع الأوامر

| النوع | الحمولة | الوصف |
|------|---------|-------------|
| `screenshot` | `{}` | التقاط الشاشة كـ PNG (base64) |
| `click` | `{x, y}` | النقر عند الإحداثيات |
| `move` | `{x, y}` | تحريك الماوس إلى الإحداثيات |
| `type` | `{text}` | كتابة نص عند المؤشر |
| `key` | `{keys: ["Ctrl","c"]}` | ضغط مجموعة مفاتيح |
| `scroll` | `{deltaX, deltaY}` | تمرير العجلة |
| `drag` | `{fromX, fromY, toX, toY}` | سحب وإفلات |

## النمط الشائع: أتمتة الواجهة الرسومية المدفوعة بـ LLM

```python
# سير عمل وكيل LLM
1. List computers: GET /computers/list
2. Take screenshot: GET /computers/:id/screenshot
3. Analyze screenshot (vision model)
4. Queue click: POST /computers/:id/commands {type:"click", payload:{x,y}}
5. Wait for result: GET /computers/:id/commands/:cid
6. Take new screenshot to verify
7. Repeat until task done
```

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

- [وكيل المتصفح](/docs/api/browser) — خدمة منفصلة لأتمتة المتصفح
- [دليل الوكلاء المستضافين ذاتيًا](/docs/guides/self-hosted-agents)