Pilot Protocol

حزمة الشبكة لوكلاء الذكاء الاصطناعي.
عناوين. منافذ. أنفاق. تشفير. ثقة.

Docs  ·  Wire Spec  ·  Whitepaper  ·  IETF Draft  ·  Agent Skills  ·  Polo (Live Dashboard)

---

بُني الإنترنت للبشر. لا يملك وكلاء الذكاء الاصطناعي عنوانًا، ولا هوية، ولا وسيلة للوصول إليهم. Pilot Protocol هي شبكة طبقية (overlay network) تمنح الوكلاء ما منحه الإنترنت للأجهزة: عنوانًا دائمًا، وقنوات مشفّرة موثّقة، ونموذج ثقة -- كل ذلك مبني فوق UDP القياسي.

يسجّل الوكلاء لدى خدمة rendezvous للاكتشاف واختراق NAT. تتدفق بيانات التطبيق مباشرة بين الأقران على المسار المباشر؛ وعندما يفشل اختراق NAT (مثل NAT المتماثل)، يعيد الـ beacon ترحيل حركة المرور المشفّرة من الطرف إلى الطرف كخيار احتياطي. إنها ليست واجهة برمجية. إنها ليست إطار عمل. إنها بنية تحتية.

---

المشكلة

اليوم، يتحدث الوكلاء عبر واجهات برمجية مركزية. تمر كل رسالة عبر منصة -- ترى المنصة كل حركة المرور، وتتحكم في الوصول، وتصبح نقطة فشل واحدة.```mermaid graph LR A1[Agent A] -->|HTTP API| P[Platform / Cloud] A2[Agent B] -->|HTTP API| P A3[Agent C] -->|HTTP API| P style P fill:#f66,stroke:#333,color:#fff style A1 fill:#4a9,stroke:#333,color:#fff style A2 fill:#4a9,stroke:#333,color:#fff style A3 fill:#4a9,stroke:#333,color:#fff

بروتوكول Pilot يُخرج المنصة من مسار البيانات. تتولى خدمة **rendezvous** خفيفة الوزن عملية الاكتشاف واختراق NAT، ولكن بمجرد أن يجد الوكلاء بعضهم البعض، يتحدثون مباشرة عبر أنفاق مصادَق عليها ومشفَّرة:```mermaid
graph LR
    A1[Agent A<br/><small>0:0000.0000.0001</small>] <-->|Encrypted UDP Tunnel| A2[Agent B<br/><small>0:0000.0000.0002</small>]
    A1 <-->|Encrypted UDP Tunnel| A3[Agent C<br/><small>0:0000.0000.0003</small>]
    A2 <-->|Encrypted UDP Tunnel| A3
    A1 -.->|discovery| RV[Rendezvous]
    A2 -.->|discovery| RV
    A3 -.->|discovery| RV
    style A1 fill:#4a9,stroke:#333,color:#fff
    style A2 fill:#4a9,stroke:#333,color:#fff
    style A3 fill:#4a9,stroke:#333,color:#fff
    style RV fill:#888,stroke:#333,color:#fff

ما الذي يحصل عليه الوكلاء```bash

pilotctl info # show your address, hostname, peer count pilotctl set-hostname my-agent # claim a name other agents can resolve pilotctl find agent-alpha # resolve a public demo peer pilotctl ping agent-alpha # round-trip over the encrypted tunnel pilotctl bench agent-alpha # 1 MB echo benchmark

بمجرد أن يكون لديك نظير موثوق، تستخدم المراسلة بين الوكلاء خدمة تبادل البيانات على المنفذ 1001:```bash
# Send a structured message (waits for reply by default)
pilotctl send-message other-agent --data "hello"

# Read messages delivered to your inbox
pilotctl inbox

# Read a specific message
pilotctl inbox read <id>

للتعامل مع الرسائل الخام على مستوى المنفذ المنخفض:```bash

on the sender

pilotctl send other-agent 1000 --data "hello"

on the receiver

pilotctl recv 1000 --count 5 --timeout 30s

كل أمر CLI يدعم `--json` للحصول على مخرجات منظمة — راجع [مرجع CLI](https://pilotprotocol.network/docs/cli-reference) للاطلاع على كامل الواجهة المتاحة.

<details>
<summary><strong>مثال على مخرجات JSON</strong></summary>```json
$ pilotctl --json info
{"status":"ok","data":{"address":"0:0000.0000.0005","node_id":5,"hostname":"my-agent","peers":3,"connections":1,"uptime_secs":3600}}

$ pilotctl --json find other-agent
{"status":"ok","data":{"hostname":"other-agent","address":"0:0000.0000.0003"}}

$ pilotctl --json recv 1000 --count 1
{"status":"ok","data":{"messages":[{"seq":0,"port":1000,"data":"hello","bytes":5}]}}

$ pilotctl --json find nonexistent
{"status":"error","code":"not_found","message":"cannot find \"nonexistent\" — hostname not found or no mutual trust","hint":"establish trust first: pilotctl handshake nonexistent \"reason\""}

---

الوصول البرمجي (SDKs)

بمجرد تشغيل الخادم (daemon)، يمكنك التفاعل مع الوكلاء برمجيًا عبر SDK بدلاً من CLI. تتواصل جميع حزم SDK الثلاث مع خادم Pilot المحلي عبر IPC الخاص بمقبس Unix، وتكشف عن كامل واجهة الوكيل — handshake وtrust وsend وreceive وstream وgateway — باللغة التي تختارها.

اللغة	الحزمة	البدء السريع
Node.js / TypeScript	pilotprotocol على npm	npm install pilotprotocol — راجع sdk-node README
Python	pilotprotocol على PyPI	pip install pilotprotocol — راجع sdk-python README
Swift / iOS / macOS	pilotprotocol على GitHub	أضِفه عبر Package.swift — راجع sdk-swift README

مثال استعلام أولي بسيط بـ Node.js بعد daemon start:```js import { createPilot, createAgent } from 'pilotprotocol';

const pilot = await createPilot(); const conn = await pilot.handshake('agent-alpha', 'hello'); await conn.trust();

// Send a message await conn.send(3000, Buffer.from('ping'));

// Receive on any port const msgs = await conn.recv(3000, { count: 1, timeout: 10 }); console.log('Received:', msgs[0].data.toString());

راجع README الخاص بكل SDK للحصول على وثائق API الكاملة، وأمثلة البث، والإعداد الخاص بكل منصة (محاكي iOS، إضافات PyPI، إلخ).

## أبرز الميزات

<table>
<tr>
<td width="50%" valign="top">

**العنونة**
- عناوين افتراضية 48-بت (`N:NNNN.HHHH.LLLL`)
- منافذ 16-بت مع تعيينات معروفة
- الاكتشاف القائم على اسم المضيف

**النقل**
- تدفقات موثوقة (مكافئة لـ TCP)
- نافذة منزلقة، SACK، التحكم في الازدحام (AIMD)
- التحكم في التدفق (نافذة الاستقبال المُعلنة)
- دمج Nagle، التقسيم التلقائي، استقصاء النافذة الصفرية
- اختراق NAT: اكتشاف STUN، ثقب الثقوب، الاحتياط عبر المرحّل

</td>
<td width="50%" valign="top">

**الأمان**
- تبادل مفاتيح موثّق (X25519 موقّع بـ Ed25519 + AES-256-GCM)
- مفاتيح هوية Ed25519 مرتبطة بجلسات النفق
- العُقد خاصة افتراضيًا
- بروتوكول مصافحة الثقة المتبادلة (موقّع، عبر السجل المرحّل)